General Utilities¶

Utilities routines.

pyvista.set_error_output_file(filename)¶: Set a file to write out the VTK errors.

pyvista.is_inside_bounds(point, bounds)¶

Check if a point is inside a set of bounds.

This is implemented through recursion so that this is N-dimensional.

Object Conversions¶

pyvista.wrap(dataset)¶

Wrap any given VTK data object to its appropriate pyvista data object.

Other formats that are supported include: * 2D numpy.ndarray of XYZ vertices * 3D numpy.ndarray representing a volume. Values will be scalars. * 3D trimesh.Trimesh mesh. * 3D meshio mesh.

Parameters: dataset (numpy.ndarray, trimesh.Trimesh, or VTK object) – Dataset to wrap.
Returns: wrapped_dataset – The pyvista wrapped dataset.
Return type: pyvista class

Examples

Wrap a numpy array representing a random point cloud.

>>> import numpy as np
>>> import pyvista
>>> points = np.random.random((10, 3))
>>> cloud = pyvista.wrap(points)
>>> cloud  
PolyData (0x7fc52db83d70)
  N Cells:  10
  N Points: 10
  X Bounds: 1.123e-01, 7.457e-01
  Y Bounds: 1.009e-01, 9.877e-01
  Z Bounds: 2.346e-03, 9.640e-01
  N Arrays: 0

Wrap a Trimesh object.

>>> import trimesh
>>> import pyvista
>>> points = [[0, 0, 0], [0, 0, 1], [0, 1, 0]]
>>> faces = [[0, 1, 2]]
>>> tmesh = trimesh.Trimesh(points, faces=faces, process=False)
>>> mesh = pyvista.wrap(tmesh)
>>> mesh  
PolyData (0x7fc55ff27ad0)
  N Cells:  1
  N Points: 3
  X Bounds: 0.000e+00, 0.000e+00
  Y Bounds: 0.000e+00, 1.000e+00
  Z Bounds: 0.000e+00, 1.000e+00
  N Arrays: 0

Wrap a VTK object.

>>> import pyvista
>>> import vtk
>>> points = vtk.vtkPoints()
>>> p = [1.0, 2.0, 3.0]
>>> vertices = vtk.vtkCellArray()
>>> pid = points.InsertNextPoint(p)
>>> _ = vertices.InsertNextCell(1)
>>> _ = vertices.InsertCellPoint(pid)
>>> point = vtk.vtkPolyData()
>>> _ = point.SetPoints(points)
>>> _ = point.SetVerts(vertices)
>>> mesh = pyvista.wrap(point)
>>> mesh  
PolyData (0x7fc55ff27ad0)
  N Cells:  1
  N Points: 3
  X Bounds: 0.000e+00, 0.000e+00
  Y Bounds: 0.000e+00, 1.000e+00
  Z Bounds: 0.000e+00, 1.000e+00
  N Arrays: 0

pyvista.is_pyvista_dataset(obj)¶: Return True if the Object is a PyVista wrapped dataset.

pyvista.image_to_texture(image)¶: Convert vtkImageData (pyvista.UniformGrid) to a vtkTexture.

pyvista.numpy_to_texture(image)¶: Convert a NumPy image array to a vtk.vtkTexture.

pyvista.array_from_vtkmatrix(matrix)¶

Convert a vtk matrix to a numpy.ndarray.

Parameters: matrix (vtk.vtkMatrix3x3 or vtk.vtkMatrix4x4) – The vtk matrix to be converted to a numpy.ndarray. Returned ndarray has shape (3, 3) or (4, 4) as appropriate.

pyvista.vtkmatrix_from_array(array)¶

Convert a numpy.ndarray or array-like to a vtk matrix.

Parameters: array (numpy.ndarray or array-like) – The array or array-like to be converted to a vtk matrix. Shape (3, 3) gets converted to a vtk.vtkMatrix3x3, shape (4, 4) gets converted to a vtk.vtkMatrix4x4. No other shapes are valid.

File IO¶

pyvista.read(filename, attrs=None, file_format=None)¶

Read any VTK file.

It will figure out what reader to use then wrap the VTK object for use in PyVista.

Parameters

filename (str) – The string path to the file to read. If a list of files is given, a pyvista.MultiBlock dataset is returned with each file being a separate block in the dataset.
attrs (dict, optional) – A dictionary of attributes to call on the reader. Keys of dictionary are the attribute/method names and values are the arguments passed to those calls. If you do not have any attributes to call, pass None as the value.
file_format (str, optional) – Format of file to read with meshio.

Examples

Load an example mesh

>>> import pyvista
>>> from pyvista import examples
>>> mesh = pyvista.read(examples.antfile)

Load a vtk file

>>> mesh = pyvista.read('my_mesh.vtk')  

Load a meshio file

>>> mesh = pyvista.read("mesh.obj")  

pyvista.read_exodus(filename, animate_mode_shapes=True, apply_displacements=True, displacement_magnitude=1.0, read_point_data=True, read_cell_data=True, enabled_sidesets=None)¶

Read an ExodusII file ('.e' or '.exo').

Parameters

filename (str) – The path to the exodus file to read.
animate_mode_shapes (bool, optional) – When True then this reader will report a continuous time range [0,1] and animate the displacements in a periodic sinusoid.
apply_displacements (bool, optional) – Geometric locations can include displacements. When True, the nodal positions are ‘displaced’ by the standard exodus displacement vector. If displacements are turned off, the user can explicitly add them by applying a warp filter.
displacement_magnitude (bool, optional) – This is a number between 0 and 1 that is used to scale the DisplacementMagnitude in a sinusoidal pattern.
read_point_data (bool, optional) – Read in data associated with points. Default True.
read_cell_data (bool, optional) – Read in data associated with cells. Default True.
enabled_sidesets (str or int, optional) – The name of the array that store the mapping from side set cells back to the global id of the elements they bound.

Examples

>>> import pyvista as pv
>>> from pyvista import examples
>>> data = read_exodus('mymesh.exo')  

pyvista.read_texture(filename, attrs=None)¶: Load a vtkTexture from an image file.

pyvista.read_legacy(filename)¶: Use VTK’s legacy reader to read a file.

pyvista.save_meshio(filename, mesh, file_format=None, **kwargs)¶

Save mesh to file using meshio.

Parameters

mesh (pyvista.DataSet) – Any PyVista mesh/spatial data type.
file_format (str) – File type for meshio to save.

Mesh Creation¶

pyvista.lines_from_points(points, close=False)¶

Make a connected line set given an array of points.

Parameters

points (np.ndarray) –
Points representing the vertices of the connected segments. For example, two line segments would be represented as:

np.array([[0, 0, 0], [1, 0, 0], [1, 1, 0]])
close (bool, optional) – If True, close the line segments into a loop

Returns

lines – PolyData with lines and cells.

Return type

pyvista.PolyData

pyvista.vtk_points(points, deep=True)¶: Convert numpy array or array-like to a vtkPoints object.

pyvista.vector_poly_data(orig, vec)¶: Create a vtkPolyData object composed of vectors.

pyvista.fit_plane_to_points(points, return_meta=False)¶

Fit a plane to a set of points.

Parameters

points (np.ndarray) – Size n by 3 array of points to fit a plane through
return_meta (bool) – If true, also returns the center and normal used to generate the plane

Array Access¶

pyvista.get_array(mesh, name, preference='cell', info=False, err=False)¶

Search point, cell and field data for an array.

Parameters

name (str) – The name of the array to get the range.
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'
info (bool) – Return info about the array rather than the array itself.
err (bool) – Boolean to control whether to throw an error if array is not present.

pyvista.convert_array(arr, name=None, deep=0, array_type=None)¶

Convert a NumPy array to a vtkDataArray or vice versa.

Parameters

arr (ndarray or vtkDataArry) – A numpy array or vtkDataArry to convert
name (str) – The name of the data array for VTK
deep (bool) – if input is numpy array then deep copy values

Returns

the converted array (if input is a NumPy ndaray then returns vtkDataArray or is input is vtkDataArray then returns NumPy ndarray). If pdf==True and the input is vtkDataArry, return a pandas DataFrame.

Return type

vtkDataArray, ndarray, or DataFrame

pyvista.point_array(mesh, name)¶: Return point array of a vtk object.

pyvista.cell_array(mesh, name)¶: Return cell array of a vtk object.

pyvista.field_array(mesh, name)¶: Return field array of a vtk object.

pyvista.get_vtk_type(typ)¶

Look up the VTK type for a give python data type.

Corrects for string type mapping issues.

Returns: int
Return type: the integer type id specified in vtkType.h

pyvista.vtk_bit_array_to_char(vtkarr_bint)¶: Cast vtk bit array to a char array.

pyvista.convert_string_array(arr, name=None)¶

Convert a numpy array of strings to a vtkStringArray or vice versa.

Note that this is terribly inefficient - inefficient support is better than no support :). If you have ideas on how to make this faster, please consider opening a pull request.

Image Comparison and Regression¶

pyvista.compare_images(im1, im2, threshold=1, use_vtk=True)¶

Compare two different images of the same size.

Parameters

im1 (filename, np.ndarray, vtkRenderWindow, or vtkImageData) – Render window, numpy array representing the output of a render window, or vtkImageData
im2 (filename, np.ndarray, vtkRenderWindow, or vtkImageData) – Render window, numpy array representing the output of a render window, or vtkImageData
threshold (int) – Threshold tolerance for pixel differences. This should be greater than 0, otherwise it will always return an error, even on identical images.
use_vtk (bool) – When disabled, computes the mean pixel error over the entire image using numpy. The difference between pixel is calculated for each RGB channel, summed, and then divided by the number of pixels. This is faster than using vtk.vtkImageDifference but potentially less accurate.

Returns

error – Total error between the images if using use_vtk=True, and the mean pixel error when use_vtk=False.

Return type

float

Examples

Compare two active plotters

>>> import pyvista
>>> pl1 = pyvista.Plotter()
>>> _ = pl1.add_mesh(pyvista.Sphere(), smooth_shading=True)
>>> pl2 = pyvista.Plotter()
>>> _ = pl2.add_mesh(pyvista.Sphere(), smooth_shading=False)
>>> pyvista.compare_images(pl1, pl2)  

Compare two active plotters

>>> import pyvista
>>> img1 = pyvista.read('img1.png')  
>>> img2 = pyvista.read('img2.png')  
>>> pyvista.compare_images(img1, img2)  