warp.MarchingCubes#

class warp.MarchingCubes(*args, **kwargs)[source]#

A reusable context for marching cubes surface extraction.

This class provides a stateful interface for isosurface extraction. You can initialize it with a specific grid configuration and then call the surface() method multiple times, which is efficient for processing fields of the same size.

For a simpler, stateless operation, use the static method extract_surface_marching_cubes().

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

domain_bounds_lower_corner#

The lower bound for the mesh coordinate scaling. See the documentation in extract_surface_marching_cubes() for more details.

Type:

warp.vec3f | tuple | None

domain_bounds_upper_corner#

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

Type:

warp.vec3f | tuple | None

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 triangle indices of type warp.int32 for the output mesh. This is populated by calling the surface() method.

Type:

warp.array | None

device#

The device on which the context was created. This attribute is for backward compatibility and is not used by the class’s methods.

Type:

warp.Device

__init__(
nx,
ny,
nz,
max_verts=0,
max_tris=0,
device=None,
domain_bounds_lower_corner=None,
domain_bounds_upper_corner=None,
)[source]#

Initialize the marching cubes context with a grid configuration.

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.

  • max_verts (int) – (Deprecated) This argument is ignored.

  • max_tris (int) – (Deprecated) This argument is ignored.

  • device (Device | str | None) – (Deprecated) The value is assigned to self.device for backward compatibility but is not used by the class’s methods. It may be removed in a future version.

  • domain_bounds_lower_corner – See the documentation in extract_surface_marching_cubes().

  • domain_bounds_upper_corner – See the documentation in extract_surface_marching_cubes().

Methods

__init__(nx, ny, nz[, max_verts, max_tris, ...])

Initialize the marching cubes context with a grid configuration.

extract_surface_marching_cubes(field[, ...])

Extract a triangular mesh from a 3D scalar field.

resize(nx, ny, nz[, max_verts, max_tris])

Update the grid dimensions for the context.

surface(field, threshold)

Compute a 2D surface mesh of a given isosurface from a 3D scalar field.
resize(nx, ny, nz, max_verts=0, max_tris=0)[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.

  • max_verts (int) – (Deprecated) This argument is ignored.

  • max_tris (int) – (Deprecated) This argument is ignored.

Return type:

None

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 core static method and stores the resulting mesh data in the verts and indices attributes.

Parameters:

  • field (array(ndim=3, dtype=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

static extract_surface_marching_cubes(
field,
threshold=0.0,
domain_bounds_lower_corner=None,
domain_bounds_upper_corner=None,
)[source]#

Extract a triangular 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 domain_bounds_lower_corner and domain_bounds_upper_corner 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.

For example, setting the bounds to wp.vec3(0.0, 0.0, 0.0) and wp.vec3(1.0, 1.0, 1.0) will scale the output mesh to fit within the unit cube.

Parameters:

  • field (array(ndim=3, dtype=float32)) – A 3D array representing the scalar values on a regular grid.

  • threshold (float) – The field value defining the isosurface to extract.

  • domain_bounds_lower_corner (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.

  • domain_bounds_upper_corner (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) containing the output mesh data. The indices array is a flat list where each group of three consecutive integers forms a single triangle by referencing vertices in the vertices array.

Raises:

  • ValueError – If field is not a 3D array or is empty.

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

Return type:

tuple[array(ndim=1, dtype=vec3f), array(ndim=1, dtype=int32)]