DataSetFilters.voxelize

DataSetFilters.voxelize#

DataSetFilters.voxelize(
*,
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,
) → UnstructuredGrid[source]#

Voxelize mesh to UnstructuredGrid.

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 geometry. For all other options, the geometry is implicitly defined such that the generated mesh fits the bounds of the input mesh.

Only the foreground cells are returned, so this filter has no target_n_points or max_n_points. To bound the size of the grid, call voxelize_rectilinear() with max_n_points and threshold() its output.

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

Added in version 0.46.

Note

The input must be a surface with faces or strips. Generate a surface from a point cloud with reconstruct_surface() before voxelizing it.

Note

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

Parameters:
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 voxelized mesh. 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 mesh. 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 dimensions is 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 input’s surface is extracted first, and the p-th percentile is computed from the lengths of the edges of its cells. Up to cell_length_sample_size of those cells are used, drawn at random with a fixed seed, and degenerate edges with zero length are ignored.

Changed in version 0.50.0: The percentile is computed from every edge of the sampled cells instead of the distance between two random points of each triangulated cell, and the sample is drawn with a fixed seed. The estimate is now deterministic.

Has no effect if dimensions is specified.

cell_length_sample_sizeint, optional

Maximum number of cells to use when computing the cell_length_percentile. 100 000 cells are used by default.

progress_barbool, default: False

Display a progress bar to indicate progress.

Returns:
UnstructuredGrid

Voxelized unstructured grid of the original mesh.

Examples#

Download Python source code | Download Jupyter notebook

Create a voxelized mesh with uniform spacing.

>>> import numpy as np
>>> import pyvista as pv
>>> from pyvista import examples
>>> mesh = examples.download_bunny_coarse()
>>> vox = mesh.voxelize(spacing=0.01)
>>> vox.plot(show_edges=True)
../../../_images/pyvista-DataSetFilters-voxelize-42708b3d90048790_00_00.png

Create a voxelized mesh using non-uniform spacing.

>>> vox = mesh.voxelize(spacing=(0.01, 0.005, 0.002))
>>> vox.plot(show_edges=True)
../../../_images/pyvista-DataSetFilters-voxelize-42708b3d90048790_01_00.png

The bounds of the voxelized mesh always match the bounds of the input.

>>> mesh.bounds
BoundsTuple(x_min = -0.13155962526798248,
            x_max =  0.18016336858272552,
            y_min = -0.12048563361167908,
            y_max =  0.18769524991512299,
            z_min = -0.14300920069217682,
            z_max =  0.09850578755140305)

>>> vox.bounds
BoundsTuple(x_min = -0.13155962526798248,
            x_max =  0.18016336858272552,
            y_min = -0.12048563361167908,
            y_max =  0.18769524991512299,
            z_min = -0.14300920069217682,
            z_max =  0.09650979936122894)

Create a voxelized mesh with 3 x 4 x 5 cells. Since dimensions is the number of points, not cells, we need to add 1 to get the number of desired cells.

>>> mesh = pv.Box()
>>> cell_dimensions = np.array((3, 4, 5))
>>> vox = mesh.voxelize(dimensions=cell_dimensions + 1)
>>> vox.plot(show_edges=True)
../../../_images/pyvista-DataSetFilters-voxelize-42708b3d90048790_02_00.png

See Also#

voxelize_rectilinear

Similar function that returns a RectilinearGrid with cell data.

voxelize_binary_mask

Similar function that returns a ImageData with point data.

pyvista.DataObjectFilters.resample_to_image

Similar function which generates a ImageData of the same geometry. It resamples the input’s data arrays instead of generating a mask, and fills the voxels its cells or points reach rather than a closed surface’s interior.