pyvista.ImageDataFilters.cells_to_points#

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

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

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

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

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 points instead of as voxel cells.

Added in version 0.44.0.

Parameters:

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

Returns:

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

See also

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

Examples

Load an image with cell data.

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

Show the current properties and cell 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.cell_data.keys()
['Spatial Cell Data']

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

>>> points_image = image.cells_to_points()

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

>>> points_image
ImageData (...)
  N Cells:      512
  N Points:     729
  X Bounds:     5.000e-01, 8.500e+00
  Y Bounds:     5.000e-01, 8.500e+00
  Z Bounds:     5.000e-01, 8.500e+00
  Dimensions:   9, 9, 9
  Spacing:      1.000e+00, 1.000e+00, 1.000e+00
  N Arrays:     1

>>> points_image.point_data.keys()
['Spatial Cell Data']

Observe that:

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

See Image Data Representations for more examples using this filter.