Deformable Migration Guide

This guide provides information on how to migrate deprecated deformable body or particle cloth schema code, helper functions in omni.physx.scripts.deformableUtils, and describes the limited support for automatically upgrading deprecated USD assets.

Note

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

PhysX Deformable Body

The new 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 deprecated implementation, but in the new implementation refers to deformables, including surface deformable (or “cloth”), in general.

PhysxSchema

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

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

• OmniPhysicsBodyAPI

• OmniPhysicsDeformableBodyAPI

• PhysxBaseDeformableBodyAPI

• OmniPhysicsVolumeDeformableSimAPI

• UsdPhysics.CollisionAPI

• PhysxSchema.PhysxCollisionAPI

For an example setup, see Volume Deformable Hierarchy.

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

• PhysxAutoDeformableBodyAPI

• PhysxAutoDeformableHexahedralMeshAPI

• PhysxAutoDeformableMeshSimplificationAPI

For an example setup, see Auto Volume Deformable Hierarchy.

PhysxSchema.PhysxDeformableAPI:

• physxDeformable:deformableEnabled → OmniPhysicsDeformableBodyAPI, omniphysics:deformableBodyEnabled

• physxDeformable:simulationOwner → OmniPhysicsBodyAPI, omniphysics:simulationOwner

• physxDeformable:solverPositionIterationCount → PhysxBaseDeformableBodyAPI, physxDeformableBody:solverPositionIterationCount

• physxDeformable:vertexVelocityDamping → PhysxBaseDeformableBodyAPI, physxDeformableBody:linearDamping

• physxDeformable:sleepDamping → PhysxBaseDeformableBodyAPI, physxDeformableBody:settlingDamping

• physxDeformable:sleepThreshold → PhysxBaseDeformableBodyAPI, physxDeformableBody:sleepThreshold

• physxDeformable:settlingThreshold → PhysxBaseDeformableBodyAPI, physxDeformableBody:settlingThreshold

• physxDeformable:maxDepenetrationVelocity → PhysxBaseDeformableBodyAPI, physxDeformableBody:maxDepenetrationVelocity

• physxDeformable:selfCollision → PhysxBaseDeformableBodyAPI, physxDeformableBody:selfCollision

• physxDeformable:selfCollisionFilterDistance → PhysxBaseDeformableBodyAPI, physxDeformableBody:selfCollisionFilterDistance

• physxDeformable:enableCCD → PhysxBaseDeformableBodyAPI, physxDeformableBody:enableSpeculativeCCD

• physxDeformable:restPoints → N/A - the deprecated restPoints specify the original positions of the render mesh vertices, which are assumed to be implicitly defined by the original positions of the simulation mesh and the bind pose (OmniPhysicsDeformablePoseAPI with bindPose purpose in omniphysics:purposes and omniphysics:points) of the simulation mesh and the render mesh.

• physxDeformable:simulationVelocities → Simulation UsdGeom.TetMesh with OmniPhysicsVolumeDeformableSimAPI, velocities

• physxDeformable:simulationIndices → Simulation UsdGeom.TetMesh with OmniPhysicsVolumeDeformableSimAPI, tetVertexIndices, omniphysics:restTetVtxIndices, both need to be set to the same indices currently.

PhysxSchema.PhysxDeformableBodyAPI:

• physxDeformable:disableGravity → PhysxBaseDeformableBodyAPI, physxDeformableBody:disableGravity

• physxDeformable:collisionIndices → Collision UsdGeom.TetMesh with UsdPhysics.CollisionAPI, tetVertexIndices

• physxDeformable:collisionPoints → Collision UsdGeom.TetMesh with UsdPhysics.CollisionAPI, points

• physxDeformable:collisionRestPoints → N/A - the deprecated collisionRestPoints specify the original positions of the collision mesh vertices, which are assumed to be implicitly defined by the original positions of the simulation mesh and the bind pose (OmniPhysicsDeformablePoseAPI with bindPose purpose in omniphysics:purposes and omniphysics:points) of the simulation mesh and the collision mesh.

• physxDeformable:simulationPoints → Simulation UsdGeom.TetMesh with OmniPhysicsVolumeDeformableSimAPI, points

• physxDeformable:simulationRestPoints → OmniPhysicsVolumeDeformableSimAPI, omniphysics:restShapePoints

UsdPhysics.MassAPI:

• mass → OmniPhysicsDeformableBodyAPI, omniphysics:mass

• density → N/A - density can still be expressed through material.

PhysxSchema.PhysxCollisionAPI:

• physxCollision:contactOffset, physxCollision:restOffset → are now applied to UsdGeom.TetMesh with UsdPhysics.CollisionAPI.

Custom Kinematic Attributes:

• physxDeformable:kinematicEnabled → OmniPhysicsBodyAPI, omniphysics:kinematicEnabled. Note that the new schema 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:

• physxDeformable:simulationHexahedralResolution → PhysxAutoDeformableHexahedralMeshAPI, physxDeformableBody:resolution

• physxDeformable:collisionSimplification → PhysxAutoDeformableMeshSimplificationAPI, physxDeformableBody:autoDeformableMeshSimplificationEnabled

• physxDeformable:collisionSimplificationResolution → PhysxAutoDeformableMeshSimplificationAPI, physxDeformableBody:remeshingEnabled

• physxDeformable:collisionSimplificationRemeshingResolution → PhysxAutoDeformableMeshSimplificationAPI, physxDeformableBody:remeshingResolution

• physxDeformable:collisionSimplificationTargetTriangleCount → PhysxAutoDeformableMeshSimplificationAPI, physxDeformableBody:targetTriangleCount

• physxDeformable:collisionSimplificationForceConforming → PhysxAutoDeformableMeshSimplificationAPI, physxDeformableBody:forceConforming

PhysxSchema.PhysxDeformableBodyMaterialAPI:

• physxDeformableBodyMaterial:density → OmniPhysicsBaseMaterialAPI, omniphysics:density

• physxDeformableBodyMaterial:dynamicFriction → OmniPhysicsBaseMaterialAPI, omniphysics:dynamicFriction

• physxDeformableBodyMaterial:youngsModulus → OmniPhysicsDeformableMaterialAPI, omniphysics:youngsModulus

• physxDeformableBodyMaterial:poissonsRatio → OmniPhysicsDeformableMaterialAPI, omniphysics:poissonsRatio

• physxDeformableBodyMaterial:elasticityDamping → PhysxDeformableMaterialAPI, physxDeformableMaterial:elasticityDamping

• physxDeformableBodyMaterial:dampingScale → N/A

Deformable Utils

The deprecated implementation offers functions in omni.physx.scripts.deformableUtils for setting up a deformable body. Setup exclusively through USD is theoretically possible, but involves configuration of non-documented custom attributes. The new 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

Soft body APIs in Omni Physics Tensors are deprecated:

• SimulationView.create_soft_body_view

• SimulationView.create_soft_body_material_view

• SoftBodyView

• SoftBodyMaterialView

These APIs should all be replaced with the following APIs supporting the new volume deformable bodies:

• SimulationView.create_volume_deformable_body_view

• SimulationView.create_deformable_material_view

• VolumeDeformableBodyView

• DeformableMaterialView

When porting to the new APIs, 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 schema are deprecated. Cloth is replaced by the new deformable implementation, which also supports surface deformables. The USD representation of surface deformables differs from that of volume deformables as follows:

• The simulation mesh is represented as a UsdGeom.Mesh, limited to triangle faces, with OmniPhysicsSurfaceDeformableSimAPI.

• The simulation mesh always doubles as the collision mesh.

• Kinematic motion is currently not supported.

Note

While it should be possible to port soft bodies of the deprecated implementation to the new 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 is 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

PhysxSchema.PhysxParticleClothAPI is deprecated. 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 new deformable system. They should be kept only if used for non-cloth particles.

PhysxSchema.PhysxParticleAPI:

• physxParticle:particleEnabled → OmniPhysicsDeformableBodyAPI, omniphysics:deformableBodyEnabled

• physxParticle:particleSystem → N/A

• physxParticle:selfCollision → PhysxBaseDeformableBodyAPI, physxDeformableBody:selfCollision

• physxParticle:particleGroup → N/A - |UsdCollisionGroupAPI|_ and |UsdFilteredPairsAPI|_ can be used to configure collision filtering.

PhysxSchema.PhysxParticleClothAPI:

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

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

• 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

PhysxSchema.PhysxAutoParticleClothAPI:

• physxAutoParticleCloth:springBendStiffness → OmniPhysicsSurfaceDeformableMaterialAPI, omniphysics:surfaceBendStiffness

• physxAutoParticleCloth:springStretchStiffness, physxAutoParticleCloth:springShearStiffness → OmniPhysicsDeformableMaterialAPI and OmniPhysicsSurfaceDeformableMaterialAPI, omniphysics:surfaceThickness, omniphysics:youngsModulus, omniphysics:poissonsRatio - omniphysics:surfaceStretchStiffness is currently not supported

• physxAutoParticleCloth:springDamping → PhysxDeformableMaterialAPI, physxDeformableMaterial:elasticityDamping

• physxAutoParticleCloth:disableMeshWelding → N/A

UsdPhysics.MassAPI:

• mass → OmniPhysicsDeformableBodyAPI, omniphysics:mass

• density → N/A - density can still be expressed through material.

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 deprecated implementation offers 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

Particle cloth APIs in Omni Physics Tensors are deprecated:

• SimulationView.create_particle_system_view

• SimulationView.create_particle_cloth_view

• SimulationView.create_particle_material_view

• ParticleSystemView

• ParticleClothView

• ParticleMaterialView

These APIs exclusively support particle cloth and should all be replaced with the following APIs supporting surface deformable bodies:

• SimulationView.create_surface_deformable_body_view

• SimulationView.create_deformable_material_view

• DeformableBodyView

• DeformableMaterialView

When porting to the new APIs, 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 new attachment feature is different from the deprecated one in the following ways:

• Generation of attachments and filters are now represented as a high-level attachment schema API that links

  • deformable root prim with OmniPhysicsDeformableBodyAPI and another deformable root prim

  • deformable root prim with OmniPhysicsDeformableBodyAPI and a UsdGeom.Xformable (for example a prim with UsdPhysics.CollisionAPI)

• Poisson sampling based attachment points along rigid surfaces are currently not supported.

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 replaced by PhysxAutoDeformableAttachmentAPI. PhysxSchema.PhysxPhysicsAttachment has been replaced by multiple schema subtypes of OmniPhysicsAttachment and OmniPhysicsElementCollisionFilter.

PhysxSchema.PhysxAutoAttachmentAPI:

• physxAutoAttachment:enableDeformableVertexAttachments → PhysxAutoDeformableAttachmentAPI, physxAutoDeformableAttachment:enableDeformableVertexAttachments

• physxAutoAttachment:deformableVertexOverlapOffset → PhysxAutoDeformableAttachmentAPI, physxAutoDeformableAttachment:deformableVertexOverlapOffset

• physxAutoAttachment:enableRigidSurfaceAttachments → PhysxAutoDeformableAttachmentAPI, physxAutoDeformableAttachment:enableRigidSurfaceAttachments

• physxAutoAttachment:rigidSurfaceSamplingDistance → PhysxAutoDeformableAttachmentAPI, physxAutoDeformableAttachment:rigidSurfaceSamplingDistance

• physxAutoAttachment:enableCollisionFiltering → PhysxAutoDeformableAttachmentAPI, physxAutoDeformableAttachment:enableCollisionFiltering

• physxAutoAttachment:collisionFilteringOffset → PhysxAutoDeformableAttachmentAPI, physxAutoDeformableAttachment:collisionFilteringOffset

• physxAutoAttachment:enableDeformableFilteringPairs → PhysxAutoDeformableAttachmentAPI, physxAutoDeformableAttachment:enableDeformableFilteringPairs

PhysxSchema.PhysxPhysicsAttachment:

• attachmentEnabled → N/A - but can be expressed through low-level OmniPhysicsAttachment, attachmentEnabled and OmniPhysicsElementCollisionFilter, filterEnabled

• actor0, actor1 → PhysxAutoDeformableAttachmentAPI, physxAutoDeformableAttachment:attachable0, physxAutoDeformableAttachment:attachable1 (referring to deformable root prims with OmniPhysicsDeformableBodyAPI or UsdGeom.Xformable prims)

Other attributes are automatically generated when using PhysxAutoDeformableAttachmentAPI.

Deformable Utils

There are no utils for the legacy attachment feature. The new 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

Deprecated 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 are deprecated and 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 currently not supported. It is therefore recommended to recreate deformable assets for the new schemas. However, the conversion may serve as quick workaround, reference or starting point.

The following API schemas and custom attributes supporting authoring of the deprecated features are currently not supported 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