rigid-body-detailed-mass#

Code

RB.008

Validator

Compatibility

openusd

Tags

💎

Summary#

Rigid bodies or their descendent collision shapes may have detailed mass properties including density, center of mass, and inertia tensor.

Description#

While basic mass specification is required, rigid bodies can have additional mass properties for more accurate physics simulation:

  • physics:density: Specifies the mass density of the object in kg/m³. When specified, mass is computed as density × volume.

  • physics:centerOfMass: Defines the center of mass in the prim’s local space (in meters).

  • physics:diagonalInertia: Specifies the diagonalized inertia tensor along principal axes (in kgâ‹…m²).

  • physics:principalAxes: Defines the orientation of the inertia tensor’s principal axes in the prim’s local space.

All units must be consistent with the stage’s unit system as defined by meters-per-unit and kilograms-per-unit.

Note: Density can be specified either through the MassAPI or through the MaterialAPI. When both specify density, the MassAPI’s density takes precedence. Additionally, if MassAPI specifies a mass value, it takes precedence over any density values.

Why is it required?#

  • Detailed mass properties enable more accurate physics simulation:

    • Density allows mass to be computed from volume

    • Center of mass affects rotational behavior

    • Inertia tensor determines how the object rotates around different axes

    • Principal axes alignment ensures correct rotational behavior

Examples#

#usda 1.0
(
    metersPerUnit = 0.01  # 1cm = 0.01m
    kilogramsPerUnit = 0.001  # 1g = 0.001kg
)

def Xform "RigidBody" (
      prepend apiSchemas = ["PhysicsRigidBodyAPI", "PhysicsMassAPI"]
) {
      # Basic mass specification
      physics:mass = 1000.0  # 1000g = 1kg
}


# Detailed mass properties
def Xform "RigidBody" (
   prepend apiSchemas = ["PhysicsRigidBodyAPI", "PhysicsMassAPI"]
) {
   # Basic mass (1000g = 1kg)
   physics:mass = 1000.0
   
   # Density (1g/cm³ = 1000kg/m³)
   physics:density = 1000.0
   
   # Center of mass offset (10cm = 0.1m)
   physics:centerOfMass = (10.0, 0.0, 0.0)
   
   # Inertia tensor (diagonalized) in g⋅cm²
   physics:diagonalInertia = (100.0, 200.0, 100.0)
   
   # Principal axes orientation
   physics:principalAxes = (0.0, 0.0, 0.0, 1.0)  # quaternion
}

# Example showing MassAPI density taking precedence over MaterialAPI
def Material "steel" (
   prepend apiSchemas = ["PhysicsMaterialAPI"]
) {
   physics:density = 800.0  # 0.8g/cm³
}

def Xform "RigidBody" (
   prepend apiSchemas = ["PhysicsRigidBodyAPI", "PhysicsMassAPI"]
) {
   # This density (1g/cm³) takes precedence over the material's density
   physics:density = 1000.0
   
   # This mass takes precedence over both density values
   physics:mass = 2000.0
}

How to comply#

  • Add the desired mass properties using the UsdPhysicsMassAPI attributes

  • Note the precedence rules for mass and density:

    • MassAPI mass value takes precedence over any density values

    • MassAPI density takes precedence over MaterialAPI density

    • If no mass or density is specified, simulators will compute mass automatically

  • Center of mass should be specified in the prim’s local space

  • Inertia tensor should be diagonalized and aligned with principal axes

  • All units must be consistent with the stage’s unit system:

    • Linear measurements (centerOfMass) should use the stage’s metersPerUnit

    • Mass measurements (mass, density) should use the stage’s kilogramsPerUnit

    • Inertia measurements should use the appropriate combination of mass and length units

For More Information#