DataSetFilters.voxelize_rectilinear

DataSetFilters.voxelize_rectilinear#

DataSetFilters.voxelize_rectilinear(
*,
background_value: int | float = 0,
foreground_value: int | float = 1,
reference_volume: ImageData | None = None,
dimensions: VectorLikeInt | None = None,
spacing: float | VectorLikeFloat | None = None,
target_n_points: int | None = None,
max_n_points: int | None = None,
rounding_func: Callable[[VectorLikeFloat], VectorLikeInt] | None = None,
cell_length_percentile: float | None = None,
cell_length_sample_size: int | None = None,
progress_bar: bool = False,
) → RectilinearGrid[source]#

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 target_n_points. The spacing is isotropic and estimated so the output has approximately this many points.

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

Set max_n_points to cap the result of any of these. It differs from target_n_points, which is a resolution to aim for: a geometry specified explicitly raises if it exceeds the cap, while an estimated one is coarsened to fit.

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

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:
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.

dimensionsVectorLikeInt, 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 | VectorLikeFloat, 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.

target_n_pointsint, optional

Approximate number of points to generate. The spacing is isotropic and chosen so the output holds about this many points, distributed between the axes in proportion to the input’s bounds. An axis with no extent holds a single point and takes no part in the count. Rounding to whole voxels means the count is approached, not matched exactly. Cannot be set with reference_volume, dimensions, spacing, or the cell length options.

Note

Like dimensions, this counts the points of the output, which has one more point than cells along each axis. The same holds for max_n_points.

Added in version 0.50.

max_n_pointsint, optional

Strict upper bound on the number of points generated. Unlike target_n_points, which is only approached, this limit is never exceeded. How it is enforced depends on how the geometry is defined:

  • Geometry set explicitly, with reference_volume, dimensions, spacing or a cell length option, raises if it exceeds the limit.

  • target_n_points must not exceed the limit, and the grid estimated from it is coarsened if rounding would take it above.

  • Geometry left to the defaults is coarsened to fit, without raising.

Added in version 0.50.

rounding_funcCallable[VectorLikeFloat, VectorLikeInt], 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 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 or reference_volume are 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:
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()
../../../_images/pyvista-DataSetFilters-voxelize_rectilinear-2b4e2d2b8f45f9c4_00_00.png

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)
../../../_images/pyvista-DataSetFilters-voxelize_rectilinear-2b4e2d2b8f45f9c4_01_00.png

Slice the voxel volume to view the mask scalars.

>>> slices = vox.slice_orthogonal()
>>> slices.plot(scalars='mask', show_edges=True)
../../../_images/pyvista-DataSetFilters-voxelize_rectilinear-2b4e2d2b8f45f9c4_02_00.png

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)
../../../_images/pyvista-DataSetFilters-voxelize_rectilinear-2b4e2d2b8f45f9c4_03_00.png

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

>>> slices = vox.slice_orthogonal()
>>> slices.plot(scalars='mask', show_edges=True, cpos=cpos)
../../../_images/pyvista-DataSetFilters-voxelize_rectilinear-2b4e2d2b8f45f9c4_04_00.png

See Also#

voxelize

Similar function that returns a UnstructuredGrid of VOXEL cells.

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.