Physx Joint Schema

The Physx joint schemas are defined in the PhysX Schema Addition and provide:

• Additional parameters for the simulation in PhysX

• Per-axis control of joint properties

• Parameters to model actuator performance characteristics

PhysxJointAxisAPI

PhysxJointAxisAPI is a multiple-apply API schema that provides PhysX-specific joint parameters defined per axis. It can be applied to a UsdPhysics.Joint prim or the derived classes UsdPhysics.RevoluteJoint, UsdPhysics.PrismaticJoint, or UsdPhysics.SphericalJoint. For overlapping parameters with PhysxJointAPI, the parameters of PhysxJointAxisAPI take precedence for that axis.

Note

Parameters in this API only apply to joints that are part of an articulation (see UsdPhysics.ArticulationRootAPI).

class "PhysxJointAxisAPI"
(
    inherits = </APISchemaBase>
    customData = {
        token apiSchemaType = "multipleApply"
        token propertyNamespacePrefix = "physxJointAxis"
    }
)
{
    float physxJointAxis:__INSTANCE_NAME__:armature = 0 ()
    float physxJointAxis:__INSTANCE_NAME__:dynamicFrictionEffort = 0 ()
    float physxJointAxis:__INSTANCE_NAME__:maxJointVelocity = 1000000 ()
    float physxJointAxis:__INSTANCE_NAME__:staticFrictionEffort = 0 ()
    float physxJointAxis:__INSTANCE_NAME__:viscousFrictionCoefficient = 0 ()
}

• armature: Conceptually, armature represents the inertia of an actuator driving the joint. It is an artificial mass/inertia that is added to the joint-space inertia and can help stabilize an articulation. Note that this parameter is used only when the joint belongs to an articulation (see UsdPhysics.ArticulationRootAPI). Valid range: [0, inf). Units: Linear joint - mass; Angular joint - mass * distance^2.

• dynamicFrictionEffort: Coulomb friction force or torque applied to resist motion in moving joints. Only applies to joints that are part of an articulation (see UsdPhysics.ArticulationRootAPI). Should be less than or equal to staticFrictionEffort. Valid range: [0, inf). Units: Linear joint - force (mass * distance / second^2); Angular joint - torque (mass * distance^2 / second^2).

• maxJointVelocity: Maximum joint velocity. Only applies to joints that are part of an articulation (see UsdPhysics.ArticulationRootAPI). The solver will apply appropriate joint-space impulses in order to enforce the per-axis joint-velocity limit. Valid range: [0, inf). Units: Linear joint - distance / seconds; Angular joint - degrees / seconds.

• staticFrictionEffort: Maximum static friction force or torque applied to resist motion in stationary joints. Only applies to joints that are part of an articulation (see UsdPhysics.ArticulationRootAPI). Prevents motion initiation until the applied force exceeds this threshold. Valid range: [0, inf). Units: Linear joint - force (mass * distance / second^2); Angular joint - torque (mass * distance^2 / second^2).

• viscousFrictionCoefficient: Coefficient used to calculate velocity-dependent friction effort. Only applies to joints that are part of an articulation (see UsdPhysics.ArticulationRootAPI). Total friction effort in moving joints = -sign(jointVelocity) * (dynamicFrictionEffort + viscousFrictionCoefficient * abs(jointVelocity)). Valid range: [0, inf). Units: Linear joint - force * second / distance; Angular joint - torque * second / degrees.

PhysxDrivePerformanceEnvelopeAPI

PhysxDrivePerformanceEnvelopeAPI is a multiple-apply API schema that defines performance envelope parameters for joint drives. It can be applied to a UsdPhysics.Joint prim or the derived classes UsdPhysics.RevoluteJoint and UsdPhysics.PrismaticJoint (similar to UsdPhysics.DriveAPI).

For the PhysxDrivePerformanceEnvelopeAPI to take effect, the UsdPhysics.DriveAPI must also be defined for the same axis. This is because the maxForce parameter of the UsdPhysics.DriveAPI is utilized by the PhysxDrivePerformanceEnvelopeAPI.

This API defines characteristics that limit the total joint force (drive force + external cached joint force) and provides a static model that constrains the behavior of an articulated joint based on actuator performance characteristics.

class "PhysxDrivePerformanceEnvelopeAPI"
(
    inherits = </APISchemaBase>
    customData = {
        token apiSchemaType = "multipleApply"
        token propertyNamespacePrefix = "physxDrivePerformanceEnvelope"
    }
)
{
    float physxDrivePerformanceEnvelope:__INSTANCE_NAME__:maxActuatorVelocity = inf ()
    float physxDrivePerformanceEnvelope:__INSTANCE_NAME__:speedEffortGradient = 0 ()
    float physxDrivePerformanceEnvelope:__INSTANCE_NAME__:velocityDependentResistance = 0 ()
}

• maxActuatorVelocity: Defines speed limit above which actuator cannot produce any torque/force. Valid range: [0, inf). Units: Linear joint - distance / second; Angular joint - degrees / second.

• speedEffortGradient: Defines how the maximum joint speed decreases as torque increases according to the constraint: |jointVelocity| <= maxActuatorVelocity - speedEffortGradient * |jointForce|. It incorporates back EMF (electromotive force) effects of the motor. Valid range: [0, inf). Units: Linear joint - distance / second / force; Angular joint - degrees / second / torque.

• velocityDependentResistance: Defines a slope of the maxForce line of the performance envelope: |F| <= maxForce - velocityDependentResistance * |jointVelocity|. The available max force/torque decreases as velocity magnitude increases due to the effect of the power losses of the motor. MaxForce parameter is defined in UsdPhysics.DriveAPI. Valid range: [0, inf). Units: Linear joint - force * second / distance; Angular joint - torque * second / degrees.