warp.geometry.IsoSurfaceNets#

class warp.geometry.IsoSurfaceNets(
nx,
ny,
nz,
*,
lower=None,
upper=None,
topology='triangle',
)[source]#

A reusable isosurface extractor using Surface Nets.

The surface gets one vertex inside each grid cell it passes through, or one per pass if it passes through the same cell more than once. Each vertex lies at the average of the points where the surface crosses the cell’s edges.

A surface that lies entirely inside the grid produces a closed mesh with no holes, where every edge is shared by exactly two faces. A surface that extends past the grid produces an open mesh, which may end slightly before the edge of the grid instead of reaching it. Every vertex belongs to at least one face.

This class provides a stateful interface following warp.geometry.IsoSurfaceBase: initialize it with a specific grid configuration and then call the surface() method multiple times, which is convenient for processing fields of the same size. For a simpler, stateless operation, use the extract() class method.

The topology parameter selects whether the output faces are triangles (the default) or quads. Faces are wound counter-clockwise viewed from outside for a signed distance field (negative inside).

If field has requires_grad=True and the call runs inside a warp.Tape(), gradients propagate from verts back to field. Cell classification and mesh topology are not differentiated.

Parameters:
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. See the documentation in extract() for more details.

Type:

warp.vec3f | tuple | None

upper#

The upper bound for the mesh coordinate scaling. See the documentation in extract() for more details.

Type:

warp.vec3f | tuple | None

topology#

The type of the faces that surface() produces: "triangle" or "quad".

Type:

str

verts#

An array of vertex positions of type warp.vec3f for the output mesh. This is populated by calling the surface() method.

Type:

warp.array | None

indices#

An array of face vertex indices of type warp.int32 for the output mesh, with three consecutive indices per face when topology is "triangle", and four when it is "quad". This is populated by calling the surface() method.

Type:

warp.array | None

Methods

extract(field[, threshold, lower, upper, ...])

Extract a mesh from a 3D scalar field.

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.
surface(field, threshold)[source]#

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

This method is a convenience wrapper that calls the extract() class method and stores the resulting mesh data in the verts and indices attributes, with the faces of the type selected by topology.

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

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

Extract a mesh from a 3D scalar field.

This function generates an isosurface by processing the entire input field. The resolution of the output mesh is determined by the shape of the field array and may differ along each dimension.

The coordinates of the mesh can be scaled to a specific bounding box using the lower and upper parameters. If a bound is not provided (i.e., left as None), it will be assigned a default value that aligns the mesh with the integer indices of the input grid.

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.

  • topology (Literal['triangle', 'quad']) – The type of the faces to produce: "triangle" or "quad".

Returns:

A tuple (vertices, indices) containing the output mesh data. The indices array is a flat list where each group of three consecutive integers forms a single triangle, or four a single quad, by referencing vertices in the vertices array.

Raises:

  • ValueError – If field is not a 3D array, has fewer than two nodes on any axis, or if topology is not a valid face type.

  • TypeError – If the field data type is not warp.float32.

Return type:

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