Skip to main content

UpstreamDrift Conventions Reference

reference
tools
Pinned UpstreamDrift state layouts, native engine formats, world frames, spatial-vector order, and analytics sign conventions for AffineDrift.

What This Shows / What It Does Not Show

What This Page Establishes (Evidence Level: Convention inventory tied to a pinned UpstreamDrift commit)

  • How UpstreamDrift spells floating-base state, quaternions, spatial vectors, gravity, and world frames at commit c8814a1b9d120ce382ee1de9a6583bb5ef569a15.
  • Where engine adapters convert to canonical-v2 and what remains engine-native when adapters are bypassed.

What This Page Does Not Establish

  • That every AffineDrift article uses the same world frame or path sign as the code tables below.
  • Biomechanical validation, coaching guidance, or launch-monitor vendor equivalence.

UpstreamDrift is the implementation authority for multibody state, mocap registration, flight physics, and analytics kernels that AffineDrift cites. This page records what the code fixes at one commit, not what every article on this site assumes. All UpstreamDrift evidence links below use the frozen revision c8814a1b9d120ce382ee1de9a6583bb5ef569a15 (re-checked 2026-11-10 against issue #5619).

AffineDrift’s normative symbol layer remains Mathematical Notation and Notation Quick Reference. Where those documents disagree with UpstreamDrift or with each other, trust the pinned UpstreamDrift definitions for array layout and sign when executing code; use the site’s notation for prose on this repository only after an explicit conversion. A consolidated NOTATION repair is tracked separately (#5589, PR #5633).

Units, Gravity, and Angle Policy

Quantity UpstreamDrift canonical-v2 Evidence
Length, mass, time SI (m, kg, s) docs/conventions/canonical-v2.md
World frame Z-up, right-handed canonical-v2.md §1
Gravity g = [0, 0, -9.80665] m/s² canonical-v2.md §1 and velocity_conventions.py CANONICAL_GRAVITY_INERTIAL
Dynamic state angles Radians in canonical-v2 q/v canonical-v2.md §1–2
Pose interchange (canonical-v1) Intrinsic XYZ Euler in degrees for pelvis + joint dict in degrees pose_interchange/canonical.py, se3.py R = Rx·Ry·Rz
OpenSim / Simscape pose import Degrees at adapter boundary cross_engine_conventions.md §B

Many AffineDrift articles use 9.81 or radians-only notation; do not silently equate them with UpstreamDrift arrays.

Canonical State Layouts (V1 and V2)

canonical-v1 (CanonicalPose, convention tag canonical-v1): pelvis translation (m) + intrinsic XYZ Euler (degrees) + joint-angle dict (degrees). Velocities are out of scope; Pose Studio materialises v = 0 at import (canonical.py).

canonical-v2 (frozen dynamic contract, ADR-0026): configuration q, velocity v, acceleration a, metadata convention="canonical-v2", frame="world_Zup", units="SI" (canonical-v2.md).

For a floating base and n_j internal joints:

  • q (length 7 + n_j): [base_xyz_m, quat_wxyz, joint_angles_rad…]
  • v (length 6 + n_j): [base_linear_world_m/s, base_angular_body_rad/s, joint_rates…]
  • nq = nv + 1 because the unit quaternion is not a free tangent coordinate; integrate with integrate(q, dq), never q + dq (canonical-v2.md §2).

Per-Engine Native vs Canonical-V2

Conversions run only at the engine adapter boundary unless noted. Low-level get_state() calls that return raw qpos/qvel (MuJoCo) or Pinocchio data are not canonical unless routed through the adapter/CC contract (canonical-v2.md §3 intro).

Engine Native floating-base q Native quaternion order Native base velocity / spatial order Converted at adapter Not converted by default
MuJoCo / MJX [xyz, quat_wxyz, …] w-first (w,x,y,z) Free-joint qvel: linear in world, angular in body (matches v2 base block) Quaternion order only at pose-IO boundary; canonical-v2 state mapping per CC-10 Raw physics_engine.get_state returns native qpos/qvel
Pinocchio [xyz, quat_xyzw] w-last (x,y,z,w) Free-flyer linear & angular in body/local frame; Jacobian native [linear; angular] Reorder quaternion; rotate base linear vel/accel to world via velocity_map (CC-9); restack spatial Jacobian to [angular; linear] Internal data.q, data.v until adapter export
Drake QuaternionFloatingJoint: [quat_wxyz, xyz] or URDF RPY [xyz, rpy] w-first for quaternion joint Spatial Jacobian [angular; linear] in Drake native API Base block reorder + RPY path via se3 (CC-28) Internal MultibodyPlant state vector layout
JaxSim [xyz, quat_wxyz, joints…] in backend data w-first Backend default mixed: body angular + world linear at COM Reads/writes canonical [angular; linear] base v via velocity_conventions; see jaxsim_backend.py get_state/set_state Native JaxSim tape if bypassing backend wrapper
MyoSuite MuJoCo MJCF free joint (same as MuJoCo row) w-first MuJoCo free-joint qvel pattern Same family as MuJoCo CC-10 / MyoSuite adapter Activation & muscle states (not part of q,v contract)
OpenSim FreeJoint coordinates (often XYZ Euler) n/a (Euler joints) Per-coordinate speeds, degrees on disk Degrees → radians at pose boundary (CC-10) .osim shoulder Y sign flips per model
Simscape Parameter-bus start pose, degrees n/a Pose import only (no shared v2 dynamics export) Degrees → radians at boundary Simulink internal states

Spatial Jacobian contract (suite-wide): combined spatial Jacobian is [angular; linear] rows (engine_core/capabilities.py SPATIAL_JACOBIAN_ORDER). Pinocchio’s native frame Jacobian is transposed to that order in pinocchio_physics_engine.py. Drake exposes the same stacking in drake_physics_engine.py.

Pose Studio cross-engine table (pelvis prefix, joint units, quaternion order): cross_engine_conventions.md §A–C. MuJoCo ↔︎ Pinocchio quaternion swap example: pinocchio_interface.py.

Spatial Twist, Wrench, and Control Notation in Code

Topic UpstreamDrift canonical usage AffineDrift site note
6D spatial Jacobian rows [ω; v] (angular first) NOTATION.md declares ξ = (ω, v) but describes V as “Linear + angular” and F as “Torque + linear force”, which reads as conflicting orderings
Floating-base v in canonical-v2 World linear + body angular Site articles sometimes use all-world or all-body twists without stating the split
Drake native spatial velocity Often [angular; linear] in Jacobians; joint velocity blocks may differ Match CC-28 adapter, not a textbook excerpt
Input map in dynamics UpstreamDrift SPEC.md uses ẋ = f(x) + g(x)u (lowercase g) AffineDrift NOTATION.md reserves G(x) for the input matrix and warns against lowercase g(x) for the map

World, Target, Camera, and Lab Frames

UpstreamDrift simultaneously documents several right-handed world frames. A single AffineDrift pass declaring “X forward, Y lateral, Z up” does not identify which of these is in use.

Frame id Axes (summary) Typical use Evidence
ADR-0041 mocap world x → target, y up, z → golfer’s right Pinhole reconstruction, camera rig cameras.py module doc
Canonical z-up registration x → target, y → golfer’s left, z up Marker YAML, registration import registration.py canonical_z_up_to_adr0041_world
ISB-style golfer lab Built from explicit up/target/handedness Trunk/pelvis anatomical angles trunk_pelvis.py header
Impact parameters (ADR-0041 default) Z-up; golfer faces −X; target −Y Launch-monitor-style club metrics impact_parameters/__init__.py
Ball flight integrator Z-up; +X forward at azimuth 0; +Y left Trajectory / spin vector flight_models.py

Camera storage convention: extrinsics are T_world_from_camera (not world-from-camera inversion). OpenCV camera axes: +z forward, +y down (cameras.py). AffineDrift Motion Capture discusses P = K[R|t] with world→camera; multiply through the stored direction when fitting UD calibrations.

Registration map (canonical z-up → ADR-0041): x_w = x_c, y_w = z_c, z_w = -y_c (registration.py).

Impact Parameters, Club Path, and Face Signs

Definitions are in impact_parameters/__init__.py:

  • Target basis: x_t along target, z_t up, y_t = z_t × x_t (left of target for a right-handed golfer).
  • Club path positive = in-to-out; face angle positive = open; signs pick up a handedness factor s = ±1.
  • Attack angle negative when descending.
  • Swing plane fit uses face-centre samples within ±20 ms of impact; impact state is last pre-contact sample.

Compare carefully with AffineDrift articles that declare y-up target frames or path positive right (for example Impact Mechanics and Launch Monitor Vendor Reference).

Ball-Flight Spin and Launch Axes

In the unified flight models, spin builds as [backspin·sin(az), -backspin·cos(az), sidespin] with Z-up and +Y left (flight_models.py). Positive spin-axis tilt can curve the ball left relative to that frame—opposite to many monitor exports that treat positive tilt as fade/right unless converted.

Ground Reaction, Grip Wrench, and Missing Data

Ground reaction uses force by the ground on the foot, Z-up world, CoP valid only when F_z ≥ COP_MIN_FZ_N, and None/NaN gaps—not zero—when unavailable (ground_reaction.py). Grip wrench summaries use force by the hand on the club, reduced to the grip midpoint, with documented split_method when two-hand allocation is indeterminate (manual ch10–11; see biomechanics modules).

Analytics: Lateral Sign and Dispersion Ellipses

Tool / module Horizontal plane convention “95%” ellipse meaning Evidence
SG optimizer TiltedBivariateGaussian Δ⊥ positive = left of target (yards) confidence_ellipse: a, b are semi-axes at level p (χ²₂ scaling inside) distributions.py, §ellipse
Shot pattern analysis x downrange, y right (metres) Empirical/HDR bins in density tools—not the same object as a Gaussian semi-axis dispersion_stats.py
AffineDrift Shot Pattern Analysis States lateral positive right Describes binned HDR, not χ² covariance ellipses

Conversion cheat sheet: y_left = −y_right; correlation ρ changes sign when flipping lateral; 1 yd = 0.9144 m. When comparing ellipse sizes, check whether a report gives semi-axes or full axis lengths (factor of two).

AffineDrift Site vs UpstreamDrift Code

This subsection absorbs the convention bullets tracked in #5593 at the level of a single reference table (full NOTATION harmonisation remains out of scope here).

Topic Common AffineDrift article pattern UpstreamDrift code default Conversion
World frame Mix of Z-up (NOTATION) and Y-up golf articles (x target, y up) Z-up canonical-v2; multiple named frames (table above) Apply fixed axis permutation per source frame; never assume one global site frame
Target / path sign Several articles: path right positive Impact params: in-to-out positive; SG optimizer: left positive lateral Multiply lateral component by −1 when crossing tables; document handedness
Euler pose NOTATION.md extrinsic Z-Y-X radians canonical-v1 intrinsic XYZ degrees Reorder rotation sequence and convert units before Pose Studio import
Spatial 6-vectors Mix of angular-first, linear-first, and force-first wrenches across books Suite Jacobian and canonical-v2 base v: angular then linear; separate wrench policies in biomechanics modules Permute blocks consistently; check power pairing WᵀV
Gravity magnitude Often 9.81 in prose 9.80665 m/s² Use UD constant when reproducing UD numbers
Camera extrinsics Textbook P=K[R|t] world→camera Stored T_world_from_camera Invert/transpose per cameras.py

Using This Page With Models and Agents

  1. Start from canonical-v2 when reading dynamics APIs, datasets, or cross-engine conformance tests.
  2. Start from canonical-v1 / Pose Studio when importing human-readable pose degrees.
  3. Name the world frame before comparing impact, mocap, or flight numbers—ADR-0041 impact defaults differ from flight-model axes.
  4. Run conversions at the boundary; do not assume get_state() on a raw engine object is already canonical.

Programming integration context: UpstreamDrift Educational Integration, Programming Companion, and engine pages under models/models-*.html.

Citation

BibTeX citation: Download .bib
@online{untitled,
  author = {},
  title = {UpstreamDrift {Conventions} {Reference}},
  url = {https://affinedrift.com/pages/upstreamdrift-conventions.html},
  langid = {en}
}
For attribution, please cite this work as:
“UpstreamDrift Conventions Reference.” n.d. https://affinedrift.com/pages/upstreamdrift-conventions.html.