newton.geometry.HydroelasticSDF#

class newton.geometry.HydroelasticSDF(num_shape_pairs, total_num_tiles, max_num_blocks_per_shape, shape_sdf_block_coords, shape_sdf_shape2blocks, shape_material_kh, n_shapes, config=None, device=None, writer_func=None)[source]#

Bases: object

Hydroelastic contact generation with SDF-based collision detection.

This class implements hydroelastic contact modeling between shapes represented by Signed Distance Fields (SDFs). It uses an octree-based broadphase to identify potentially colliding regions, then applies marching cubes to extract the zero-isosurface where both SDFs intersect. Contact points are generated at triangle centroids on this isosurface, with contact forces proportional to penetration depth and represented area.

The collision pipeline consists of:

  1. Broadphase: Identifies overlapping OBBs of SDF between shape pairs

  2. Octree refinement: Hierarchically subdivides blocks to find iso-voxels

  3. Marching cubes: Extracts contact surface triangles from iso-voxels

  4. Contact generation: Computes contact points, normals, depths, and areas

  5. Optional contact reduction: Bins and reduces contacts per shape pair

Parameters:

  • num_shape_pairs (int) – Maximum number of hydroelastic shape pairs to process.

  • total_num_tiles (int) – Total number of SDF blocks across all hydroelastic shapes.

  • max_num_blocks_per_shape (int) – Maximum block count for any single shape.

  • shape_sdf_block_coords (wp.array[wp.vec3us]) – Block coordinates for each shape’s SDF representation.

  • shape_sdf_shape2blocks (wp.array[wp.vec2i]) – Mapping from shape index to (start, end) block range.

  • shape_material_kh (wp.array[wp.float32]) – Hydroelastic stiffness coefficient for each shape.

  • n_shapes (int) – Total number of shapes in the simulation.

  • config (HydroelasticSDF.Config | None) – Configuration options controlling buffer sizes, contact reduction, and other behavior. Defaults to HydroelasticSDF.Config.

  • device (Devicelike | None) – Warp device for GPU computation.

  • writer_func (Any) – Callback for writing decoded contact data.

Note

Instances are typically created internally by the collision pipeline (via collide()) rather than constructed directly. The pipeline automatically extracts the required SDF data and shape information from the simulation Model.

Contact IDs are packed into 32-bit integers using 9 bits per voxel axis coordinate. For SDF grids larger than 512 voxels per axis, contact ID collisions may occur, which can affect contact matching accuracy for warm-starting physics solvers.

See also

HydroelasticSDF.Config: Configuration options for this class.

class Config(reduce_contacts=True, pre_prune_contacts=True, buffer_fraction=1.0, buffer_mult_broad=1, buffer_mult_iso=1, buffer_mult_contact=1, contact_buffer_fraction=0.5, grid_size=262144, output_contact_surface=False, normal_matching=True, anchor_contact=False, moment_matching=False, margin_contact_area=0.01)#

Bases: object

Controls properties of SDF hydroelastic collision handling.

__init__(reduce_contacts=True, pre_prune_contacts=True, buffer_fraction=1.0, buffer_mult_broad=1, buffer_mult_iso=1, buffer_mult_contact=1, contact_buffer_fraction=0.5, grid_size=262144, output_contact_surface=False, normal_matching=True, anchor_contact=False, moment_matching=False, margin_contact_area=0.01)#
anchor_contact: bool = False#

Whether to add an anchor contact at the center of pressure for each normal bin. The anchor contact helps preserve moment balance. Only active when reduce_contacts is True.

buffer_fraction: float = 1.0#

(0, 1].

This scales pre-allocated broadphase, iso-refinement, and face-contact buffers before applying stage multipliers. Lower values reduce memory usage and may cause overflows in dense scenes. Overflows are bounds-safe and emit warnings; increase this value when warnings appear.

Type:

Fraction of worst-case hydroelastic buffer allocations. Range

buffer_mult_broad: int = 1#

Multiplier for the preallocated broadphase buffer that stores overlapping block pairs. Increase only if a broadphase overflow warning is issued.

buffer_mult_contact: int = 1#

Multiplier for the preallocated face contact buffer that stores contact positions, normals, depths, and areas. Increase only if a face contact overflow warning is issued.

buffer_mult_iso: int = 1#

Multiplier for preallocated iso-surface extraction buffers used during hierarchical octree refinement (subblocks and voxels). Increase only if an iso buffer overflow warning is issued.

contact_buffer_fraction: float = 0.5#

Fraction of the face contact buffer to allocate when reduce_contacts is True. The reduce kernel selects winners from whatever fits in the buffer, so a smaller buffer trades off coverage for memory savings. Range: (0, 1]. Only applied when reduce_contacts is enabled; ignored otherwise.

grid_size: int = 262144#

Grid size for contact handling. Can be tuned for performance.

margin_contact_area: float = 0.01#

Contact area used for non-penetrating contacts at the margin.

moment_matching: bool = False#

Whether to adjust per-contact friction scales so that the maximum friction moment per normal bin is preserved between reduced and unreduced contacts. Automatically enables anchor_contact. Only active when reduce_contacts is True.

normal_matching: bool = True#

Whether to rotate reduced contact normals so their weighted sum aligns with the aggregate force direction. Only active when reduce_contacts is True.

output_contact_surface: bool = False#

Whether to output hydroelastic contact surface vertices for visualization.

pre_prune_contacts: bool = True#

Whether to perform local-first face compaction during generation. This mode avoids global hashtable traffic in the hot generation loop and writes a smaller contact set to the buffer before the normal reduce pass. Only active when reduce_contacts is True.

reduce_contacts: bool = True#

Whether to reduce contacts to a smaller representative set per shape pair. When False, all generated contacts are passed through without reduction.

class ContactSurfaceData(contact_surface_point, contact_surface_depth, contact_surface_shape_pair, face_contact_count, max_num_face_contacts)#

Bases: object

Data container for hydroelastic contact surface visualization.

Contains the vertex arrays and metadata needed for rendering the contact surface triangles from hydroelastic collision detection.

__init__(contact_surface_point, contact_surface_depth, contact_surface_shape_pair, face_contact_count, max_num_face_contacts)#
contact_surface_depth: wp.array(dtype=wp.float32, ndim=1)#

Penetration depth at each face centroid.

contact_surface_point: wp.array(dtype=wp.vec3f, ndim=1)#

World-space positions of contact surface triangle vertices (3 per face).

contact_surface_shape_pair: wp.array(dtype=wp.vec2i, ndim=1)#

Shape pair indices (shape_a, shape_b) for each face.

face_contact_count: wp.array(dtype=wp.int32, ndim=1)#

Array containing the number of face contacts.

max_num_face_contacts: int#

Maximum number of face contacts (buffer size).

__init__(num_shape_pairs, total_num_tiles, max_num_blocks_per_shape, shape_sdf_block_coords, shape_sdf_shape2blocks, shape_material_kh, n_shapes, config=None, device=None, writer_func=None)#
get_contact_surface()#

Get hydroelastic ContactSurfaceData for visualization.

Returns:

A ContactSurfaceData instance containing vertex arrays and metadata for rendering, or None if output_contact_surface is False.

Return type:

ContactSurfaceData | None

launch(texture_sdf_data, shape_sdf_index, shape_transform, shape_gap, shape_collision_aabb_lower, shape_collision_aabb_upper, shape_voxel_resolution, shape_pairs_sdf_sdf, shape_pairs_sdf_sdf_count, writer_data)#

Run the full hydroelastic collision pipeline.

All internal kernel launches use record_tape=False so that this method is safe to call inside a warp.Tape context.

Parameters:

  • texture_sdf_data (wp.array(dtype=TextureSDFData, ndim=1)) – Compact texture SDF table.

  • shape_sdf_index (wp.array(dtype=wp.int32, ndim=1)) – Per-shape SDF index into texture_sdf_data.

  • shape_transform (wp.array(dtype=wp.transformf, ndim=1)) – World transforms for each shape.

  • shape_gap (wp.array(dtype=wp.float32, ndim=1)) – Per-shape contact gap (detection threshold) for each shape.

  • shape_collision_aabb_lower (wp.array(dtype=wp.vec3f, ndim=1)) – Per-shape collision AABB lower bounds.

  • shape_collision_aabb_upper (wp.array(dtype=wp.vec3f, ndim=1)) – Per-shape collision AABB upper bounds.

  • shape_voxel_resolution (wp.array(dtype=wp.vec3i, ndim=1)) – Per-shape voxel grid resolution.

  • shape_pairs_sdf_sdf (wp.array(dtype=wp.vec2i, ndim=1)) – Pairs of shape indices to check for collision.

  • shape_pairs_sdf_sdf_count (wp.array(dtype=wp.int32, ndim=1)) – Number of valid shape pairs.

  • writer_data (Any) – Contact data writer for output.