PhysxJointAxisAPI#
Per-axis PhysX properties of an articulation joint (armature, maximum joint velocity, static, dynamic and viscous friction), applied as PhysxJointAxisAPI:
Applies to:
PhysicsJointMulti-apply: applied as
PhysxJointAxisAPI:<instance>;<inst>in a column name is the instance. Instances:angular,linear,rotX,rotY,rotZ.Read only when listed in
usd-schemas.
What USD population writes#
All five declared attributes of every applied instance are published at their resolved values. physxJointAxis:
Columns#
Raw fallback is the USD schema value. Producer writes is what ovstage population puts in the column for a USD stage. Parser default applies on the consumer when the column is absent, in stage units. diverges means writing the raw fallback literally parses differently from omitting the column (the parser default): USD population may well publish that very value for an unauthored attribute, so the marker is about the column being present, not about its value.
Column |
Type |
Units |
Raw fallback |
Producer writes |
Parser default |
If absent |
|---|---|---|---|---|---|---|
|
float32 |
linear/transX..Z: mass; angular/rotX..Z: mass*length^2 |
0.0 |
resolved USD value (authored, else raw fallback) |
0.0 |
newton:armature, then 0 survives on this axis. Only a strictly positive per-axis value displaces that seed, including on USD; an explicit PhysX zero cannot clear a nonzero Newton seed. |
|
float32 |
linear: length/s; angular/rotX..Z: deg/s (deg_to_rad) |
|
when unauthored: |
|
newton:velocityLimit, then FLT_MAX survives on this axis. A value >= FLT_MAX counts as unauthored. |
|
float32 |
linear: force; angular: torque |
0.0 |
resolved USD value (authored, else raw fallback) |
0.0 |
newton:friction seeds both friction efforts, or zero when absent. If either per-axis PhysX effort is strictly positive, both efforts come from PhysX (zero for a missing effort), so the parser never mixes the two sources. |
|
float32 |
linear: force; angular: torque |
0.0 |
resolved USD value (authored, else raw fallback) |
0.0 |
newton:friction seeds both friction efforts, or zero when absent. If either per-axis PhysX effort is strictly positive, both efforts come from PhysX (zero for a missing effort), so the parser never mixes the two sources. |
|
float32 |
linear: forces/length; angular: torques/deg |
0.0 |
resolved USD value (authored, else raw fallback) |
0.0 |
newton:damping, or zero when absent, survives unless the per-axis PhysX coefficient is strictly positive. Explicit PhysX zero also preserves the Newton seed. |
Interactions#
PhysicsJoint: On a standalone joint every applied instance is removed from the prim with a ‘supported only for joints that are part of an articulation’ warning.
Known divergences#
fragile (consumer)
physxJointAxis:<inst>:armature: Only strictly positive PhysX armature values displace the seed (newton:armature, then zero), because zero is both the fallback and a legal authored value and ovstage has no authored bit. Explicit PhysX zero therefore cannot clear a nonzero seed on either backend.fragile (consumer)
physxJointAxis:<inst>:maxJointVelocity: Only a PhysX value below FLT_MAX displaces the seed (newton:velocityLimit, then FLT_MAX), because unlimited is both the fallback and a legal authored value and ovstage has no authored bit. An explicitly unlimited PhysX value therefore cannot clear a finite Newton limit on either backend.fragile (consumer)
physxJointAxis:<inst>:staticFrictionEffort: The PhysX friction efforts displace the seed (newton:friction for both, then zero) only when either of them is strictly positive, because zero is both the fallback and a legal authored value and ovstage has no authored bit. Explicit PhysX zeros for both efforts therefore cannot clear a nonzero seed on either backend.fragile (consumer)
physxJointAxis:<inst>:dynamicFrictionEffort: The PhysX friction efforts displace the seed (newton:friction for both, then zero) only when either of them is strictly positive, because zero is both the fallback and a legal authored value and ovstage has no authored bit. Explicit PhysX zeros for both efforts therefore cannot clear a nonzero seed on either backend.fragile (consumer)
physxJointAxis:<inst>:viscousFrictionCoefficient: Only strictly positive PhysX coefficients displace the seed (newton:damping, then zero), because zero is both the fallback and a legal authored value and ovstage has no authored bit. Explicit PhysX zero therefore cannot clear a nonzero seed on either backend.
Notes#
Per-joint-type instance matrix: Fixed none; Revolute angular; Prismatic linear (no rotational conversion); Spherical rotX, rotY, rotZ (all three, each with rotational conversions); Distance none; D6 (PhysicsJoint) rotX, rotY, rotZ only, translational axes are never read; Gear, Rack, Custom none.
Articulation axis mapping: angular and rotX -> PxArticulationAxis::eTWIST; rotY -> eSWING1; rotZ -> eSWING2; linear -> eX.
The D6 descriptor’s jointProperties always has exactly three entries (rotX, rotY, rotZ) even when no instance is applied; unapplied entries have the Newton seeds or the defaults.
Unrecognised instance names fall back to a runtime internToken(‘PhysxJointAxisAPI:’ + inst) and are read the same way.
At attachment, newton:armature seeds armature, newton:friction seeds both friction efforts, and newton:damping seeds viscous friction on each supported axis. Newton values use the same units and conversions as their PhysX counterparts. Register the Newton schema before the first USD schema read, including population or export.
PhysX friction efforts override the Newton pair together if either is positive; positive PhysX viscous friction overrides Newton damping. Applying an API only for another property preserves these seeds. Explicit PhysX zeros cannot clear the Newton seeds.
Edits of the NewtonJointAPI values are forwarded to every axis without a per-axis opinion on the same quantity, and removing a PhysxJointAxisAPI instance at runtime reseeds the axis from them.