pyvista.PolyData

class PolyData(*args, **kwargs)

Dataset consisting of surface geometry (e.g. vertices, lines, and polygons).

Can be initialized in several ways:

• Create an empty mesh

• Initialize from a vtk.vtkPolyData

• Using vertices

• Using vertices and faces

• From a file

Deprecated since version 0.44.0: The parameters n_faces, n_lines, n_strips, and n_verts are deprecated and no longer used. They were previously used to speed up the construction of the corresponding cell arrays but no longer provide any benefit.

Parameters:

var_inpvtk.vtkPolyData, str, sequence, optional

Flexible input type. Can be a vtk.vtkPolyData, in which case this PolyData object will be copied if deep=True and will be a shallow copy if deep=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. If faces, lines, strips, and verts are all None, then the PolyData object will be created with vertex cells with n_verts equal to the number of points.

facessequence[int], vtk.vtkCellArray, CellArray, optional

Polygonal faces of the mesh. Can be either a padded connectivity array or an explicit cell array object.

In the padded array format, 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_facesint, optional

Deprecated. Not used.

linessequence[int], vtk.vtkCellArray, CellArray, optional

Line connectivity. Like faces, this can be either a padded connectivity array or an explicit cell array object. The padded array format 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_linesint, optional

Deprecated. Not used.

stripssequence[int], vtk.vtkCellArray, CellArray, optional

Triangle strips connectivity. Triangle strips require an initial triangle, and the following points of the strip. Each triangle is built with the new point and the two previous points.

Just as in lines and faces, this connectivity can be specified as either a padded array or an explicit cell array object. The padded array requires a padding indicating the number of points. For example, a single triangle strip of the 10 point indices [0, 1, 2, 3, 6, 7, 4, 5, 0, 1] requires padding of 10 and should be input as [10, 0, 1, 2, 3, 6, 7, 4, 5, 0, 1].

n_stripsint, optional

Deprecated. Not used.

deepbool, 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 is False.

force_extstr, optional

If initializing from a file, force the reader to treat the file as if it had this extension as opposed to the one in the file.

force_floatbool, optional

Casts the datatype to float32 if points datatype is non-float. Default True. Set this to False to allow non-float types, though this may lead to truncation of intermediate floats when transforming datasets.

vertssequence[int], vtk.vtkCellArray, CellArray, optional

The verts connectivity. Like faces, lines, and strips this can be supplied as either a padded array or an explicit cell array object. In the padded array format, the padding indicates the number of vertices in each cell. For example, [1, 0, 1, 1, 1, 2] indicates three vertex cells each with one point, and [2, 0, 1, 2, 2, 3] indicates two polyvertex cells each with two points.

n_vertsint, optional

Deprecated. Not used.

See also

pyvista.PolyData.from_regular_faces

pyvista.PolyData.from_irregular_faces

Examples

>>> import vtk
>>> import numpy as np
>>> from pyvista import examples
>>> import pyvista as pv

Seed random number generator for reproducible plots

>>> rng = np.random.default_rng(seed=0)

Create an empty mesh.

>>> mesh = pv.PolyData()

Initialize from a vtk.vtkPolyData object.

>>> vtkobj = vtk.vtkPolyData()
>>> mesh = pv.PolyData(vtkobj)

Initialize from just points, creating vertices

>>> points = np.array([[0, 0, 0], [1, 0, 0], [1, 0.5, 0], [0, 0.5, 0]])
>>> mesh = pv.PolyData(points)

Initialize from points and faces, creating polygonal faces.

>>> faces = np.hstack([[3, 0, 1, 2], [3, 0, 3, 2]])
>>> mesh = pv.PolyData(points, faces)

Initialize from points and lines.

>>> lines = np.hstack([[2, 0, 1], [2, 1, 2]])
>>> mesh = pv.PolyData(points, lines=lines)

Initialize from points and triangle strips.

>>> strips = np.hstack([[4, 0, 1, 3, 2]])
>>> mesh = pv.PolyData(points, strips=strips)

It is also possible to create with multiple cell types.

>>> verts = [1, 0]
>>> lines = [2, 1, 2]
>>> mesh = pv.PolyData(points, verts=verts, lines=lines)

Initialize from a filename.

>>> mesh = pv.PolyData(examples.antfile)

Construct a set of random line segments using a pv.CellArray`. Because every line in this example has the same size, in this case two points, we can use ``pv.CellArray.from_regular_cells to construct the lines cell array. This is the most efficient method to construct a cell array.

>>> n_points = 20
>>> n_lines = n_points // 2
>>> points = rng.random((n_points, 3))
>>> lines = rng.integers(low=0, high=n_points, size=(n_lines, 2))
>>> mesh = pv.PolyData(points, lines=pv.CellArray.from_regular_cells(lines))
>>> mesh.cell_data['line_idx'] = np.arange(n_lines)
>>> mesh.plot(scalars='line_idx')

Static Scene

Interactive Scene

Construct a set of random triangle strips using a pv.CellArray. Because each strip in this example can have a different number of points, we use pv.CellArray.from_irregular_cells to construct the strips cell array.

>>> n_strips = 4
>>> n_verts_per_strip = rng.integers(low=3, high=7, size=n_strips)
>>> n_points = 10 * sum(n_verts_per_strip)
>>> points = rng.random((n_points, 3))
>>> strips = [
...     rng.integers(low=0, high=n_points, size=nv) for nv in n_verts_per_strip
... ]
>>> mesh = pv.PolyData(
...     points, strips=pv.CellArray.from_irregular_cells(strips)
... )
>>> mesh.cell_data['strip_idx'] = np.arange(n_strips)
>>> mesh.plot(show_edges=True, scalars='strip_idx')

Static Scene

Interactive Scene

Construct a mesh reusing the faces pv.CellArray from another mesh. The VTK methods GetPolys, GetLines, GetStrips, and GetVerts return the underlying CellArray``s for the ``faces, lines, strips, and verts properties respectively. Reusing cell arrays like this can be a performance optimization for large meshes because it avoids allocating new arrays.

>>> small_sphere = pv.Sphere().compute_normals()
>>> inflated_points = (
...     small_sphere.points + 0.1 * small_sphere.point_data['Normals']
... )
>>> larger_sphere = pv.PolyData(inflated_points, faces=small_sphere.GetPolys())
>>> plotter = pv.Plotter()
>>> _ = plotter.add_mesh(small_sphere, color='red', show_edges=True)
>>> _ = plotter.add_mesh(
...     larger_sphere, color='blue', opacity=0.3, show_edges=True
... )
>>> plotter.show()

Static Scene

Interactive Scene

See Create PolyData for more examples.

Methods

PolyData.from_irregular_faces(points, faces)	Alternate pyvista.PolyData convenience constructor from point and ragged face arrays.
PolyData.from_regular_faces(points, faces[, ...])	Alternate pyvista.PolyData convenience constructor from point and regular face arrays.
PolyData.save(filename[, binary, texture, ...])	Write a surface mesh to disk.
PolyData.use_strict_n_faces(mode)	Global opt-in to strict n_faces.

Attributes

PolyData.cell_normals	Return the cell normals.
PolyData.face_normals	Return the cell normals.
PolyData.faces	Return the connectivity array of the faces of this PolyData.
PolyData.irregular_faces	Return a tuple of face arrays.
PolyData.is_all_triangles	Return if all the faces of the pyvista.PolyData are triangles.
PolyData.is_manifold	Return if the mesh is manifold (no open edges).
PolyData.lines	Return the connectivity array of the lines of this PolyData.
PolyData.n_faces	Return the number of cells.
PolyData.n_faces_strict	Return the number of polygonal faces.
PolyData.n_lines	Return the number of lines.
PolyData.n_open_edges	Return the number of open edges on this mesh.
PolyData.n_strips	Return the number of strips.
PolyData.n_verts	Return the number of vertices.
PolyData.obbTree	Return the obbTree of the polydata.
PolyData.point_normals	Return the point normals.
PolyData.regular_faces	Return a face array of point indices when all faces have the same size.
PolyData.strips	Return a pointer to the strips as a numpy array.
PolyData.verts	Get the vertex cells.
PolyData.volume	Return the approximate volume of the dataset.