PhysicsArticulationRootAPI#

Marks the root of a reduced-coordinate articulation. Declares no attributes: the schema token itself is the whole signal, and the consumer derives the root link, the fixed-base flag and the set of articulated bodies and joints from the joint graph under the prim. PhysX tuning lives on PhysxArticulationAPI.

  • Applies to: Xformable, PhysicsJoint

  • Read only when listed in usd-schemas.

  • Uses blocks: prim

What USD population writes#

The prim gets a row with PhysicsArticulationRootAPI in usd-schemas whenever the API is applied, even on a bare Xform with no other physics data. No attributes to publish. physics:filteredPairs (PhysicsFilteredPairsAPI) is published when authored and becomes the articulation’s filtered collision list.

Interactions#

  • prim: Enumerated by schema membership (usd-schemas CONTAINS PhysicsArticulationRootAPI), so the probe is the usd-schemas column itself; a root on a bare Xform is recovered. The API on an enabled dynamic non-kinematic rigid body makes that body the user-defined root with no election. On a static or disabled body it is ignored with a warning (‘ArticulationRootAPI definition on non rigid body is not allowed’); on a kinematic body likewise (‘on a kinematic rigid body not allowed’). On an Xform or any other prim the root is elected by weight over the namespace subtree.

  • PhysicsJoint: The API on a joint prim with body0 or body1 absent (joint to world) makes that joint the root and the valid body the base link; on a joint with both bodies valid it falls through to election. During election a joint with one side absent or not an accepted link (static, disabled or kinematic body) and excludeFromArticulation false adds weight 100000 to its link and records itself as that link’s root joint.

  • PhysxArticulationAPI: fixBase is true exactly when the elected root key is itself a joint prim, which happens when a joint-to-world anchor wins the election; the runtime then sets PxArticulationFlag::eFIX_BASE. Without such a joint the root is re-elected through the nested-articulation and centre-of-graph fallbacks and the articulation floats. Observable as articulation->getArticulationFlags().isSet(::physx::PxArticulationFlag::eFIX_BASE).

  • PhysicsRigidBodyAPI: Only enabled, dynamic, non-kinematic bodies are accepted as links; every other body under the root counts as world for the purpose of anchoring.

  • PhysicsFilteredPairsAPI: physics:filteredPairs on the root prim becomes the articulation-level filtered collision list (sourceFilteredCollisions).

Known divergences#

  • note (consumer) usd-schemas: Nested articulation roots (a root prim inside another root’s subtree) are rejected with an error and skipped. A root with nothing aggregable still emits one default articulation descriptor anchored on the root prim.

Notes#

  • Per root the consumer runs setToDefault(ArticulationFields, units), parseArticulation (PhysxArticulationAPI overrides), parseFilteredPairs and then the shared buildArticulations graph pass that the USD walker also runs.

  • applies_to lists PhysicsJoint next to Xformable because the USD schema declares no apiSchemaCanOnlyApplyTo for this API and documents the fixed-base pattern with the API on the root joint itself (usdPhysics schema.usda); the consumer registers the PxArticulationReducedCoordinate on the prim carrying the API (ArticulationGraph.cpp emitArticulationDesc articulationPrim), so the contract tests read the articulation there.

  • physxArticulation:articulationEnabled false on the same prim skips the root entirely: no descriptor is emitted (see PhysxArticulationAPI).

  • PhysxArticulationForceSensorAPI is not parsed anywhere in the runtime and is explicitly out of scope for this contract.

  • Articulation joint types created from the joint prims under the root: Fixed -> eFIX; Revolute -> eREVOLUTE_UNWRAPPED (limited) or eREVOLUTE (free) on eTWIST; Prismatic -> ePRISMATIC on eX; Spherical -> eSPHERICAL with eTWIST free and symmetric eSWING1/eSWING2 limits; D6 -> eSPHERICAL with all three rotational axes free. Distance, gear and rack joints are never articulation joints.