newton.geometry.NarrowPhase#

class newton.geometry.NarrowPhase(*, max_candidate_pairs, max_triangle_pairs=1000000, max_heightfield_cell_pairs=1000000, reduce_contacts=True, device=None, shape_aabb_lower=None, shape_aabb_upper=None, shape_voxel_resolution=None, contact_writer_warp_func=None, hydroelastic_sdf=None, has_meshes=True, has_heightfields=False)[source]#

Bases: object

Resolve broad-phase shape pairs into simulation contacts.

This class orchestrates the narrow-phase collision pipeline by launching the appropriate Warp kernels for primitive, mesh, heightfield, and SDF shape pairs. It owns the intermediate counters and pair buffers used while processing candidate pairs, then writes final contacts through a configurable contact writer function.

__init__(*, max_candidate_pairs, max_triangle_pairs=1000000, max_heightfield_cell_pairs=1000000, reduce_contacts=True, device=None, shape_aabb_lower=None, shape_aabb_upper=None, shape_voxel_resolution=None, contact_writer_warp_func=None, hydroelastic_sdf=None, has_meshes=True, has_heightfields=False)#

Initialize NarrowPhase with pre-allocated buffers.

Parameters:

  • max_candidate_pairs (int) – Maximum number of candidate pairs from broad phase

  • max_triangle_pairs (int) – Maximum number of mesh triangle pairs (conservative estimate)

  • max_heightfield_cell_pairs (int) – Maximum number of heightfield cell pairs generated by the heightfield midphase.

  • reduce_contacts (bool) – Whether to reduce contacts for mesh-mesh and mesh-plane collisions. When True, uses shared memory contact reduction to select representative contacts. This improves performance and stability for meshes with many vertices. Defaults to True.

  • device (Devicelike | None) – Device to allocate buffers on

  • shape_aabb_lower (wp.array(dtype=wp.vec3) | None) – Optional external AABB lower bounds array (if provided, AABBs won’t be computed internally)

  • shape_aabb_upper (wp.array(dtype=wp.vec3) | None) – Optional external AABB upper bounds array (if provided, AABBs won’t be computed internally)

  • shape_voxel_resolution (wp.array(dtype=wp.vec3i) | None) – Optional per-shape voxel resolution array used for mesh/SDF and hydroelastic contact processing.

  • contact_writer_warp_func (Any | None) – Optional custom contact writer function (first arg: ContactData, second arg: custom struct type)

  • hydroelastic_sdf (HydroelasticSDF | None) – Optional SDF hydroelastic instance. Set is_hydroelastic=True on shapes to enable hydroelastic collisions.

  • has_meshes (bool) – Whether the scene contains any mesh shapes (GeoType.MESH). When False, mesh-related kernel launches are skipped, improving performance for scenes with only primitive shapes. Defaults to True for safety. Set to False when constructing from a model with no meshes.

  • has_heightfields (bool) – Whether the scene contains any heightfield shapes (GeoType.HFIELD). When True, heightfield collision buffers and kernels are allocated. Defaults to False.

launch(*, candidate_pair, candidate_pair_count, shape_types, shape_data, shape_transform, shape_source, sdf_data=None, shape_sdf_index=None, shape_gap, shape_collision_radius, shape_flags, shape_collision_aabb_lower=None, shape_collision_aabb_upper=None, shape_voxel_resolution, contact_pair, contact_position, contact_normal, contact_penetration, contact_count, contact_tangent=None, device=None, **kwargs)#

Launch narrow phase collision detection on candidate pairs from broad phase.

Parameters:

  • candidate_pair (wp.array(dtype=wp.vec2i, ndim=1)) – Array of potentially colliding shape pairs from broad phase

  • candidate_pair_count (wp.array(dtype=wp.int32, ndim=1)) – Single-element array containing the number of candidate pairs

  • shape_types (wp.array(dtype=wp.int32, ndim=1)) – Array of geometry types for all shapes

  • shape_data (wp.array(dtype=wp.vec4, ndim=1)) – Array of vec4 containing scale (xyz) and margin (w) for each shape

  • shape_transform (wp.array(dtype=wp.transform, ndim=1)) – Array of world-space transforms for each shape

  • shape_source (wp.array(dtype=wp.uint64, ndim=1)) – Array of source pointers (mesh IDs, etc.) for each shape

  • sdf_data (wp.array(dtype=SDFData, ndim=1) | None) – Compact array of SDFData structs

  • shape_sdf_index (wp.array(dtype=wp.int32, ndim=1) | None) – Per-shape SDF table index (-1 for shapes without SDF)

  • shape_gap (wp.array(dtype=wp.float32, ndim=1)) – Array of per-shape contact gaps (detection threshold) for each shape

  • shape_collision_radius (wp.array(dtype=wp.float32, ndim=1)) – Array of collision radii for each shape (for AABB fallback for planes/meshes)

  • shape_collision_aabb_lower (wp.array(dtype=wp.vec3, ndim=1) | None) – Local-space AABB lower bounds for each shape (for voxel binning)

  • shape_collision_aabb_upper (wp.array(dtype=wp.vec3, ndim=1) | None) – Local-space AABB upper bounds for each shape (for voxel binning)

  • shape_voxel_resolution (wp.array(dtype=wp.vec3i, ndim=1)) – Voxel grid resolution for each shape (for voxel binning)

  • contact_pair (wp.array(dtype=wp.vec2i)) – Output array for contact shape pairs

  • contact_position (wp.array(dtype=wp.vec3)) – Output array for contact positions (center point)

  • contact_normal (wp.array(dtype=wp.vec3)) – Output array for contact normals

  • contact_penetration (wp.array(dtype=float)) – Output array for penetration depths

  • contact_tangent (wp.array(dtype=wp.vec3) | None) – Output array for contact tangents, or None to disable tangent computation

  • contact_count (wp.array(dtype=int)) – Output array (single element) for contact count

  • device (Devicelike | None) – Device to launch on

launch_custom_write(*, candidate_pair, candidate_pair_count, shape_types, shape_data, shape_transform, shape_source, sdf_data, shape_sdf_index, shape_gap, shape_collision_radius, shape_flags, shape_collision_aabb_lower, shape_collision_aabb_upper, shape_voxel_resolution, shape_heightfield_data=None, heightfield_elevation_data=None, writer_data, device=None)#

Launch narrow phase collision detection with a custom contact writer struct.

Parameters:

  • candidate_pair (wp.array(dtype=wp.vec2i, ndim=1)) – Array of potentially colliding shape pairs from broad phase

  • candidate_pair_count (wp.array(dtype=wp.int32, ndim=1)) – Single-element array containing the number of candidate pairs

  • shape_types (wp.array(dtype=wp.int32, ndim=1)) – Array of geometry types for all shapes

  • shape_data (wp.array(dtype=wp.vec4, ndim=1)) – Array of vec4 containing scale (xyz) and margin (w) for each shape

  • shape_transform (wp.array(dtype=wp.transform, ndim=1)) – Array of world-space transforms for each shape

  • shape_source (wp.array(dtype=wp.uint64, ndim=1)) – Array of source pointers (mesh IDs, etc.) for each shape

  • sdf_data (wp.array(dtype=SDFData, ndim=1)) – Compact array of SDFData structs

  • shape_sdf_index (wp.array(dtype=wp.int32, ndim=1)) – Per-shape SDF table index (-1 for shapes without SDF)

  • shape_gap (wp.array(dtype=wp.float32, ndim=1)) – Array of per-shape contact gaps (detection threshold) for each shape

  • shape_collision_radius (wp.array(dtype=wp.float32, ndim=1)) – Array of collision radii for each shape (for AABB fallback for planes/meshes)

  • shape_flags (wp.array(dtype=wp.int32, ndim=1)) – Array of shape flags for each shape (includes ShapeFlags.HYDROELASTIC)

  • shape_collision_aabb_lower (wp.array(dtype=wp.vec3, ndim=1)) – Local-space AABB lower bounds for each shape (for voxel binning)

  • shape_collision_aabb_upper (wp.array(dtype=wp.vec3, ndim=1)) – Local-space AABB upper bounds for each shape (for voxel binning)

  • shape_voxel_resolution (wp.array(dtype=wp.vec3i, ndim=1)) – Voxel grid resolution for each shape (for voxel binning)

  • writer_data (Any) – Custom struct instance for contact writing (type must match the custom writer function)

  • device (Devicelike | None) – Device to launch on