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(dtype=wp.vec3us)) – Block coordinates for each shape’s SDF representation.

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

  • shape_material_kh (wp.array(dtype=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

Use _from_model() to construct from a simulation Model, which automatically extracts the required SDF data and shape information.

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, margin_contact_area=0.01, pre_prune_accumulate_all_penetrating_aggregates=False)#

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, margin_contact_area=0.01, pre_prune_accumulate_all_penetrating_aggregates=False)#
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.

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_accumulate_all_penetrating_aggregates: bool = False#

When pre-pruning is enabled, also accumulate aggregate force terms from all penetrating faces before pruning writes to the contact buffer.

This preserves aggregate stiffness/normal/anchor fidelity while keeping the fast local compaction path for contact storage. The default keeps the current fastest behavior (aggregates from retained contacts only).

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: array(ndim=1, dtype=float32)#

Penetration depth at each face centroid.

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

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

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

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

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

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 config.output_contact_surface is False.

Return type:

ContactSurfaceData | None

launch(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.

Parameters:

  • sdf_data (array(ndim=1, dtype=newton._src.geometry.sdf_utils.SDFData)) – Compact SDF table.

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

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

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

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

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

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

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

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

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