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)
../../_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, 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)
../../_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.lines_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, 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()
../../_images/helpers-5_00_00.png