Deformable Migration Guide#

This guide provides information on how to migrate from the removed deformable body and particle cloth schemas, APIs, helper functions, and tensor views to their replacements, and describes the limited support for automatically converting legacy USD assets.

Note

The deformable implementation is based on codeless USD schemas. See Deformable Bodies for examples on how to write code against codeless schemas in Python.

The volume and surface deformable feature set achieves near-complete feature parity with the removed deformable body and particle cloth features, with the following notable exceptions:

  • Particle cloth behavior can only be approximated using surface deformables, as the two systems are based on different underlying physical models. Particle cloth is implemented using a PBD mass-spring system, whereas surface deformables use an XPBD FEM corotational linear elasticity model.

  • The particle cloth aerodynamics model, which includes lift, drag, and wind parameters, is not supported by surface deformables.

  • Simulation of inflatables using particle cloth is not supported with surface deformables.

  • Kinematic volume deformables can only be animated by moving simulation mesh points. Animation through movement of graphical mesh points is no longer supported.

PhysX Deformable Body#

The current deformable implementation separates concerns, making the USD representation more explicit and flexible. Key points for migration:

  • Explicit representation of simulation, collision and graphical meshes as UsdGeom prims.

  • Hierarchical organization of deformable body, if multiple mesh geometries are required.

  • The rest shape is represented as attributes on the simulation mesh prim. Collision and render meshes have no rest shape.

  • Collision and render meshes are registered to the simulation mesh via bind poses.

  • Parameters for procedural generation of simulation and collision meshes are explicitly represented at the root prim of the deformable body.

  • Kinematic motion is supported for the simulation mesh only. Render-mesh–driven kinematics are not supported.

Note that the expression “deformable body” refers to “soft bodies” or “volume deformables” in the previous implementation, but in the current implementation refers to deformables, including surface deformable (or “cloth”), in general.

PhysxSchema#

PhysxDeformableAPI, PhysxDeformableBodyAPI defined in the PhysxSchema have been removed. They defined deformable simulation parameter attributes as well as attributes to define simulation and collision mesh data, all on the same graphical UsdGeom.Mesh prim that was skinned to the deformable motion when simulated. Parameters to control simulation and collision mesh generation were represented as custom attributes.

As described above, the deformable feature set represents a deformable body as a prim hierarchy employing the following USD schemas:

For an example setup, see Volume Deformable Hierarchy.

Further, the generation of simulation and collision meshes is now driven by:

For an example setup, see Auto Volume Deformable Hierarchy.

PhysxDeformableAPI:

PhysxDeformableBodyAPI:

UsdPhysics.MassAPI:

PhysxSchema.PhysxCollisionAPI:

Custom Kinematic Attributes:

  • physxDeformable:kinematicEnabled → OmniPhysicsBodyAPI, omniphysics:kinematicEnabled. Note that the current implementation only supports kinematic driven motion on the simulation mesh. Render mesh driven kinematic motion is not supported.

  • physxDeformable:collisionVertexToSimulationTetIndices → N/A

  • physxDeformable:collisionVertexToSkinTriVertexIndices → N/A

  • physxDeformable:collisionVertexToSkinTriBarycentrics → N/A

Custom Attributes for Mesh Generation:

PhysxDeformableBodyMaterialAPI:

Deformable Utils#

The previous implementation offered functions in omni.physx.scripts.deformableUtils for setting up a deformable body. Setup exclusively through USD was theoretically possible, but involved configuration of non-documented custom attributes. The current implementation improves on this and should make a custom USD setup feasible. Helper functions still simplify the setup though.

omni.physx.scripts.deformableUtils:

  • add_physx_deformable_body → set_physics_volume_deformable_body for single prim setups, and create_auto_volume_deformable_hierarchy for hierarchical setups supporting the procedural generation of simulation and collision meshes.

  • add_deformable_body_material → add_deformable_material

omni.physx.PhysXCooking:

  • cook_deformable_body_mesh → cook_auto_deformable_body, used to synchronously execute the generation of simulation and collision meshes.

Tensor API#

The following soft body tensor APIs have been removed:

  • SimulationView.create_soft_body_view

  • SimulationView.create_soft_body_material_view

  • SoftBodyView

  • SoftBodyMaterialView

Use the following APIs for volume deformable bodies instead:

  • SimulationView.create_volume_deformable_body_view

  • SimulationView.create_deformable_material_view

  • DeformableBodyView

  • DeformableMaterialView

When porting, the following should be considered:

  • An instance of DeformableBodyView can either contain surface deformable bodies or volume deformable bodies but not both. It always refers to the root prims with OmniPhysicsDeformableBodyAPI.

  • DeformableBodyView.simulation_mesh_prim_paths provides access to the corresponding simulation mesh prim paths. These will be identical to prim_paths for single prim volume deformable bodies, where the roots are identical to the simulation meshes.

  • Similarly, DeformableBodyView.collision_mesh_prim_paths provides access to the corresponding collision mesh prim paths, which may or may not be identical to the simulation mesh prim paths.

  • For volume deformable bodies, DeformableBodyView.num_nodes_per_element will always return 4, as a volume deformable simulation mesh consists of tetrahedra.

PhysX Particle Cloth#

The PhysX particle cloth feature, its Omni PhysX integration, and the related schemas have been removed. Cloth is replaced by the deformable implementation, which also supports surface deformables. The USD representation of surface deformables differs from that of volume deformables as follows:

Note

While it should be possible to port soft bodies of the previous implementation to volume deformables, while maintaining the same behavior in most cases, the same is not true when porting particle cloth to surface deformables, as they don’t share the same underlying physical model. Particle cloth was implemented based on a PBD mass-spring system, while surface deformables are implemented based on a XPBD FEM corotational linear elasticity model.

How to set up a surface deformable is shown in Surface Deformable Hierarchy and Auto Surface Deformable Hierarchy.

PhysxSchema#

PhysxParticleClothAPI has been removed. The particle system schemas it depended on remain supported for non-cloth particle simulations:

  • PhysxSchema.PhysxParticleAPI

  • PhysxSchema.PhysxParticleSystem

  • PhysxSchema.PhysxPBDMaterialAPI

When cloth is migrated, all of the above should be replaced with the deformable system. They should be kept only if used for non-cloth particles.

PhysxSchema.PhysxParticleAPI:

PhysxParticleClothAPI:

  • physxParticle:selfCollisionFilter → N/A - PhysxBaseDeformableBodyAPI, physxDeformableBody:selfCollisionFilterDistance can be used to configure the self collision filtering.

  • physxParticle:restPoints → N/A - the original positions of the render mesh vertices are now implicitly defined by the simulation mesh positions and the bind pose (OmniPhysicsDeformablePoseAPI with bindPose purpose in omniphysics:purposes and omniphysics:points).

  • physxParticle:springIndices, physxParticle:springStiffnesses, physxParticle:springDampings, physxParticle:springRestLengths → N/A - physical properties are defined through materials and the rest shape attributes of the simulation mesh.

  • physxParticle:pressure → N/A

PhysxAutoParticleClothAPI:

UsdPhysics.MassAPI:

PhysxSchema.PhysxParticleSystem:

  • particleSystemEnabled → OmniPhysicsDeformableBodyAPI, omniphysics:deformableBodyEnabled

  • simulationOwner → OmniPhysicsBodyAPI, omniphysics:simulationOwner

  • contactOffset → PhysxSchema.PhysxCollisionAPI, physxCollision:contactOffset

  • restOffset → PhysxSchema.PhysxCollisionAPI, physxCollision:restOffset

  • particleContactOffset → N/A

  • solidRestOffset → N/A

  • fluidRestOffset → N/A

  • enableCCD → PhysxBaseDeformableBodyAPI, physxDeformableBody:enableSpeculativeCCD

  • solverPositionIterationCount → PhysxBaseDeformableBodyAPI, physxDeformableBody:solverPositionIterationCount

  • maxDepenetrationVelocity → PhysxBaseDeformableBodyAPI, physxDeformableBody:maxDepenetrationVelocity

  • wind → N/A

  • maxNeighborhood → N/A

  • neighborhoodScale → N/A

  • maxVelocity → PhysxBaseDeformableBodyAPI, physxDeformableBody:maxLinearVelocity

  • globalSelfCollisionEnabled → N/A

  • nonParticleCollisionEnabled → N/A

PhysxSchema.PhysxPBDMaterialAPI:

  • physxPBDMaterial:friction → OmniPhysicsBaseMaterialAPI, omniphysics:dynamicFriction

  • physxPBDMaterial:particleFrictionScale → N/A

  • physxPBDMaterial:damping → PhysxBaseDeformableBodyAPI, physxDeformableBody:linearDamping

  • physxPBDMaterial:viscosity → N/A

  • physxPBDMaterial:vorticityConfinement → N/A

  • physxPBDMaterial:surfaceTension → N/A

  • physxPBDMaterial:cohesion → N/A

  • physxPBDMaterial:adhesion → N/A

  • physxPBDMaterial:particleAdhesionScale → N/A

  • physxPBDMaterial:adhesionOffsetScale → N/A

  • physxPBDMaterial:gravityScale → PhysxBaseDeformableBodyAPI, physxDeformableBody:disableGravity

  • physxPBDMaterial:lift, physxPBDMaterial:drag → N/A - no support for aerodynamics, but simulation velocities can be manipulated directly.

  • physxPBDMaterial:density → OmniPhysicsBaseMaterialAPI, omniphysics:density

  • physxPBDMaterial:cflCoefficient → N/A

Deformable Utils#

The previous implementation offered functions in omni.physx.scripts.particleUtils for setting up a particle cloth. Similar functionality can be found in omni.physx.scripts.deformableUtils for surface deformables.

omni.physx.scripts.particleUtils:

  • add_physx_particle_cloth → set_physics_surface_deformable_body for single prim setups, and create_auto_surface_deformable_hierarchy for hierarchical setups supporting the procedural generation of the simulation mesh.

  • add_physx_particle_cloth_with_constraints → N/A

  • add_pbd_particle_material → add_deformable_material

Tensor API#

The following particle cloth tensor APIs have been removed:

  • SimulationView.create_particle_system_view

  • SimulationView.create_particle_cloth_view

  • SimulationView.create_particle_material_view

  • ParticleSystemView

  • ParticleClothView

  • ParticleMaterialView

Use the following APIs for surface deformable bodies instead:

  • SimulationView.create_surface_deformable_body_view

  • SimulationView.create_deformable_material_view

  • DeformableBodyView

  • DeformableMaterialView

When porting, the following should be considered:

  • An instance of DeformableBodyView can either contain surface deformable bodies or volume deformable bodies but not both. It always refers to the root prims with OmniPhysicsDeformableBodyAPI.

  • DeformableBodyView.simulation_mesh_prim_paths provides access to the corresponding simulation mesh prim paths. These will be identical to prim_paths for single prim surface deformable bodies, where the roots are identical to the simulation meshes.

  • For surface deformable bodies, DeformableBodyView.collision_mesh_prim_paths will always return the same paths as simulation_mesh_prim_paths.

  • For surface deformable bodies, DeformableBodyView.num_nodes_per_element will always return 3, as a surface deformable simulation mesh consists of triangle faces.

  • An instance of DeformableMaterialView may contain both OmniPhysicsDeformableMaterialAPI and OmniPhysicsSurfaceDeformableMaterialAPI prims, however, currently only OmniPhysicsDeformableMaterialAPI attributes can be accessed.

PhysX Attachments#

The previous attachment schemas (PhysxSchema.PhysxAutoAttachmentAPI, PhysxSchema.PhysxPhysicsAttachment) have been removed. The current attachment feature is different in the following ways:

High-level attachments between deformable bodies or deformable bodies and xformable prims are implemented with low-level attachment and element collision filter schema types. This migration guide, however, focuses on high-level attachments.

See Attachments and Collision Filters for examples on how to set up low-level or high-level attachments.

PhysxSchema#

PhysxSchema.PhysxAutoAttachmentAPI, used for creating attachments based on geometric overlap, has been removed and replaced by PhysxAutoDeformableAttachmentAPI. PhysxSchema.PhysxPhysicsAttachment has been removed and replaced by multiple schema subtypes of OmniPhysicsAttachment and OmniPhysicsElementCollisionFilter.

PhysxSchema.PhysxAutoAttachmentAPI:

PhysxSchema.PhysxPhysicsAttachment:

Other attributes are automatically generated when using PhysxAutoDeformableAttachmentAPI.

Deformable Utils#

There are no utils for the legacy attachment feature. The current implementation offers omni.physx.scripts.deformableUtils.create_auto_deformable_attachment for setting up attachments, see Attaching a Volume Deformable to a Collider and Attaching a Surface Deformable to an Xformable for examples.

USD Asset Conversion#

Legacy USD assets that still use the removed deformable schemas can be converted using the Asset Validator feature in Omniverse. The UI for deformable feature conversion is described here.

The following types and API schemas have been removed; existing USD assets using them can be converted:

  • PhysxParticleClothAPI

    • PhysxParticleSystem prims are not removed. Need to be manually removed if not required anymore.

    • PhysxPBDMaterialAPI is not removed. Need to be manually removed if not required anymore.

  • PhysxDeformableBodyAPI

  • PhysxDeformableBodyMaterialAPI

  • PhysxDeformableSurfaceAPI (never officially supported)

  • PhysxDeformableSurfaceMaterialAPI (never officially supported)

  • PhysxPhysicsAttachment

    • Attachments between particle cloths and colliders/rigid bodies/world are converted.

    • Attachments between deformable bodies and colliders/rigid bodies/world are converted.

    • Attachments between deformable bodies and deformable bodies are not converted.

    • Attachments between particle cloths and deformable bodies are not converted.

  • TetrahedralMesh

Schema APIs supporting particle cloth, deformable body and attachment authoring are not supported by the converter. It is therefore recommended to recreate deformable assets for the current schemas. However, the conversion may serve as a quick reference or starting point.

The following API schemas and custom attributes supporting authoring of the removed features are not supported by the converter and will be ignored:

  • PhysxAutoParticleClothAPI

  • physxParticle:weldedTriangleIndices

  • physxParticle:weldedVerticesRemapToWeld

  • physxParticle:weldedVerticesRemapToOrig

  • physxParticle:inflatableVolume

  • physxDeformable:collisionSimplification

  • physxDeformable:collisionSimplificationRemeshing

  • physxDeformable:collisionSimplificationRemeshingResolution

  • physxDeformable:collisionSimplificationTargetTriangleCount

  • physxDeformable:collisionSimplificationForceConforming

  • physxDeformable:simulationHexahedralResolution

  • physxDeformable:numberOfTetsPerHex

  • physxDeformable:collisionVertexToSimulationTetIndices

  • physxDeformable:collisionVertexToSkinTriVertexIndices

  • physxDeformable:collisionVertexToSkinTriBarycentrics

  • physxDeformable:invMassScale