PhysxDrivePerformanceEnvelopeAPI#

Actuator performance envelope of one joint drive (maximum actuator velocity, velocity-dependent resistance, speed-effort gradient), applied as PhysxDrivePerformanceEnvelopeAPI: alongside PhysicsDriveAPI:. Effective only on articulation joints: standalone joints strip it with a warning. Every instance except linear is treated as rotational and converted.

  • Applies to: PhysicsJoint

  • Requires on the same prim: PhysicsDriveAPI

  • Multi-apply: applied as PhysxDrivePerformanceEnvelopeAPI:<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 three declared attributes of every applied instance are published at their resolved values. physxDrivePerformanceEnvelope::maxActuatorVelocity is rewritten to FLT_MAX when unauthored for each applied instance.

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

physxDrivePerformanceEnvelope:<inst>:maxActuatorVelocity

float32

linear: length/s; others: deg/s (deg_to_rad)

inf

when unauthored: FLT_MAX

FLT_MAX

Unbounded actuator speed.

physxDrivePerformanceEnvelope:<inst>:velocityDependentResistance

float32

linear: forces/length; others: torques/deg

0.0

resolved USD value (authored, else raw fallback)

0.0

No slope on the maximum-effort line (constant maxForce over speed).

physxDrivePerformanceEnvelope:<inst>:speedEffortGradient

float32

linear: length/s per force; others: deg/s per torque (deg_to_rad)

0.0

resolved USD value (authored, else raw fallback)

0.0

No back-EMF term (maximum velocity independent of effort).

Interactions#

  • PhysicsDriveAPI: Read only when the matching PhysicsDriveAPI: drive exists; applying the envelope sets drive.isEnvelopeUsed and the runtime then builds PxArticulationDrive with a PxPerformanceEnvelope whose maxEffort is the drive’s maxForce.

  • 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 and the plain drive is kept.

Known divergences#

  • note (consumer) physxDrivePerformanceEnvelope:<inst>:maxActuatorVelocity: The rotational branch is instance != linear, so angular, rotX, rotY, rotZ and any unrecognised instance name receive the degrees-to-radians conversions. Unlike PhysxJointAxisAPI, whose conversions are selected explicitly per joint type, an unknown instance here is silently treated as rotational.

Notes#

  • Per-joint-type instance matrix: Fixed none; Revolute angular; Prismatic linear; Spherical none; Distance none; D6 (PhysicsJoint) rotX, rotY, rotZ only, translational D6 drives skip the envelope entirely; Gear, Rack, Custom none.

  • Articulation axis mapping: angular/rotX -> PxArticulationAxis::eTWIST, rotY -> eSWING1, rotZ -> eSWING2, linear -> eX.