ImageDataFilters.cells_to_points

ImageDataFilters.cells_to_points#

ImageDataFilters.cells_to_points(
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 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. The 'vtkGhostType' array is the one exception: its cell ghost flags are translated into the equivalent point ghost flags, so hidden cells at the input become hidden points at the output. Cell flags with no point equivalent are cleared.

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 (that is, 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 (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 points instead of as voxel cells.

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

Note

This filter does not modify singleton dimensions with dimensionality set as 'preserve' by default.

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

Returns:
pyvista.ImageData

Image with a point-based representation.

Examples#

Download Python source code | Download Jupyter notebook

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

cell_data_to_point_data()

Resample point data as cell data without modifying the container.