isaaclab_physx.sim.schemas

isaaclab_physx.sim.schemas#

Sub-module containing utilities for schemas used in Omniverse for PhysX backend.

Classes

DeformableBodyPropertiesCfg

Properties to apply to a deformable body.

Functions

`define_deformable_body_properties`(prim_path, cfg)	Apply the deformable body schema on the input prim and set its properties.
`modify_deformable_body_properties`(prim_path, cfg)	Modify PhysX parameters for a deformable body prim.

Deformable Body#

class isaaclab_physx.sim.schemas.DeformableBodyPropertiesCfg[source]#

Bases: OmniPhysicsPropertiesCfg, PhysXDeformableBodyPropertiesCfg, PhysXCollisionPropertiesCfg

Properties to apply to a deformable body.

A deformable body is a body that can deform under forces, both surface and volume deformables. The configuration allows users to specify the properties of the deformable body, such as the solver iteration counts, damping, and self-collision.

An FEM-based deformable body is created by providing a collision mesh and simulation mesh. The collision mesh is used for collision detection and the simulation mesh is used for simulation.

See modify_deformable_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:

`contact_offset`	Contact offset for the collision shape [m].
`rest_offset`	Rest offset for the collision shape [m].
`solver_position_iteration_count`	Number of the solver positional iterations per step.
`linear_damping`	Linear damping coefficient, in units of [1/s] and constrained to the range [0, inf).
`max_linear_velocity`	Maximum allowable linear velocity for the deformable body, in units of distance/second and constrained to the range [0, inf).
`settling_damping`	Additional damping applied when a vertex's velocity falls below `settling_threshold`.
`settling_threshold`	Velocity threshold below which `settling_damping` is applied in addition to standard damping.
`sleep_threshold`	Velocity threshold below which a vertex becomes a candidate for sleeping.
`max_depenetration_velocity`	Maximum velocity that the solver may apply to resolve intersections.
`self_collision`	Enables self-collisions for the deformable body, preventing self-intersections.
`self_collision_filter_distance`	Distance below which self-collision is disabled [m].
`enable_speculative_c_c_d`	Enables dynamic adjustment of contact offset based on velocity (speculative continuous collision detection).
`disable_gravity`	Disables gravity for the deformable body.
`collision_pair_update_frequency`	Determines how often surface-to-surface collision pairs are updated during each time step.
`collision_iteration_multiplier`	Determines how many collision subiterations are used in each solver iteration.
`deformable_body_enabled`	Enables deformable body.
`kinematic_enabled`	Enables kinematic body.
`mass`	The material mass in [kg].

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.

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.

solver_position_iteration_count: int#: Number of the solver positional iterations per step. Range is [1,255], default to 16.

linear_damping: float | None#: Linear damping coefficient, in units of [1/s] and constrained to the range [0, inf).

max_linear_velocity: float | None#: Maximum allowable linear velocity for the deformable body, in units of distance/second and constrained to the range [0, inf). A negative value allows the simulation to choose suitable a per vertex value dynamically, currently only supported for surface deformables. This can help prevent surface-surface intersections.

settling_damping: float | None#: Additional damping applied when a vertex’s velocity falls below settling_threshold. Specified in units of [1/s] and constrained to the range [0, inf).

settling_threshold: float | None#: Velocity threshold below which settling_damping is applied in addition to standard damping. Specified in units of distance/second and constrained to the range [0, inf).

sleep_threshold: float | None#: Velocity threshold below which a vertex becomes a candidate for sleeping. Specified in units of distance/seconds and constrained to the range [0, inf).

max_depenetration_velocity: float | None#: Maximum velocity that the solver may apply to resolve intersections. Specified in units of distance/seconds and constrained to the range [0, inf).

self_collision: bool | None#: Enables self-collisions for the deformable body, preventing self-intersections.

self_collision_filter_distance: float | None#

Distance below which self-collision is disabled [m].

The default value of -inf indicates that the simulation selects a suitable value. Constrained to range [rest_offset * 2, inf].

enable_speculative_c_c_d: bool | None#: Enables dynamic adjustment of contact offset based on velocity (speculative continuous collision detection).

disable_gravity: bool | None#: Disables gravity for the deformable body.

collision_pair_update_frequency: int | None#

Determines how often surface-to-surface collision pairs are updated during each time step. Increasing this value results in more frequent updates to the contact pairs, which provides better contact points.

For example, a value of 2 means collision pairs are updated twice per time step: once at the beginning and once in the middle of the time step (i.e., during the middle solver iteration). If set to 0, the solver adaptively determines when to update the surface-to-surface contact pairs, instead of using a fixed frequency.

Valid range: [1, solver_position_iteration_count].

collision_iteration_multiplier: float | None#

Determines how many collision subiterations are used in each solver iteration. By default, collision constraints are applied once per solver iteration. Increasing this value applies collision constraints more frequently within each solver iteration.

For example, a value of 2 means collision constraints are applied twice per solver iteration (i.e., collision constraints are applied 2 x solver_position_iteration_count times per time step). Increasing this value does not update collision pairs more frequently; refer to collision_pair_update_frequency for that.

Valid range: [1, solver_position_iteration_count / 2].

deformable_body_enabled: bool | None#: Enables deformable body.

kinematic_enabled: bool#: Enables kinematic body. Defaults to False, which means that the body is not kinematic.

mass: float | None#: The material mass in [kg]. Defaults to None, in which case the material density is used to compute the mass.

isaaclab_physx.sim.schemas.define_deformable_body_properties(prim_path: str, cfg: DeformableBodyPropertiesCfg, stage: Usd.Stage | None = None, deformable_type: str = 'volume', sim_mesh_prim_path: str | None = None)[source]#

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

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.

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 PhysX API to use for the deformable body. Defaults to “volume”.
sim_mesh_prim_path – Optional override for the simulation mesh prim path. If None, it is set to {prim_path}/sim_mesh for surface deformables and {prim_path}/sim_tetmesh for volume deformables.

Raises:

ValueError – When the prim path is not valid.
ValueError – When the prim has no mesh or multiple meshes.
RuntimeError – When setting the deformable body properties fails.

isaaclab_physx.sim.schemas.modify_deformable_body_properties(prim_path: str, cfg: DeformableBodyPropertiesCfg, stage: Usd.Stage | None = None)[source]#

Modify PhysX parameters for a deformable body prim.

A deformable body is a single body (either surface or volume deformable) that can be simulated by PhysX. 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:

Simulation mesh: This mesh is used for the simulation and is the one that is deformed by the solver.
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.

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.

isaaclab_physx.sim.schemas

Contents

isaaclab_physx.sim.schemas#

Deformable Body#