Physics Joint Prims#

PhysicsJoint Prims define constraints which reduce the degrees of freedom between two bodies.

The PhysicsJoint prims can be thought of as existing in two places at once: relative to each body that they constrain. Properly defining PhysicsJoints relative to both bodies can be arduous, especially given differences in source data specification across maximal coordinate (free-body) and reduced coordinate solvers.

This module simplifies the authoring process and ensures PhysicsJoints are aligned to both bodies, regardless of the source data specification.

Classes#

usdex::core::JointFrame

Specifies a position and rotation in the coordinate system specified by space

Functions#

void usdex::core::alignPhysicsJoint(pxr::UsdPhysicsJoint joint, const JointFrame &frame, const pxr::GfVec3f &axis=pxr::GfVec3f(1.0f, 0.0f, 0.0f))

Aligns an existing joint with the specified position, rotation, and axis.

pxr::UsdPhysicsFixedJoint usdex::core::definePhysicsFixedJoint(pxr::UsdPrim prim, const pxr::UsdPrim &body0, const pxr::UsdPrim &body1, const JointFrame &frame)

Creates a fixed joint connecting two rigid bodies.

pxr::UsdPhysicsFixedJoint usdex::core::definePhysicsFixedJoint(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::UsdPrim &body0, const pxr::UsdPrim &body1, const JointFrame &frame)

Creates a fixed joint connecting two rigid bodies.

pxr::UsdPhysicsFixedJoint usdex::core::definePhysicsFixedJoint(pxr::UsdPrim parent, const std::string &name, const pxr::UsdPrim &body0, const pxr::UsdPrim &body1, const JointFrame &frame)

Creates a fixed joint connecting two rigid bodies.

pxr::UsdPhysicsPrismaticJoint usdex::core::definePhysicsPrismaticJoint(pxr::UsdPrim parent, const std::string &name, const pxr::UsdPrim &body0, const pxr::UsdPrim &body1, const JointFrame &frame, const pxr::GfVec3f &axis=pxr::GfVec3f(1.0f, 0.0f, 0.0f), std::optional< float > lowerLimit=std::nullopt, std::optional< float > upperLimit=std::nullopt)

Creates a prismatic joint, which acts as a slider along a single axis, connecting two rigid bodies.

pxr::UsdPhysicsPrismaticJoint usdex::core::definePhysicsPrismaticJoint(pxr::UsdPrim prim, const pxr::UsdPrim &body0, const pxr::UsdPrim &body1, const JointFrame &frame, const pxr::GfVec3f &axis=pxr::GfVec3f(1.0f, 0.0f, 0.0f), std::optional< float > lowerLimit=std::nullopt, std::optional< float > upperLimit=std::nullopt)

Creates a prismatic joint, which acts as a slider along a single axis, connecting two rigid bodies.

pxr::UsdPhysicsPrismaticJoint usdex::core::definePhysicsPrismaticJoint(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::UsdPrim &body0, const pxr::UsdPrim &body1, const JointFrame &frame, const pxr::GfVec3f &axis=pxr::GfVec3f(1.0f, 0.0f, 0.0f), std::optional< float > lowerLimit=std::nullopt, std::optional< float > upperLimit=std::nullopt)

Creates a prismatic joint, which acts as a slider along a single axis, connecting two rigid bodies.

pxr::UsdPhysicsRevoluteJoint usdex::core::definePhysicsRevoluteJoint(pxr::UsdPrim parent, const std::string &name, const pxr::UsdPrim &body0, const pxr::UsdPrim &body1, const JointFrame &frame, const pxr::GfVec3f &axis=pxr::GfVec3f(1.0f, 0.0f, 0.0f), std::optional< float > lowerLimit=std::nullopt, std::optional< float > upperLimit=std::nullopt)

Creates a revolute joint, which acts as a hinge around a single axis, connecting two rigid bodies.

pxr::UsdPhysicsRevoluteJoint usdex::core::definePhysicsRevoluteJoint(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::UsdPrim &body0, const pxr::UsdPrim &body1, const JointFrame &frame, const pxr::GfVec3f &axis=pxr::GfVec3f(1.0f, 0.0f, 0.0f), std::optional< float > lowerLimit=std::nullopt, std::optional< float > upperLimit=std::nullopt)

Creates a revolute joint, which acts as a hinge around a single axis, connecting two rigid bodies.

pxr::UsdPhysicsRevoluteJoint usdex::core::definePhysicsRevoluteJoint(pxr::UsdPrim prim, const pxr::UsdPrim &body0, const pxr::UsdPrim &body1, const JointFrame &frame, const pxr::GfVec3f &axis=pxr::GfVec3f(1.0f, 0.0f, 0.0f), std::optional< float > lowerLimit=std::nullopt, std::optional< float > upperLimit=std::nullopt)

Creates a revolute joint, which acts as a hinge around a single axis, connecting two rigid bodies.

pxr::UsdPhysicsSphericalJoint usdex::core::definePhysicsSphericalJoint(pxr::UsdPrim prim, const pxr::UsdPrim &body0, const pxr::UsdPrim &body1, const JointFrame &frame, const pxr::GfVec3f &axis=pxr::GfVec3f(1.0f, 0.0f, 0.0f), std::optional< float > coneAngle0Limit=std::nullopt, std::optional< float > coneAngle1Limit=std::nullopt)

Creates a spherical joint, which acts as a ball and socket joint, connecting two rigid bodies.

pxr::UsdPhysicsSphericalJoint usdex::core::definePhysicsSphericalJoint(pxr::UsdPrim parent, const std::string &name, const pxr::UsdPrim &body0, const pxr::UsdPrim &body1, const JointFrame &frame, const pxr::GfVec3f &axis=pxr::GfVec3f(1.0f, 0.0f, 0.0f), std::optional< float > coneAngle0Limit=std::nullopt, std::optional< float > coneAngle1Limit=std::nullopt)

Creates a spherical joint, which acts as a ball and socket joint, connecting two rigid bodies.

pxr::UsdPhysicsSphericalJoint usdex::core::definePhysicsSphericalJoint(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::UsdPrim &body0, const pxr::UsdPrim &body1, const JointFrame &frame, const pxr::GfVec3f &axis=pxr::GfVec3f(1.0f, 0.0f, 0.0f), std::optional< float > coneAngle0Limit=std::nullopt, std::optional< float > coneAngle1Limit=std::nullopt)

Creates a spherical joint, which acts as a ball and socket joint, connecting two rigid bodies.

Functions#

void usdex::core::alignPhysicsJoint(
pxr::UsdPhysicsJoint joint,
const JointFrame &frame,
const pxr::GfVec3f &axis = pxr::GfVec3f(1.0f, 0.0f, 0.0f),
)#

Aligns an existing joint with the specified position, rotation, and axis.

The Joint’s local position & orientation relative to each Body will be authored to align to the specified position, orientation, and axis.

The axis specifies the primary axis for rotation or translation, based on the local joint orientation relative to each body.

  • To rotate or translate about the X-axis, specify (1, 0, 0). To operate in the opposite direction, specify (-1, 0, 0).

  • To rotate or translate about about the Y-axis, specify (0, 1, 0). To operate in the opposite direction, specify (0, -1, 0).

  • To rotate or translate about about the Z-axis, specify (0, 0, 1). To operate in the opposite direction, specify (0, 0, -1).

  • Any other direction will be aligned to X-axis via a local rotation or translation for both bodies.

Parameters:

  • joint – The joint to align

  • frame – The position and rotation of the joint in the specified coordinate system.

  • axis – The axis of the joint.

pxr::UsdPhysicsFixedJoint usdex::core::definePhysicsFixedJoint(
pxr::UsdPrim prim,
const pxr::UsdPrim &body0,
const pxr::UsdPrim &body1,
const JointFrame &frame,
)#

Creates a fixed joint connecting two rigid bodies.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

  • prim – Prim to define the joint. The prim’s type will be set to UsdPhysicsFixedJoint.

  • body0 – The first body of the joint

  • body1 – The second body of the joint

  • frame – The position and rotation of the joint in the specified coordinate system.

Returns:

UsdPhysicsFixedJoint schema wrapping the defined UsdPrim

pxr::UsdPhysicsFixedJoint usdex::core::definePhysicsFixedJoint(
pxr::UsdStagePtr stage,
const pxr::SdfPath &path,
const pxr::UsdPrim &body0,
const pxr::UsdPrim &body1,
const JointFrame &frame,
)#

Creates a fixed joint connecting two rigid bodies.

A fixed joint connects two prims making them effectively welded together. For maximal coordinate (free-body) solvers it is important to fully constrain the two bodies. For reduced coordinate solvers this is may seem redundant, but it is important for consistency & cross-solver portability.

Using the coordinate system specified by the jointFrame, the local position and rotation corresponding to body0 and body1 of the joint are automatically calculated.

Parameters:

  • stage – The stage on which to define the joint

  • path – The absolute prim path at which to define the joint

  • body0 – The first body of the joint

  • body1 – The second body of the joint

  • frame – The position and rotation of the joint in the specified coordinate system.

Returns:

UsdPhysicsFixedJoint schema wrapping the defined UsdPrim

pxr::UsdPhysicsFixedJoint usdex::core::definePhysicsFixedJoint(
pxr::UsdPrim parent,
const std::string &name,
const pxr::UsdPrim &body0,
const pxr::UsdPrim &body1,
const JointFrame &frame,
)#

Creates a fixed joint connecting two rigid bodies.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

  • parent – Prim below which to define the physics joint

  • name – Name of the physics joint

  • body0 – The first body of the joint

  • body1 – The second body of the joint

  • frame – The position and rotation of the joint in the specified coordinate system.

Returns:

UsdPhysicsFixedJoint schema wrapping the defined UsdPrim

pxr::UsdPhysicsPrismaticJoint usdex::core::definePhysicsPrismaticJoint(
pxr::UsdPrim parent,
const std::string &name,
const pxr::UsdPrim &body0,
const pxr::UsdPrim &body1,
const JointFrame &frame,
const pxr::GfVec3f &axis = pxr::GfVec3f(1.0f, 0.0f, 0.0f),
std::optional<float> lowerLimit = std::nullopt,
std::optional<float> upperLimit = std::nullopt,
)#

Creates a prismatic joint, which acts as a slider along a single axis, connecting two rigid bodies.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

  • parent – Prim below which to define the physics joint

  • name – Name of the physics joint

  • body0 – The first body of the joint

  • body1 – The second body of the joint

  • frame – The position and rotation of the joint in the specified coordinate system.

  • axis – The axis of the joint.

  • lowerLimit – The lower limit of the joint (distance).

  • upperLimit – The upper limit of the joint (distance).

Returns:

UsdPhysicsPrismaticJoint schema wrapping the defined UsdPrim

pxr::UsdPhysicsPrismaticJoint usdex::core::definePhysicsPrismaticJoint(
pxr::UsdPrim prim,
const pxr::UsdPrim &body0,
const pxr::UsdPrim &body1,
const JointFrame &frame,
const pxr::GfVec3f &axis = pxr::GfVec3f(1.0f, 0.0f, 0.0f),
std::optional<float> lowerLimit = std::nullopt,
std::optional<float> upperLimit = std::nullopt,
)#

Creates a prismatic joint, which acts as a slider along a single axis, connecting two rigid bodies.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

  • prim – Prim to define the joint. The prim’s type will be set to UsdPhysicsPrismaticJoint.

  • body0 – The first body of the joint

  • body1 – The second body of the joint

  • frame – The position and rotation of the joint in the specified coordinate system.

  • axis – The axis of the joint.

  • lowerLimit – The lower limit of the joint (distance).

  • upperLimit – The upper limit of the joint (distance).

Returns:

UsdPhysicsPrismaticJoint schema wrapping the defined UsdPrim

pxr::UsdPhysicsPrismaticJoint usdex::core::definePhysicsPrismaticJoint(
pxr::UsdStagePtr stage,
const pxr::SdfPath &path,
const pxr::UsdPrim &body0,
const pxr::UsdPrim &body1,
const JointFrame &frame,
const pxr::GfVec3f &axis = pxr::GfVec3f(1.0f, 0.0f, 0.0f),
std::optional<float> lowerLimit = std::nullopt,
std::optional<float> upperLimit = std::nullopt,
)#

Creates a prismatic joint, which acts as a slider along a single axis, connecting two rigid bodies.

Using the coordinate system specified by the jointFrame, the local position and rotation corresponding to body0 and body1 of the joint are automatically calculated.

The axis specifies the primary axis for rotation, based on the local joint orientation relative to each body.

  • To slide along the X-axis, specify (1, 0, 0). To slide in the opposite direction, specify (-1, 0, 0).

  • To slide along the Y-axis, specify (0, 1, 0). To slide in the opposite direction, specify (0, -1, 0).

  • To slide along the Z-axis, specify (0, 0, 1). To slide in the opposite direction, specify (0, 0, -1).

  • Any other direction will be aligned to X-axis via a local rotation for both bodies.

The lowerLimit and upperLimit are specified as distance along the axis in linear units of the stage.

Parameters:

  • stage – The stage on which to define the joint

  • path – The absolute prim path at which to define the joint

  • body0 – The first body of the joint

  • body1 – The second body of the joint

  • frame – The position and rotation of the joint in the specified coordinate system.

  • axis – The axis of the joint.

  • lowerLimit – The lower limit of the joint (distance).

  • upperLimit – The upper limit of the joint (distance).

Returns:

UsdPhysicsPrismaticJoint schema wrapping the defined UsdPrim

pxr::UsdPhysicsRevoluteJoint usdex::core::definePhysicsRevoluteJoint(
pxr::UsdPrim parent,
const std::string &name,
const pxr::UsdPrim &body0,
const pxr::UsdPrim &body1,
const JointFrame &frame,
const pxr::GfVec3f &axis = pxr::GfVec3f(1.0f, 0.0f, 0.0f),
std::optional<float> lowerLimit = std::nullopt,
std::optional<float> upperLimit = std::nullopt,
)#

Creates a revolute joint, which acts as a hinge around a single axis, connecting two rigid bodies.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

  • parent – Prim below which to define the physics joint

  • name – Name of the physics joint

  • body0 – The first body of the joint

  • body1 – The second body of the joint

  • frame – The position and rotation of the joint in the specified coordinate system.

  • axis – The axis of rotation

  • lowerLimit – The lower limit of the joint (degrees).

  • upperLimit – The upper limit of the joint (degrees).

Returns:

UsdPhysicsRevoluteJoint schema wrapping the defined UsdPrim

pxr::UsdPhysicsRevoluteJoint usdex::core::definePhysicsRevoluteJoint(
pxr::UsdStagePtr stage,
const pxr::SdfPath &path,
const pxr::UsdPrim &body0,
const pxr::UsdPrim &body1,
const JointFrame &frame,
const pxr::GfVec3f &axis = pxr::GfVec3f(1.0f, 0.0f, 0.0f),
std::optional<float> lowerLimit = std::nullopt,
std::optional<float> upperLimit = std::nullopt,
)#

Creates a revolute joint, which acts as a hinge around a single axis, connecting two rigid bodies.

Using the coordinate system specified by the jointFrame, the local position and rotation corresponding to body0 and body1 of the joint are automatically calculated.

The axis specifies the primary axis for rotation, based on the local joint orientation relative to each body.

  • To rotate around the X-axis, specify (1, 0, 0). To rotate in the opposite direction, specify (-1, 0, 0).

  • To rotate around the Y-axis, specify (0, 1, 0). To rotate in the opposite direction, specify (0, -1, 0).

  • To rotate around the Z-axis, specify (0, 0, 1). To rotate in the opposite direction, specify (0, 0, -1).

  • Any other direction will be aligned to X-axis via a local rotation for both bodies.

Parameters:

  • stage – The stage on which to define the joint

  • path – The absolute prim path at which to define the joint

  • body0 – The first body of the joint

  • body1 – The second body of the joint

  • frame – The position and rotation of the joint in the specified coordinate system.

  • axis – The axis of rotation

  • lowerLimit – The lower limit of the joint (degrees).

  • upperLimit – The upper limit of the joint (degrees).

Returns:

UsdPhysicsRevoluteJoint schema wrapping the defined UsdPrim

pxr::UsdPhysicsRevoluteJoint usdex::core::definePhysicsRevoluteJoint(
pxr::UsdPrim prim,
const pxr::UsdPrim &body0,
const pxr::UsdPrim &body1,
const JointFrame &frame,
const pxr::GfVec3f &axis = pxr::GfVec3f(1.0f, 0.0f, 0.0f),
std::optional<float> lowerLimit = std::nullopt,
std::optional<float> upperLimit = std::nullopt,
)#

Creates a revolute joint, which acts as a hinge around a single axis, connecting two rigid bodies.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

  • prim – Prim to define the joint. The prim’s type will be set to UsdPhysicsRevoluteJoint.

  • body0 – The first body of the joint

  • body1 – The second body of the joint

  • frame – The position and rotation of the joint in the specified coordinate system.

  • axis – The axis of rotation

  • lowerLimit – The lower limit of the joint (degrees).

  • upperLimit – The upper limit of the joint (degrees).

Returns:

UsdPhysicsRevoluteJoint schema wrapping the defined UsdPrim

pxr::UsdPhysicsSphericalJoint usdex::core::definePhysicsSphericalJoint(
pxr::UsdPrim prim,
const pxr::UsdPrim &body0,
const pxr::UsdPrim &body1,
const JointFrame &frame,
const pxr::GfVec3f &axis = pxr::GfVec3f(1.0f, 0.0f, 0.0f),
std::optional<float> coneAngle0Limit = std::nullopt,
std::optional<float> coneAngle1Limit = std::nullopt,
)#

Creates a spherical joint, which acts as a ball and socket joint, connecting two rigid bodies.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

  • prim – Prim to define the joint. The prim’s type will be set to UsdPhysicsSphericalJoint.

  • body0 – The first body of the joint

  • body1 – The second body of the joint

  • frame – The position and rotation of the joint in the specified coordinate system.

  • axis – The axis of the joint.

  • coneAngle0Limit – The lower limit of the cone angle (degrees).

  • coneAngle1Limit – The upper limit of the cone angle (degrees).

Returns:

UsdPhysicsSphericalJoint schema wrapping the defined UsdPrim

pxr::UsdPhysicsSphericalJoint usdex::core::definePhysicsSphericalJoint(
pxr::UsdPrim parent,
const std::string &name,
const pxr::UsdPrim &body0,
const pxr::UsdPrim &body1,
const JointFrame &frame,
const pxr::GfVec3f &axis = pxr::GfVec3f(1.0f, 0.0f, 0.0f),
std::optional<float> coneAngle0Limit = std::nullopt,
std::optional<float> coneAngle1Limit = std::nullopt,
)#

Creates a spherical joint, which acts as a ball and socket joint, connecting two rigid bodies.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

  • parent – Prim below which to define the physics joint

  • name – Name of the physics joint

  • body0 – The first body of the joint

  • body1 – The second body of the joint

  • frame – The position and rotation of the joint in the specified coordinate system.

  • axis – The axis of the joint.

  • coneAngle0Limit – The lower limit of the cone angle (degrees).

  • coneAngle1Limit – The upper limit of the cone angle (degrees).

Returns:

UsdPhysicsSphericalJoint schema wrapping the defined UsdPrim

pxr::UsdPhysicsSphericalJoint usdex::core::definePhysicsSphericalJoint(
pxr::UsdStagePtr stage,
const pxr::SdfPath &path,
const pxr::UsdPrim &body0,
const pxr::UsdPrim &body1,
const JointFrame &frame,
const pxr::GfVec3f &axis = pxr::GfVec3f(1.0f, 0.0f, 0.0f),
std::optional<float> coneAngle0Limit = std::nullopt,
std::optional<float> coneAngle1Limit = std::nullopt,
)#

Creates a spherical joint, which acts as a ball and socket joint, connecting two rigid bodies.

Using the coordinate system specified by the jointFrame, the local position and rotation corresponding to body0 and body1 of the joint are automatically calculated.

The axis specifies the primary axis for rotation, based on the local joint orientation relative to each body.

  • To rotate around the X-axis, specify (1, 0, 0). To rotate in the opposite direction, specify (-1, 0, 0).

  • To rotate around the Y-axis, specify (0, 1, 0). To rotate in the opposite direction, specify (0, -1, 0).

  • To rotate around the Z-axis, specify (0, 0, 1). To rotate in the opposite direction, specify (0, 0, -1).

  • Any other direction will be aligned to X-axis via a local rotation for both bodies.

For SphericalJoint, the axis specified here is used as the center, and the horizontal and vertical cone angles are limited by coneAngle0Limit and coneAngle1Limit.

Parameters:

  • stage – The stage on which to define the joint

  • path – The absolute prim path at which to define the joint

  • body0 – The first body of the joint

  • body1 – The second body of the joint

  • frame – The position and rotation of the joint in the specified coordinate system.

  • axis – The axis of the joint.

  • coneAngle0Limit – The lower limit of the cone angle (degrees).

  • coneAngle1Limit – The upper limit of the cone angle (degrees).

Returns:

UsdPhysicsSphericalJoint schema wrapping the defined UsdPrim