General Utilities¶
Utilities routines.
-
pyvista.
set_error_output_file
(filename)¶ Set a file to write out the VTK errors.
-
pyvista.
trans_from_matrix
(matrix)¶ Convert a vtk matrix to a numpy.ndarray.
-
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 * 3Dnumpy.ndarray
representing a volume. Values will be scalars. * 3dtrimesh.Trimesh
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 avtkTexture
.
-
pyvista.
numpy_to_texture
(image)¶ Convert a NumPy image array to a vtk.vtkTexture.
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, enabled_sidesets=None)¶ Read an ExodusII file (
'.e'
or'.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.Common) – 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.
vtk_points
(points, deep=True)¶ Convert numpy points 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 isvtkDataArray
then returns NumPyndarray
). If pdf==True and the input isvtkDataArry
, 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 whenuse_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)