Collision Behavior Guide#

This guide explains how to resolve common contact quality issues and provides best practices for configuring colliders.

Settings Affecting Collision Behavior#

Contact quality issues can be fixed by adjusting the following settings:

Increase the maximum number of contacts per frame (especially when using the GPU based physics pipeline)
- When using GPU dynamics, depending on the overall complexity of your scene, the default value for the maximum number of contacts that can be processed per frame might be too low. Note that SDF colliders tend to generate many contacts. If the collision response seems to be incorrect, it is worth to try increasing the maximum number of GPU contacts in the Physics Scene. A warning will be displayed when the contact buffer does not have enough storage capacity.
Increase the contact offset
- Larger contact offsets allow the solver to react a bit earlier to collisions potentially happening in subsequent timesteps. Too large contact offsets will slow down the collision detection performance, so it’s usually an iterative process of finding a good value.
Enable speculative CCD
- Speculative CCD increases the contact offset further based on the object’s velocity. This helps to improve the collision response of fast-moving objects.
- See Configure CCD
Make objects heavier, within reasonable limits
- Objects that are extremely lightweight or if objects with very different mass come in contact, the collision response might not be perfect since those cases make convergence of the solver more difficult
Reduce the maximum depenetration velocity
- Makes the collision response a bit slower and can help to avoid overshooting.
Increase the number of position iterations
- Gives the solver more iterations to improve convergence.
Increase friction
- Helps objects in contact come to rest.
- Be careful not to violate physically reasonable ranges (e.g., only few materials have friction values higher than approximately 2.0).
Reduce the timestep of the physics simulation
- This is only recommended if all other adjustments don’t lead to good results.

Improving SDF Collision Behavior#

Use meshes with a good tessellation when generating the SDF
- Watertight triangle meshes without self intersections or other defects simplify the cooking process. In case the mesh has holes, the cooker attempts to close them, but the closing surface will be defined by the cooker.
- When two dynamic SDF mesh colliders interact, each triangle mesh will be tested against the other’s SDF. Because at most one contact is generated per triangle, collision performance between objects of vastly different sizes may yield suboptimal results if either mesh has large faces. Remeshing to create smaller triangles is helpful in such cases. Note that for static mesh colliders, their triangles may be subdivided automatically during contact generation.
Adjust the SDF resolution
- A resolution that is too low can lead to thin portions of the mesh being omitted from the SDF since it cannot fully capture them.
- A resolution that is too high can lead to increased memory consumption and somewhat slower collision detection performance.
- In most cases, a resolution of around 250 produces good results; resolutions exceeding 1000 are rarely necessary.
- In cases where an extremely high SDF resolution would be required, consider splitting the mesh into multiple parts with separate SDFs.
- Because the SDF is sampled on a regular grid, thin, shell-like structures with a thickness below about twice the grid spacing may not be represented accurately.
- When an SDF collider interacts with a static triangle mesh, each triangle of the static mesh will be tested against the dynamic collider’s SDF. The reverse cannot be done as the static trimesh does not have an SDF. Therefore, ensure that the dynamic collider has a high-quality SDF.

Example#

The following snippet shows how to set up a scene that explicitly configures the mentioned properties:

from omni.physx.scripts import physicsUtils
from pxr import UsdGeom, Gf, UsdPhysics, PhysxSchema, UsdLux, Vt
import omni.physx.scripts.utils as utils

def setupPhysicsScene(stage):
    UsdGeom.SetStageUpAxis(stage, UsdGeom.Tokens.z)
    UsdGeom.SetStageMetersPerUnit(stage, 1)
    physicsScene = UsdPhysics.Scene.Define(stage, "/World/PhysicsScene")
    physicsScene.CreateGravityDirectionAttr(Gf.Vec3f(0.0, 0.0, -1.0))
    physicsScene.CreateGravityMagnitudeAttr(9.81)
    physxSceneApi = PhysxSchema.PhysxSceneAPI.Apply(stage.GetPrimAtPath("/World/PhysicsScene"))

    # Increase the maximum number of contacts per frame
    physxSceneApi.CreateGpuMaxRigidContactCountAttr(1000000)  # Increase GPU contact count to handle complex collisions
    physxSceneApi.CreateGpuMaxRigidPatchCountAttr(100000)  # Increase GPU patch count to improve collision accuracy
    physxSceneApi.CreateTimeStepsPerSecondAttr(120)  # Increase sim frquency to 120 steps per second - contacts get recomputed at smaller time intervals
    return "/World/PhysicsScene"

def createPhysicsMaterial(stage):
    materialPath = "/World/PhysicsMaterials/ConesMaterial"
    utils.addRigidBodyMaterial(stage, materialPath, density=1000, staticFriction=0.5, dynamicFriction=0.4)  # Define the friction
    return materialPath

def createCone(stage, name, index, position, materialPath, height=1.0, radius=0.5):
    conePath = f"/World/{name}"
    coneGeom = physicsUtils.create_mesh_cone(stage, conePath, height, radius)
    coneGeom.AddTranslateOp().Set(Gf.Vec3f(*position))
    color = Vt.Vec3fArray([Gf.Vec3f(255 - 0.5 * index * 255, 0.5 * index * 255, 0)])
    coneGeom.CreateDisplayColorAttr(color)

    conePrim = stage.GetPrimAtPath(conePath)
    UsdPhysics.CollisionAPI.Apply(conePrim)
    meshCollisionApi = UsdPhysics.MeshCollisionAPI.Apply(conePrim)
    meshCollisionApi.CreateApproximationAttr().Set("sdf")  # Use SDF for collision

    # Increase the contact offset
    physxCollisionApi = PhysxSchema.PhysxCollisionAPI.Apply(conePrim)
    physxCollisionApi.CreateContactOffsetAttr().Set(0.25)  # Increase the contact offset for better collision detection, especially for fast moving objects

    # Adjust the SDF resolution
    physxSdfApi = PhysxSchema.PhysxSDFMeshCollisionAPI.Apply(conePrim)
    physxSdfApi.CreateSdfResolutionAttr().Set(200)  # Set SDF resolution to 200, balancing performance and accuracy

    # Make objects heavier, within reasonable limits
    physicsApi = UsdPhysics.RigidBodyAPI.Apply(conePrim)
    massApi = UsdPhysics.MassAPI.Apply(conePrim)
    massApi.CreateMassAttr().Set(10)  # Set masses of colliding objects to similar values - this helps to improve convergence

    # Increase the number of position iterations
    rigidBodyApi = PhysxSchema.PhysxRigidBodyAPI.Apply(conePrim)
    rigidBodyApi.CreateSolverPositionIterationCountAttr().Set(30)  # Increase position iterations for better solver convergence
    rigidBodyApi.CreateMaxDepenetrationVelocityAttr().Set(100)  # Reduce depenetration velocity to avoid violent collision responses
    rigidBodyApi.CreateEnableSpeculativeCCDAttr().Set(True)  # Enable speculative CCD - dynamically increases the contact offset based on the object's velocity

    physicsUtils.add_physics_material_to_prim(stage, conePrim, materialPath)
    return conePath

def createThreeCones(stage, materialPath):
    for i, pos in enumerate([[0.0, 0.0, 0.5], [0.0, 0.1, 2.5], [0.0, 0.2, 4.5]]):
        createCone(stage, f"Cone{i + 1}", i, pos, materialPath)

def createGroundPlane(stage):
    physicsUtils.add_ground_plane(stage, "/groundPlane", "Z", 7.5, Gf.Vec3f(0.0), Gf.Vec3f(0.5))

def createDomeLight(stage):
    domeLight = UsdLux.DomeLight.Define(stage, "/World/DomeLight")
    domeLight.CreateIntensityAttr(2000.0)
    return "/World/DomeLight"

if __name__ == "__main__":
    from omni.usd import get_context
    stage = get_context().get_stage()
    stage.GetRootLayer().Clear()
    setupPhysicsScene(stage)
    materialPath = createPhysicsMaterial(stage)
    createThreeCones(stage, materialPath)
    createGroundPlane(stage)
    createDomeLight(stage)