newton.SDF#

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

Bases: object

Opaque SDF container owning kernel payload and runtime references.

Experimental

The SDF API (including newton.SDF, newton.geometry.SDF and related helpers such as SDF.create_from_mesh(), SDF.create_from_points(), SDF.create_from_data() and the SDF storage on Model) may change without notice.

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, construction_padding=None)#

Create an SDF from precomputed runtime resources.

Parameters:

sparse_volume (Volume | None) – Sparse narrow-band SDF volume.
coarse_volume (Volume | None) – Coarse background SDF volume.
block_coords (ndarray | Sequence[vec3us] | None) – Sparse-volume block coordinates.
center (Sequence[float] | None) – Shared SDF extent center [m].
half_extents (Sequence[float] | None) – Shared SDF extent half extents [m].
background_value (float) – Value [m] identifying unallocated sparse voxels.
scale_baked (bool) – Whether shape scale is already baked into the SDF.
shape_margin (float) – Shape margin offset [m] subtracted from sampled SDF values.
texture_data (TextureSDFData | None) – Precomputed texture SDF runtime data.
construction_padding (float | None) – AABB padding [m] used when constructing texture_data. Hydroelastic shape validation uses this value to verify that the SDF covers the shape’s margin and gap. Leave as None when the construction padding is unknown.

Returns:

A validated SDF runtime handle.

Raises:

ValueError – If construction_padding is negative or non-finite.

Return type:

SDF

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, paired_samples=True)#

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', 'normal']) –
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.
- "normal": always use wp.mesh_query_point_sign_normal (angle-weighted pseudo-normal). Signs voxels by the local side of the nearest surface; the choice for open sheets, where neither parity nor winding defines a consistent inside.
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).
paired_samples (bool) – Store each SDF sample with its positive-X neighbor for faster software interpolation. Disable to halve texture memory at the cost of slower hydroelastic sampling. This optimization is automatically disabled on CUDA devices with architectures older than SM90 when Warp was built with CUDA Toolkit 13.0 or earlier.

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_data=None, shape_margin=0.0, construction_padding=None, _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.