ImageData

class ImageData(*args, **kwargs)

Models datasets with uniform spacing in the three coordinate directions.

Can be initialized in one of several ways:

• Create empty grid

• Initialize from a vtkImageData object

• Initialize based on dimensions, cell spacing, and origin.

Changed in version 0.33.0: First argument must now be either a path or vtkImageData. Use keyword arguments to specify the dimensions, spacing, and origin of the uniform grid.

Changed in version 0.37.0: The dims parameter has been renamed to dimensions.

Parameters:

uinputstr | vtkImageData | ImageData, optional

Filename or dataset to initialize the uniform grid from. If set, remainder of arguments are ignored.

dimensionssequence[int], optional

dimensions of the uniform grid.

spacingsequence[float], default: (1.0, 1.0, 1.0)

spacing of the uniform grid in each dimension. Must be positive.

originsequence[float], default: (0.0, 0.0, 0.0)

origin of the uniform grid.

deepbool, default: False

Whether to deep copy a vtkImageData object. Keyword only.

direction_matrixRotationLike, optional

The direction_matrix is a 3x3 matrix which controls the orientation of the image data.

Added in version 0.45.

offsetint | VectorLike[int], default: (0, 0, 0)

The offset defines the minimum extent of the image. Offset values can be positive or negative. In physical space, the offset is relative to the image’s origin.

Added in version 0.45.

validatebool | MeshValidationFields | sequence[MeshValidationFields], default: False

Validate the mesh using validate_mesh() after initialization. Set this to True to validate all fields, or specify any combination of fields allowed by validate_mesh.

Added in version 0.47.

Examples

Download Python source code | Download Jupyter notebook

Create an empty ImageData.

>>> import pyvista as pv
>>> grid = pv.ImageData()

Initialize from a vtkImageData object.

>>> import vtk
>>> vtkgrid = vtk.vtkImageData()
>>> grid = pv.ImageData(vtkgrid)

Initialize using just the grid dimensions and default spacing and origin. These must be keyword arguments.

>>> grid = pv.ImageData(dimensions=(10, 10, 10))

Initialize using dimensions and spacing.

>>> grid = pv.ImageData(
...     dimensions=(10, 10, 10),
...     spacing=(2, 1, 5),
... )

Initialize using dimensions, spacing, and an origin.

>>> grid = pv.ImageData(
...     dimensions=(10, 10, 10),
...     spacing=(2, 1, 5),
...     origin=(10, 35, 50),
... )

Initialize from another ImageData.

>>> grid = pv.ImageData(
...     dimensions=(10, 10, 10),
...     spacing=(2, 1, 5),
...     origin=(10, 35, 50),
... )
>>> grid_from_grid = pv.ImageData(grid)
>>> grid_from_grid == grid
True

Used In

Guides

• PyVista Data Model (1 use)
• Transitioning From VTK to PyVista (1 use)

Docstring Examples

• DataObject.add_field_data (1 use)
• DataObject.copy_attributes (1 use)
• DataObject.copy_structure (1 use)
• DataSet.area (1 use)
• DataSet.cell (1 use)
• 40 more

  • DataSet.dimensionality (1 use)
  • DataSet.find_containing_cell (1 use)
  • DataSet.intersect_with_line (1 use)
  • DataSet.plot (1 use)
  • DataSet.volume (1 use)
  • DataSetFilters.contour (1 use)
  • DataSetFilters.partition (1 use)
  • DataSetFilters.remove_nan_cells (1 use)
  • DataSetFilters.voxelize_binary_mask (1 use)
  • Grid.dimensions (1 use)
  • Grid.to_hexahedra (1 use)
  • Grid.to_quads (1 use)
  • ImageData.extent (1 use)
  • ImageData.offset (1 use)
  • ImageData.origin (1 use)
  • ImageData.points (1 use)
  • ImageData.spacing (1 use)
  • ImageData.x (1 use)
  • ImageData.y (1 use)
  • ImageData.z (1 use)
  • ImageDataFilters.dilate (1 use)
  • ImageDataFilters.erode (1 use)
  • ImageDataFilters.label_connectivity (1 use)
  • ImageDataFilters.resample (1 use)
  • ImageDataFilters.slice_index (1 use)
  • MultiBlock.flatten (1 use)
  • MultiBlock.get (1 use)
  • MultiBlock.get_block (1 use)
  • MultiBlock.plot (1 use)
  • PartitionedDataSet.plot (1 use)
  • Plotter.add_volume (1 use)
  • Plotter.enable_ssao (1 use)
  • PointSet.plot (1 use)
  • RectilinearGrid.dimensions (1 use)
  • Renderer.enable_ssao (1 use)
  • Volume.mapper (1 use)
  • Volume.prop (1 use)
  • VolumeProperty.interpolation_type (1 use)
  • cartesian_to_spherical (1 use)
  • plot (1 use)

Gallery Examples

Compare Interpolation/Sampling Methods

Compare Interpolation/Sampling Methods

5 uses

Creating a Uniform Grid

Creating a Uniform Grid

2 uses

Image Data Representations

Image Data Representations

2 uses

Marching Cubes

Marching Cubes

2 uses

Blurring

Blurring

1 use

Clip Volume Widget

Clip Volume Widget

1 use

Depth of Field Plotting

Depth of Field Plotting

1 use

Detailed Interpolating Points

Detailed Interpolating Points

1 use

Electronics Cooling CFD

Electronics Cooling CFD

1 use

Extract Cell Centers

Extract Cell Centers

1 use

Extract Surface

Extract Surface

1 use

Fast Fourier Transform With Perlin Noise

Fast Fourier Transform With Perlin Noise

1 use

Plot CFD Data

Plot CFD Data

1 use

Plot a Gyroid Surface

Plot a Gyroid Surface

1 use

Streamlines

Streamlines

1 use

Surface Space Ambient Occlusion

Surface Space Ambient Occlusion

1 use

Inheritance

Inherited members are documented on Grid, DataSet, _BoundsSizeMixin, ImageDataFilters, DataSetFilters, DataObjectFilters, DataObject.

See them all under Inherited Attributes, Inherited Methods and Filters.

Wraps vtkImageData.

Attributes

ImageData.direction_matrix	Set or get the direction matrix.
ImageData.extent	Return or set the extent of the ImageData.
ImageData.index_to_physical_matrix	Return or set 4x4 matrix to transform index space (ijk) to physical space (xyz).
ImageData.offset	Return or set the index offset of the ImageData.
ImageData.origin	Return the origin of the grid (bottom southwest corner).
ImageData.physical_to_index_matrix	Return or set the 4x4 matrix from physical (xyz) to index (ijk) space.
ImageData.points	Build a copy of the implicitly defined points as a NumPy array.
ImageData.spacing	Return or set the spacing for each axial direction.
ImageData.x	Return all the X points.
ImageData.y	Return all the Y points.
ImageData.z	Return all the Z points.

Inherited Attributes

DataSet.active_normals	Return the active normals as an array.
DataSet.active_scalars	Return the active scalars as an array.
DataSet.active_scalars_info	Return the active scalar’s association and name.
DataSet.active_scalars_name	Return the name of the active scalars.
DataSet.active_tensors	Return the active tensors array.
DataSet.active_tensors_info	Return the active tensor’s field and name: [field, name].
DataSet.active_tensors_name	Return the name of the active tensor array.
DataSet.active_texture_coordinates	Return the active texture coordinates on the points.
DataSet.active_vectors	Return the active vectors array.
DataSet.active_vectors_info	Return the active vector’s association and name.
DataSet.active_vectors_name	Return the name of the active vectors array.
DataObject.actual_memory_size	Return the actual size of the dataset object.
DataSet.area	Return the mesh area if 2D.
DataSet.array_names	Return a list of array names for the dataset.
DataSet.arrows	Return a glyph representation of the active vector data as arrows.
DataSet.bounding_sphere	Compute the radius and center of a bounding sphere.
DataSet.bounds	Return the bounding box of this dataset.
_BoundsSizeMixin.bounds_size	Return the size of each axis of the object’s bounding box.
DataSet.cell	A generator that provides an easy way to loop over all cells.
DataSet.cell_data	Return cell data as DataSetAttributes.
DataSet.center	Set or return the center of the bounding box.
DataSet.dimensionality	Return the number of spatial dimensions spanned by this dataset’s points.
Grid.dimensions	Return the grid’s dimensions.
DataSet.distinct_cell_types	Return the set of distinct cell types in this dataset.
DataObject.field_data	Return FieldData as DataSetAttributes.
DataSet.has_nonlinear_cells	Return True if the mesh contains any non-linear cells.
DataSet.is_empty	Return True if there are no points.
DataSet.length	Return the length of the diagonal of the bounding box.
DataSet.max_cell_dimensionality	Return the maximum spatial dimensionality of all cells in this mesh.
DataObject.memory_address	Get address of the underlying VTK C++ object.
DataSet.min_cell_dimensionality	Get the minimum spatial dimensionality of all cells in this mesh.
DataSet.n_arrays	Return the number of arrays present in the dataset.
DataSet.n_cells	Return the number of cells in the entire dataset.
DataSet.n_points	Return the number of points in the entire dataset.
DataSet.number_of_cells	Return the number of cells.
DataSet.number_of_points	Return the number of points.
DataSet.point_data	Return point data as DataSetAttributes.
DataObject.user_dict	Set or return a user-specified data dictionary.
DataSet.volume	Return the mesh volume.

Methods

ImageData.cast_to_rectilinear_grid()	Cast this uniform grid to a rectilinear grid.
ImageData.cast_to_structured_grid()	Cast this image data to a StructuredGrid.
ImageData.to_tetrahedra([tetra_per_cell, ...])	Create a tetrahedral mesh structured grid.

Inherited Methods

DataObject.add_field_data	Add field data.
DataObject.cast_to_multiblock	Convert this DataObject to a MultiBlock.
DataSet.cast_to_pointset	Extract the points of this dataset and return a pyvista.PointSet.
DataSet.cast_to_poly_points	Extract the points of this dataset and return a pyvista.PolyData.
DataSet.cast_to_unstructured_grid	Get a new representation of this object as a UnstructuredGrid.
DataSet.cell_neighbors	Get the cell neighbors of the ind-th cell.
DataSet.cell_neighbors_levels	Get consecutive levels of cell neighbors.
DataSet.clear_cell_data	Remove all cell arrays.
DataSet.clear_data	Remove all arrays from point/cell/field data.
DataObject.clear_field_data	Remove all field data.
DataSet.clear_point_data	Remove all point arrays.
DataObject.copy	Return a copy of the object.
DataObject.copy_attributes	Copy the data attributes of the input dataset object.
DataSet.copy_from	Overwrite this dataset in-place with the new dataset’s geometries and data.
DataSet.copy_meta_from	Copy pyvista meta data onto this object from another object.
DataObject.copy_structure	Copy the structure (geometry and topology) of the input dataset object.
DataObject.deep_copy	Overwrite this data object with another data object as a deep copy.
DataSet.find_cells_along_line	Find the index of cells whose bounds intersect a line.
DataSet.find_cells_intersecting_line	Find the index of cells that intersect a line.
DataSet.find_cells_within_bounds	Find the index of cells in this mesh within bounds.
DataSet.find_closest_cell	Find index of closest cell in this mesh to the given point.
DataSet.find_closest_point	Find index of closest point in this mesh to the given point.
DataSet.find_containing_cell	Find index of a cell that contains the given point.
DataSet.get_array	Search both point, cell, and field data for an array.
DataSet.get_array_association	Get the association of an array.
DataSet.get_cell	Return a pyvista.Cell object.
DataSet.get_data_range	Get the min and max of a named array.
DataObject.head	Return the header stats of this dataset.
DataSet.intersect_with_line	Locate points and cell ids that intersect a line.
DataSet.plot	Plot a PyVista, NumPy, or VTK object.
DataSet.point_cell_ids	Get the cell IDs that use the ind-th point.
DataSet.point_is_inside_cell	Return whether one or more points are inside a cell.
DataSet.point_neighbors	Get the point neighbors of the ind-th point.
DataSet.point_neighbors_levels	Get consecutive levels of point neighbors.
DataSet.rename_array	Change array name by searching for the array then renaming it.
DataObject.save	Save this vtk object to file.
DataSet.set_active_scalars	Find the scalars by name and appropriately sets it as active.
DataSet.set_active_tensors	Find the tensors by name and appropriately sets it as active.
DataSet.set_active_vectors	Find the vectors by name and appropriately sets it as active.
DataObject.shallow_copy	Shallow copy the given mesh to this mesh.
DataSet.to_arrow	Return this dataset’s point or cell arrays as a pyarrow.Table.
Grid.to_hexahedra	Convert voxels to hexahedra.
DataSet.to_pandas	Return this dataset’s point or cell arrays as a pandas.DataFrame.
Grid.to_quads	Convert pixels to quads.

Filters

DataSetFilters.align	Align a dataset to another.
DataSetFilters.align_xyz	Align a dataset to the x-y-z axes.
DataSetFilters.bounding_box	Return a bounding box for this dataset.
DataObjectFilters.cell_centers	Generate points at the center of the cells in this dataset.
DataObjectFilters.cell_data_to_point_data	Transform cell data into point data.
DataObjectFilters.cell_quality	Compute a function of (geometric) quality for each cell of a mesh.
DataObjectFilters.cell_validator	Check the validity of each cell in this dataset.
ImageDataFilters.cells_to_points	Re-mesh image data from a cell-based to a point-based representation.
DataObjectFilters.clip	Clip a dataset by a plane by specifying the origin and normal.
DataObjectFilters.clip_box	Clip a dataset by a bounding box defined by the bounds.
DataSetFilters.clip_scalar	Clip a dataset by a scalar.
DataObjectFilters.clip_slab	Clip a dataset by a slab of finite thickness around a plane.
DataSetFilters.clip_surface	Clip any mesh type using a pyvista.PolyData surface mesh.
ImageDataFilters.close	Perform morphological closing on continuous or binary data.
DataSetFilters.color_labels	Add RGB(A) scalars to labeled data.
DataSetFilters.compute_boundary_mesh_quality	Compute metrics on the boundary faces of a mesh.
DataObjectFilters.compute_cell_sizes	Compute sizes for 0D (vertex count), 1D (length), 2D (area) and 3D (volume) cells.
DataSetFilters.compute_derivative	Compute derivative-based quantities of point/cell scalar field.
DataSetFilters.compute_implicit_distance	Compute the implicit distance from the points to a surface.
ImageDataFilters.concatenate	Combine multiple images into one.
DataSetFilters.connectivity	Find and label connected regions.
DataSetFilters.contour	Contour an input self by an array.
ImageDataFilters.contour_labels	Generate surface contours from 3D image label maps.
DataObjectFilters.convex_hull	Compute the convex hull from this mesh’s points.
ImageDataFilters.crop	Crop this image to remove points at its boundaries.
DataObjectFilters.ctp	Transform cell data into point data.
DataSetFilters.decimate_boundary	Return a decimated version of a triangulation of the boundary.
DataSetFilters.delaunay_3d	Construct a 3D Delaunay triangulation of the mesh.
ImageDataFilters.dilate	Morphologically dilate grayscale or binary data.
DataObjectFilters.elevation	Generate scalar values on a dataset.
ImageDataFilters.erode	Morphologically erode grayscale or binary data.
DataSetFilters.explode	Push each individual cell away from the center of the dataset.
DataObjectFilters.extract_all_edges	Extract all the internal/external edges of the dataset as PolyData.
DataSetFilters.extract_cells	Return a subset of the grid.
DataSetFilters.extract_cells_by_type	Extract cells of a specified type.
DataSetFilters.extract_feature_edges	Extract edges from the surface of the mesh.
DataSetFilters.extract_geometry	Extract the outer surface of a volume or structured grid dataset.
DataSetFilters.extract_largest	Extract largest connected set in mesh.
DataSetFilters.extract_points	Return a subset of the grid (with cells) that contains any of the given point indices.
ImageDataFilters.extract_subset	Select piece (for example, volume of interest).
DataObjectFilters.extract_surface	Extract surface geometry of the mesh as PolyData.
DataSetFilters.extract_values	Return a subset of the mesh based on the values of point or cell data.
ImageDataFilters.fft	Apply a fast Fourier transform (FFT) to the active scalars.
DataObjectFilters.flip_normal	Flip mesh about the normal.
DataObjectFilters.flip_x	Flip mesh about the x-axis.
DataObjectFilters.flip_y	Flip mesh about the y-axis.
DataObjectFilters.flip_z	Flip mesh about the z-axis.
ImageDataFilters.gaussian_smooth	Smooth the data with a Gaussian kernel.
DataSetFilters.gaussian_splatting	Splat points into a volume using a Gaussian distribution.
DataSetFilters.glyph	Copy a geometric representation (called a glyph) to the input dataset.
ImageDataFilters.high_pass	Perform a Butterworth high pass filter in the frequency domain.
ImageDataFilters.image_dilate_erode	Dilates one value and erodes another.
ImageDataFilters.image_threshold	Apply a threshold to scalar values in a uniform grid.
DataSetFilters.integrate_data	Integrate point and cell data.
DataSetFilters.interpolate	Interpolate values onto this mesh from a given dataset.
ImageDataFilters.label_connectivity	Find and label connected regions in a ImageData.
ImageDataFilters.low_pass	Perform a Butterworth low pass filter in the frequency domain.
ImageDataFilters.median_smooth	Smooth data using a median filter.
DataSetFilters.merge	Join one or many other grids to this grid.
DataSetFilters.merge_points	Merge duplicate points in this mesh.
ImageDataFilters.open	Perform morphological opening on continuous or binary data.
DataSetFilters.oriented_bounding_box	Return an oriented bounding box (OBB) for this dataset.
DataSetFilters.outline	Produce an outline of the full extent for the input dataset.
DataSetFilters.outline_corners	Produce an outline of the corners for the input dataset.
DataSetFilters.pack_labels	Renumber labeled data such that labels are contiguous.
ImageDataFilters.pad_image	Enlarge an image by padding its boundaries with new points.
DataSetFilters.partition	Break down input dataset into a requested number of partitions.
DataSetFilters.plot_over_circular_arc	Sample a dataset along a circular arc and plot it.
DataSetFilters.plot_over_circular_arc_normal	Sample a dataset along a circular arc defined by a normal and polar vector and plot it.
DataSetFilters.plot_over_line	Sample a dataset along a high resolution line and plot.
DataObjectFilters.point_data_to_cell_data	Transform point data into cell data.
ImageDataFilters.points_to_cells	Re-mesh image data from a point-based to a cell-based representation.
DataObjectFilters.ptc	Transform point data into cell data.
DataObjectFilters.reflect	Reflect a dataset across a plane.
DataSetFilters.remove_nan_cells	Remove cells whose scalar values are NaN.
ImageDataFilters.resample	Resample the image to modify its dimensions and spacing.
DataObjectFilters.resize	Resize the dataset’s bounds.
ImageDataFilters.rfft	Apply a reverse fast Fourier transform (RFFT) to the active scalars.
DataObjectFilters.rotate	Rotate mesh about a point with a rotation matrix or Rotation object.
DataObjectFilters.rotate_vector	Rotate mesh about a vector.
DataObjectFilters.rotate_x	Rotate mesh about the x-axis.
DataObjectFilters.rotate_y	Rotate mesh about the y-axis.
DataObjectFilters.rotate_z	Rotate mesh about the z-axis.
DataObjectFilters.sample	Resample array data from a passed mesh onto this mesh.
DataSetFilters.sample_over_circular_arc	Sample a dataset over a circular arc.
DataSetFilters.sample_over_circular_arc_normal	Sample a dataset over a circular arc defined by a normal and polar vector and plot it.
DataSetFilters.sample_over_line	Sample a dataset onto a line.
DataSetFilters.sample_over_multiple_lines	Sample a dataset onto a multiple lines.
DataObjectFilters.scale	Scale the mesh.
DataSetFilters.select_enclosed_points	Mark points as to whether they are inside a closed surface.
DataSetFilters.select_interior_points	Mark points from this mesh as inside or outside relative to a closed surface.
ImageDataFilters.select_values	Select values of interest and fill the rest with a constant.
DataSetFilters.separate_cells	Return a copy of the dataset with separated cells with no shared points.
DataSetFilters.shrink	Shrink the individual faces of a mesh.
DataObjectFilters.slice	Slice a dataset by a plane at the specified origin and normal vector orientation.
DataObjectFilters.slice_along_axis	Create many slices of the input dataset along a specified axis.
DataObjectFilters.slice_along_line	Slice a dataset using a polyline/spline as the path.
DataObjectFilters.slice_implicit	Slice a dataset by a VTK implicit function.
ImageDataFilters.slice_index	Extract a subset using IJK indices.
DataObjectFilters.slice_orthogonal	Create three orthogonal slices through the dataset on the three Cartesian planes.
DataSetFilters.sort_labels	Sort labeled data by number of points or cells.
DataSetFilters.split_bodies	Find, label, and split connected bodies/volumes.
DataSetFilters.split_values	Split mesh into separate sub-meshes using point or cell data.
DataSetFilters.streamlines	Integrate a vector field to generate streamlines.
DataSetFilters.streamlines_evenly_spaced_2D	Generate evenly spaced streamlines on a 2D dataset.
DataSetFilters.streamlines_from_source	Generate streamlines of vectors from the points of a source mesh.
DataSetFilters.surface_indices	Return the surface indices of a grid.
DataSetFilters.tessellate	Tessellate a mesh.
DataSetFilters.texture_map_to_plane	Texture map this dataset to a user defined plane.
DataSetFilters.texture_map_to_sphere	Texture map this dataset to a user defined sphere.
DataSetFilters.threshold	Apply a vtkThreshold filter to the input dataset.
DataSetFilters.threshold_percent	Threshold the dataset by a percentage of its range on the active scalars array.
DataObjectFilters.transform	Transform this mesh with a 4x4 transform.
DataObjectFilters.translate	Translate the mesh.
DataObjectFilters.triangulate	Return an all triangle mesh.
DataObjectFilters.validate_mesh	Validate this mesh’s array data, points, and cells.
DataSetFilters.voxelize	Voxelize mesh to UnstructuredGrid.
DataSetFilters.voxelize_binary_mask	Voxelize mesh as a binary ImageData mask.
DataSetFilters.voxelize_rectilinear	Voxelize mesh to create a RectilinearGrid voxel volume.
DataSetFilters.warp_by_scalar	Warp the dataset’s points by a point data scalars array’s values.
DataSetFilters.warp_by_vector	Warp the dataset’s points by a point data vectors array’s values.