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()#

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, or VTK object

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

Simplified Triangular Mesh Construction#

helpers.make_tri_mesh(faces)#

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
>>> 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 = pyvista.make_tri_mesh(points, faces)
>>> tri_mesh.plot(show_edges=True, line_width=5)
../../_images/helpers-2_00_00.png

Lines from Points#

helpers.lines_from_points(close=False)#

Make a connected line set given an array of points.

Parameters:
pointsnp.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]]).

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
>>> points = np.array([[0, 0, 0], [1, 0, 0], [1, 1, 0]])
>>> poly = pyvista.lines_from_points(points)
>>> poly.plot(line_width=5)
../../_images/helpers-3_00_00.png

Line Segments from Points#

helpers.line_segments_from_points()#

Generate non-connected line segments from points.

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

Parameters:
pointsnumpy.ndarray

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
>>> import numpy as np
>>> points = np.array([[0, 0, 0], [1, 0, 0], [1, 0, 0], [1, 1, 0]])
>>> lines = pyvista.line_segments_from_points(points)
>>> lines.plot()
../../_images/helpers-4_00_00.png

Convert to and from VTK Datatypes#

helpers.convert_array(name=None, deep=False, array_type=None)#

Convert a NumPy array to a vtkDataArray or vice versa.

Parameters:
arrnp.ndarray or 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 specified in vtkType.h.

Returns:
vtkDataArray, numpy.ndarray, or DataFrame

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#

helpers.fit_plane_to_points(return_meta=False)#

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

Parameters:
pointssequence

Size [N x 3] sequence of points to fit a plane through.

return_metabool, default: False

If True, also returns the center and normal used to generate the 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
>>> import numpy as np
>>> cloud = np.random.random((10, 3))
>>> cloud[:, 2] *= 0.1
>>> plane, center, normal = pyvista.fit_plane_to_points(cloud, return_meta=True)

Plot the fitted plane.

>>> pl = pyvista.Plotter()
>>> _ = pl.add_mesh(plane, color='tan', style='wireframe', line_width=4)
>>> _ = pl.add_points(cloud, render_points_as_spheres=True,
...                   color='r', point_size=30)
>>> pl.show()
../../_images/helpers-5_00_00.png