ImageDataFilters.points_to_cells

ImageDataFilters.points_to_cells#

ImageDataFilters.points_to_cells( scalars: str | None = None, *, dimensionality: VectorLikeBool | Literal[0, 1, 2, 3, '0D', '1D', '2D', '3D', 'preserve'] = 'preserve', copy: bool = True, ) → ImageData[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. The 'vtkGhostType' array is the one exception: its point ghost flags are translated into the equivalent cell ghost flags, so hidden points at the input become hidden cells at the output.

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 (that is, 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. By default, only non-singleton dimensions are increased such that 1D or 2D inputs remain 1D or 2D at the output.

Since filters may be inherently cell-based (for example, some DataSetFilters) or may operate on point data exclusively (for example, 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.

Note

Only the input’s dimensions, and origin are modified by this filter. Other spatial properties such as spacing and direction_matrix are not affected.

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. The 'vtkGhostType' array is always included.

dimensionalityVectorLikeBool, Literal[0, 1, 2, 3, “0D”, “1D”, “2D”, “3D”, “preserve”]

Control which dimensions will be modified by the filter. 'preserve' is used by default.

Can be specified as a sequence of 3 boolean to allow modification on a per
dimension basis.
0 or '0D': convenience alias to output a 0D ImageData with dimensions (1, 1, 1). Only valid for 0D inputs.
1 or '1D': convenience alias to output a 1D ImageData where exactly one dimension is greater than one, for example, (>1, 1, 1). Only valid for 0D or 1D inputs.
2 or '2D': convenience alias to output a 2D ImageData where exactly two dimensions are greater than one, for example, (>1, >1, 1). Only valid for 0D, 1D, or 2D inputs.
3 or '3D': convenience alias to output a 3D ImageData, where all three dimensions are greater than one, for example, (>1, >1, >1). Valid for any 0D, 1D, 2D, or 3D inputs.
'preserve' (default): convenience alias to not modify singleton dimensions.

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 arrays. The 'vtkGhostType' array is always copied since its values change.

Returns:

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

Examples#

Download Python source code | Download Jupyter notebook

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

Since the input points are 3D (that is, there are no singleton dimensions), the output cells are 3D VOXEL cells.

>>> cells_image.get_cell(0).type
<CellType.VOXEL: 11>

If the input points are 2D (that is, one dimension is singleton), the output cells are 2D PIXEL cells when dimensions is set to 'preserve'.

>>> image2D = examples.download_beach()
>>> image2D.dimensions
(100, 100, 1)

>>> pixel_cells_image = image2D.points_to_cells(dimensionality='preserve')
>>> pixel_cells_image.dimensions
(101, 101, 1)
>>> pixel_cells_image.get_cell(0).type
<CellType.PIXEL: 8>

This is equivalent as requesting a 2D output.

>>> pixel_cells_image = image2D.points_to_cells(dimensionality='2D')
>>> pixel_cells_image.dimensions
(101, 101, 1)
>>> pixel_cells_image.get_cell(0).type
<CellType.PIXEL: 8>

Use (True, True, True) to re-mesh 2D points as 3D cells.

>>> voxel_cells_image = image2D.points_to_cells(
...     dimensionality=(True, True, True)
... )
>>> voxel_cells_image.dimensions
(101, 101, 2)
>>> voxel_cells_image.get_cell(0).type
<CellType.VOXEL: 11>

Or request a 3D output.

>>> voxel_cells_image = image2D.points_to_cells(dimensionality='3D')
>>> voxel_cells_image.dimensions
(101, 101, 2)
>>> voxel_cells_image.get_cell(0).type
<CellType.VOXEL: 11>