newton.geometry.NarrowPhase#

class newton.geometry.NarrowPhase(*, max_candidate_pairs, max_triangle_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

__init__(*, max_candidate_pairs, max_triangle_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)

  • 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 thickness (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 – 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 thickness (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 – Device to launch on