isaaclab.sim.schemas

Sub-module containing utilities for schemas used in Omniverse.

We wrap the USD schemas for PhysX and USD Physics in a more convenient API for setting the parameters from Python. This is done so that configuration objects can define the schema properties to set and make it easier to tune the physics parameters without requiring to open Omniverse Kit and manually set the parameters into the respective USD attributes.

Caution

Schema properties cannot be applied on prims that are prototypes as they are read-only prims. This particularly affects instanced assets where some of the prims (usually the visual and collision meshes) are prototypes so that the instancing can be done efficiently.

In such cases, it is assumed that the prototypes have sim-ready properties on them that don’t need to be modified. Trying to set properties into prototypes will throw a warning saying that the prim is a prototype and the properties cannot be set.

The schemas are defined in the following links:

• UsdPhysics schema

• PhysxSchema schema

Locally, the schemas are defined in the following files:

• _isaac_sim/extsPhysics/omni.usd.schema.physics/plugins/UsdPhysics/resources/UsdPhysics/schema.usda

• _isaac_sim/extsPhysics/omni.usd.schema.physx/plugins/PhysxSchema/resources/generatedSchema.usda

Solver-common base classes

These base classes carry the universal-physics fields that every backend honors. They live in core isaaclab and have no backend dependency. For backend-specific knobs, use the matching subclass in isaaclab_physx.sim.schemas or isaaclab_newton.sim.schemas. See Schema Configuration Classes for the full design.

ArticulationRootBaseCfg	Solver-common properties to apply to the root of an articulation.
RigidBodyBaseCfg	Solver-common properties to apply to a rigid body.
CollisionBaseCfg	Solver-common properties to apply to colliders.
JointDriveBaseCfg	Solver-common properties to define the drive mechanism of a joint.
MeshCollisionBaseCfg	Solver-common properties to apply to a mesh in regards to collision.
MassPropertiesCfg	Properties to define explicit mass properties of a rigid body.
JointDrivePropertiesCfg	Deprecated: use PhysxJointDrivePropertiesCfg or JointDriveBaseCfg.
FixedTendonPropertiesCfg	Deprecated: use PhysxFixedTendonPropertiesCfg.
DeformableBodyPropertiesBaseCfg	Base deformable body properties for backend-specific extensions.

Mesh collision approximations (USD-only, no PhysX schema)

BoundingCubePropertiesCfg	Bounding-cube mesh collision approximation.
BoundingSpherePropertiesCfg	Bounding-sphere mesh collision approximation.

Schema fragments

A fragment mirrors exactly one USD applied schema and writes into a single attribute namespace. The family writers below dispatch lists of fragments to the prims matched by a target expression. See Schema Fragments for the concept and the spawner-level usage. Backend fragments live in isaaclab_physx.sim.schemas and isaaclab_newton.sim.schemas.

SchemaFragment	Base for a single-namespace USD-schema config fragment.
RigidBodyFragment	Marker base for rigid-body fragments; types the rigid_props slot.
CollisionFragment	Marker base for collision fragments; types the collision_props slot.
MassFragment	Marker base for mass fragments; types the mass_props slot.
ArticulationRootFragment	Marker base for articulation-root fragments; types the articulation_props slot.
JointDriveFragment	Marker base for joint-drive fragments; types the joint_drive_props slot.
MeshCollisionFragment	Marker base for mesh-collision fragments; types the mesh_collision_props slot.
FixedTendonFragment	Marker base for fixed-tendon fragments; types the fixed_tendons_props slot.
SpatialTendonFragment	Marker base for spatial-tendon fragments; types the spatial_tendons_props slot.
UsdPhysicsRigidBodyCfg	physics:* rigid-body attributes from UsdPhysics.RigidBodyAPI.
UsdPhysicsCollisionCfg	physics:* collision attributes from UsdPhysics.CollisionAPI.
UsdPhysicsDriveCfg	drive:<linear|angular>:physics:* joint-drive attributes from UsdPhysics.DriveAPI.
UsdPhysicsMeshCollisionCfg	physics:approximation mesh-collision token from UsdPhysics.MeshCollisionAPI.
MassCfg	physics:* mass attributes from UsdPhysics.MassAPI.

Fragment writers

apply_rigid_body_properties(prim_path_expr, ...)	Apply a list of rigid-body fragments to the rigid bodies matched by an expression.
apply_collision_properties(prim_path_expr, ...)	Apply a list of collision fragments to the colliders matched by an expression.
apply_mass_properties(prim_path_expr, fragments)	Apply a list of mass fragments to the mass-bearing prims matched by an expression.
apply_articulation_root_properties(...[, ...])	Apply a list of articulation-root fragments to the roots matched by an expression.
apply_joint_drive_properties(prim_path_expr, ...)	Apply a list of joint-drive fragments to the joint prims matched by an expression.
apply_mesh_collision_properties(prim_path, ...)	Apply a list of mesh-collision fragments to a prim.
apply_fixed_tendon_properties(...[, stage])	Apply a list of fixed-tendon fragments to the tendon prims matched by an expression.
apply_spatial_tendon_properties(...[, stage])	Apply a list of spatial-tendon fragments to the tendon prims matched by an expression.
apply_namespaced(cfg, prim_path[, stage])	Default fragment applier: apply the fragment's schema and write its namespaced attrs.
apply_drive(cfg, prim_path[, stage])	Apply a UsdPhysicsDriveCfg fragment to a single joint prim.
apply_mesh_collision(cfg, prim_path[, stage])	Apply a single mesh-collision fragment: its namespaced cooking attrs plus the shared token.

Functions

define_articulation_root_properties(...[, stage])	Apply the articulation root schema on the input prim and set its properties.
modify_articulation_root_properties(...[, stage])	Modify PhysX parameters for an articulation root prim.
define_rigid_body_properties(prim_path, cfg)	Apply the rigid body schema on the input prim and set its properties.
modify_rigid_body_properties(prim_path, cfg)	Modify parameters for a rigid body prim.
activate_contact_sensors(prim_path[, ...])	Activate the contact sensor on all rigid bodies under a specified prim path.
define_collision_properties(prim_path, cfg)	Apply the collision schema on the input prim and set its properties.
modify_collision_properties(prim_path, cfg)	Modify PhysX properties of collider prim.
define_mass_properties(prim_path, cfg[, stage])	Apply the mass schema on the input prim and set its properties.
modify_mass_properties(prim_path, cfg[, stage])	Set properties for the mass of a rigid body prim.
modify_joint_drive_properties(prim_path, cfg)	Modify parameters for a joint prim.
define_mesh_collision_properties(prim_path, cfg)	Apply the mesh collision schema on the input prim and set its properties.
modify_mesh_collision_properties(prim_path, cfg)	Set properties for the mesh collision of a prim.
modify_fixed_tendon_properties(prim_path, cfg)	Modify PhysX parameters for a fixed tendon attachment prim.
define_deformable_body_properties(prim_path, cfg)	Apply the deformable body schema on the input prim and set its properties.
define_deformable_curve_properties(prim_path)	Apply the deformable curve simulation schema.
modify_deformable_body_properties(prim_path, cfg)	Modify deformable body parameters for a deformable body prim.

Schema Fragments

class isaaclab.sim.schemas.SchemaFragment

Base for a single-namespace USD-schema config fragment.

Each subclass mirrors exactly one USD applied schema. The fragment carries class-level metadata describing which USD namespace its fields write to (_usd_namespace) and which applied schema, if any, it owns (_usd_applied_schema). The func field names the callable that applies the fragment to a prim; the default generic applier (apply_namespaced()) reads the metadata and writes each non-None field as <namespace>:<camelCase(field)>. Irregular APIs override func with a custom applier.

Note

A fragment present in a spawner slot means its schema is applied. None fields are left unchanged on the prim (partial update).

Important

Every dataclass field other than func is authored as a USD attribute <_usd_namespace>:<camelCase(field)>. A fragment must not carry non-USD/bookkeeping fields – such state belongs on the spawner cfg or as a writer keyword argument (this is why fix_root_link / ensure_drives_exist are not fragment fields). The generic applier (apply_namespaced()) enforces the invariant: it raises when a fragment has no _usd_namespace, and unsupported (non-scalar) value types raise when written.

Attributes:

func	Callable (or its module:attr import string) that applies this fragment to a prim.

func: Callable | str

Callable (or its module:attr import string) that applies this fragment to a prim.

Resolved via string_to_callable() when a string. The callable signature is func(cfg, prim_path, stage).

class isaaclab.sim.schemas.RigidBodyFragment

Bases: SchemaFragment

Marker base for rigid-body fragments; types the rigid_props slot.

Attributes:

func	Callable (or its module:attr import string) that applies this fragment to a prim.

func: Callable | str

Callable (or its module:attr import string) that applies this fragment to a prim.

Resolved via string_to_callable() when a string. The callable signature is func(cfg, prim_path, stage).

class isaaclab.sim.schemas.CollisionFragment

Bases: SchemaFragment

Marker base for collision fragments; types the collision_props slot.

Attributes:

func	Callable (or its module:attr import string) that applies this fragment to a prim.

func: Callable | str

Callable (or its module:attr import string) that applies this fragment to a prim.

Resolved via string_to_callable() when a string. The callable signature is func(cfg, prim_path, stage).

class isaaclab.sim.schemas.MassFragment

Bases: SchemaFragment

Marker base for mass fragments; types the mass_props slot.

Attributes:

func	Callable (or its module:attr import string) that applies this fragment to a prim.

func: Callable | str

Callable (or its module:attr import string) that applies this fragment to a prim.

Resolved via string_to_callable() when a string. The callable signature is func(cfg, prim_path, stage).

class isaaclab.sim.schemas.ArticulationRootFragment

Bases: SchemaFragment

Marker base for articulation-root fragments; types the articulation_props slot.

Articulation-root fragments author backend-specific articulation properties (solver iterations, sleep / stabilization thresholds, self-collision toggles). The defining UsdPhysics.ArticulationRootAPI anchor is applied by the articulation-root family writer (apply_articulation_root_properties()) only when the articulation_props slot carries fragments (presence-gated, matching the legacy modify_articulation_root_properties() behaviour).

Attributes:

func	Callable (or its module:attr import string) that applies this fragment to a prim.

func: Callable | str

Callable (or its module:attr import string) that applies this fragment to a prim.

Resolved via string_to_callable() when a string. The callable signature is func(cfg, prim_path, stage).

class isaaclab.sim.schemas.JointDriveFragment

Bases: SchemaFragment

Marker base for joint-drive fragments; types the joint_drive_props slot.

Attributes:

func	Callable (or its module:attr import string) that applies this fragment to a prim.

func: Callable | str

Callable (or its module:attr import string) that applies this fragment to a prim.

Resolved via string_to_callable() when a string. The callable signature is func(cfg, prim_path, stage).

class isaaclab.sim.schemas.MeshCollisionFragment

Bases: SchemaFragment

Marker base for mesh-collision fragments; types the mesh_collision_props slot.

A mesh-collision concept is split across one core fragment carrying the standard physics:approximation token (UsdPhysicsMeshCollisionCfg) and one cooking fragment per backend cooking schema (PhysX convex hull / decomposition / triangle mesh / SDF, Newton mesh / SDF). Whichever cooking fragment is present implies the approximation token written to physics:approximation – see apply_mesh_collision_properties().

Attributes:

func	Callable (or its module:attr import string) that applies this fragment to a prim.

func: Callable | str

Callable (or its module:attr import string) that applies this fragment to a prim.

Resolved via string_to_callable() when a string. The callable signature is func(cfg, prim_path, stage).

class isaaclab.sim.schemas.FixedTendonFragment

Bases: SchemaFragment

Marker base for fixed-tendon fragments; types the fixed_tendons_props slot.

Fixed tendons are a tune-not-apply family: the applied PhysxTendonAxisRootAPI multi-instance schemas already exist on the prim (authored in the source asset), so the family writer (apply_fixed_tendon_properties()) does not apply any anchor schema; it only tunes the existing instances via each fragment’s func.

Attributes:

func	Callable (or its module:attr import string) that applies this fragment to a prim.

func: Callable | str

Callable (or its module:attr import string) that applies this fragment to a prim.

Resolved via string_to_callable() when a string. The callable signature is func(cfg, prim_path, stage).

class isaaclab.sim.schemas.SpatialTendonFragment

Bases: SchemaFragment

Marker base for spatial-tendon fragments; types the spatial_tendons_props slot.

Spatial tendons are a tune-not-apply family: the applied PhysxTendonAttachmentRootAPI / PhysxTendonAttachmentLeafAPI multi-instance schemas already exist on the prim (authored in the source asset), so the family writer (apply_spatial_tendon_properties()) does not apply any anchor schema; it only tunes the existing instances via each fragment’s func.

Attributes:

func	Callable (or its module:attr import string) that applies this fragment to a prim.

func: Callable | str

Callable (or its module:attr import string) that applies this fragment to a prim.

Resolved via string_to_callable() when a string. The callable signature is func(cfg, prim_path, stage).

class isaaclab.sim.schemas.UsdPhysicsRigidBodyCfg

Bases: RigidBodyFragment

physics:* rigid-body attributes from UsdPhysics.RigidBodyAPI.

The UsdPhysics.RigidBodyAPI schema is applied as the implicit anchor by the rigid-body family writer, so this fragment owns no applied schema of its own.

Attributes:

rigid_body_enabled	Whether to enable or disable the rigid body.
kinematic_enabled	Determines whether the body is kinematic or not.
func	Callable (or its module:attr import string) that applies this fragment to a prim.

rigid_body_enabled: bool | None

Whether to enable or disable the rigid body.

kinematic_enabled: bool | None

Determines whether the body is kinematic or not.

A kinematic body is moved through animated or user-defined poses; the simulation still derives velocities for it based on the external motion.

func: Callable | str

Callable (or its module:attr import string) that applies this fragment to a prim.

Resolved via string_to_callable() when a string. The callable signature is func(cfg, prim_path, stage).

class isaaclab.sim.schemas.UsdPhysicsCollisionCfg

Bases: CollisionFragment

physics:* collision attributes from UsdPhysics.CollisionAPI.

The UsdPhysics.CollisionAPI schema is applied as the implicit anchor by the collision family writer (apply_collision_properties()), so this fragment owns no applied schema of its own.

Attributes:

collision_enabled	Whether to enable or disable collisions.
func	Callable (or its module:attr import string) that applies this fragment to a prim.

collision_enabled: bool | None

Whether to enable or disable collisions.

Writes physics:collisionEnabled via UsdPhysics.CollisionAPI.

func: Callable | str

Callable (or its module:attr import string) that applies this fragment to a prim.

Resolved via string_to_callable() when a string. The callable signature is func(cfg, prim_path, stage).

class isaaclab.sim.schemas.UsdPhysicsDriveCfg

Bases: JointDriveFragment

drive:<linear|angular>:physics:* joint-drive attributes from UsdPhysics.DriveAPI.

The drive attributes live under a multi-instance UsdPhysics.DriveAPI (instance "angular" for revolute joints, "linear" for prismatic joints), so this fragment cannot use the generic apply_namespaced() writer. It overrides func with apply_drive(), which selects the instance, applies UsdPhysics.DriveAPI (presence-gated, the conditional anchor for the joint-drive family), performs the radian-to-degree conversion for angular drives, and writes the typed drive:<inst>:physics:{type,maxForce,stiffness,damping} attributes.

Note

Unlike most fragments, this one is not a metadata-driven write. DriveAPI is applied only when this fragment is present in the slot.

Attributes:

func	Callable (or its module:attr import string) that applies this fragment to a prim.
drive_type	Joint drive type to apply.
max_force	Maximum force/torque that can be applied to the joint [N for linear joints, N·m for angular joints].
max_effort	Deprecated alias for max_force.
stiffness	Stiffness of the joint drive.
damping	Damping of the joint drive.

func: Callable | str

Callable (or its module:attr import string) that applies this fragment to a prim.

Resolved via string_to_callable() when a string. The callable signature is func(cfg, prim_path, stage).

drive_type: Literal['force', 'acceleration'] | None

Joint drive type to apply.

If the drive type is "force", then the joint is driven by a force. If the drive type is "acceleration", then the joint is driven by an acceleration (usually used for kinematic joints). Written to drive:<inst>:physics:type (the USD attr is type, a permanent inline carve-out from the snake-to-camel convention).

max_force: float | None

Maximum force/torque that can be applied to the joint [N for linear joints, N·m for angular joints].

Written to drive:<inst>:physics:maxForce via UsdPhysics.DriveAPI.

max_effort: float | None

Deprecated alias for max_force.

Deprecated since version 4.6.25: Use max_force instead. The cfg field is renamed so its snake_case name maps identity-style to the USD camelCase attribute (maxForce on UsdPhysics.DriveAPI). The alias is forwarded to max_force in __post_init__() and will be removed in 4.0.

stiffness: float | None

Stiffness of the joint drive.

The unit depends on the joint model:

• For linear joints, the unit is kg-m/s² (N/m).

• For angular joints, the unit is kg-m²/s²/rad (N·m/rad).

Angular drives are converted from radians to degrees (N·m/rad -> N·m/deg) before being written to drive:angular:physics:stiffness.

damping: float | None

Damping of the joint drive.

The unit depends on the joint model:

• For linear joints, the unit is kg-m/s (N·s/m).

• For angular joints, the unit is kg-m²/s/rad (N·m·s/rad).

Angular drives are converted from radians to degrees (N·m·s/rad -> N·m·s/deg) before being written to drive:angular:physics:damping.

class isaaclab.sim.schemas.UsdPhysicsMeshCollisionCfg

Bases: MeshCollisionFragment

physics:approximation mesh-collision token from UsdPhysics.MeshCollisionAPI.

Carries the standard mesh-collision approximation token (mesh_approximation_name written to physics:approximation). The UsdPhysics.MeshCollisionAPI schema is applied as the implicit anchor by the mesh-collision family writer (apply_mesh_collision_properties()), so this fragment owns no applied schema of its own.

Note

The physics:approximation attribute is a TfToken validated against MESH_APPROXIMATION_TOKENS; the family writer (not the generic apply_namespaced() applier) handles the token write, so this fragment overrides nothing but the namespace metadata. When a PhysX/Newton cooking fragment is present alongside this one, its default mesh_approximation_name sets the token.

Attributes:

mesh_approximation_name	"none".
func	Callable (or its module:attr import string) that applies this fragment to a prim.

mesh_approximation_name: str

“none”.

Writes the physics:approximation token via UsdPhysics.MeshCollisionAPI. Refer to MESH_APPROXIMATION_TOKENS for available options.

Type:

Name of mesh collision approximation method. Default

func: Callable | str

Callable (or its module:attr import string) that applies this fragment to a prim.

Resolved via string_to_callable() when a string. The callable signature is func(cfg, prim_path, stage).

class isaaclab.sim.schemas.MassCfg

Bases: MassFragment

physics:* mass attributes from UsdPhysics.MassAPI.

The UsdPhysics.MassAPI schema is applied as the implicit anchor by the mass family writer (apply_mass_properties()), so this fragment owns no applied schema of its own. Mirrors the legacy MassPropertiesCfg.

Note

A fragment present in a spawner slot means its schema is applied. None fields are left unchanged on the prim (partial update).

Attributes:

mass	The mass of the rigid body [kg].
density	The density of the rigid body [kg/m^3].
func	Callable (or its module:attr import string) that applies this fragment to a prim.

mass: float | None

The mass of the rigid body [kg].

Writes physics:mass via UsdPhysics.MassAPI.

Note

If density is non-zero, it takes precedence and is used to compute the mass instead.

density: float | None

The density of the rigid body [kg/m^3].

Writes physics:density via UsdPhysics.MassAPI. The density indirectly defines the mass of the rigid body. It is generally computed using the collision approximation of the body.

func: Callable | str

Callable (or its module:attr import string) that applies this fragment to a prim.

Resolved via string_to_callable() when a string. The callable signature is func(cfg, prim_path, stage).

isaaclab.sim.schemas.apply_rigid_body_properties(prim_path_expr: str, fragments: Iterable[schemas_cfg.RigidBodyFragment], create_if_missing: bool = False, stage: Usd.Stage | None = None) → bool

Apply a list of rigid-body fragments to the rigid bodies matched by an expression.

The prims to author on are matched with find_matching_prims(): prim_path_expr is a plain regular expression over whole prim paths, so [^/]+ selects one path segment and /World/Robot/.* every descendant of a prim. Matched prims that already carry UsdPhysics.RigidBodyAPI are modified in place: each fragment is dispatched to every such target via its func. Backend fragments carry backend-specific funcs, so core never imports a backend.

An empty fragment list is an authoring no-op and returns True. With create_if_missing, UsdPhysics.RigidBodyAPI is applied to every matched prim that lacks it; only the asset’s joints decide which bodies participate in the articulation, so the expression is trusted as written. Zero targets warn and return False. Instanced matches are skipped with a warning.

Parameters:

• prim_path_expr – The prim path expression matched against the stage.

• fragments – An iterable of RigidBodyFragment instances.

• create_if_missing – Whether to apply UsdPhysics.RigidBodyAPI to every matched prim that does not carry it. Defaults to False.

• stage – The stage where to find the prims. Defaults to None, in which case the current stage is used.

Returns:

True if every target and fragment succeeded and no instanced prim was skipped.

isaaclab.sim.schemas.apply_collision_properties(prim_path_expr: str, fragments: Iterable[schemas_cfg.CollisionFragment], create_if_missing: bool = False, stage: Usd.Stage | None = None) → bool

Apply a list of collision fragments to the colliders matched by an expression.

The prims to author on are matched with find_matching_prims(): prim_path_expr is a plain regular expression over whole prim paths, so [^/]+ selects one path segment and /World/Robot/.* every descendant of a prim. Matched prims that already carry UsdPhysics.CollisionAPI are modified in place: each fragment is dispatched to every such target via its func. Backend fragments carry backend-specific funcs, so core never imports a backend.

An empty fragment list is an authoring no-op and returns True. With create_if_missing, UsdPhysics.CollisionAPI is applied to every matched prim that lacks it. When no target remains, a warning is emitted and False is returned without authoring anything. Matched prims inside instances cannot be authored on and are skipped with a warning.

Parameters:

• prim_path_expr – The prim path expression matched against the stage.

• fragments – An iterable of CollisionFragment instances.

• create_if_missing – Whether to apply UsdPhysics.CollisionAPI to matched prims that do not carry it. Defaults to False.

• stage – The stage where to find the prims. Defaults to None, in which case the current stage is used.

Returns:

True if every target and fragment succeeded and no instanced prim was skipped.

isaaclab.sim.schemas.apply_mass_properties(prim_path_expr: str, fragments: Iterable[schemas_cfg.MassFragment], create_if_missing: bool = False, stage: Usd.Stage | None = None) → bool

Apply a list of mass fragments to the mass-bearing prims matched by an expression.

The prims to author on are matched with find_matching_prims(): prim_path_expr is a plain regular expression over whole prim paths, so [^/]+ selects one path segment and /World/Robot/.* every descendant of a prim. Matched prims that already carry UsdPhysics.MassAPI are modified in place: each fragment is dispatched to every such target via its func. Backend fragments carry backend-specific funcs, so core never imports a backend.

An empty fragment list is an authoring no-op and returns True. With create_if_missing, UsdPhysics.MassAPI is applied to every matched prim that lacks it; pairing the mass with a rigid body is the caller’s responsibility. Zero targets warn and return False. Instanced matches are skipped with a warning.

Parameters:

• prim_path_expr – The prim path expression matched against the stage.

• fragments – An iterable of MassFragment instances.

• create_if_missing – Whether to apply UsdPhysics.MassAPI to every matched prim that does not carry it. Defaults to False.

• stage – The stage where to find the prims. Defaults to None, in which case the current stage is used.

Returns:

True if every target and fragment succeeded and no instanced prim was skipped.

isaaclab.sim.schemas.apply_articulation_root_properties(prim_path_expr: str, fragments: Iterable[schemas_cfg.ArticulationRootFragment], stage: Usd.Stage | None = None, fix_root_link: bool | None = None, create_if_missing: bool = False) → bool

Apply a list of articulation-root fragments to the roots matched by an expression.

The prims to author on are matched with find_matching_prims(): prim_path_expr is a plain regular expression over whole prim paths, so [^/]+ selects one path segment and /World/Robot/.* every descendant of a prim. Matched prims that already carry UsdPhysics.ArticulationRootAPI are the targets: each fragment is dispatched to every target via its func. Sibling roots (independent articulations matched by one expression) are all processed. Nested targets are authored as matched, with a warning – resolving nested roots is the asset author’s responsibility.

With create_if_missing, the API is applied to every matched prim that lacks it. Zero targets warn and return False. Instanced matches are skipped with a warning.

An empty fragment list is an authoring no-op: it returns True immediately when fix_root_link is None, but still resolves targets and adjusts topology when the flag is set. When fix_root_link is True, the active physics manager creates or enables the world joint on each target and returns the backend’s final root prim; False only disables an existing joint.

Parameters:

• prim_path_expr – The prim path expression matched against the stage.

• fragments – Articulation-root fragments to apply.

• stage – The stage where to find the prims. Defaults to None, in which case the current stage is used.

• fix_root_link – Whether to fix the root link. None leaves topology unchanged.

• create_if_missing – Whether to apply UsdPhysics.ArticulationRootAPI to every matched prim that does not carry it. Defaults to False.

Returns:

True if every target and fragment succeeded and no instanced prim was skipped.

Raises:

• TypeError – If fragments contains a non-articulation fragment.

• RuntimeError – If fixing cannot resolve the active backend or relocate the root.

• NotImplementedError – If the backend cannot fix the resolved root.

isaaclab.sim.schemas.apply_joint_drive_properties(prim_path_expr: str, fragments, stage: Usd.Stage | None = None, ensure_drives_exist: bool = False, create_if_missing: bool = False) → bool

Apply a list of joint-drive fragments to the joint prims matched by an expression.

The prims to author on are matched with find_matching_prims(): prim_path_expr is a plain regular expression over whole prim paths, so [^/]+ selects one path segment and /World/Robot/.* every descendant of a prim. The fragments are dispatched to every matched revolute/prismatic joint prim that is not excluded by a backend-registered skip predicate (see register_joint_drive_skip_predicate(), e.g. PhysX tendon members). Non-joint matches are ignored silently – a subtree expression matches every descendant, so per-prim warnings would spam. Matched prims inside instances cannot be authored on and are skipped with a warning.

Unlike apply_rigid_body_properties(), the joint-drive family has no implicit anchor: UsdPhysics.DriveAPI is presence-gated and applied only by apply_drive() when a UsdPhysicsDriveCfg fragment is present in fragments. Each fragment is dispatched via its func, so backend fragments carry backend-specific funcs and core never imports a backend.

An empty fragment list is an authoring no-op and returns True. When no fragment succeeds on any joint, a warning is emitted and False is returned.

Parameters:

• prim_path_expr – The prim path expression matched against the stage.

• fragments – An iterable of JointDriveFragment instances.

• stage – The stage where to find the prims. Defaults to None, in which case the current stage is used.

• ensure_drives_exist – If True, write a minimal stiffness (1e-3) to any drive whose authored stiffness and damping are both zero, so that backends (e.g. Newton) treat the drive as active. Reproduces the legacy ensure_drives_exist behaviour. This is a spawner-level flag, not a fragment field.

• create_if_missing – If True, apply the axis-appropriate UsdPhysics.DriveAPI instance ("angular" for revolute joints, "linear" for prismatic joints) on matched joints that do not carry it, before dispatching the fragments. Distinct from ensure_drives_exist: this flag creates the drive API itself, whereas ensure_drives_exist seeds a minimal stiffness on fully-passive drives that already exist. Defaults to False.

Returns:

True if the fragments were applied to at least one joint prim and no instanced joint was skipped, False otherwise.

isaaclab.sim.schemas.apply_mesh_collision_properties(prim_path: str, fragments: Iterable[schemas_cfg.MeshCollisionFragment], stage: Usd.Stage | None = None) → bool

Apply a list of mesh-collision fragments to a prim.

Applies UsdPhysics.MeshCollisionAPI as the implicit anchor (the carrier of the physics:approximation token), then dispatches each fragment via its func. The default mesh-collision func (apply_mesh_collision()) authors both the fragment’s backend cooking namespace and the shared approximation token it implies, so composing a core fragment with a backend cooking fragment lets the last fragment with a non-"none" mesh_approximation_name set the token. Backend cooking fragments carry their own funcs, so core never imports a backend.

Parameters:

• prim_path – The prim path to apply the mesh-collision schemas on. This prim should be a Mesh.

• fragments – An iterable of MeshCollisionFragment instances.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Returns:

True if all fragments applied successfully, False if any fragment reported failure.

Raises:

ValueError – If the prim at prim_path is not valid, or when a fragment’s mesh approximation name is not in MESH_APPROXIMATION_TOKENS.

isaaclab.sim.schemas.apply_fixed_tendon_properties(prim_path_expr: str, fragments: Iterable[schemas_cfg.FixedTendonFragment], stage: Usd.Stage | None = None) → bool

Apply a list of fixed-tendon fragments to the tendon prims matched by an expression.

The prims to author on are matched with find_matching_prims(): prim_path_expr is a plain regular expression over whole prim paths, so [^/]+ selects one path segment and /World/Robot/.* every descendant of a prim. A matched prim is a fixed-tendon target when it carries an applied PhysxTendonAxisRootAPI multi-apply instance or is a MjcTendon prim.

Fixed tendons are a tune-not-apply family: the tendon topology is authored in the source asset, so this writer never creates instances – it only dispatches each fragment via its func to every matched target. Backend fragments carry backend-specific funcs, so core never imports a backend. A fragment succeeds when its func returns True on at least one target: each func only tunes its own backend’s representation and no-ops (returns False) on the other backend’s prims, so a mixed-backend target set does not fail the write.

An empty fragment list is an authoring no-op and returns True. When no target matches, a warning is emitted and False is returned without authoring anything. Matched prims inside instances cannot be authored on and are skipped with a warning.

Parameters:

• prim_path_expr – The prim path expression matched against the stage.

• fragments – An iterable of FixedTendonFragment instances.

• stage – The stage where to find the prims. Defaults to None, in which case the current stage is used.

Returns:

True if every fragment tuned at least one target and no instanced prim was skipped.

isaaclab.sim.schemas.apply_spatial_tendon_properties(prim_path_expr: str, fragments: Iterable[schemas_cfg.SpatialTendonFragment], stage: Usd.Stage | None = None) → bool

Apply a list of spatial-tendon fragments to the tendon prims matched by an expression.

The prims to author on are matched with find_matching_prims(): prim_path_expr is a plain regular expression over whole prim paths, so [^/]+ selects one path segment and /World/Robot/.* every descendant of a prim. A matched prim is a spatial-tendon target when it carries an applied PhysxTendonAttachmentRootAPI or PhysxTendonAttachmentLeafAPI multi-apply instance.

Spatial tendons are a tune-not-apply family: the tendon topology is authored in the source asset, so this writer never creates instances – it only dispatches each fragment via its func to every matched target. Backend fragments carry backend-specific funcs, so core never imports a backend. A fragment succeeds when its func returns True on at least one target: each func only tunes its own backend’s representation and no-ops (returns False) on the other backend’s prims, so a mixed-backend target set does not fail the write.

An empty fragment list is an authoring no-op and returns True. When no target matches, a warning is emitted and False is returned without authoring anything. Matched prims inside instances cannot be authored on and are skipped with a warning.

Parameters:

• prim_path_expr – The prim path expression matched against the stage.

• fragments – An iterable of SpatialTendonFragment instances.

• stage – The stage where to find the prims. Defaults to None, in which case the current stage is used.

Returns:

True if every fragment tuned at least one target and no instanced prim was skipped.

isaaclab.sim.schemas.apply_namespaced(cfg: schemas_cfg.SchemaFragment, prim_path: str, stage: Usd.Stage | None = None) → bool

Default fragment applier: apply the fragment’s schema and write its namespaced attrs.

Reads _usd_namespace / _usd_applied_schema from the cfg’s class. If the fragment owns an applied schema, it is applied (once). Each non-None dataclass field is written as <namespace>:<camelCase(field)>; the func field is skipped. None fields are left unchanged on the prim (partial update).

Parameters:

• cfg – The fragment instance carrying _usd_namespace / _usd_applied_schema metadata.

• prim_path – The prim path to author on.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Returns:

True if the properties were successfully set.

isaaclab.sim.schemas.apply_drive(cfg, prim_path: str, stage: Usd.Stage | None = None) → bool

Apply a UsdPhysicsDriveCfg fragment to a single joint prim.

This is the override func for the UsdPhysics.DriveAPI fragment: the drive attributes live under a multi-instance schema, so the generic apply_namespaced() writer cannot be used. The writer reproduces the solver-common drive logic of modify_joint_drive_properties():

• Selects the drive instance: "angular" for a revolute joint, "linear" for a prismatic joint. For any other prim type, the function is a no-op and returns False.

• Skips joints excluded by a backend-registered predicate (see register_joint_drive_skip_predicate(), e.g. PhysX tendon members), returning False.

• Applies UsdPhysics.DriveAPI for the selected instance (presence-gated – only applied when this fragment is present).

• Converts angular-drive stiffness and damping from radians to degrees (N·m/rad -> N·m/deg and N·m·s/rad -> N·m·s/deg); linear drives are written as-is.

• Writes the typed drive:<inst>:physics:{type,maxForce,stiffness,damping} attributes, mapping the drive_type field to the USD attribute named type.

Parameters:

• cfg – The UsdPhysicsDriveCfg fragment to apply.

• prim_path – The joint prim path to author on.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Returns:

True if the drive was applied to a joint prim, False if the prim is not a revolute or prismatic joint (or is a tendon child).

isaaclab.sim.schemas.apply_mesh_collision(cfg: schemas_cfg.MeshCollisionFragment, prim_path: str, stage: Usd.Stage | None = None) → bool

Apply a single mesh-collision fragment: its namespaced cooking attrs plus the shared token.

This is the default func for every MeshCollisionFragment. Unlike the generic apply_namespaced(), a mesh-collision fragment additionally authors the shared physics:approximation token (via the standard UsdPhysics.MeshCollisionAPI) on top of its own backend cooking namespace.

The token is not a plain namespaced attribute – it is shared state on the family anchor implied by the present cooking fragment. Each fragment carries a mesh_approximation_name whose default encodes the token its schema implies (e.g. "convexHull" for PhysxConvexHullCfg, "sdf" for PhysxSDFMeshCfg). A name of "none" leaves the token unchanged, so when several fragments are dispatched in order by apply_mesh_collision_properties() the last one with a non-"none" name wins – this is how a core fragment composes with a backend cooking fragment. The name is validated against MESH_APPROXIMATION_TOKENS; an unknown name raises ValueError. mesh_approximation_name is skipped by apply_namespaced(), so it is never authored as a spurious <namespace>:meshApproximationName attribute.

Parameters:

• cfg – The mesh-collision fragment to apply.

• prim_path – The prim path to author on. This prim should be a Mesh.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Returns:

True if the fragment was applied successfully.

Raises:

ValueError – If the prim at prim_path is not valid, or when the fragment’s mesh approximation name is not in MESH_APPROXIMATION_TOKENS.

Articulation Root

class isaaclab.sim.schemas.ArticulationRootBaseCfg

Solver-common properties to apply to the root of an articulation.

Carries fix_root_link (writer-side; materializes a UsdPhysics.FixedJoint between the world frame and the root link) and articulation_enabled whose only USD path today is the PhysX-namespaced physxArticulation:articulationEnabled attribute. The base class itself declares no USD namespace; the writer consults _usd_field_exceptions to route articulation_enabled to its non-base namespace and apply PhysxArticulationAPI only when the user authored that one field. For PhysX-only articulation-root properties (self-collisions, TGS solver iterations, sleep / stabilization thresholds), use PhysxArticulationRootPropertiesCfg.

See modify_articulation_root_properties() for more information.

Note

If the values are None, they are not modified. This is useful when you want to set only a subset of the properties and leave the rest as-is.

Attributes:

articulation_enabled	Whether to enable or disable the articulation.
fix_root_link	Whether to fix the root link of the articulation.

articulation_enabled: bool | None

Whether to enable or disable the articulation.

PhysX honors this per-articulation at sim time via physxArticulation:articulationEnabled: setting False makes PhysX skip the articulation in its solver passes.

On Newton, the field is read by the IsaacLab Newton wrapper at spawn time (isaaclab_newton/assets/rigid_object/rigid_object.py:1035) as a guard against accidentally spawning a RigidObject over a prim that still has ArticulationRootAPI applied; setting False suppresses the guard error. The Newton solver itself does not consult the flag at sim time.

Placed on the solver-common class because the user-facing intent is universal and both PhysX (sim-time) and the IL Newton wrapper (spawn-time) honor it.

fix_root_link: bool | None

Whether to fix the root link of the articulation.

• If set to None, the root link is not modified.

• If the articulation already has a fixed root link, this flag will enable or disable the fixed joint.

• If the articulation does not have a fixed root link, this flag will create a fixed joint between the world frame and the root link. The joint is created with the name “FixedJoint” under the articulation prim.

Note

This is a non-USD schema property. It is handled by the modify_articulation_root_properties() function.

isaaclab.sim.schemas.define_articulation_root_properties(prim_path: str, cfg: schemas_cfg.ArticulationRootBaseCfg, stage: Usd.Stage | None = None)

Apply the articulation root schema on the input prim and set its properties.

See modify_articulation_root_properties() for more details on how the properties are set.

Parameters:

• prim_path – The prim path where to apply the articulation root schema.

• cfg – The configuration for the articulation root.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Raises:

• ValueError – When the prim path is not valid.

• TypeError – When the prim already has conflicting API schemas.

isaaclab.sim.schemas.modify_articulation_root_properties(prim_path: str, cfg: schemas_cfg.ArticulationRootBaseCfg, stage: Usd.Stage | None = None) → bool

Modify PhysX parameters for an articulation root prim.

The articulation root marks the root of an articulation tree. For floating articulations, this should be on the root body. For fixed articulations, this API can be on a direct or indirect parent of the root joint which is fixed to the world.

The schema comprises of attributes that belong to the ArticulationRootAPI and PhysxArticulationAPI. schemas. The latter contains the PhysX parameters for the articulation root.

The properties are applied to the articulation root prim. The common properties (such as solver position and velocity iteration counts, sleep threshold, stabilization threshold) take precedence over those specified in the rigid body schemas for all the rigid bodies in the articulation.

Caution

When the attribute schemas_cfg.ArticulationRootPropertiesCfg.fix_root_link is set to True, a fixed joint is created between the root link and the world frame (if it does not already exist). However, to deal with physics parser limitations, the articulation root schema needs to be applied to the parent of the root link.

Note

This function is decorated with apply_nested() that set the properties to all the prims (that have the schema applied on them) under the input prim path.

Parameters:

• prim_path – The prim path to the articulation root.

• cfg – The configuration for the articulation root.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Returns:

True if the properties were successfully set, False otherwise.

Raises:

NotImplementedError – When the root prim is not a rigid body and a fixed joint is to be created.

For PhysX-specific articulation properties (self-collisions, TGS solver iterations, sleep/stabilization thresholds), see PhysxArticulationRootPropertiesCfg. For Newton-native self-collisions, see NewtonArticulationRootPropertiesCfg.

Rigid Body

class isaaclab.sim.schemas.RigidBodyBaseCfg

Solver-common properties to apply to a rigid body.

Contains properties from the UsdPhysics.RigidBodyAPI that are common across all simulation backends, plus disable_gravity whose USD attribute today is PhysX-namespaced but whose semantics (per-body gravity exclusion) are universal: PhysX honors it per-body; Newton’s importer consumes it at the scene level (partial honor, documented on the field). For PhysX-only rigid-body properties, use PhysxRigidBodyPropertiesCfg.

See modify_rigid_body_properties() for more information.

Note

If the values are None, they are not modified. This is useful when you want to set only a subset of the properties and leave the rest as-is.

Attributes:

rigid_body_enabled	Whether to enable or disable the rigid body.
kinematic_enabled	Determines whether the body is kinematic or not.
disable_gravity	Disable gravity for the body.

rigid_body_enabled: bool | None

Whether to enable or disable the rigid body.

kinematic_enabled: bool | None

Determines whether the body is kinematic or not.

A kinematic body is a body that is moved through animated poses or through user defined poses. The simulation still derives velocities for the kinematic body based on the external motion.

For more information on kinematic bodies, please refer to the documentation.

disable_gravity: bool | None

Disable gravity for the body.

PhysX honors this per-body via physxRigidBody:disableGravity: setting True excludes the body from world gravity integration.

Newton currently consumes the same USD attribute at the scene level – Newton’s importer reads physxRigidBody:disableGravity on the scene prim and uses it to drive the scene-wide builder.gravity flag (import_usd.py:1212). Per-body intent is therefore partially honored on Newton: whichever rigid body has the attribute authored ends up controlling scene-wide gravity, and other bodies cannot be selectively excluded.

The field is placed on the base because the user-facing intent (per-body gravity exclusion for markers, sensors, kinematic targets) is universal physics and PhysX honors it fully. Closing the Newton gap is a kernel-level fix (introduce Model.body_disable_gravity boolean array consumed by the integrator) that does not require a cfg-API change.

isaaclab.sim.schemas.define_rigid_body_properties(prim_path: str, cfg: schemas_cfg.RigidBodyBaseCfg, stage: Usd.Stage | None = None)

Apply the rigid body schema on the input prim and set its properties.

See modify_rigid_body_properties() for more details on how the properties are set.

Parameters:

• prim_path – The prim path where to apply the rigid body schema.

• cfg – The configuration for the rigid body.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Raises:

• ValueError – When the prim path is not valid.

• TypeError – When the prim already has conflicting API schemas.

isaaclab.sim.schemas.modify_rigid_body_properties(prim_path: str, cfg: schemas_cfg.RigidBodyBaseCfg, stage: Usd.Stage | None = None) → bool

Modify parameters for a rigid body prim.

A rigid body is a single body that can be simulated by a physics engine. It can be either dynamic or kinematic. A dynamic body responds to forces and collisions. A kinematic body can be moved by the user, but does not respond to forces.

Solver-common properties (from RigidBodyAPI) are always written. Solver-specific properties are written based on the cfg subclass metadata (_usd_namespace, _usd_applied_schema).

Note

This function is decorated with apply_nested() that sets the properties to all the prims (that have the schema applied on them) under the input prim path.

Parameters:

• prim_path – The prim path to the rigid body.

• cfg – The configuration for the rigid body. Accepts RigidBodyBaseCfg for solver-common properties, PhysxRigidBodyPropertiesCfg for PhysX properties, or MujocoRigidBodyPropertiesCfg for Newton (MuJoCo) properties.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Returns:

True if the properties were successfully set, False otherwise.

isaaclab.sim.schemas.activate_contact_sensors(prim_path: str, threshold: float = 0.0, stage: pxr.Usd.Stage = None)

Activate the contact sensor on all rigid bodies under a specified prim path.

This function adds the PhysX contact report API to all rigid bodies under the specified prim path. It also sets the force threshold beyond which the contact sensor reports the contact. The contact reporting API can only be added to rigid bodies.

Parameters:

• prim_path – The prim path under which to search and prepare contact sensors.

• threshold – The threshold for the contact sensor. Defaults to 0.0.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Raises:

• ValueError – If the input prim path is not valid.

• ValueError – If there are no rigid bodies under the prim path.

For PhysX-specific rigid body properties (damping, max velocities, solver iterations, sleep/stabilization), see PhysxRigidBodyPropertiesCfg. For MuJoCo-specific gravity compensation, see MujocoRigidBodyPropertiesCfg.

Collision

class isaaclab.sim.schemas.CollisionBaseCfg

Solver-common properties to apply to colliders.

Contains collision_enabled from the UsdPhysics.CollisionAPI and the contact_offset / rest_offset knobs whose USD attributes today are PhysX-namespaced (physxCollision:contactOffset, physxCollision:restOffset) but whose semantics (collision-pair generation distance, rest separation gap) are universal physics: PhysX consumes them natively, Newton’s importer consumes them via the PhysX bridge resolver and populates Model.shape_collision_radius / Model.shape_collision_thickness from the gap and margin keys (see import_usd.py:2104, 2111). For PhysX-only collision properties (e.g. torsional patch friction), use PhysxCollisionPropertiesCfg.

See modify_collision_properties() for more information.

Note

If the values are None, they are not modified. This is useful when you want to set only a subset of the properties and leave the rest as-is.

Attributes:

collision_enabled	Whether to enable or disable collisions.
contact_offset	Contact offset for the collision shape [m].
rest_offset	Rest offset for the collision shape [m].
mesh_collision_property	Optional mesh-collision approximation to author on this collider.

collision_enabled: bool | None

Whether to enable or disable collisions.

Writes physics:collisionEnabled via UsdPhysics.CollisionAPI.

contact_offset: float | None

Contact offset for the collision shape [m].

The collision detector generates contact points as soon as two shapes get closer than the sum of their contact offsets. This quantity should be non-negative which means that contact generation can potentially start before the shapes actually penetrate.

Writes physxCollision:contactOffset. Newton’s USD importer consumes the same attribute via its PhysX-bridge resolver.

rest_offset: float | None

Rest offset for the collision shape [m].

The rest offset quantifies how close a shape gets to others at rest, At rest, the distance between two vertically stacked objects is the sum of their rest offsets. If a pair of shapes have a positive rest offset, the shapes will be separated at rest by an air gap.

Writes physxCollision:restOffset. Newton’s USD importer consumes the same attribute via its PhysX-bridge resolver.

mesh_collision_property: MeshCollisionBaseCfg | None

Optional mesh-collision approximation to author on this collider.

When set, it is dispatched to modify_mesh_collision_properties() so the physics:approximation token (and any backend mesh-collision tuning) is written on the collision mesh prim. Use this to override a file-spawned USD asset’s authored collision approximation (e.g. convex hull / convex decomposition) — such assets otherwise expose no approximation knob through collision_props. None leaves the USD-authored approximation untouched.

isaaclab.sim.schemas.define_collision_properties(prim_path: str, cfg: schemas_cfg.CollisionPropertiesCfg, stage: Usd.Stage | None = None)

Apply the collision schema on the input prim and set its properties.

See modify_collision_properties() for more details on how the properties are set.

Parameters:

• prim_path – The prim path where to apply the rigid body schema.

• cfg – The configuration for the collider.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Raises:

ValueError – When the prim path is not valid.

isaaclab.sim.schemas.modify_collision_properties(prim_path: str, cfg: schemas_cfg.CollisionPropertiesCfg, stage: Usd.Stage | None = None) → bool

Modify PhysX properties of collider prim.

These properties are based on the UsdPhysics.CollisionAPI and PhysxSchema.PhysxCollisionAPI schemas. For more information on the properties, please refer to the official documentation.

Tuning these parameters influence the contact behavior of the rigid body. For more information on tune them and their effect on the simulation, please refer to the PhysX documentation.

Note

This function is decorated with apply_nested() that sets the properties to all the prims (that have the schema applied on them) under the input prim path.

Parameters:

• prim_path – The prim path of parent.

• cfg – The configuration for the collider.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Returns:

True if the properties were successfully set, False otherwise.

For PhysX torsional patch friction, see PhysxCollisionPropertiesCfg. For Newton-native contact margin/gap, see NewtonCollisionPropertiesCfg. For Newton SDF and hydroelastic collision configuration, see NewtonSDFCollisionPropertiesCfg.

Mass

class isaaclab.sim.schemas.MassPropertiesCfg

Properties to define explicit mass properties of a rigid body.

See modify_mass_properties() for more information.

Note

If the values are None, they are not modified. This is useful when you want to set only a subset of the properties and leave the rest as-is.

Attributes:

mass	The mass of the rigid body (in kg).
density	The density of the rigid body (in kg/m^3).

mass: float | None

The mass of the rigid body (in kg).

Note

If non-zero, the mass is ignored and the density is used to compute the mass.

density: float | None

The density of the rigid body (in kg/m^3).

The density indirectly defines the mass of the rigid body. It is generally computed using the collision approximation of the body.

isaaclab.sim.schemas.define_mass_properties(prim_path: str, cfg: schemas_cfg.MassPropertiesCfg, stage: Usd.Stage | None = None)

Apply the mass schema on the input prim and set its properties.

See modify_mass_properties() for more details on how the properties are set.

Parameters:

• prim_path – The prim path where to apply the rigid body schema.

• cfg – The configuration for the mass properties.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Raises:

ValueError – When the prim path is not valid.

isaaclab.sim.schemas.modify_mass_properties(prim_path: str, cfg: schemas_cfg.MassPropertiesCfg, stage: Usd.Stage | None = None) → bool

Set properties for the mass of a rigid body prim.

These properties are based on the UsdPhysics.MassAPI schema. If the mass is not defined, the density is used to compute the mass. However, in that case, a collision approximation of the rigid body is used to compute the density. For more information on the properties, please refer to the documentation.

Caution

The mass of an object can be specified in multiple ways and have several conflicting settings that are resolved based on precedence. Please make sure to understand the precedence rules before using this property.

Note

This function is decorated with apply_nested() that sets the properties to all the prims (that have the schema applied on them) under the input prim path.

Parameters:

• prim_path – The prim path of the rigid body.

• cfg – The configuration for the mass properties.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Returns:

True if the properties were successfully set, False otherwise.

Joint Drive

class isaaclab.sim.schemas.JointDriveBaseCfg

Solver-common properties to define the drive mechanism of a joint.

Contains properties from the UsdPhysics.DriveAPI that are common across all simulation backends, plus max_joint_velocity whose USD attribute today is PhysX-namespaced but whose semantics (per-DOF velocity limit) are universal: Newton’s importer consumes physxJoint:maxJointVelocity and populates Model.joint_velocity_limit; PhysX consumes it natively. For PhysX-only drive properties, use PhysxJointDrivePropertiesCfg.

See modify_joint_drive_properties() for more information.

Note

If the values are None, they are not modified. This is useful when you want to set only a subset of the properties and leave the rest as-is.

Attributes:

drive_type	Joint drive type to apply.
max_force	Maximum force/torque that can be applied to the joint [N for linear joints, N-m for angular joints].
max_effort	Deprecated alias for max_force.
stiffness	Stiffness of the joint drive.
damping	Damping of the joint drive.
ensure_drives_exist	If True, ensure every joint has a non-zero drive so that physics backends (e.g. Newton) create proper actuators for it.
max_joint_velocity	Maximum velocity of the joint [m/s for linear joints, rad/s for angular joints].
max_velocity	Deprecated alias for max_joint_velocity.

drive_type: Literal['force', 'acceleration'] | None

Joint drive type to apply.

If the drive type is “force”, then the joint is driven by a force. If the drive type is “acceleration”, then the joint is driven by an acceleration (usually used for kinematic joints).

max_force: float | None

Maximum force/torque that can be applied to the joint [N for linear joints, N-m for angular joints].

Writes drive:<linear|angular>:physics:maxForce via UsdPhysics.DriveAPI.

max_effort: float | None

Deprecated alias for max_force.

Deprecated since version 4.6.25: Use max_force instead. The cfg field is renamed so its snake_case name maps identity-style to the USD camelCase attribute (maxForce on UsdPhysics.DriveAPI). The alias is forwarded to max_force in __post_init__() and will be removed in 4.0.

stiffness: float | None

Stiffness of the joint drive.

The unit depends on the joint model:

• For linear joints, the unit is kg-m/s^2 (N/m).

• For angular joints, the unit is kg-m^2/s^2/rad (N-m/rad).

damping: float | None

Damping of the joint drive.

The unit depends on the joint model:

• For linear joints, the unit is kg-m/s (N-s/m).

• For angular joints, the unit is kg-m^2/s/rad (N-m-s/rad).

ensure_drives_exist: bool

If True, ensure every joint has a non-zero drive so that physics backends (e.g. Newton) create proper actuators for it.

When a USD asset defines PhysicsDriveAPI with stiffness=0 and damping=0, some backends treat the joint as passive (no PD control). Enabling this flag writes a minimal stiffness (1e-3) to any drive whose stiffness and damping are both zero, guaranteeing that the backend recognises the drive as active. The actual gains are expected to be overridden later by the actuator model.

max_joint_velocity: float | None

Maximum velocity of the joint [m/s for linear joints, rad/s for angular joints].

Notes

Today this writes physxJoint:maxJointVelocity (a PhysX add-on schema attribute). Newton’s USD importer consumes the same attribute via its PhysX-bridge resolver and populates Model.joint_velocity_limit; the PhysX engine consumes it natively. The Kamino solver honors the limit at the simulation step. The XPBD, Featherstone, and Semi-implicit Newton solvers import the value but do not consume it in their kernels; the MuJoCo (MJC) solver explicitly drops it. When Newton ships newton:maxJointVelocity as a registered applied API, the writer namespace will switch transparently and this docstring caveat will be removed.

max_velocity: float | None

Deprecated alias for max_joint_velocity.

Deprecated since version 4.6.25: Use max_joint_velocity instead. The cfg field is renamed so its snake_case name maps identity-style to the USD camelCase attribute (physxJoint:maxJointVelocity). The alias is forwarded to max_joint_velocity in __post_init__() and will be removed in 4.0.

isaaclab.sim.schemas.modify_joint_drive_properties(prim_path: str, cfg: schemas_cfg.JointDriveBaseCfg, stage: Usd.Stage | None = None) → bool

Modify parameters for a joint prim.

This function checks if the input prim is a prismatic or revolute joint and applies the joint drive schema on it. If the joint is a tendon (i.e., it has the PhysxTendonAxisAPI schema applied on it), then the joint drive schema is not applied.

Solver-common properties (from UsdPhysics.DriveAPI) are always written. Solver-specific properties are written based on the cfg subclass metadata (_usd_namespace, _usd_applied_schema).

Caution

We highly recommend modifying joint properties of articulations through the functionalities in the isaaclab.actuators module. The methods here are for setting simulation low-level properties only.

Parameters:

• prim_path – The prim path where to apply the joint drive schema.

• cfg – The configuration for the joint drive. Accepts JointDriveBaseCfg for solver-common properties, PhysxJointDrivePropertiesCfg for PhysX properties, or MujocoJointDrivePropertiesCfg for Newton (MuJoCo) properties.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Returns:

True if the properties were successfully set, False otherwise.

Raises:

ValueError – If the input prim path is not valid.

For PhysX-specific drive properties, see PhysxJointDrivePropertiesCfg. For MuJoCo actuator gravity compensation, see MujocoJointDrivePropertiesCfg.

Mesh Collision

class isaaclab.sim.schemas.MeshCollisionBaseCfg

Solver-common properties to apply to a mesh in regards to collision.

Carries only the standard UsdPhysics:MeshCollisionAPI token (mesh_approximation_name -> physics:approximation). For PhysX-cooking tunables (convex hull / decomposition / triangle mesh / SDF), use the Physx*PropertiesCfg subclasses in isaaclab_physx.sim.schemas.

See modify_mesh_collision_properties() for more information.

Note

If the values are None, they are not modified. This is useful when you want to set only a subset of the properties and leave the rest as-is.

Attributes:

mesh_approximation_name

"none".

mesh_approximation_name: str

“none”.

Writes physics:approximation via UsdPhysics.MeshCollisionAPI. Refer to schemas.MESH_APPROXIMATION_TOKENS for available options.

Type:

Name of mesh collision approximation method. Default

class isaaclab.sim.schemas.BoundingCubePropertiesCfg

Bases: MeshCollisionBaseCfg

Bounding-cube mesh collision approximation. USD-only; authors no PhysX schema.

Writes the boundingCube token to physics:approximation via UsdPhysics.MeshCollisionAPI.

Original USD Documentation: https://docs.omniverse.nvidia.com/kit/docs/omni_usd_schema_physics/latest/class_usd_physics_mesh_collision_a_p_i.html

Attributes:

mesh_approximation_name

"boundingCube".

mesh_approximation_name: str

“boundingCube”.

Type:

Name of mesh collision approximation method. Default

class isaaclab.sim.schemas.BoundingSpherePropertiesCfg

Bases: MeshCollisionBaseCfg

Bounding-sphere mesh collision approximation. USD-only; authors no PhysX schema.

Writes the boundingSphere token to physics:approximation via UsdPhysics.MeshCollisionAPI.

Original USD Documentation: https://docs.omniverse.nvidia.com/kit/docs/omni_usd_schema_physics/latest/class_usd_physics_mesh_collision_a_p_i.html

Attributes:

mesh_approximation_name

"boundingSphere".

mesh_approximation_name: str

“boundingSphere”.

Type:

Name of mesh collision approximation method. Default

isaaclab.sim.schemas.define_mesh_collision_properties(prim_path: str, cfg: schemas_cfg.MeshCollisionBaseCfg, stage: Usd.Stage | None = None)

Apply the mesh collision schema on the input prim and set its properties.

See modify_mesh_collision_properties() for more details on how the properties are set.

Parameters:

• prim_path – The prim path where to apply the mesh collision schema.

• cfg – The configuration for the mesh collision properties.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Raises:

ValueError – When the prim path is not valid.

isaaclab.sim.schemas.modify_mesh_collision_properties(prim_path: str, cfg: schemas_cfg.MeshCollisionBaseCfg, stage: Usd.Stage | None = None) → bool

Set properties for the mesh collision of a prim.

Metadata-driven writer. The standard UsdPhysics.MeshCollisionAPI is applied unconditionally (it is the carrier of the physics:approximation token). The PhysX cooking schema declared by _usd_applied_schema (e.g. PhysxConvexHullCollisionAPI) is gated on the user authoring at least one non-None namespaced tuning field, mirroring the gating used by the other consumption-gated writers (rigid body, joint drive, collision, articulation root).

Note

This function is decorated with apply_nested() that sets the properties to all the prims (that have the schema applied on them) under the input prim path.

Parameters:

• prim_path – The prim path of the rigid body. This prim should be a Mesh prim.

• cfg – The configuration for the mesh collision properties.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Returns:

True if the properties were successfully set, False otherwise.

Raises:

ValueError – When the mesh approximation name is invalid.

For PhysX cooking schemas (convex hull / decomposition / triangle mesh / SDF), see the Physx*PropertiesCfg family in isaaclab_physx.sim.schemas. For Newton hull-vertex limit, see NewtonMeshCollisionPropertiesCfg.

Tendon

isaaclab.sim.schemas.modify_fixed_tendon_properties(prim_path: str, cfg: schemas_cfg.PhysxFixedTendonPropertiesCfg, stage: Usd.Stage | None = None) → bool

Modify PhysX parameters for a fixed tendon attachment prim.

A fixed tendon can be used to link multiple degrees of freedom of articulation joints through length and limit constraints. For instance, it can be used to set up an equality constraint between a driven and passive revolute joints.

The schema comprises of attributes that belong to the PhysxTendonAxisRootAPI schema.

Note

This function is decorated with apply_nested() that sets the properties to all the prims (that have the schema applied on them) under the input prim path.

Parameters:

• prim_path – The prim path to the tendon attachment.

• cfg – The configuration for the tendon attachment.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Returns:

True if the properties were successfully set, False otherwise.

Raises:

ValueError – If the input prim path is not valid.

isaaclab.sim.schemas.modify_spatial_tendon_properties(prim_path: str, cfg: schemas_cfg.PhysxSpatialTendonPropertiesCfg, stage: Usd.Stage | None = None) → bool

Modify PhysX parameters for a spatial tendon attachment prim.

A spatial tendon can be used to link multiple degrees of freedom of articulation joints through length and limit constraints. For instance, it can be used to set up an equality constraint between a driven and passive revolute joints.

The schema comprises of attributes that belong to the PhysxTendonAxisRootAPI schema.

Note

This function is decorated with apply_nested() that sets the properties to all the prims (that have the schema applied on them) under the input prim path.

Parameters:

• prim_path – The prim path to the tendon attachment.

• cfg – The configuration for the tendon attachment.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Returns:

True if the properties were successfully set, False otherwise.

Raises:

ValueError – If the input prim path is not valid.

Tendon cfg classes are PhysX-only and live in isaaclab_physx.sim.schemas (PhysxFixedTendonPropertiesCfg, PhysxSpatialTendonPropertiesCfg).

Deformable Body

class isaaclab.sim.schemas.DeformableBodyPropertiesBaseCfg

Bases: object

Base deformable body properties for backend-specific extensions.

This class is currently empty. It will be populated once the USD deformable schemas can be unified more cleanly between physics backends.

isaaclab.sim.schemas.define_deformable_body_properties(prim_path: str, cfg: schemas_cfg.DeformableBodyPropertiesBaseCfg, stage: Usd.Stage | None = None, deformable_type: str = 'volume', sim_mesh_prim_path: str | None = None)

Apply the deformable body schema on the input prim and set its properties. The input prim should have a visual surface mesh as child. Volume deformables will have their simulation tetrahedral mesh automatically computed from the surface mesh of the input prim. Surface deformables simply copy the visual mesh as simulation mesh.

See modify_deformable_body_properties() for more details on how the properties are set.

Note

If the input prim is not a mesh, this function will traverse the prim and find the first mesh under it. If no mesh or multiple meshes are found, an error is raised. This is because the deformable body schema can only be applied to a single mesh.

Note

This function authors a new deformable body setup from scratch. It does not remove or clear existing deformable body schemas, simulation meshes, or pose data. Use modify_deformable_body_properties() to update properties on an existing deformable body, or clear any previous setup before calling this function.

Parameters:

• prim_path – The prim path where to apply the deformable body schema.

• cfg – The configuration for the deformable body.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

• deformable_type – The type of the deformable body (surface or volume). This is used to determine which USD API to use for the deformable body. Defaults to “volume”.

• sim_mesh_prim_path – Optional override for the simulation mesh creation prim path. Ignored when pre-tetrahedralized mesh is found for volume deformables. If None, it is set to {prim_path}/sim_mesh.

Raises:

• ValueError – When the prim path is not valid.

• ValueError – When the prim has no mesh or multiple meshes.

• ModuleNotFoundError – When automatic volume tetrahedralization is requested without its optional dependencies.

• RuntimeError – When setting the deformable body properties fails.

isaaclab.sim.schemas.define_deformable_curve_properties(prim_path: str, stage: Usd.Stage | None = None) → None

Apply the deformable curve simulation schema.

Parameters:

• prim_path – The path of the UsdGeom.BasisCurves prim.

• stage – The stage where the prim exists. Defaults to the current stage.

Raises:

• ValueError – If the prim path is invalid or is not a UsdGeom.BasisCurves prim.

• RuntimeError – If the schema cannot be applied.

isaaclab.sim.schemas.modify_deformable_body_properties(prim_path: str, cfg: schemas_cfg.DeformableBodyPropertiesBaseCfg, stage: Usd.Stage | None = None)

Modify deformable body parameters for a deformable body prim.

A deformable body is a single body (either surface or volume deformable) that can be simulated by PhysX or Newton. Unlike rigid bodies, deformable bodies support relative motion of the nodes in the mesh. Consequently, they can be used to simulate deformations under applied forces.

PhysX deformable body simulation employs Finite Element Analysis (FEA) to simulate the deformations of the mesh. It uses two meshes to represent the deformable body:

1. Simulation mesh: This mesh is used for the simulation and is the one that is deformed by the solver.

2. Collision mesh: This mesh only needs to match the surface of the simulation mesh and is used for collision detection.

For most applications, we assume that the above two meshes are computed from the “render mesh” of the deformable body. The render mesh is the mesh that is visible in the scene and is used for rendering purposes. It is composed of triangles, while the simulation mesh is composed of tetrahedrons for volume deformables, and triangles for surface deformables.

We apply similar design choices to the simulation in Newton with a separate visual, simulation and collision mesh.

Caution

The deformable body schema is still under development by the Omniverse team. The current implementation works with the PhysX schemas shipped with Isaac Sim 6.0.0 onwards. It may change in future releases.

Note

This function is decorated with apply_nested() that sets the properties to all the prims (that have the schema applied on them) under the input prim path.

Parameters:

• prim_path – The prim path to the deformable body.

• cfg – The configuration for the deformable body.

• stage – The stage where to find the prim. Defaults to None, in which case the current stage is used.

Returns:

True if the properties were successfully set, False otherwise.