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.

pyvista.cubemap(path='', prefix='', ext='.jpg')

Construct a cubemap from 6 images.

Each of the 6 images must be in the following format:

  • <prefix>negx<ext>

  • <prefix>negy<ext>

  • <prefix>negz<ext>

  • <prefix>posx<ext>

  • <prefix>posy<ext>

  • <prefix>posz<ext>

Prefix may be empty, and extension will default to '.jpg'

For example, if you have 6 images with the skybox2 prefix:

  • 'skybox2-negx.jpg'

  • 'skybox2-negy.jpg'

  • 'skybox2-negz.jpg'

  • 'skybox2-posx.jpg'

  • 'skybox2-posy.jpg'

  • 'skybox2-posz.jpg'

Parameters

  • prefix (str, optional) – Prefix to the filename.

  • ext (str, optional) – The filename extension. For example '.jpg'.

  • path (str, optional) – Directory containing the cubemap images.

Returns

Texture with cubemap.

Return type

pyvista.Texture

Examples

>>> import pyvista
>>> skybox = pyvista.cubemap('my_directory', 'skybox', '.jpeg')

File IO

pyvista.read(filename, attrs=None, force_ext=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.

  • force_ext (str, optional) – If specified, the reader will be chosen by an extension which is different to its actual extension. For example, '.vts', '.vtu'.

  • 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)
>>> error = pyvista.compare_images(pl1, pl2)

Compare images from file.

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