Point Data¶
The pyvista.PolyData
object adds additional functionality to the
vtk.vtkPolyData
object, to include direct array access through NumPy,
one line plotting, and other mesh functions.
PolyData Creation¶
See Create PolyData for an example on creating a pyvista.PolyData
object
from NumPy arrays.
Empty Object¶
A polydata object can be initialized with:
import pyvista
grid = pyvista.PolyData()
This creates an empty grid, and is not useful until points and cells are added
to it. VTK points and cells can be added with SetPoints
and SetCells
,
but the inputs to these need to be vtk.vtkCellArray
and vtk.vtkPoints
objects, which need to be populated with values.
Grid creation is simplified by initializing the grid directly from NumPy
arrays as in the following section.
Initialize from a File¶
Both binary and ASCII .ply, .stl, and .vtk files can be read using PyVista. For example, the PyVista package contains example meshes and these can be loaded with:
import pyvista
from pyvista import examples
# Load mesh
mesh = pyvista.PolyData(examples.planefile)
mesh
PolyData  Information 

N Cells  2452 
N Points  1335 
X Bounds  1.391e+02, 1.655e+03 
Y Bounds  3.209e+01, 1.320e+03 
Z Bounds  1.774e+01, 2.821e+02 
N Arrays  0 
This mesh can then be written to a vtk file using:
mesh.save('plane.vtk')
These meshes are identical.
import numpy as np
mesh_from_vtk = pyvista.PolyData('plane.vtk')
print(np.allclose(mesh_from_vtk.points, mesh.points))
Mesh Manipulation and Plotting¶
Meshes can be directly manipulated using NumPy or with the builtin translation and rotation routines. This example loads two meshes and moves, scales, copies them, and finally plots them.
To plot more than one mesh a plotting class must be created to manage the plotting. The following code creates the class and plots the meshes with various colors.
import pyvista
from pyvista import examples
# load and shrink airplane
airplane = pyvista.PolyData(examples.planefile)
airplane.points /= 10 # shrink by 10x
# rotate and translate ant so it is on the plane
ant = pyvista.PolyData(examples.antfile)
ant.rotate_x(90)
ant.translate([90, 60, 15])
# Make a copy and add another ant
ant_copy = ant.copy()
ant_copy.translate([30, 0, 10])
# Create plotting object
plotter = pyvista.Plotter()
plotter.add_mesh(ant, 'r')
plotter.add_mesh(ant_copy, 'b')
# Add airplane mesh and make the color equal to the Y position. Add a
# scalar bar associated with this mesh
plane_scalars = airplane.points[:, 1]
plotter.add_mesh(airplane, scalars=plane_scalars,
scalar_bar_args={'title': 'Airplane Y\nLocation'})
# Add annotation text
plotter.add_text('Ants and Plane Example')
plotter.show()
pyvista.PolyData Grid Class Methods¶
The following is a description of the methods available to a pyvista.PolyData
object. It inherits all methods from the original vtk object,
vtk.vtkPolyData.
Attributes
Return the mesh surface area. 

Return the cell normals. 

Return the cell normals. 

Return a pointer to the faces as a numpy object. 

Return a pointer to the lines as a numpy object. 

Return the number of cells. 

Return the number of open edges on this mesh. 

Return the number of cells. 

Return the obbTree of the polydata. 

Return the point normals. 

Get the vertex cells. 

Return the mesh volume. 
Methods
Return 


Write a surface mesh to disk. 
 class pyvista.PolyData(var_inp=None, faces=None, n_faces=None, lines=None, n_lines=None, deep=False, force_ext=None)¶
Bases:
vtkmodules.vtkCommonDataModel.vtkPolyData
,pyvista.core.pointset.PointSet
,pyvista.core.filters.PolyDataFilters
Extend the functionality of a vtk.vtkPolyData object.
Can be initialized in several ways:
Create an empty mesh
Initialize from a vtk.vtkPolyData
Using vertices
Using vertices and faces
From a file
 Parameters
var_inp (vtk.vtkPolyData, str, sequence, optional) –
Flexible input type. Can be a
vtk.vtkPolyData
, in which case this PolyData object will be copied ifdeep=True
and will be a shallow copy ifdeep=False
.Also accepts a path, which may be local path as in
'my_mesh.stl'
or global path like'/tmp/my_mesh.ply'
or'C:/Users/user/my_mesh.ply'
.Otherwise, this must be a points array or list containing one or more points. Each point must have 3 dimensions.
faces (sequence, optional) –
Face connectivity array. Faces must contain padding indicating the number of points in the face. For example, the two faces
[10, 11, 12]
and[20, 21, 22, 23]
will be represented as[3, 10, 11, 12, 4, 20, 21, 22, 23]
. This lets you have an arbitrary number of points per face.When not including the face connectivity array, each point will be assigned to a single vertex. This is used for point clouds that have no connectivity.
n_faces (int, optional) – Number of faces in the
faces
connectivity array. While optional, setting this speeds up the creation of thePolyData
.lines (sequence, optional) – The line connectivity array. Like
faces
, this array requires padding indicating the number of points in a line segment. For example, the two line segments[0, 1]
and[1, 2, 3, 4]
will be represented as[2, 0, 1, 4, 1, 2, 3, 4]
.n_lines (int, optional) – Number of lines in the
lines
connectivity array. While optional, setting this speeds up the creation of thePolyData
.deep (bool, optional) – Whether to copy the inputs, or to create a mesh from them without copying them. Setting
deep=True
ensures that the original arrays can be modified outside the mesh without affecting the mesh. Default isFalse
.
Examples
>>> import vtk >>> import numpy as np >>> from pyvista import examples >>> import pyvista
Create an empty mesh
>>> mesh = pyvista.PolyData()
Initialize from a
vtk.vtkPolyData
object>>> vtkobj = vtk.vtkPolyData() >>> mesh = pyvista.PolyData(vtkobj)
Initialize from just vertices
>>> vertices = np.array([[0, 0, 0], [1, 0, 0], [1, 0.5, 0], [0, 0.5, 0]]) >>> mesh = pyvista.PolyData(vertices)
Initialize from vertices and faces
>>> faces = np.hstack([[3, 0, 1, 2], [3, 0, 3, 2]]) >>> mesh = pyvista.PolyData(vertices, faces)
Initialize from vertices and lines
>>> lines = np.hstack([[2, 0, 1], [2, 1, 2]]) >>> mesh = pyvista.PolyData(vertices, lines=lines)
Initialize from a filename
>>> mesh = pyvista.PolyData(examples.antfile)
 property area¶
Return the mesh surface area.
 Returns
area – Total area of the mesh.
 Return type
float
 property cell_normals¶
Return the cell normals.
 property face_normals¶
Return the cell normals.
 property faces¶
Return a pointer to the faces as a numpy object.
 is_all_triangles()¶
Return
True
if all the faces of thePolyData
are triangles.
 property lines¶
Return a pointer to the lines as a numpy object.
 property n_faces¶
Return the number of cells.
Alias for
n_cells
.
 property n_open_edges¶
Return the number of open edges on this mesh.
 property number_of_faces¶
Return the number of cells.
 property obbTree¶
Return the obbTree of the polydata.
An obbTree is an object to generate oriented bounding box (OBB) trees. An oriented bounding box is a bounding box that does not necessarily line up along coordinate axes. The OBB tree is a hierarchical tree structure of such boxes, where deeper levels of OBB confine smaller regions of space.
 property point_normals¶
Return the point normals.
 save(filename, binary=True)¶
Write a surface mesh to disk.
Written file may be an ASCII or binary ply, stl, or vtk mesh file. If ply or stl format is chosen, the face normals are computed in place to ensure the mesh is properly saved.
 Parameters
filename (str) – Filename of mesh to be written. File type is inferred from the extension of the filename unless overridden with ftype. Can be one of the following types (.ply, .stl, .vtk)
binary (bool, optional) – Writes the file as binary when True and ASCII when False.
Notes
Binary files write much faster than ASCII and have a smaller file size.
 property verts¶
Get the vertex cells.
 property volume¶
Return the mesh volume.
This will throw a VTK error/warning if not a closed surface
 Returns
volume – Total volume of the mesh.
 Return type
float