warp.geometry.IsoSurfaceBase#

class warp.geometry.IsoSurfaceBase(nx, ny, nz, *, lower=None, upper=None)[source]#

Abstract base class for isosurface extraction from dense 3D scalar fields.

Concrete backends such as warp.geometry.IsoSurfaceMarchingCubes implement this interface so that extraction algorithms can be swapped behind a single API: construct an instance with the grid dimensions, then call surface() repeatedly to extract meshes from fields of that size, reading the results from the verts and indices attributes. For a stateless one-shot extraction, use the extract() class method instead.

All backends share the same conventions: the input is a dense 3D warp.float32 field sampled at grid nodes, the output faces are wound counter-clockwise when viewed from outside for a signed distance field (negative inside), and the indices array is a flat warp.int32 array listing the vertices of each face in order. Backends produce triangles, where each group of three consecutive entries forms one face, unless they support another face type and were configured to use it.

All backends support backward-mode automatic differentiation from field to the output verts positions; indices is always discrete and carries no gradient. See each backend’s class docstring for the specific interpolation its gradient flows through.

Parameters:

nx (int) – Number of grid nodes in the x-direction.
ny (int) – Number of grid nodes in the y-direction.
nz (int) – Number of grid nodes in the z-direction.
lower (warp.vec3 | tuple[float, float, float] | None) – The 3D coordinate that the grid’s corner at index (0,0,0) maps to. Defaults to (0.0, 0.0, 0.0) if None.
upper (warp.vec3 | tuple[float, float, float] | None) – The 3D coordinate that the grid’s corner at index (nx-1, ny-1, nz-1) maps to. Defaults to align with the grid’s maximal indices if None.

nx#

The number of grid nodes in the x-direction.

Type:: int

ny#

The number of grid nodes in the y-direction.

Type:: int

nz#

The number of grid nodes in the z-direction.

Type:: int

lower#

The lower bound for the mesh coordinate scaling.

Type:: warp.vec3f | tuple | None

upper#

The upper bound for the mesh coordinate scaling.

Type:: warp.vec3f | tuple | None

Methods

`extract`(field[, threshold, lower, upper])	Extract a mesh from a 3D scalar field in a single stateless call.
`resize`(nx, ny, nz)	Update the grid dimensions for the context.
`surface`(field, threshold)	Compute a 2D surface mesh of a given isosurface from a 3D scalar field.

Attributes

`verts`	An array of vertex positions of type `warp.vec3f` for the output mesh.
`indices`	An array of face vertex indices of type `warp.int32` for the output mesh.

verts: wp.array[wp.vec3f] | None#: An array of vertex positions of type warp.vec3f for the output mesh. This is populated by calling the surface() method.

indices: wp.array[wp.int32] | None#: An array of face vertex indices of type warp.int32 for the output mesh. This is populated by calling the surface() method.

resize(nx, ny, nz)[source]#

Update the grid dimensions for the context.

This allows the instance to be reused for scalar fields of a different resolution. The new dimensions take effect on the next call to surface().

Parameters:

nx (int) – New number of nodes in the x-direction.
ny (int) – New number of nodes in the y-direction.
nz (int) – New number of nodes in the z-direction.

Return type:

None

abstractmethod surface(field, threshold)[source]#

Compute a 2D surface mesh of a given isosurface from a 3D scalar field.

The resulting mesh data is stored in the verts and indices attributes, replacing any previous outputs.

Parameters:

field (warp.array3d[warp.float32]) – A 3D scalar field whose shape must match the grid dimensions (nx, ny, nz) of the instance.
threshold (float) – The field value defining the isosurface to extract.

Raises:

ValueError – If the shape of field does not match the configured grid dimensions of the instance.

Return type:

None

abstractmethod classmethod extract( field, threshold=0.0, *, lower=None, upper=None, )[source]#

Extract a mesh from a 3D scalar field in a single stateless call.

Parameters:

field (warp.array3d[warp.float32]) – A 3D array representing the scalar values on a regular grid.
threshold (float) – The field value defining the isosurface to extract.
lower (vec3f | tuple[float, float, float] | None) – The 3D coordinate that the grid’s corner at index (0,0,0) maps to. Defaults to (0.0, 0.0, 0.0) if None.
upper (vec3f | tuple[float, float, float] | None) – The 3D coordinate that the grid’s corner at index (nx-1, ny-1, nz-1) maps to. Defaults to align with the grid’s maximal indices if None.

Returns:

A tuple (vertices, indices), where indices is a flat warp.int32 array in which each group of three consecutive entries forms one triangle by referencing vertices in the vertices array. Backends that support another face type accept a keyword argument to select it, and then write that type of face to indices instead.

Raises:

ValueError – If field is not a 3D array, or has fewer than two nodes on any axis.
TypeError – If the field data type is not warp.float32.

Return type:

tuple[wp.array[wp.vec3f], wp.array[wp.int32]]