Datasets

Datasets are any spatially reference information and usually consist of geometrical representations of a surface or volume in 3D space. In VTK, this superclass is represented by the vtk.vtkDataSet abstract class.

In VTK, datasets consist of geometry, topology, and attributes to which PyVista provides direct access:

  • Geometry is the collection of points and cells in 2D or 3D space.

  • Topology defines the structure of the dataset, or how the points are connected to each other to form a cells making a surface or volume.

  • Attributes are any data values that are associated to either the points or cells of the dataset

All of the following data types are listed subclasses of a dataset and share a set of common functionality which we wrap into the base class pyvista.DataSet.

The DataSet Model

The pyvista.DataSet class holds attributes that are common to all spatially referenced datasets in PyVista. This base class is analogous to VTK’s vtk.vtkDataSet class.

Attributes

active_scalars

Return the active scalars as an array.

active_scalars_info

[field, name].

active_scalars_name

Return the active scalar’s name.

active_tensors

Return the active tensors array.

active_tensors_info

[field, name].

active_tensors_name

Return the name of the active tensor array.

active_vectors

Return the active vectors array.

active_vectors_info

[field, name].

active_vectors_name

Return the name of the active vectors array.

array_names

Return a list of array names for the dataset.

arrows

Return a glyph representation of the active vector data as arrows.

bounds

Return the bounding box of this dataset.

cell_arrays

Return vtkCellData as DataSetAttributes.

center

Return the center of the bounding box.

extent

Return the range of the bounding box.

length

Return the length of the diagonal of the bounding box.

n_arrays

Return the number of arrays present in the dataset.

n_cells

Return the number of cells in the entire dataset.

n_points

Return the number of points in the entire dataset.

number_of_cells

Return the number of cells.

number_of_points

Return the number of points.

point_arrays

Return vtkPointData as DataSetAttributes.

points

Return a pointer to the points as a numpy object.

t_coords

Return the active texture coordinates on the points.

textures

Return a dictionary to hold compatible vtk.vtkTexture objects.

vectors

Return active vectors.

volume

Return the mesh volume.

Methods

cast_to_unstructured_grid()

Get a new representation of this object as an pyvista.UnstructuredGrid.

cell_bounds(ind)

Return the bounding box of a cell.

cell_n_points(ind)

Return the number of points in a cell.

cell_points(ind)

Return the points in a cell.

cell_type(ind)

Return the type of a cell.

clear_arrays()

Remove all arrays from point/cell/field data.

clear_cell_arrays()

Remove all cell arrays.

clear_point_arrays()

Remove all point arrays.

clear_textures()

Clear the textures from this mesh.

copy_meta_from(ido)

Copy pyvista meta data onto this object from another object.

find_closest_cell(point)

Find index of closest cell in this mesh to the given point.

find_closest_point(point[, n])

Find index of closest point in this mesh to the given point.

get_array(name[, preference, info])

Search both point, cell and field data for an array.

get_data_range([arr_var, preference])

Get the non-NaN min and max of a named array.

overwrite(mesh)

Overwrite this mesh inplace with the new mesh’s geometries and data.

plot([off_screen, full_screen, screenshot, …])

Plot a vtk or numpy object.

points_to_double()

Make points double precision.

rename_array(old_name, new_name[, preference])

Change array name by searching for the array then renaming it.

rotate_x(angle[, transform_all_input_vectors])

Rotate mesh about the x-axis.

rotate_y(angle[, transform_all_input_vectors])

Rotate mesh about the y-axis.

rotate_z(angle[, transform_all_input_vectors])

Rotate mesh about the z-axis.

set_active_scalars(name[, preference])

Find the scalars by name and appropriately sets it as active.

set_active_tensors(name[, preference])

Find the tensors by name and appropriately sets it as active.

set_active_vectors(name[, preference])

Find the vectors by name and appropriately sets it as active.

translate(xyz)

Translate the mesh.

class pyvista.DataSet(*args, **kwargs)

Bases: pyvista.core.filters.DataSetFilters, pyvista.core.dataobject.DataObject

Methods in common to spatially referenced objects.

property active_scalars

Return the active scalars as an array.

property active_scalars_info

[field, name].

Type

Return the active scalar’s field and name

property active_scalars_name

Return the active scalar’s name.

property active_tensors

Return the active tensors array.

property active_tensors_info

[field, name].

Type

Return the active tensor’s field and name

property active_tensors_name

Return the name of the active tensor array.

property active_vectors

Return the active vectors array.

property active_vectors_info

[field, name].

Type

Return the active scalar’s field and name

property active_vectors_name

Return the name of the active vectors array.

property array_names

Return a list of array names for the dataset.

This makes sure to put the active scalars’ name first in the list.

property arrows

Return a glyph representation of the active vector data as arrows.

Arrows will be located at the points of the mesh and their size will be dependent on the length of the vector. Their direction will be the “direction” of the vector

Returns

arrows – Active scalars represented as arrows.

Return type

pyvista.PolyData

property bounds

Return the bounding box of this dataset.

The form is: (xmin,xmax, ymin,ymax, zmin,zmax).

cast_to_unstructured_grid()pyvista.core.pointset.UnstructuredGrid

Get a new representation of this object as an pyvista.UnstructuredGrid.

property cell_arrays

Return vtkCellData as DataSetAttributes.

cell_bounds(ind: int)List[float]

Return the bounding box of a cell.

Parameters

ind (int) – Cell ID.

Returns

The limits of the cell in the X, Y and Z directions respectivelly.

Return type

list(float)

Examples

>>> from pyvista import examples
>>> mesh = examples.load_airplane()
>>> mesh.cell_bounds(0)
[896.9940185546875, 907.5390014648438, 48.760101318359375, 55.49020004272461, 80.74520111083984, 83.65809631347656]
cell_n_points(ind: int)int

Return the number of points in a cell.

Parameters

ind (int) – Cell ID.

Returns

Number of points in the cell.

Return type

int

Examples

>>> from pyvista import examples
>>> mesh = examples.load_airplane()
>>> mesh.cell_n_points(0)
3
cell_points(ind: int)numpy.ndarray

Return the points in a cell.

Parameters

ind (int) – Cell ID.

Returns

An array of floats with shape (number of points, 3) containing the coordinates of the cell corners.

Return type

numpy.ndarray

Examples

>>> from pyvista import examples
>>> mesh = examples.load_airplane()
>>> mesh.cell_points(0)  
[[896.99401855  48.76010132  82.26560211]
 [906.59301758  48.76010132  80.74520111]
 [907.53900146  55.49020004  83.65809631]]
cell_type(ind: int)int

Return the type of a cell.

Parameters

ind (int) – Cell ID.

Returns

VTK cell type. See <https://vtk.org/doc/nightly/html/vtkCellType_8h_source.html>.

Return type

int

Examples

>>> from pyvista import examples
>>> mesh = examples.load_airplane()
>>> mesh.cell_type(0)
5
property center

Return the center of the bounding box.

clear_arrays()

Remove all arrays from point/cell/field data.

clear_cell_arrays()

Remove all cell arrays.

clear_point_arrays()

Remove all point arrays.

clear_textures()

Clear the textures from this mesh.

copy_meta_from(ido: pyvista.core.dataset.DataSet)

Copy pyvista meta data onto this object from another object.

property extent

Return the range of the bounding box.

find_closest_cell(point: Union[int, numpy.ndarray])Union[int, numpy.ndarray]

Find index of closest cell in this mesh to the given point.

Parameters

point (iterable(float) or np.ndarray) – Length 3 coordinate of the point to query or a numpy array of coordinates.

Returns

index – Index or indices of the cell in this mesh that is closest to the given point.

Return type

int or np.ndarray

Examples

Find nearest cell to a point on a sphere

>>> import pyvista
>>> mesh = pyvista.Sphere()
>>> index = mesh.find_closest_cell([0, 0, 0.5])
>>> index
59

Find the nearest cells to several random points. Note that -1 indicates that the locator was not able to find a reasonably close cell.

>>> import numpy as np
>>> points = np.random.random((1000, 3))
>>> indices = mesh.find_closest_cell(points)
>>> print(indices.shape)
(1000,)
find_closest_point(point: Iterable[float], n=1)int

Find index of closest point in this mesh to the given point.

If wanting to query many points, use a KDTree with scipy or another library as those implementations will be easier to work with.

See: https://github.com/pyvista/pyvista-support/issues/107

Parameters
  • point (iterable(float)) – Length 3 coordinate of the point to query.

  • n (int, optional) – If greater than 1, returns the indices of the n closest points.

Returns

int

Return type

the index of the point in this mesh that is closes to the given point.

get_array(name: str, preference='cell', info=False)Union[Tuple, numpy.ndarray]

Search both point, cell and field data for an array.

get_data_range(arr_var: Optional[Union[str, numpy.ndarray]] = None, preference='cell')Tuple[Union[float, numpy.ndarray], Union[float, numpy.ndarray]]

Get the non-NaN min and max of a named array.

Parameters
  • arr_var (str, np.ndarray, optional) – The name of the array to get the range. If None, the active scalars is used.

  • preference (str, optional) – When scalars is specified, this is the preferred array type to search for in the dataset. Must be either 'point', 'cell', or 'field'.

property length

Return the length of the diagonal of the bounding box.

property n_arrays

Return the number of arrays present in the dataset.

property n_cells

Return the number of cells in the entire dataset.

property n_points

Return the number of points in the entire dataset.

property number_of_cells

Return the number of cells.

property number_of_points

Return the number of points.

overwrite(mesh: vtkmodules.vtkCommonDataModel.vtkDataSet)

Overwrite this mesh inplace with the new mesh’s geometries and data.

Parameters

mesh (vtk.vtkDataSet) – The overwriting mesh.

plot(off_screen=None, full_screen=False, screenshot=None, interactive=True, cpos=None, window_size=None, show_bounds=False, show_axes=True, notebook=None, background=None, text='', return_img=False, eye_dome_lighting=False, volume=False, parallel_projection=False, use_ipyvtk=None, jupyter_backend=None, return_viewer=False, jupyter_kwargs={}, **kwargs)

Plot a vtk or numpy object.

Parameters
  • item (vtk or numpy object) – VTK object or numpy array to be plotted.

  • off_screen (bool) – Plots off screen when True. Helpful for saving screenshots without a window popping up.

  • full_screen (bool, optional) – Opens window in full screen. When enabled, ignores window_size. Default False.

  • screenshot (str or bool, optional) –

    Saves screenshot to file when enabled. See: help(pyvista.Plotter.screenshot). Default False.

    When True, takes screenshot and returns numpy array of image.

  • window_size (list, optional) – Window size in pixels. Defaults to [1024, 768]

  • show_bounds (bool, optional) – Shows mesh bounds when True. Default False. Alias show_grid also accepted.

  • notebook (bool, optional) – When True, the resulting plot is placed inline a jupyter notebook. Assumes a jupyter console is active.

  • show_axes (bool, optional) – Shows a vtk axes widget. Enabled by default.

  • text (str, optional) – Adds text at the bottom of the plot.

  • volume (bool, optional) – Use the add_volume method for volume rendering.

  • use_ipyvtk (bool, optional) – Deprecated. Instead, set the backend either globally with pyvista.set_jupyter_backend('ipyvtklink') or with backend='ipyvtklink'.

  • jupyter_backend (str, optional) –

    Jupyter notebook plotting backend to use. One of the following:

    • 'none' : Do not display in the notebook.

    • 'static' : Display a static figure.

    • 'ipygany' : Show a ipygany widget

    • 'panel' : Show a panel widget.

    This can also be set globally with pyvista.set_jupyter_backend

  • jupyter_kwargs (dict, optional) – Keyword arguments for the Jupyter notebook plotting backend.

  • **kwargs (optional keyword arguments) – See help(Plotter.add_mesh) for additional options.

Returns

  • cpos (list) – List of camera position, focal point, and view up.

  • img (numpy.ndarray) – Array containing pixel RGB and alpha. Sized: [Window height x Window width x 3] for transparent_background=False [Window height x Window width x 4] for transparent_background=True Returned only when screenshot enabled

property point_arrays

Return vtkPointData as DataSetAttributes.

property points

Return a pointer to the points as a numpy object.

points_to_double()

Make points double precision.

rename_array(old_name: str, new_name: str, preference='cell')

Change array name by searching for the array then renaming it.

rotate_x(angle: float, transform_all_input_vectors=False)

Rotate mesh about the x-axis.

Parameters

angle (float) – Angle in degrees to rotate about the x-axis.

rotate_y(angle: float, transform_all_input_vectors=False)

Rotate mesh about the y-axis.

Parameters

angle (float) – Angle in degrees to rotate about the y-axis.

rotate_z(angle: float, transform_all_input_vectors=False)

Rotate mesh about the z-axis.

Parameters

angle (float) – Angle in degrees to rotate about the z-axis.

set_active_scalars(name: str, preference='cell')

Find the scalars by name and appropriately sets it as active.

To deactivate any active scalars, pass None as the name.

set_active_tensors(name: str, preference='point')

Find the tensors by name and appropriately sets it as active.

To deactivate any active tensors, pass None as the name.

set_active_vectors(name: str, preference='point')

Find the vectors by name and appropriately sets it as active.

To deactivate any active vectors, pass None as the name.

property t_coords

Return the active texture coordinates on the points.

property textures

Return a dictionary to hold compatible vtk.vtkTexture objects.

When casting back to a VTK dataset or filtering this dataset, these textures will not be passed.

translate(xyz: Union[list, tuple, numpy.ndarray])

Translate the mesh.

Parameters

xyz (list or tuple or np.ndarray) – Length 3 list, tuple or array.

property vectors

Return active vectors.

property volume

Return the mesh volume.

Returns

volume – Total volume of the mesh.

Return type

float