newton.SDF#

class newton.SDF(*, data, sparse_volume=None, coarse_volume=None, block_coords=None, texture_block_coords=None, texture_data=None, shape_margin=0.0, _coarse_texture=None, _subgrid_texture=None, _internal=False)[source]#

Bases: object

Opaque SDF container owning kernel payload and runtime references.

static create_from_data(*, sparse_volume=None, coarse_volume=None, block_coords=None, center=None, half_extents=None, background_value=MAXVAL, scale_baked=False, shape_margin=0.0, texture_data=None)#

Create an SDF from precomputed runtime resources.

static create_from_mesh(mesh, *, device=None, narrow_band_range=(-0.1, 0.1), target_voxel_size=None, max_resolution=None, margin=0.05, shape_margin=0.0, scale=None, texture_format='uint16', sign_method='auto', cache_dir=None)#

Create an SDF from a mesh in local mesh coordinates.

The SDF is built entirely via the texture-based sparse construction path. NanoVDB volumes are not created; all downstream collision and simulation code uses the texture SDF.

Parameters:

  • mesh (Mesh) – Source mesh geometry.

  • device (Device | str | None) – CUDA device for SDF allocation. When None, uses the current wp.ScopedDevice or the Warp default device.

  • narrow_band_range (tuple[float, float]) – Signed narrow-band distance range [m] as (inner, outer).

  • target_voxel_size (float | None) – Target sparse-grid voxel size [m]. If provided, takes precedence over max_resolution.

  • max_resolution (int | None) – Maximum sparse-grid dimension [voxel]. Used when target_voxel_size is not provided.

  • margin (float) – Extra AABB padding [m] added before discretization.

  • shape_margin (float) – Shape margin offset [m] to subtract from SDF values. When non-zero, the SDF surface is effectively shrunk inward by this amount. Useful for modeling compliant layers in hydroelastic collision. Defaults to 0.0.

  • scale (tuple[float, float, float] | None) – Scale factors (sx, sy, sz) [unitless] to bake into the SDF. When provided, mesh vertices are scaled before SDF generation and scale_baked is set to True in the resulting SDF. Required for hydroelastic collision with non-unit shape scale. Defaults to None (no scale baking; scale applied at runtime).

  • texture_format (str) – Subgrid texture storage format. "uint16" (default) uses 16-bit normalized textures for half the memory of "float32" with negligible precision loss. "uint8" uses 8-bit textures for minimum memory.

  • sign_method (Literal['auto', 'parity', 'winding']) –

    Inside/outside sign query strategy.

    • "auto" (default): use parity rays if Mesh.is_watertight is True, else fall back to winding numbers.

    • "parity": always use wp.mesh_query_point_sign_parity. Cheaper per sample but requires a watertight mesh; results on open meshes are undefined.

    • "winding": always use wp.mesh_query_point_sign_winding_number. Robust for general (possibly open or non-manifold) meshes but more expensive to build and query.

  • cache_dir (str | PathLike[str] | None) – Optional directory holding cached cooked SDFs. When provided, the cooked SDF data (everything that backs the GPU 3D textures) is keyed by mesh content + build parameters and persisted as a single {hash}.sdf.npz file (an uncompressed np.savez bundle of typed numpy arrays). A subsequent call with the same inputs reloads from disk and skips the expensive mesh-SDF build. shape_margin is applied at sample time and is not part of the cache key. Defaults to None (cache disabled).

Returns:

A validated SDF runtime handle.

Raises:

  • RuntimeError – if no CUDA device is available. The texture SDF build pipeline requires CUDA kernels and 3D textures.

  • ValueError – if texture_format or sign_method is not one of the supported values.

Return type:

SDF

static create_from_points(points, indices, *, device=None, narrow_band_range=(-0.1, 0.1), target_voxel_size=None, max_resolution=None, margin=0.05, shape_margin=0.0, scale=None)#

Create an SDF from triangle mesh points and indices.

Parameters:

  • points (ndarray | Sequence[Sequence[float]]) – Vertex positions [m], shape (N, 3).

  • indices (ndarray | Sequence[int]) – Triangle vertex indices [index], flattened or shape (M, 3).

  • device (Device | str | None) – CUDA device for SDF allocation. When None, uses the current wp.ScopedDevice or the Warp default device.

  • narrow_band_range (tuple[float, float]) – Signed narrow-band distance range [m] as (inner, outer).

  • target_voxel_size (float | None) – Target sparse-grid voxel size [m]. If provided, takes precedence over max_resolution.

  • max_resolution (int | None) – Maximum sparse-grid dimension [voxel]. Used when target_voxel_size is not provided.

  • margin (float) – Extra AABB padding [m] added before discretization.

  • shape_margin (float) – Shape margin offset [m] to subtract from SDF values.

  • scale (tuple[float, float, float] | None) – Scale factors (sx, sy, sz) to bake into the SDF.

Returns:

A validated SDF runtime handle with sparse/coarse volumes.

Return type:

SDF

__init__(*, data, sparse_volume=None, coarse_volume=None, block_coords=None, texture_block_coords=None, texture_data=None, shape_margin=0.0, _coarse_texture=None, _subgrid_texture=None, _internal=False)#
extract_isomesh(isovalue=0.0, device=None)#

Extract an isosurface mesh at the requested isovalue.

Uses the texture SDF path for mesh-generated SDFs (the only path populated by create_from_mesh()). For primitive SDFs built via create_from_data() with a NanoVDB sparse_volume, the fallback branch extracts from the sparse volume instead.

The isovalue argument is always interpreted in raw mesh-distance units: 0.0 yields the base geometry surface regardless of how the SDF was constructed, and positive values give an outward offset. Both storage backends are normalized to this convention:

  • Texture SDFs store unmodified signed distance d (the texture builder does not bake shape_margin), so the requested isovalue is forwarded as-is to the isomesh extractor.

  • NanoVDB sparse volumes built via _compute_sdf_from_shape_impl store d - shape_margin. The extractor compensates with corrected_isovalue = isovalue - shape_margin so external behavior matches the texture path.

As a consequence, shape_margin is only consulted on the legacy sparse-volume branch; on the texture branch it is stored for backward compatibility with callers that introspect the SDF but has no effect on the extracted surface.

Parameters:

  • isovalue (float) – Surface level to extract [m] in base geometry distance units. 0.0 gives the original surface; positive values give an outward offset.

  • device (Device | str | None) – CUDA device. When None uses the current device.

Returns:

Mesh or None when the SDF has no data or the isovalue falls outside the stored narrow band.

Return type:

Mesh | None

is_empty()#

Return True when this SDF has no sparse/coarse or texture payload.

to_kernel_data()#

Return kernel-facing SDF payload.

to_texture_kernel_data()#

Return texture SDF kernel payload, or None if unavailable.

validate()#

Validate consistency of kernel pointers and owned volumes.