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.

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)

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, optional: 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)

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.lines_from_points(points)
>>> lines.plot()

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, optional: 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, optional: 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()