pyvista.ImageDataFilters.points_to_cells#

ImageDataFilters.points_to_cells(scalars: str | None = None, *, copy: bool = True)[source]#

Re-mesh image data from a point-based to a cell-based representation.

This filter changes how image data is represented. Data represented as points at the input is re-meshed into an alternative representation as cells at the output. Only the ImageData container is modified so that the number of input points equals the number of output cells. The re-meshing is otherwise lossless in the sense that point data at the input is passed through unmodified and stored as cell data at the output. Any cell data at the input is ignored and is not used by this filter.

To change the image data’s representation, the input points are used to represent the centers of the output cells. This has the effect of “growing” the input image dimensions by one along each axis (i.e. half the cell width on each side). For example, an image with 100 points and 99 cells along an axis at the input will have 101 points and 100 cells at the output. If the input has 1mm spacing, the axis size will also increase from 99mm to 100mm.

Since filters may be inherently cell-based (e.g. some DataSetFilters) or may operate on point data exclusively (e.g. most ImageDataFilters), re-meshing enables the same data to be used with either kind of filter while ensuring the input data to those filters has the appropriate representation. This filter is also useful when plotting image data to achieve a desired visual effect, such as plotting images as voxel cells instead of as points.

Added in version 0.44.0.

Parameters:

scalarsstr, optional: Name of point data scalars to pass through to the output as cell data. Use this parameter to restrict the output to only include the specified array. By default, all point data arrays at the input are passed through as cell data at the output.
copybool, default: True: Copy the input point data before associating it with the output cell data. If False, the input and output will both refer to the same data array(s).

Returns:

pyvista.ImageData: Image with a cell-based representation.

See also

cells_to_points: Inverse of this filter to represent cells as points.
point_data_to_cell_data(): Resample point data as cell data without modifying the container.
cell_data_to_point_data(): Resample cell data as point data without modifying the container.

Examples

Load an image with point data.

>>> from pyvista import examples
>>> image = examples.load_uniform()

Show the current properties and point arrays of the image.

>>> image
ImageData (...)
  N Cells:      729
  N Points:     1000
  X Bounds:     0.000e+00, 9.000e+00
  Y Bounds:     0.000e+00, 9.000e+00
  Z Bounds:     0.000e+00, 9.000e+00
  Dimensions:   10, 10, 10
  Spacing:      1.000e+00, 1.000e+00, 1.000e+00
  N Arrays:     2

>>> image.point_data.keys()
['Spatial Point Data']

Re-mesh the points and point data as cells and cell data.

>>> cells_image = image.points_to_cells()

Show the properties and cell arrays of the re-meshed image.

>>> cells_image
ImageData (...)
  N Cells:      1000
  N Points:     1331
  X Bounds:     -5.000e-01, 9.500e+00
  Y Bounds:     -5.000e-01, 9.500e+00
  Z Bounds:     -5.000e-01, 9.500e+00
  Dimensions:   11, 11, 11
  Spacing:      1.000e+00, 1.000e+00, 1.000e+00
  N Arrays:     1

>>> cells_image.cell_data.keys()
['Spatial Point Data']

Observe that:

The input point array is now a cell array
The output has one less array (the input cell data is ignored)
The dimensions have increased by one
The bounds have increased by half the spacing
The output N Cells equals the input N Points

See Image Data Representations for more examples using this filter.