pyvista.ImageDataFilters.points_to_cells

pyvista.ImageDataFilters.points_to_cells#

ImageDataFilters.points_to_cells(
scalars: str | None = None,
*,
dimensionality: VectorLike[bool] | Literal[0, 1, 2, 3, '0D', '1D', '2D', '3D', 'preserve'] = 'preserve',
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. 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 (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.

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.

dimensionalityVectorLike[bool], Literal[0, 1, 2, 3, “0D”, “1D”, “2D”, “3D”, “preserve”], default: ‘preserve’

Control which dimensions will be modified by the filter.

  • 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, e.g. (>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, e.g. (>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, e.g. (>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 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

Since the input points are 3D (i.e. 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 (i.e. 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>

See Image Data Representations for more examples using this filter.