Helpers#

The pyvista module contains several functions to simplify the creation and manipulation of meshes or interfacing with VTK datasets.

Wrap a VTK Dataset#

helpers.wrap() → pyvista.DataSet | pyvista.pyvista_ndarray | None[source]#

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 mesh.

Changed in version 0.38.0: If the passed object is already a wrapped PyVista object, then this is no-op and will return that object directly. In previous versions of PyVista, this would perform a shallow copy.

Parameters:

datasetnumpy.ndarray | trimesh.Trimesh | vtk.DataSet: Dataset to wrap.

Returns:

pyvista.DataSet: The PyVista wrapped dataset.

Examples

Wrap a numpy array representing a random point cloud.

>>> import numpy as np
>>> import pyvista as pv
>>> points = np.random.default_rng().random((10, 3))
>>> cloud = pv.wrap(points)
>>> cloud
PolyData (...)
  N Cells:    10
  N Points:   10
  N Strips:   0
  X Bounds:   ...
  Y Bounds:   ...
  Z Bounds:   ...
  N Arrays:   0

Wrap a VTK object.

>>> import pyvista as pv
>>> 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 = pv.wrap(point)
>>> mesh
PolyData (...)
  N Cells:    1
  N Points:   1
  N Strips:   0
  X Bounds:   1.000e+00, 1.000e+00
  Y Bounds:   2.000e+00, 2.000e+00
  Z Bounds:   3.000e+00, 3.000e+00
  N Arrays:   0

Wrap a Trimesh object.

>>> import trimesh
>>> import pyvista as pv
>>> points = [[0, 0, 0], [0, 0, 1], [0, 1, 0]]
>>> faces = [[0, 1, 2]]
>>> tmesh = trimesh.Trimesh(points, faces=faces, process=False)
>>> mesh = pv.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

Simplified Triangular Mesh Construction#

points.make_tri_mesh(faces)[source]#

Construct a pyvista.PolyData mesh using points and faces arrays.

Construct a mesh from an Nx3 array of points and an Mx3 array of triangle indices, resulting in a mesh with N vertices and M triangles. This function does not require the standard VTK “padding” column and simplifies mesh creation.

Parameters:

pointsnp.ndarray: Array of points with shape (N, 3) storing the vertices of the triangle mesh.
facesnp.ndarray: Array of indices with shape (M, 3) containing the triangle indices.

Returns:

pyvista.PolyData: PolyData instance containing the triangle mesh.

Examples

This example discretizes the unit square into a triangle mesh with nine vertices and eight faces.

>>> import numpy as np
>>> import pyvista as pv
>>> points = np.array(
...     [
...         [0, 0, 0],
...         [0.5, 0, 0],
...         [1, 0, 0],
...         [0, 0.5, 0],
...         [0.5, 0.5, 0],
...         [1, 0.5, 0],
...         [0, 1, 0],
...         [0.5, 1, 0],
...         [1, 1, 0],
...     ]
... )
>>> faces = np.array(
...     [
...         [0, 1, 4],
...         [4, 7, 6],
...         [2, 5, 4],
...         [4, 5, 8],
...         [0, 4, 3],
...         [3, 4, 6],
...         [1, 2, 4],
...         [4, 8, 7],
...     ]
... )
>>> tri_mesh = pv.make_tri_mesh(points, faces)
>>> tri_mesh.plot(show_edges=True, line_width=5)

Static Scene

Interactive Scene

Lines from Points#

points.lines_from_points(close=False)[source]#

Make a connected line set given an array of points.

Parameters:

pointsarray_like[float]: 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]]).
closebool, default: False: If True, close the line segments into a loop.

Returns:

pyvista.PolyData: PolyData with lines and cells.

Examples

>>> import numpy as np
>>> import pyvista as pv
>>> points = np.array([[0, 0, 0], [1, 0, 0], [1, 1, 0]])
>>> poly = pv.lines_from_points(points)
>>> poly.plot(line_width=5)

Static Scene

Interactive Scene

Line Segments from Points#

points.line_segments_from_points()[source]#

Generate non-connected line segments from points.

Assumes points are ordered as line segments and an even number of points.

Parameters:

pointsarray_like[float]: Points representing line segments. An even number must be given as every two vertices represent a single line segment. For example, two line segments would be represented as np.array([[0, 0, 0], [1, 0, 0], [1, 0, 0], [1, 1, 0]]).

Returns:

pyvista.PolyData: PolyData with lines and cells.

Examples

This example plots two line segments at right angles to each other.

>>> import pyvista as pv
>>> import numpy as np
>>> points = np.array([[0, 0, 0], [1, 0, 0], [1, 0, 0], [1, 1, 0]])
>>> lines = pv.line_segments_from_points(points)
>>> lines.plot()

Static Scene

Interactive Scene

Convert to and from VTK Data Types#

arrays.convert_array(name=None, deep=False, array_type=None)[source]#

Convert a NumPy array to a vtkDataArray or vice versa.

Parameters:

arrnp.ndarray | vtkDataArray: A numpy array or vtkDataArry to convert.
namestr, optional: The name of the data array for VTK.
deepbool, default: False: If input is numpy array then deep copy values.
array_typeint, optional: VTK array type ID as specified in vtkType.h.

Returns:

vtkDataArray or numpy.ndarray: The converted array. If input is a numpy.ndarray then returns vtkDataArray or is input is vtkDataArray then returns NumPy ndarray.

Fit Plane to Points#

points.fit_plane_to_points(return_meta=False)[source]#

Fit a plane to a set of points using the SVD algorithm.

The plane is automatically sized and oriented to fit the extents of the points.

Parameters:

pointsarray_like[float]: Size [N x 3] sequence of points to fit a plane through.
return_metabool, default: False: If True, also returns the center and normal of the generated plane.

Returns:

pyvista.PolyData: Plane mesh.
numpy.ndarray: Plane center if return_meta=True.
numpy.ndarray: Plane normal if return_meta=True.

Examples

Fit a plane to a random point cloud.

>>> import pyvista as pv
>>> import numpy as np
>>>
>>> # Create point cloud
>>> rng = np.random.default_rng(seed=0)
>>> cloud = rng.random((10, 3))
>>> cloud[:, 2] *= 0.1
>>>
>>> # Fit plane
>>> plane, center, normal = pv.fit_plane_to_points(
...     cloud, return_meta=True
... )
>>>
>>> # Plot the fitted plane
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(
...     plane, color='lightblue', style='wireframe', line_width=4
... )
>>> _ = pl.add_points(
...     cloud,
...     render_points_as_spheres=True,
...     color='r',
...     point_size=30,
... )
>>> pl.show()

Static Scene

Interactive Scene

Fit a plane to a mesh.

>>> import pyvista as pv
>>> from pyvista import examples
>>>
>>> # Create mesh
>>> mesh = examples.download_shark()
>>>
>>> # Fit plane
>>> plane = pv.fit_plane_to_points(mesh.points)
>>>
>>> # Plot the fitted plane
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(
...     plane, show_edges=True, color='lightblue', opacity=0.25
... )
>>> _ = pl.add_mesh(mesh, color='gray')
>>> pl.camera_position = [
...     (-117, 76, 235),
...     (1.69, -1.38, 0),
...     (0.189, 0.957, -0.22),
... ]
>>> pl.show()

Static Scene

Interactive Scene