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

The Common Model

The pyvista.Common 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_scalar	Returns the active scalar as an array
active_scalar_info	[field, name]
active_scalar_name	Returns the active scalar’s name
active_vectors	The active vectors array
active_vectors_info	[field, name]
active_vectors_name	The name of the active vectors array
array_names	A list of scalar names for the dataset.
arrows	Returns a glyph representation of the active vector data as arrows.
bounds	bounding box of this dataset in the form (xmin,xmax, ymin,ymax, zmin,zmax)
cell_arrays	Returns the all cell arrays
center	Center of the bounding box
extent	The range of the bounding box
length	the length of the diagonal of the bounding box
n_arrays	The number of scalar arrays present in the dataset
n_cells	The number of cells in the entire dataset
n_points	The number of points in the entire dataset
n_scalars	Please use n_arrays
number_of_cells	returns the number of cells
number_of_points	returns the number of points
point_arrays	Returns the all point arrays
points	returns a pointer to the points as a numpy object
quality	Returns cell quality using PyANSYS.
scalar_names	Please use array_names
t_coords	The active texture coordinates on the points
textures	A dictionary to hold vtk.vtkTexture objects that can be associated with this dataset.
vectors	Returns active vectors
volume	Mesh volume

Methods

cast_to_unstructured_grid()	Get a new representation of this object as an pyvista.UnstructuredGrid
clear_arrays()	removes all arrays from point/cell/field data
clear_cell_arrays()	removes all cell arrays
clear_point_arrays()	removes all point arrays
clear_textures()	Clear the textures from this mesh
copy_meta_from(ido)	Copies pyvista meta data onto this object from another object
get_array(name[, preference, info])	Searches both point, cell and field data for an array
get_data_range([arr, preference])	Get the non-NaN min and max of a named scalar array
overwrite(mesh)	Overwrites this mesh inplace with the new mesh’s geometries and data
plot([off_screen, full_screen, screenshot, …])	Convenience plotting function for a vtk or numpy object.
points_to_double()	Makes points double precision
rename_scalar(old_name, new_name[, preference])	Changes array name by searching for the array then renaming it
rotate_x(angle)	Rotates mesh about the x-axis.
rotate_y(angle)	Rotates mesh about the y-axis.
rotate_z(angle)	Rotates mesh about the z-axis.
set_active_scalar(name[, preference])	Finds the scalar by name and appropriately sets it as active.
set_active_vectors(name[, preference])	Finds the vectors by name and appropriately sets it as active To deactivate any active scalars, pass None as the name.
transform(trans)	Compute a transformation in place using a 4x4 transform.
translate(xyz)	Translates the mesh.

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

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

Methods in common to spatially referenced objects

property active_scalar

Returns the active scalar as an array

property active_scalar_info

[field, name]

Type

Return the active scalar’s field and name

property active_scalar_name

Returns the active scalar’s name

property active_vectors

The active vectors array

property active_vectors_info

[field, name]

Type

Return the active scalar’s field and name

property active_vectors_name

The name of the active vectors array

property array_names

A list of scalar names for the dataset. This makes sure to put the active scalar’s name first in the list.

property arrows

Returns 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

bounding box of this dataset in the form (xmin,xmax, ymin,ymax, zmin,zmax)

cast_to_unstructured_grid()

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

property cell_arrays

Returns the all cell arrays

property center

Center of the bounding box

clear_arrays()

removes all arrays from point/cell/field data

clear_cell_arrays()

removes all cell arrays

clear_point_arrays()

removes all point arrays

clear_textures()

Clear the textures from this mesh

copy_meta_from(ido)

Copies pyvista meta data onto this object from another object

property extent

The range of the bounding box

get_array(name, preference='cell', info=False)

Searches both point, cell and field data for an array

get_data_range(arr=None, preference='cell')

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

Parameters

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

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

property length

the length of the diagonal of the bounding box

property n_arrays

The number of scalar arrays present in the dataset

property n_cells

The number of cells in the entire dataset

property n_points

The number of points in the entire dataset

property n_scalars

Please use n_arrays

Type

DEPRECATED

property number_of_cells

returns the number of cells

property number_of_points

returns the number of points

overwrite(mesh)

Overwrites 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, use_panel=None, volume=False, parallel_projection=False, **kwargs)

Convenience plotting function for 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(pyvistanterface.Plotter.screenshot). Default disabled.

  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.

• **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

Returns the all point arrays

property points

returns a pointer to the points as a numpy object

points_to_double()

Makes points double precision

property quality

Returns cell quality using PyANSYS. Computes the minimum scaled jacobian of each cell. Cells that have values below 0 are invalid for a finite element analysis.

Note

This casts the input to an unstructured grid

Returns

cellquality – Minimum scaled jacobian of each cell. Ranges from -1 to 1.

Return type

np.ndarray

Notes

Requires pyansys to be installed.

rename_scalar(old_name, new_name, preference='cell')

Changes array name by searching for the array then renaming it

rotate_x(angle)

Rotates mesh about the x-axis.

Parameters

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

rotate_y(angle)

Rotates mesh about the y-axis.

Parameters

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

rotate_z(angle)

Rotates mesh about the z-axis.

Parameters

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

property scalar_names

Please use array_names

Type

DEPRECATED

set_active_scalar(name, preference='cell')

Finds the scalar by name and appropriately sets it as active. To deactivate any active scalars, pass None as the name.

set_active_vectors(name, preference='point')

Finds the vectors by name and appropriately sets it as active To deactivate any active scalars, pass None as the name.

property t_coords

The active texture coordinates on the points

property textures

A dictionary to hold vtk.vtkTexture objects that can be associated with this dataset. When casting back to a VTK dataset or filtering this dataset, these textures will not be passed.

transform(trans)

Compute a transformation in place using a 4x4 transform.

Parameters

trans (vtk.vtkMatrix4x4, vtk.vtkTransform, or np.ndarray) – Accepts a vtk transformation object or a 4x4 transformation matrix.

translate(xyz)

Translates the mesh.

Parameters

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

property vectors

Returns active vectors

property volume

Mesh volume

Returns

volume – Total volume of the mesh.

Return type

float