UpstreamDrift Conventions Reference
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(length7 + n_j):[base_xyz_m, quat_wxyz, joint_angles_rad…]v(length6 + n_j):[base_linear_world_m/s, base_angular_body_rad/s, joint_rates…]nq = nv + 1because the unit quaternion is not a free tangent coordinate; integrate withintegrate(q, dq), neverq + 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_talong target,z_tup,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
- Start from
canonical-v2when reading dynamics APIs, datasets, or cross-engine conformance tests. - Start from
canonical-v1/ Pose Studio when importing human-readable pose degrees. - Name the world frame before comparing impact, mocap, or flight numbers—ADR-0041 impact defaults differ from flight-model axes.
- 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
@online{untitled,
author = {},
title = {UpstreamDrift {Conventions} {Reference}},
url = {https://affinedrift.com/pages/upstreamdrift-conventions.html},
langid = {en}
}