Rigid Bodies#

Create and Destroy a Rigid Body#

A rigid body may be created by applying UsdPhysics.RigidBodyAPI to a prim of type UsdGeom.Xformable. The following Python snippet demonstrates the creation and destruction of a rigid body:

from pxr import Usd, UsdGeom, UsdPhysics, Gf
import omni.usd

# Create a stage
omni.usd.get_context().new_stage()
stage = omni.usd.get_context().get_stage()

# Define the root Xform (transformable object)
rootxform = UsdGeom.Xform.Define(stage, "/World")

# Create an xformable
rigidBodyPath = "/World/rigidBody"
rigidBodyXform = UsdGeom.Xform.Define(stage, rigidBodyPath)
rigidBodyPrim = rigidBodyXform.GetPrim()

# Apply RigidBodyAPI to the xformable
rigidBodyAPI = UsdPhysics.RigidBodyAPI.Apply(rigidBodyPrim)

# Remove the rigid body
stage.RemovePrim(rigidBodyPath)

Kinematic Rigid Body#

Rigid bodies can be configured in two ways:

• By default rigid bodies are created as dynamic objects that are moved by the simulation. Their velocity is the product of forces and constraints integrated over time.

• Alternatively rigid bodies can be configured to act as kinematic objects, in which case their motion is directly controlled by the application.

Another way to think about dynamic vs. kinematic rigid bodies is in terms of transform read/write access by the simulation engine:

• a dynamic rigid body has its transform written to by the simulation.

• a kinematic rigid body’s transform is read by the simulation.

The following code snippet demonstrates how a rigid body can be created and, optionally, configured as kinematic object:

from pxr import Usd, UsdGeom, UsdPhysics, Gf
import omni.usd

# Create a stage
omni.usd.get_context().new_stage()
stage  = omni.usd.get_context().get_stage()

# Define the root Xform (transformable object)
rootxform = UsdGeom.Xform.Define(stage, "/World")

rigidBodyPaths = ["/World/rigidBody0", "/World/rigidBody1"]
enableKinematic = [False, True]

for i in range(2):
    rigidBodyXform = UsdGeom.Xform.Define(stage, rigidBodyPaths[i])
    rigidBodyPrim = rigidBodyXform.GetPrim()
    rigidBodyAPI = UsdPhysics.RigidBodyAPI.Apply(rigidBodyPrim)
    if enableKinematic[i]:
        rigidBodyAPI.CreateKinematicEnabledAttr(True)
    isKinematic = rigidBodyAPI.GetKinematicEnabledAttr().Get()
    print(f"i = {i}: Kinematic enabled is {isKinematic}")

Disabling a Rigid Body#

All prims in the sub-tree of a rigid body prim translate and rotate rigidly with the motion of the rigid body, following the rules of the transform hierarchy. This includes colliders on or below the rigid body prim. Disabling a rigid body by setting its rigidBodyEnabled attribute to False cancels any effect of the UsdPhysics.RigidBodyAPI. As a result any colliders in the sub-tree act as static colliders.

The following Python script demonstrates how a rigid body can be created and then disabled:

from pxr import Usd, UsdGeom, UsdPhysics, Gf
import omni.usd

# Create a stage
omni.usd.get_context().new_stage()
stage  = omni.usd.get_context().get_stage()

# Define the root Xform (transformable object)
rootxform = UsdGeom.Xform.Define(stage, "/World")

rigidBodyPath = "/World/rigidBody"

rigidBodyXform = UsdGeom.Xform.Define(stage, rigidBodyPath)
rigidBodyPrim = rigidBodyXform.GetPrim()
rigidBodyAPI = UsdPhysics.RigidBodyAPI.Apply(rigidBodyPrim)
rigidBodyAPI.GetRigidBodyEnabledAttr().Set(False)

Rigid Body Frames#

Rigid body setups have multiple associated coordinate frames. These are referred to here as:

• rigid-body-prim frame

• center of mass frame (see section Configure Rigid Body Mass Properties)

• collider frames (see section Create a Rigid Body with a Collider)

• joint local frames (see section Joint Frames)

• velocity frames (see section Set Rigid Body Velocity)

• force frames (see section Apply Force to a Rigid Body)

The rigid body may be considered as a container of sub-frames. Internally, simulation proceeds with reference to the center of mass. The introduction of the concept of the rigid-body-prim frame, however, provides a common reference for joints and colliders. This allows, for example, the center of mass to be modified without impacting joint or collider frames defined relatively to the rigid-body-prim frame.

The rigid-body-prim frame describes the pose of the prim with the UsdPhysics.RigidBodyAPI relative to the origin of the world coordinate frame. The center of mass frame, on the other hand, is specified relative to the rigid body frame. The position and orientation of the center of mass frame in the world coordinate frame is therefore a function of the rigid body pose in the world frame and the center of mass pose in the rigid body frame. Collider and joint local frames are similarly specified in the frame of an associated rigid body.

Create a Rigid Body with a Collider#

This section introduces the creation of rigid bodies with colliders, which allows them to collide with other objects in the scene.

Static colliders are discussed in section Create and Destroy a Static Collider.

Collider prims are associated with rigid body prims by their relative location in the USD stage hierarchy. A collider in the sub-tree of a rigid body prim is part of that rigid body and can be posed relative to the rigid body transformation frame employing the USD transformation hierarchy.

The following Python script illustrates the creation of a rigid body with cube collision geometry:

from pxr import Usd, UsdGeom, UsdPhysics, Gf
import omni.usd

# Create a stage
omni.usd.get_context().new_stage()
stage  = omni.usd.get_context().get_stage()

# Define the root Xform (transformable object)
rootxform = UsdGeom.Xform.Define(stage, "/World")

rigidBodyPath = "/World/rigidBody"
cubePath = rigidBodyPath + "/cube"

# Properties of the geometry
cubePosition = Gf.Vec3f(2.0, 0.0, 0.0)
cubeOrientation = Gf.Quatf(1.0)
cubeScale = Gf.Vec3f(1.0, 1.0, 1.0)
cubeSize = 2.0
cubeHalfExtent = cubeSize/2.0

# Create a rigid body
rigidBodyXform = UsdGeom.Xform.Define(stage, rigidBodyPath)
rigidBodyXform.AddTranslateOp().Set(Gf.Vec3f(0.0))
rigidBodyXform.AddOrientOp().Set(Gf.Quatf(1.0))
rigidBodyPrim = rigidBodyXform.GetPrim()
UsdPhysics.RigidBodyAPI.Apply(rigidBodyPrim)

# Create the cube as a child of the rigid body prim
cubeGeom = UsdGeom.Cube.Define(stage, cubePath)
cubeGeom.CreateSizeAttr(cubeSize)
cubeGeom.CreateExtentAttr([Gf.Vec3f(-cubeHalfExtent), Gf.Vec3f(cubeHalfExtent)])
cubeGeom.AddTranslateOp().Set(cubePosition)
cubeGeom.AddOrientOp().Set(cubeOrientation)
cubeGeom.AddScaleOp().Set(cubeScale)
cubePrim = cubeGeom.GetPrim()
UsdPhysics.CollisionAPI.Apply(cubePrim)

The cube collider in the snippet is created as a child of the rigid body. As a result, the pose assigned to the collider prim is represented relative to the rigid body frame, as discussed in section Rigid Body Frames.

Configure a Rigid Body with multiple Colliders#

The previous script example can be extended to create a rigid body with multiple colliders. The following script demonstrates a rigid body with two cube colliders, each centered at a different position relative to the parent:

from pxr import Usd, UsdGeom, UsdPhysics, Gf
import omni.usd

# Create a stage
omni.usd.get_context().new_stage()
stage  = omni.usd.get_context().get_stage()

# Define the root Xform (transformable object)
rootxform = UsdGeom.Xform.Define(stage, "/World")

rigidBodyPath = "/World/rigidBody"
cubePaths = [rigidBodyPath + "/cube0", rigidBodyPath + "/cube1"]
cubePositions = [Gf.Vec3f(-2.0, 0.0, 0.0), Gf.Vec3f(2.0, 0.0, 0.0)]
cubeOrientation = Gf.Quatf(1.0)
cubeScale = Gf.Vec3f(1.0, 1.0, 1.0)
cubeSize = 2.0
cubeHalfExtent = cubeSize/2.0

# Create the rigid body
rigidBody = UsdGeom.Xform.Define(stage, rigidBodyPath)
rigidBody.AddTranslateOp().Set(Gf.Vec3f(0.0))
rigidBody.AddOrientOp().Set(Gf.Quatf(1.0))
rigidBodyPrim = rigidBody.GetPrim()
UsdPhysics.RigidBodyAPI.Apply(rigidBodyPrim)

for i in range(2):

    # Create the cube as a child of the rigid body prim
    cubeGeom = UsdGeom.Cube.Define(stage, cubePaths[i])
    cubeGeom.CreateSizeAttr(cubeSize)
    cubeGeom.CreateExtentAttr([Gf.Vec3f(-cubeHalfExtent), Gf.Vec3f(cubeHalfExtent)])
    cubeGeom.AddTranslateOp().Set(cubePositions[i])
    cubeGeom.AddOrientOp().Set(cubeOrientation)
    cubeGeom.AddScaleOp().Set(cubeScale)
    cubePrim = cubeGeom.GetPrim()
    UsdPhysics.CollisionAPI.Apply(cubePrim)

In the above example, cube0 is positioned at (-2, 0, 0), while cube1 is positioned at (2, 0, 0)

Configure Rigid Body’s Material Properties#

UsdPhysics.MaterialAPI can be used to create physics material properties (static friction, dynamic friction, restitution, and density) when applied to a material prim. The density attribute is discussed in more detail in section Automatic Computation of Rigid Body Mass Distribution.

The following snippet illustrates binding a material to a rigid actor using UsdShade.MaterialBindingAPI with a “physics” purpose:

from pxr import Usd, UsdGeom, UsdShade, UsdPhysics, Gf
import omni.usd

# Create a stage
omni.usd.get_context().new_stage()
stage  = omni.usd.get_context().get_stage()

# Define the root Xform (transformable object)
rootxform = UsdGeom.Xform.Define(stage, "/World")

rigidBodyPath = "/World/rigidBody"
cubePath = rigidBodyPath + "/cube"
materialPath = "/path/to/material"

# Properties of the geometry
cubePosition = Gf.Vec3f(2.0, 0.0, 0.0)
cubeOrientation = Gf.Quatf(1.0)
cubeScale = Gf.Vec3f(1.0, 1.0, 1.0)
cubeSize = 2.0
cubeHalfExtent = cubeSize/2.0

# Create a rigid body
rigidBodyXform = UsdGeom.Xform.Define(stage, rigidBodyPath)
rigidBodyXform.AddTranslateOp().Set(Gf.Vec3f(0.0))
rigidBodyXform.AddOrientOp().Set(Gf.Quatf(1.0))
rigidBodyPrim = rigidBodyXform.GetPrim()
UsdPhysics.RigidBodyAPI.Apply(rigidBodyPrim)

# Create the cube as a child of the rigid body prim
cubeGeom = UsdGeom.Cube.Define(stage, cubePath)
cubeGeom.CreateSizeAttr(cubeSize)
cubeGeom.CreateExtentAttr([Gf.Vec3f(-cubeHalfExtent), Gf.Vec3f(cubeHalfExtent)])
cubeGeom.AddTranslateOp().Set(cubePosition)
cubeGeom.AddOrientOp().Set(cubeOrientation)
cubeGeom.AddScaleOp().Set(cubeScale)
cubePrim = cubeGeom.GetPrim()
UsdPhysics.CollisionAPI.Apply(cubePrim)

# Create a material
material = UsdShade.Material.Define(stage, materialPath)
materialPrim = material.GetPrim()
materialAPI = UsdPhysics.MaterialAPI.Apply(materialPrim)
materialAPI.CreateStaticFrictionAttr(1.0)
materialAPI.CreateDynamicFrictionAttr(0.9)
materialAPI.CreateRestitutionAttr(0.8)

# Bind the rigid body and the material
bindingAPI = UsdShade.MaterialBindingAPI.Apply(rigidBodyPrim)
shadeMaterial = UsdShade.Material(materialPrim)
bindingAPI.Bind(shadeMaterial, UsdShade.Tokens.weakerThanDescendants, "physics")

Physics materials follow the same resolution logic based on binding strength as render materials, as they are both based on the same material prim type.

Configure Rigid Body Mass Properties#

Rigid bodies have mass distribution properties defined by mass, center of mass, moment of inertia, and principal axes. The Python snippets so far don’t set any mass properties; therefore a uniform density across all collider volumes is assumed by default. This section describes how the mass distribution properties can be configured explicitly or how they are inferred implicitly.

from pxr import Usd, UsdGeom, UsdPhysics, Gf
import omni.usd

# Create a stage
omni.usd.get_context().new_stage()
stage  = omni.usd.get_context().get_stage()

# Define the root Xform (transformable object)
rootxform = UsdGeom.Xform.Define(stage, "/World")

rigidBodyPath = "/World/rigidBody"

# Mass properties of the rigid body
rigidBodyMass = 3.0
rigidBodyMomentOfInertia = Gf.Vec3f(2.0, 2.0, 2.0)
rigidBodyCenterOfMass = Gf.Vec3f(0.0, 3.0, 0.0)
rigidBodyPrincipalAxes = Gf.Quatf(Gf.Rotation(Gf.Vec3d(0.0, 0.0, 1.0), 90.0).GetQuat())

# Create a rigid body and set the mass distribution properties
rigidBodyXform = UsdGeom.Xform.Define(stage, rigidBodyPath)
rigidBodyXform.AddTranslateOp().Set(Gf.Vec3f(0.0))
rigidBodyXform.AddOrientOp().Set(Gf.Quatf(1.0))
rigidBodyPrim = rigidBodyXform.GetPrim()
UsdPhysics.RigidBodyAPI.Apply(rigidBodyPrim)
massAPI = UsdPhysics.MassAPI.Apply(rigidBodyPrim)
massAPI.CreateMassAttr(rigidBodyMass)
massAPI.CreateDiagonalInertiaAttr(rigidBodyMomentOfInertia)
massAPI.CreateCenterOfMassAttr(rigidBodyCenterOfMass)
massAPI.CreatePrincipalAxesAttr(rigidBodyPrincipalAxes)

MassAPI:mass > MassAPI:density > MaterialAPI:density > default density
MassAPI:centerOfMass > MassAPI:density > MaterialAPI:density > default density
MassAPI:momentOfInertia > MassAPI:density > MaterialAPI:density > default density

Configure Continuous Collision Detection on a Rigid Body#

It is recommended to enable CCD (continuous collision detection) if fast-moving or thin objects are tunneling; that is, contacts are missed due to the discretized advancement of simulation time. Two forms of CCD are supported:

• Sweep-based CCD, also known as “linear CCD”. This form of CCD linearly sweeps the motion of objects over the duration of the simulation timestep to find collisions that would otherwise have been missed by discrete collision tests at the start or end of the timestep. This is called “linear CCD” because the angular motions of objects are ignored. For example this system would prevent a small object from going through a wall, but it would not catch collisions between small obstacles and the blades of a quickly rotating fan (as the linear motion of the fan is zero).

• Speculative CCD, also known as “angular CCD”. This cheaper approach operates entirely as part of the discrete simulation. It computes dynamic contact offsets based on object motions and relies on the constraint solver to ensure that objects do not tunnel through each-other. Contrary to the sweep-based CCD, speculative CCD can catch missed contacts generated by fast angular motions. It also handles linear motions and fixes most tunnelling problem. On the other hand it can introduce ghost collisions when large linear motions are involved.

It is possible to enable both sweep-based CCD and speculative CCD at the same time on a given rigid body. This hybrid CCD mode often results in a best-of-both-worlds behavior, enabling both accurate linear CCD and angular CCD on selected objects.

To enable sweep-based CCD:

• Enable the corresponding attribute on the scene by applying PhysxSchema.PhysxSceneAPI.

• CCD may then be judiciously applied to individual rigid bodies in the scene by applying UsdPhysics.RigidBodyAPI and enabling the corresponding CCD attribute.

To enable speculative CCD:

• No PhysxSchema.PhysxSceneAPI properties need to be set.

• If using the hybrid mode (where both sweep-based and speculative CCD are enabled) it is important to apply that scene-level schema. Without it the linear CCD is deactivated in the speculative CCD system, but not enabled yet in the sweep-based system - and as a result, linear CCD is effectively disabled.

The following snippet enables sweep-based CCD on the scene and on a rigid body:

from pxr import Usd, UsdGeom, UsdPhysics, Gf, PhysxSchema
import omni.usd

# Create a stage
omni.usd.get_context().new_stage()
stage  = omni.usd.get_context().get_stage()

# Define the root Xform (transformable object)
rootxform = UsdGeom.Xform.Define(stage, "/World")

# Enable CCD on the scene
defaultPrimPath = str(stage.GetDefaultPrim().GetPath())
physicsScenePath = defaultPrimPath + "/physicsScene"
physicsScene = UsdPhysics.Scene.Define(stage, physicsScenePath)
physicsScenePrim = physicsScene.GetPrim()
physxSceneAPI = PhysxSchema.PhysxSceneAPI.Apply(physicsScenePrim)
physxSceneAPI.CreateEnableCCDAttr(True)

rigidBodyPath = "/World/rigidBody"
cubePath = rigidBodyPath + "/cube"

# Properties of the geometry
cubePosition = Gf.Vec3f(2.0, 0.0, 0.0)
cubeOrientation = Gf.Quatf(1.0)
cubeScale = Gf.Vec3f(1.0, 1.0, 1.0)
cubeSize = 2.0
cubeHalfExtent = cubeSize/2.0

# Create a dynamic rigid body with default mass properties
rigidBodyXform = UsdGeom.Xform.Define(stage, rigidBodyPath)
rigidBodyXform.AddTranslateOp().Set(cubePosition)
rigidBodyXform.AddOrientOp().Set(cubeOrientation)
rigidBodyPrim = rigidBodyXform.GetPrim()
UsdPhysics.RigidBodyAPI.Apply(rigidBodyPrim)

# Create the cube as a child of the rigid body prim
cubeGeom = UsdGeom.Cube.Define(stage, cubePath)
cubeGeom.CreateSizeAttr(cubeSize)
cubeGeom.CreateExtentAttr([Gf.Vec3f(-cubeHalfExtent), Gf.Vec3f(cubeHalfExtent)])
cubeGeom.AddTranslateOp().Set(cubePosition)
cubeGeom.AddOrientOp().Set(cubeOrientation)
cubeGeom.AddScaleOp().Set(cubeScale)
cubePrim = cubeGeom.GetPrim()
UsdPhysics.CollisionAPI.Apply(cubePrim)

# Enable CCD on the rigid body prim
physxRbAPI = PhysxSchema.PhysxRigidBodyAPI.Apply(rigidBodyPrim)
physxRbAPI.CreateEnableCCDAttr(True)

Speculative CCD does not require the CCD attribute of PhysxSchema.PhysxSceneAPI to be raised. It is sufficient to simply enable the speculative CCD attribute on individual rigid bodies:

physxRbAPI = PhysxSchema.PhysxRigidBodyAPI.Apply(rigidBodyPrim)
physxRbAPI.CreateEnableSpeculativeCCDAttr(True)

In terms of performance, speculative CCD is usually cheaper, except in edge cases where, for example, a very fast object is moving against a highly tessellated mesh.

Set Rigid Body Velocity#

The linear and angular velocity may be set and queried by applying UsdPhysics.RigidBodyAPI and setting/querying the attributes associated with linear and angular velocity. To set the velocity a rigid body, the Python snippet in section Create a Rigid Body with a Collider be appended as follows:

linVel = Gf.Vec3f(1.0, 2.0, 3.0)
angVel = Gf.Vec3f(-30.0, -60.0, -90.0)
rigidBodyAPI = UsdPhysics.RigidBodyAPI.Apply(rigidBodyPrim)
rigidBodyAPI.CreateVelocityAttr(linVel)
rigidBodyAPI.CreateAngularVelocityAttr(angVel)

The linear and angular velocity may be queried with the following pattern:

newlinvel = rigidBodyAPI.GetVelocityAttr().Get()
newangvel = rigidBodyAPI.GetAngularVelocityAttr().Get()

Apply Force to a Rigid Body#

Forces and torques may be applied to dynamic rigid bodies by applying PhysxSchema.PhysxForceAPI and setting the associated force and torque attributes. The following Python snippet demonstrates the application of force and torque to a dynamic rigid body:

from pxr import Usd, UsdGeom, UsdPhysics, Gf, PhysxSchema
import omni.usd

# Create a stage
omni.usd.get_context().new_stage()
stage  = omni.usd.get_context().get_stage()

# Define the root Xform (transformable object)
rootxform = UsdGeom.Xform.Define(stage, "/World")

rigidBodyPath = "/World/rigidBody"

# Mass properties of the rigid body
rigidBodyMass = 3.0
rigidBodyMomentOfInertia = Gf.Vec3f(2.0, 3.0, 4.0)
rigidBodyCenterOfMass = Gf.Vec3f(0.0, 0.0, 0.0)
rigidBodyPrincipalAxes = Gf.Quatf(1.0)

# Create the rigid body
rigidBodyXform = UsdGeom.Xform.Define(stage, rigidBodyPath)
rigidBodyXform.AddTranslateOp().Set(Gf.Vec3f(0, 0, 0))
rigidBodyXform.AddOrientOp().Set(Gf.Quatf(1.0))
rigidBodyPrim = rigidBodyXform.GetPrim()
rigidBodyAPI = UsdPhysics.RigidBodyAPI.Apply(rigidBodyPrim)
massAPI = UsdPhysics.MassAPI.Apply(rigidBodyPrim)
massAPI.CreateMassAttr(rigidBodyMass)
massAPI.CreateDiagonalInertiaAttr(rigidBodyMomentOfInertia)
massAPI.CreateCenterOfMassAttr(rigidBodyCenterOfMass)
massAPI.CreatePrincipalAxesAttr(rigidBodyPrincipalAxes)

physxRbAPI = PhysxSchema.PhysxRigidBodyAPI.Apply(rigidBodyPrim)
physxRbAPI.CreateRetainAccelerationsAttr(False)

physxForceAPI = PhysxSchema.PhysxForceAPI.Apply(rigidBodyPrim)
physxForceAPI.CreateModeAttr("acceleration")
#physxForceAPI.CreateModeAttr("force")
physxForceAPI.CreateForceAttr(Gf.Vec3f(0.0, 1000.0, 0.0))
physxForceAPI.CreateTorqueAttr(Gf.Vec3f(0.0, 0.0, 2000.0))
physxForceAPI.CreateWorldFrameEnabledAttr(True)

It is important to note the frame of the applied force. Forces and torques are applied directly to the center of mass either in the world coordinate frame or in the local prim coordinate frame. The choice here is controlled by the worldFrameEnabled attribute.

Forces and torques may be applied as accelerations, as implemented in the above Python snippet, or as forces/torques. The snippet above creates a linear acceleration of 1000.0 along the y-axis and an angular acceleration of 2000.0 around the z-axis. The snippet could be amended to apply forces and torques as actual forces and torques, by setting the mode attribute to force. This would create an initial linear acceleration of 1000.0/3.0 along the y-axis and an initial angular acceleration of 2000.0/4.0 along the z-axis. The snippet may also be amended to alter the lifetime of the applied force attributes. The retainAccelerations attribute of the PhysxSchema.PhysxRigidBodyAPI allows force and torque attributes to be maintained until they are explicitly reset to (0, 0, 0). The alternative is for force and torque attributes to apply only for the next simulation step and then be automatically reset to (0, 0, 0), which is the behavior of the above snippet.

Configure Surface Velocity on Rigid Bodies#

Surface velocity is used to simulate conveyor-like behavior. It can be applied through PhysxSchema.PhysxSurfaceVelocityAPI and setting the associated linear and angular velocity attributes. The API can be applied to both kinematic and dynamic rigid bodies. The following Python snippet demonstrates how to add a conveyor-like behavior to two kinematic rigid bodies:

from pxr import Usd, UsdGeom, UsdPhysics, Gf, Sdf
import omni.usd

# Create a stage
omni.usd.get_context().new_stage()
stage = omni.usd.get_context().get_stage()

# Kinematic Angular Conveyor (cylinder)
cylinderBodyPath = "/World/kinematicCircularConveyor"
cylinderGeom = UsdGeom.Cylinder.Define(stage, cylinderBodyPath)
UsdGeom.SetStageUpAxis(stage, "Z")

size = 25.0
radius = size * 10.0
height = size * 0.5
cylinderGeom.CreateHeightAttr(height)
cylinderGeom.CreateRadiusAttr(radius)
cylinderGeom.GetAxisAttr().Set("Z")
cylinderGeom.CreateExtentAttr(
    [(-radius, -radius, -height * 0.5), (radius, radius, height * 0.5)]
)
cylinderPrim = stage.GetPrimAtPath(cylinderBodyPath)
cylinderGeom.CreateDisplayColorAttr([[0.45, 0.166, 1]])

UsdPhysics.CollisionAPI.Apply(cylinderPrim)
angularConveyor = UsdPhysics.RigidBodyAPI.Apply(cylinderPrim)
angularConveyor.CreateKinematicEnabledAttr(True)
targetAngularSurfaceVelocity = Gf.Vec3f(0.0, 0.0, size * 0.25)
cylinderSurfaceVelocityAPI = PhysxSchema.PhysxSurfaceVelocityAPI.Apply(cylinderPrim)
cylinderSurfaceVelocityAPI.CreateSurfaceAngularVelocityAttr(targetAngularSurfaceVelocity)
# make the cylinder high-quality render
cylinderPrim.CreateAttribute(
    "refinementEnableOverride", Sdf.ValueTypeNames.Bool, True
).Set(True)
cylinderPrim.CreateAttribute("refinementLevel", Sdf.ValueTypeNames.Int, True).Set(2)

# Kinematic Linear Conveyor (box)
boxBodyPath = "/World/kinematicBoxConveyor"
position = Gf.Vec3f(0, 0, size)
cubeGeom = UsdGeom.Cube.Define(stage, boxBodyPath)
cubePrim = stage.GetPrimAtPath(boxBodyPath)
cubeGeom.CreateSizeAttr(1.0)
half_extent = 0.5
cubeGeom.CreateExtentAttr([Gf.Vec3f(-half_extent), Gf.Vec3f(half_extent)])
cubeGeom.AddTranslateOp().Set(position)
cubeGeom.AddScaleOp().Set(Gf.Vec3f(3, 10.0, 0.5) * size)
cubeGeom.CreateDisplayColorAttr([[0.78, 0.09, 1]])

UsdPhysics.CollisionAPI.Apply(cubePrim)
linarConveyor = UsdPhysics.RigidBodyAPI.Apply(cubePrim)
linarConveyor.CreateKinematicEnabledAttr(True)
cubeSurfaceVelocityAPI = PhysxSchema.PhysxSurfaceVelocityAPI.Apply(cubePrim)
velocityAttribute = cubeSurfaceVelocityAPI.GetSurfaceVelocityAttr()
mpu = UsdGeom.GetStageMetersPerUnit(stage)
targetSurfaceVelocity = Gf.Vec3f(0.0, size * 3.0, 0.0) * mpu
velocityAttribute.Set(value=targetSurfaceVelocity)

The above Snippet creates:

• A kinematic cylinder with a surface angular velocity.

• A kinematic box with a surface linear velocity along its longest axis.

Rigid Body Collider Compatibility#

This section outlines the subset of all combinations of collider types and rigid body configurations that are supported. Some combinations supported with CPU simulation are not supported with GPU simulation and vice versa.

The Primitive Geometry Colliders and Mesh Geometry Colliders sections introduce a variety of collision types. These include sphere, cube, convex mesh, convex decomposition, simplified mesh, and signed distance field. Section Kinematic Rigid Body introduces the concept of dynamic and kinematic rigid bodies, and section Create and Destroy a Static Collider introduces the concept of static colliders.

Table Notes

• ✓ CPU: compatible, running on CPU. See also performance consideration notes below.

• ✓ (1): Particles can collide within the same particle system, but cannot collide with particles that are in another particle system.

Collider Geometry Notes

• Sphere: includes Mesh Bounding Sphere, and Sphere Approximation

• Cube: includes Mesh Bounding Cube

• Convex CPU: Convex Hulls are cooked for both CPU and GPU compatibility in general and automatically use the appropriate data and compute device depending on the simulation running on CPU or GPU. A CPU-only convex is generated if the input mesh data (before scaling) is oblong, in which case a warning will be issued in the console: [Warning] [omni.physx.cooking.plugin] ConvexMeshCookingTask: failed to cook GPU-compatible mesh, collision detection will fall back to CPU. Collisions with particles and deformables will not work with this mesh. Prim /World/Cone

• Mesh CPU: Triangle meshes are cooked for both CPU and GPU compatibility in general and automatically use the appropriate data and compute device depending on the simulation running on CPU or GPU. A multi-material triangle mesh is a CPU-only mesh.

Performance Considerations with CPU Collision Geometry

In general, CPU collision geometry generates contacts on the CPU, while GPU collision geometry generates contacts on the GPU. Most geometry supports both CPU and GPU, for example, Spheres or Convex Hulls (see note above), and automatically uses the appropriate compute device based on the simulation running on the CPU or on the GPU.

GPU-only features such as Deformable Bodies or Particles can only be used when GPU simulation is enabled. However, this is not true for some of the CPU-only collision geometry with GPU simulation. For example, a CPU-only convex hull can collide with a dynamic SDF Mesh. This is achieved by running the contact generation on CPU, which may incur a performance penalty, particularly for large GPU simulations such as reinforcement learning environments. In the table above, CPU/GPU collision pairs that are supported but run on the CPU are marked accordingly (✓ CPU).

Rigid Body Instancing#

USD supports two types of instancing:

• Scenegraph Instancing

• UsdGeom.PointInstancer

Both approaches work with rigid bodies, but each has their own restrictions.

from pxr import Usd, UsdGeom, UsdPhysics, Gf
import omni.usd

# Create a stage
omni.usd.get_context().new_stage()
stage = omni.usd.get_context().get_stage()

# Define the root Xform (transformable object)
rootxform = UsdGeom.Xform.Define(stage, "/World")

# Create a rigid body with two collider spheres.
# The two collider spheres will be referenced by multiple rigid bodies.
# Note that this would usually be prepared in a different USD file.
rigidBodyPath = "/World/rigidBody"
spheresRootPath = rigidBodyPath + "/theSpheres"
spherePaths = [spheresRootPath + "/sphere0", spheresRootPath + "/sphere1"]
spherePositions = [Gf.Vec3f(0, 2, 0), Gf.Vec3f(0, -2, 0)]
sphereRadii = [1, 2]
rigidBodyXform = UsdGeom.Xform.Define(stage, rigidBodyPath)
rigidBodyPrim = rigidBodyXform.GetPrim()
UsdPhysics.RigidBodyAPI.Apply(rigidBodyPrim)
massAPI = UsdPhysics.MassAPI.Apply(rigidBodyPrim)
massAPI.CreateMassAttr(1.0)
for i in range(2):
    sphereGeom = UsdGeom.Sphere.Define(stage, spherePaths[i])
    sphereGeom.CreateRadiusAttr(sphereRadii[i])
    sphereGeom.AddTranslateOp().Set(spherePositions[i])
    UsdPhysics.CollisionAPI.Apply(sphereGeom.GetPrim())

# Make three dynamic rigid bodies that have collision provided by
# references to the two spheres.
rigidBodyPaths = [
    "/World/theRigidBodies/rigidBody0",
    "/World/theRigidBodies/rigidBody1",
    "/World/theRigidBodies/rigidBody2"
]
rigidBodyStartPositions = [Gf.Vec3f(5, 0, 0), Gf.Vec3f(10, 0, 0), Gf.Vec3f(15, 0, 0)]
rigidBodyMasses = [2, 3, 4]
for i in range(3):
    rigidBody = UsdGeom.Xform.Define(stage, rigidBodyPaths[i])
    rigidBody.AddTranslateOp().Set(rigidBodyStartPositions[i])
    rigidBodyPrim = rigidBody.GetPrim()
    UsdPhysics.RigidBodyAPI.Apply(rigidBodyPrim)
    massAPI = UsdPhysics.MassAPI.Apply(rigidBodyPrim)
    massAPI.CreateMassAttr(rigidBodyMasses[i])
    # Configure with a reference to the two sphere colliders
    rigidBodyPrim.GetReferences().AddInternalReference(spheresRootPath)
    rigidBodyPrim.SetInstanceable(True)

rigidBodyPrim.GetReferences().AddInternalReference(spheresRootPath)

from pxr import Usd, UsdGeom, UsdPhysics, Gf
import omni.usd

# Create a stage
omni.usd.get_context().new_stage()
stage = omni.usd.get_context().get_stage()

# Define the root Xform (transformable object)
rootxform = UsdGeom.Xform.Define(stage, "/World")

# Create the point instancer
pointInstancerPath = "/World/pointinstancer"
pointInstancer = UsdGeom.PointInstancer.Define(stage, pointInstancerPath)

# Create a  prototype rigid body with 2 collider spheres under pointInstancerPath
prototypeRigidBodyPath = pointInstancerPath + "/rigidBodyPrototype"
prototypeRigidBody = UsdGeom.Xform.Define(stage, prototypeRigidBodyPath)
prototypeRigidBody.AddTranslateOp().Set(Gf.Vec3f(0.0))
prototypeRigidBody.AddOrientOp().Set(Gf.Quatf(1.0))
prototypeRigidBodyPrim = prototypeRigidBody.GetPrim()
UsdPhysics.RigidBodyAPI.Apply(prototypeRigidBodyPrim)
massAPI = UsdPhysics.MassAPI.Apply(prototypeRigidBodyPrim)
massAPI.CreateMassAttr(2.0)
# Create two sphere colliders as children of the prototype rigid body.
prototypeRigidBodySpherePaths = [
    pointInstancerPath + "/rigidBodyPrototype/sphere0",
    pointInstancerPath + "/rigidBodyPrototype/sphere1"
]
prototypeRigidBodySpherePositions = [Gf.Vec3f(0, 2, 0), Gf.Vec3f(0, -2, 0)]
prototypeRigidBodySphereRadii = [1, 2]
for i in range(2):
    sphereGeom = UsdGeom.Sphere.Define(stage, prototypeRigidBodySpherePaths[i])
    sphereGeom.AddTranslateOp().Set(prototypeRigidBodySpherePositions[i])
    sphereGeom.CreateRadiusAttr(prototypeRigidBodySphereRadii[i])
    UsdPhysics.CollisionAPI.Apply(sphereGeom.GetPrim())

# Point instancer setup
# Add the prototype rigid body
prototypeList = pointInstancer.GetPrototypesRel()
prototypeList.AddTarget(prototypeRigidBodyPath)

# Setup the point instancer to create three instances of the prototype
prototypeIndices = [0, 0, 0]
rigidBodyStartPositions = [Gf.Vec3f(5, 0, 0), Gf.Vec3f(10, 0, 0), Gf.Vec3f(15, 0, 0)]
rigidBodyStartRotations = [Gf.Quath(1.0), Gf.Quath(1.0), Gf.Quath(1.0)]
rigidBodyStartLinVelocities = [
    Gf.Vec3f(0.0, 5.0, 0.0),
    Gf.Vec3f(0.0, 10.0, 0.0),
    Gf.Vec3f(0.0, 15.0, 0.0)
]
rigidBodyStartAngVelocities = [
    Gf.Vec3f(0.0, 30.0, 0.0),
    Gf.Vec3f(0.0, 60.0, 0.0),
    Gf.Vec3f(0.0, 90.0, 0.0)
]

# Configure the three instances with initial positions and velocities.
pointInstancer.GetProtoIndicesAttr().Set(prototypeIndices)
pointInstancer.GetPositionsAttr().Set(rigidBodyStartPositions)
pointInstancer.GetOrientationsAttr().Set(rigidBodyStartRotations)
pointInstancer.GetVelocitiesAttr().Set(rigidBodyStartLinVelocities)
pointInstancer.GetAngularVelocitiesAttr().Set(rigidBodyStartAngVelocities)