Physx Deformable Schema#

The Physx deformable schemas are defined in the PhysX Schema Addition and provide:

  • Additional paramters for the simulation in PhysX

  • Parameters to control the generation of simulation and collision mesh geometry

  • Parameters to control the generation of attachments and collision filters

PhysxBaseDeformableBodyAPI#

PhysxBaseDeformableBodyAPI extends OmniPhysicsDeformableBodyAPI. It provides additional parameters for simulating volume and surface deformables in PhysX.

class "PhysxBaseDeformableBodyAPI"
(
    inherits = </APISchemaBase>
)
{
    uint physxDeformableBody:solverPositionIterationCount = 16 ()
    float physxDeformableBody:linearDamping = 0.0 ()
    float physxDeformableBody:maxLinearVelocity = inf ()
    float physxDeformableBody:settlingDamping = 10.0 ()
    float physxDeformableBody:settlingThreshold = 0.10 ()
    float physxDeformableBody:sleepThreshold = 0.05 ()
    float physxDeformableBody:maxDepenetrationVelocity = inf ()
    bool physxDeformableBody:selfCollision = False ()
    float physxDeformableBody:selfCollisionFilterDistance = -inf ()
    bool physxDeformableBody:enableSpeculativeCCD = False ()
    bool physxDeformableBody:disableGravity = False ()
}

  • solverPositionIterationCount: Number of solver position iterations per time step. Valid range: [1, 255].

  • linearDamping: Linear damping coefficient, in units of 1/seconds and constrainted to the range [0, inf).

  • maxLinearVelocity: 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.

  • settlingDamping: Additional damping applied when a vertex’s velocity falls below settlingThreshold. Specified in units of 1/seconds and constraint to the range [0, inf).

  • settlingThreshold: Velocity threshold below which settlingDamping is applied in addition to standard damping. Specified in units of distance/seconds and constraint to the range [0, inf).

  • sleepThreshold: Velocity threshold below which a vertex becomes a candidate for sleeping. Specified in units of distance/seconds and constraint to the range [0, inf).

  • maxDepenetrationVelocity: Maximum velocity that the solver may apply to resolve intersections. Specified in units of distance/seconds and constraint to the range [0, inf).

  • selfCollision: Enables self-collisions for the deformable body, preventing self-intersections.

  • selfCollisionFilterDistance: Distance below which self-collision is disabled. The default value of -inf indicates that the simulation selects a suitable value. Specified in units of distance and constraint to the range [restOffset * 2, inf].

  • enableSpeculativeCCD: Enables dynamic adjustment of the contact offset based on velocity (speculative continuous colision detection).

  • disableGravity: Disables gravity for the deformable body.

PhysxSurfaceDeformableBodyAPI#

PhysxSurfaceDeformableBodyAPI extends OmniPhysicsDeformableBodyAPI and PhysxBaseDeformableBodyAPI. It provides additional parameters for simulating surface deformables in PhysX.

class "PhysxSurfaceDeformableBodyAPI"
(
    inherits = </APISchemaBase>
    prepend apiSchemas = ["PhysxBaseDeformableBodyAPI"]
)
{
    uint physxDeformableBody:collisionPairUpdateFrequency = 1 ()
    uint physxDeformableBody:collisionIterationMultiplier = 1 ()
}

  • collisionPairUpdateFrequency: 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, solverPositionIterationCount].

  • collisionIterationMultiplier: 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 solverPositionIterationCount times per time step). Increasing this value does not update collision pairs more frequently; refer to collisionPairUpdateFrequency for that. Valid range: [1, solverPositionIterationCount / 2].

PhysxDeformableMaterialAPI#

PhysxDeformableMaterialAPI extends OmniPhysicsDeformableMaterialAPI. It provides additional properties for deformable materials in PhysX.

class "PhysxDeformableMaterialAPI"
(
    inherits = </APISchemaBase>
)
{
    float physxDeformableMaterial:elasticityDamping = 0.0 ()
}

  • elasticityDamping: Damping acting against elasticity forces. Specified in units of 1/seconds and constraint to the range [0, inf).

PhysxSurfaceDeformableMaterialAPI#

PhysxSurfaceDeformableMaterialAPI extends OmniPhysicsSurfaceDeformableMaterialAPI and PhysxDeformableMaterialAPI. It provides additional properties for surface deformable materials in PhysX.

class "PhysxSurfaceDeformableMaterialAPI"
(
    inherits = </APISchemaBase>
    prepend apiSchemas = ["PhysxDeformableMaterialAPI"]
)
{
    float physxDeformableMaterial:bendDamping = 0.0 ()
}

  • bendDamping: Damping acting against bend-resistance forces. Specified in units of 1/seconds and constraint to the range [0, inf).

PhysxAutoDeformableBodyAPI#

PhysxAutoDeformableBodyAPI is used to mark up a UsdGeom.Xformable prim with OmniPhysicsDeformableBodyAPI for automatic, parameter driven generation of simulation and collision mesh geometry. By default, a suitable simulation mesh is generated based on the UsdGeom.Mesh specified by the cookingSourceMesh relationship. The resulting mesh is configured to be used for collision as well. If the source mesh contains too much detail, PhysxAutoDeformableMeshSimplificationAPI can be used. PhysxAutoDeformableHexahedralMeshAPI can be used for volume deformables that should be represented using two UsdGeom.TetMesh meshes, one optimized for dynamics and one for collision. After configuring the auto generation, OmniPhysics will generate the necessary mesh data before the simulation starts. However, all necessary prims and APIs need to be prepared by the application, which is covered for example in Auto Volume Deformable Hierarchy.

class "PhysxAutoDeformableBodyAPI"
(
    inherits = </APISchemaBase>
)
{
    bool physxDeformableBody:autoDeformableBodyEnabled = true ()
    rel physxDeformableBody:cookingSourceMesh ()
}

  • autoDeformableBodyEnabled: Determines whether automatic mesh generation is enabled.

  • cookingSourceMesh: Relationship to a single UsdGeom.Mesh prim that is used to generate the simulation and collision mesh geometry. The source mesh can reside outside of the deformable body hierachy. This is useful if the source mesh is not intended to be used for the graphical representation of the deformable body, but other more suitable render meshes are available.

PhysxAutoDeformableMeshSimplificationAPI#

PhysxAutoDeformableMeshSimplificationAPI extends PhysxAutoDeformableBodyAPI and specifies parameters related to mesh geometry simplification. The simplification process is applied to the cooking source mesh specified by PhysxAutoDeformableBodyAPI.

class "PhysxAutoDeformableMeshSimplificationAPI"
(
    inherits = </APISchemaBase>
)
{
    bool physxDeformableBody:autoDeformableMeshSimplificationEnabled = true ()
    bool physxDeformableBody:remeshingEnabled = true ()
    uint physxDeformableBody:remeshingResolution = 0 ()
    uint physxDeformableBody:targetTriangleCount = 0 ()
    bool physxDeformableBody:forceConforming = false ()
}

  • autoDeformableMeshSimplificationEnabled: Determines whether mesh simplification is enabled.

  • remeshingEnabled: Determines whether remeshing is enabled.

  • remeshingResolution: Remeshing resolution, 0 indicates that the resolution is automatically determined.

  • targetTriangleCount: Target triangle count, 0 indicates that the target count is automatically determined.

  • forceConforming: Determines whether to force conformation with triangle surface. This parameter only affects the mesh geometry generation for volume deformable bodies.

PhysxAutoDeformableHexahedralMeshAPI#

PhysxAutoDeformableHexahedralMeshAPI extends PhysxAutoDeformableBodyAPI and specifies parameters related to volume deformable hexahedral simulation mesh generation.

class "PhysxAutoDeformableHexahedralMeshAPI"
(
    inherits = </APISchemaBase>
    prepend apiSchemas = ["PhysxDeformableMaterialAPI"]
)
{
    uint physxDeformableBody:resolution = 0 ()
}

  • resolution: The number of hexahedral elements along the longest edge of the simulation mesh. A value of 0 indicates that the resolution is automatically determined.

PhysxAutoDeformableAttachmentAPI#

PhysxAutoDeformableAttachmentAPI is applied to a UsdGeom.Imageable prim, usually a UsdGeom.Scope, and represents a high level attachment between two deformable bodies or a deformable body and an xformable prim, based on geometric overlap. The attachment is implemented by setting up low level attachments (e.g.: OmniPhysicsVtxVtxAttachment) and filters (OmniPhysicsElementCollisionFilter) child prims. OmniPhysics will setup the attachment and filter data before the simulation starts. However, all necessary prims need to be prepared by the application, which is covered in Attachments and Collision Filters.

class "PhysxAutoDeformableMeshSimplificationAPI"
(
    inherits = </APISchemaBase>
)
{
    rel physxAutoDeformableAttachment:attachable0 ()
    rel physxAutoDeformableAttachment:attachable1 ()
    bool physxAutoDeformableAttachment:enableDeformableVertexAttachments = true ()
    float physxAutoDeformableAttachment:deformableVertexOverlapOffset = 0.0 ()
    bool physxAutoDeformableAttachment:enableRigidSurfaceAttachments = false ()
    float physxAutoDeformableAttachment:rigidSurfaceSamplingDistance = -inf ()
    bool physxAutoDeformableAttachment:enableCollisionFiltering = true ()
    float physxAutoDeformableAttachment:collisionFilteringOffset = -inf ()
    rel physxAutoDeformableAttachment:maskShapes ()
    bool physxAutoDeformableAttachment:enableDeformableFilteringPairs = false ()
}

  • attachable0: Relationship to a prim which is either a UsdGeom.Xformable prim or has a OmniPhysicsDeformableBodyAPI. Either attachable0 or attachable1 needs to have a OmniPhysicsDeformableBodyAPI.

  • attachable1: Relationship to a prim which is either a UsdGeom.Xformable prim or has a OmniPhysicsDeformableBodyAPI. Either attachable0 or attachable1 needs to have a OmniPhysicsDeformableBodyAPI.

  • enableDeformableVertexAttachments: Enables attaching deformable mesh vertices which overlap with the other actor’s volume.

  • deformableVertexOverlapOffset: Deformable mesh vertices are attached if their distance to the other actor’s volume is smaller than the offset.

  • enableRigidSurfaceAttachments: Enables sampling attachment points on the rigid actor’s surface.

  • rigidSurfaceSamplingDistance: Sampling distance for attachment points on the rigid surface.

  • enableCollisionFiltering: Enables adding collision filtering in the vicinity of the attachment points.

  • collisionFilteringOffset: Filtering ids are generated for deformable mesh vertices if their distance to the other actor’s volume is smaller than the offset.

  • maskShapes: Relationship to UsdGeom.Sphere , UsdGeom.Box or UsdGeom.Capsule geometries. The union of the shapes defines a mask volume within which attachment points are generated.

  • enableDeformableFilteringPairs: Enables geometry pair based collision filtering for deformable-deformable attachments. By default a filtered geometry of one actor is filtered against all geometries of the other actor.