DataSetFilters.voxelize_rectilinear

DataSetFilters.voxelize_rectilinear(

*,

background_value: int | float = 0,

foreground_value: int | float = 1,

reference_volume: ImageData | None = None,

dimensions: VectorLike[int] | None = None,

spacing: float | VectorLike[float] | None = None,

rounding_func: Callable[[VectorLike[float]], VectorLike[int]] | None = None,

cell_length_percentile: float | None = None,

cell_length_sample_size: int | None = None,

progress_bar: bool = False,

) → RectilinearGrid

Voxelize mesh to create a RectilinearGrid voxel volume.

The voxelization can be controlled in several ways:

1. Specify the output geometry using a reference_volume.

2. Specify the spacing explicitly.

3. Specify the dimensions explicitly.

4. Specify the cell_length_percentile. The spacing is estimated from the surface’s cells using the specified percentile.

Use reference_volume for full control of the output grid’s geometry. For all other options, the geometry is implicitly defined such that the generated grid fits the bounds of the input mesh.

If no inputs are provided, cell_length_percentile=0.1 (tenth percentile) is used by default to estimate the spacing.

A point data array mask is included where points inside and outside of the input surface are labelled with foreground_value and background_value, respectively.

Added in version 0.46.

Note

This method is a wrapper around voxelize_binary_mask(). See that method for additional information.

Parameters:

background_valueint, default: 0

Background value of the generated grid.

foreground_valueint, default: 1

Foreground value of the generated grid.

reference_volumeImageData, optional

Volume to use as a reference. The output will have the same dimensions, origin, spacing, offset, and direction_matrix as the reference.

dimensionsVectorLike[int], optional

Dimensions of the generated rectilinear grid. Set this value to control the dimensions explicitly. If unset, the dimensions are defined implicitly through other parameter. See summary and examples for details.

Note

Dimensions is the number of points along each axis, not cells. Set dimensions to N+1 instead for N cells along each axis.

spacingfloat | VectorLike[float], optional

Approximate spacing to use for the generated grid. Set this value to control the spacing explicitly. If unset, the spacing is defined implicitly through other parameters. See summary and examples for details.

rounding_funcCallable[VectorLike[float], VectorLike[int]], optional

Control how the dimensions are rounded to integers based on the provided or calculated spacing. Should accept a length-3 vector containing the dimension values along the three directions and return a length-3 vector. numpy.round() is used by default.

Rounding the dimensions implies rounding the actual spacing.

Has no effect if reference_volume or dimensions are specified.

cell_length_percentilefloat, optional

Cell length percentage p to use for computing the default spacing. Default is 0.1 (tenth percentile) and must be between 0 and 1. The p-th percentile is computed from the cumulative distribution function (CDF) of lengths which are representative of the cell length scales present in the input. The CDF is computed by:

1. Triangulating the input cells.

2. Sampling a subset of up to cell_length_sample_size cells.

3. Computing the distance between two random points in each cell.

4. Inserting the distance into an ordered set to create the CDF.

Has no effect if dimensions or reference_volume are specified.

cell_length_sample_sizeint, optional

Number of samples to use for the cumulative distribution function (CDF) when using the cell_length_percentile option. 100 000 samples are used by default.

progress_barbool, default: False

Display a progress bar to indicate progress.

Returns:

RectilinearGrid

RectilinearGrid as voxelized volume with discretized cells.

Examples

Download Python source code | Download Jupyter notebook

Create a voxel volume of a nut. By default, the spacing is automatically estimated.

>>> import pyvista as pv
>>> from pyvista import examples
>>> mesh = pv.examples.load_nut()
>>> vox = mesh.voxelize_rectilinear()

Plot the mesh together with its volume.

>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(mesh=vox, show_edges=True)
>>> _ = pl.add_mesh(mesh=mesh, show_edges=True, opacity=1)
>>> pl.show()

Static Scene

Interactive Scene

Load a mesh of a cow.

>>> mesh = examples.download_cow()

Create an equal density voxel volume and plot the result.

>>> vox = mesh.voxelize_rectilinear(spacing=0.15)
>>> cpos = pv.CameraPosition(
...     position=(15, 3, 15), focal_point=(0, 0, 0), viewup=(0, 1, 0)
... )
>>> vox.plot(scalars='mask', show_edges=True, cpos=cpos)

Static Scene

Interactive Scene

Slice the voxel volume to view the mask scalars.

>>> slices = vox.slice_orthogonal()
>>> slices.plot(scalars='mask', show_edges=True)

Static Scene

Interactive Scene

Create a voxel volume from unequal density dimensions and plot result.

>>> vox = mesh.voxelize_rectilinear(spacing=(0.15, 0.15, 0.5))
>>> vox.plot(scalars='mask', show_edges=True, cpos=cpos)

Static Scene

Interactive Scene

Slice the unequal density voxel volume to view the mask scalars.

>>> slices = vox.slice_orthogonal()
>>> slices.plot(scalars='mask', show_edges=True, cpos=cpos)

Static Scene

Interactive Scene

See Also

voxelize

Similar function that returns a UnstructuredGrid of VOXEL cells.

voxelize_binary_mask

Similar function that returns a ImageData with point data.