Filters

These classes hold methods to apply general filters to any data type. By inherritting these classes into the wrapped VTK data structures, a user can easily apply common filters in an intuitive manner.

Example

>>> import pyvista
>>> from pyvista import examples
>>> dataset = examples.load_uniform()
>>> # Threshold
>>> thresh = dataset.threshold([100, 500])
>>> # Slice
>>> slc = dataset.slice()
>>> # Clip
>>> clp = dataset.clip(invert=True)
>>> # Contour
>>> iso = dataset.contour()

Dataset Filters

The pyvista.DataSetFilters is inherited by pyvista.Common making all the the following filters available as callable methods directly from any PyVista dataset.

Methods

cell_centers([vertex])

Generate points at the center of the cells in this dataset.

cell_data_to_point_data([pass_cell_data])

Transforms cell data (i.e., data specified per cell) into point data (i.e., data specified at cell points).

clip([normal, origin, invert, value, inplace])

Clip a dataset by a plane by specifying the origin and normal.

clip_box([bounds, invert, factor])

Clips a dataset by a bounding box defined by the bounds.

clip_surface(surface[, invert, value, …])

Clip any mesh type using a pyvista.PolyData surface mesh.

compute_cell_quality([quality_measure, …])

compute a function of (geometric) quality for each cell of a mesh.

compute_cell_sizes([length, area, volume])

This filter computes sizes for 1D (length), 2D (area) and 3D (volume) cells.

compute_gradient([scalars, gradient_name, …])

Computes per cell gradient of point scalar field or per point gradient of cell scalar field.

connectivity([largest])

Find and label connected bodies/volumes.

contour([isosurfaces, scalars, …])

Contours an input dataset by an array.

ctp([pass_cell_data])

An alias/shortcut for cell_data_to_point_data

decimate_boundary([target_reduction])

Return a decimated version of a triangulation of the boundary of this mesh’s outer surface

delaunay_3d([alpha, tol, offset])

Constructs a 3D Delaunay triangulation of the mesh.

elevation([low_point, high_point, …])

Generate scalar values on a dataset.

extract_cells(ind)

Returns a subset of the grid

extract_edges([feature_angle, …])

Extracts edges from the surface of the mesh.

extract_geometry()

Extract the outer surface of a volume or structured grid dataset as PolyData.

extract_largest([inplace])

Extract largest connected set in mesh.

extract_points(ind)

Returns a subset of the grid (with cells) that contains the points that contain any of the given point indices.

extract_selection_points(ind)

extract_surface([pass_pointid, pass_cellid, …])

Extract surface mesh of the grid

glyph([orient, scale, factor, geom, …])

Copies a geometric representation (called a glyph) to every point in the input dataset.

interpolate(points[, sharpness, radius, …])

Interpolate values onto this mesh from the point data of a given pyvista.PolyData object (typically a point cloud).

merge([grid, merge_points, inplace, …])

Join one or many other grids to this grid.

outline([generate_faces])

Produces an outline of the full extent for the input dataset.

outline_corners([factor])

Produces an outline of the corners for the input dataset.

plot_over_line(pointa, pointb[, resolution, …])

Sample a dataset along a high resolution line and plot the variables of interest in 2D where the X-axis is distance from Point A and the Y-axis is the varaible of interest.

point_data_to_cell_data([pass_point_data])

Transforms point data (i.e., data specified per node) into cell data (i.e., data specified within cells).

ptc([pass_point_data])

An alias/shortcut for point_data_to_cell_data

sample(target[, tolerance, …])

Resample scalar data from a passed mesh onto this mesh using vtk.vtkResampleWithDataSet.

select_enclosed_points(surface[, tolerance, …])

Mark points as to whether they are inside a closed surface.

slice([normal, origin, generate_triangles, …])

Slice a dataset by a plane at the specified origin and normal vector orientation.

slice_along_axis([n, axis, tolerance, …])

Create many slices of the input dataset along a specified axis.

slice_along_line(line[, generate_triangles, …])

Slices a dataset using a polyline/spline as the path.

slice_orthogonal([x, y, z, …])

Creates three orthogonal slices through the dataset on the three caresian planes.

split_bodies([label])

Find, label, and split connected bodies/volumes.

streamlines([vectors, source_center, …])

Integrate a vector field to generate streamlines.

surface_indices()

The surface indices of a grid.

texture_map_to_plane([origin, point_u, …])

Texture map this dataset to a user defined plane.

threshold([value, scalars, invert, …])

This filter will apply a vtkThreshold filter to the input dataset and return the resulting object.

threshold_percent([percent, scalars, …])

Thresholds the dataset by a percentage of its range on the active scalar array or as specified

triangulate([inplace])

Returns an all triangle mesh.

warp_by_scalar([scalars, factor, normal, …])

Warp the dataset’s points by a point data scalar array’s values.

wireframe()

Extract all the internal/external edges of the dataset as PolyData.

class pyvista.DataSetFilters

A set of common filters that can be applied to any vtkDataSet

cell_centers(vertex=True)

Generate points at the center of the cells in this dataset. These points can be used for placing glyphs / vectors.

Parameters

vertex (bool) – Enable/disable the generation of vertex cells.

cell_data_to_point_data(pass_cell_data=False)

Transforms cell data (i.e., data specified per cell) into point data (i.e., data specified at cell points). The method of transformation is based on averaging the data values of all cells using a particular point. Optionally, the input cell data can be passed through to the output as well.

See aslo: pyvista.DataSetFilters.point_data_to_cell_data()

Parameters

pass_cell_data (bool) – If enabled, pass the input cell data through to the output

clip(normal='x', origin=None, invert=True, value=0.0, inplace=False)

Clip a dataset by a plane by specifying the origin and normal. If no parameters are given the clip will occur in the center of that dataset

Parameters
  • normal (tuple(float) or str) – Length 3 tuple for the normal vector direction. Can also be specified as a string conventional direction such as 'x' for (1,0,0) or '-x' for (-1,0,0), etc.

  • origin (tuple(float)) – The center (x,y,z) coordinate of the plane on which the clip occurs

  • invert (bool) – Flag on whether to flip/invert the clip

  • value (float:) – Set the clipping value of the implicit function (if clipping with implicit function) or scalar value (if clipping with scalars). The default value is 0.0.

  • inplace (bool, optional) – Updates mesh in-place while returning nothing.

clip_box(bounds=None, invert=True, factor=0.35)

Clips a dataset by a bounding box defined by the bounds. If no bounds are given, a corner of the dataset bounds will be removed.

Parameters
  • bounds (tuple(float)) – Length 6 iterable of floats: (xmin, xmax, ymin, ymax, zmin, zmax)

  • invert (bool) – Flag on whether to flip/invert the clip

  • factor (float, optional) – If bounds are not given this is the factor along each axis to extract the default box.

clip_surface(surface, invert=True, value=0.0, compute_distance=False)

Clip any mesh type using a pyvista.PolyData surface mesh. This will return a pyvista.UnstructuredGrid of the clipped mesh. Geometry of the input dataset will be preserved where possible - geometries near the clip intersection will be triangulated/tesselated.

Parameters
  • surface (pyvista.PolyData) – The PolyData surface mesh to use as a clipping function. If this mesh is not PolyData, the external surface will be extracted.

  • invert (bool) – Flag on whether to flip/invert the clip

  • value (float:) – Set the clipping value of the implicit function (if clipping with implicit function) or scalar value (if clipping with scalars). The default value is 0.0.

  • compute_distance (bool, optional) – Compute the implicit distance from the mesh onto the input dataset. A new array called 'implicit_distance' will be added to the output clipped mesh.

compute_cell_quality(quality_measure='scaled_jacobian', null_value=-1.0)

compute a function of (geometric) quality for each cell of a mesh. The per-cell quality is added to the mesh’s cell data, in an array named “CellQuality”. Cell types not supported by this filter or undefined quality of supported cell types will have an entry of -1.

Defaults to computing the scaled jacobian.

Options for cell quality measure:

  • 'area'

  • 'aspect_beta'

  • 'aspect_frobenius'

  • 'aspect_gamma'

  • 'aspect_ratio'

  • 'collapse_ratio'

  • 'condition'

  • 'diagonal'

  • 'dimension'

  • 'distortion'

  • 'jacobian'

  • 'max_angle'

  • 'max_aspect_frobenius'

  • 'max_edge_ratio'

  • 'med_aspect_frobenius'

  • 'min_angle'

  • 'oddy'

  • 'radius_ratio'

  • 'relative_size_squared'

  • 'scaled_jacobian'

  • 'shape'

  • 'shape_and_size'

  • 'shear'

  • 'shear_and_size'

  • 'skew'

  • 'stretch'

  • 'taper'

  • 'volume'

  • 'warpage'

Parameters
  • quality_measure (str) – The cell quality measure to use

  • null_value (float) – Float value for undefined quality. Undefined quality are qualities that could be addressed by this filter but is not well defined for the particular geometry of cell in question, e.g. a volume query for a triangle. Undefined quality will always be undefined. The default value is -1.

compute_cell_sizes(length=True, area=True, volume=True)

This filter computes sizes for 1D (length), 2D (area) and 3D (volume) cells.

Parameters
  • length (bool) – Specify whether or not to compute the length of 1D cells.

  • area (bool) – Specify whether or not to compute the area of 2D cells.

  • volume (bool) – Specify whether or not to compute the volume of 3D cells.

compute_gradient(scalars=None, gradient_name='gradient', preference='point')

Computes per cell gradient of point scalar field or per point gradient of cell scalar field.

Parameters
  • scalars (str) – String name of the scalars array to use when computing gradient.

  • gradient_name (str, optional) – The name of the output array of the computed gradient.

connectivity(largest=False)

Find and label connected bodies/volumes. This adds an ID array to the point and cell data to distinguish seperate connected bodies. This applies a vtkConnectivityFilter filter which extracts cells that share common points and/or meet other connectivity criterion. (Cells that share vertices and meet other connectivity criterion such as scalar range are known as a region.)

Parameters

largest (bool) – Extract the largest connected part of the mesh.

contour(isosurfaces=10, scalars=None, compute_normals=False, compute_gradients=False, compute_scalars=True, rng=None, preference='point')

Contours an input dataset by an array. isosurfaces can be an integer specifying the number of isosurfaces in the data range or an iterable set of values for explicitly setting the isosurfaces.

Parameters
  • isosurfaces (int or iterable) – Number of isosurfaces to compute across valid data range or an iterable of float values to explicitly use as the isosurfaces.

  • scalars (str, optional) – Name of scalars to threshold on. Defaults to currently active scalars.

  • compute_normals (bool, optional) –

  • compute_gradients (bool, optional) – Desc

  • compute_scalars (bool, optional) – Preserves the scalar values that are being contoured

  • rng (tuple(float), optional) – If an integer number of isosurfaces is specified, this is the range over which to generate contours. Default is the scalar arrays’s full data range.

  • preference (str, optional) – When scalars is specified, this is the perfered scalar type to search for in the dataset. Must be either 'point' or 'cell'

ctp(pass_cell_data=False)

An alias/shortcut for cell_data_to_point_data

decimate_boundary(target_reduction=0.5)

Return a decimated version of a triangulation of the boundary of this mesh’s outer surface

Parameters

target_reduction (float) – Fraction of the original mesh to remove. Default is 0.5 TargetReduction is set to 0.9, this filter will try to reduce the data set to 10% of its original size and will remove 90% of the input triangles.

delaunay_3d(alpha=0, tol=0.001, offset=2.5)

Constructs a 3D Delaunay triangulation of the mesh. This helps smooth out a rugged mesh.

Parameters
  • alpha (float, optional) – Distance value to control output of this filter. For a non-zero alpha value, only verts, edges, faces, or tetra contained within the circumsphere (of radius alpha) will be output. Otherwise, only tetrahedra will be output.

  • tol (float, optional) – tolerance to control discarding of closely spaced points. This tolerance is specified as a fraction of the diagonal length of the bounding box of the points.

  • offset (float, optional) – multiplier to control the size of the initial, bounding Delaunay triangulation.

elevation(low_point=None, high_point=None, scalar_range=None, preference='point', set_active=True)

Generate scalar values on a dataset. The scalar values lie within a user specified range, and are generated by computing a projection of each dataset point onto a line. The line can be oriented arbitrarily. A typical example is to generate scalars based on elevation or height above a plane.

Parameters
  • low_point (tuple(float), optional) – The low point of the projection line in 3D space. Default is bottom center of the dataset. Otherwise pass a length 3 tuple(float).

  • high_point (tuple(float), optional) – The high point of the projection line in 3D space. Default is top center of the dataset. Otherwise pass a length 3 tuple(float).

  • scalar_range (str or tuple(float), optional) – The scalar range to project to the low and high points on the line that will be mapped to the dataset. If None given, the values will be computed from the elevation (Z component) range between the high and low points. Min and max of a range can be given as a length 2 tuple(float). If str name of scalara array present in the dataset given, the valid range of that array will be used.

  • preference (str, optional) – When a scalar name is specified for scalar_range, this is the perfered scalar type to search for in the dataset. Must be either ‘point’ or ‘cell’.

  • set_active (bool, optional) – A boolean flag on whethter or not to set the new Elevation scalar as the active scalar array on the output dataset.

Warning

This will create a scalar array named Elevation on the point data of the input dataset and overasdf write an array named Elevation if present.

extract_cells(ind)

Returns a subset of the grid

Parameters

ind (np.ndarray) – Numpy array of cell indices to be extracted.

Returns

subgrid – Subselected grid

Return type

pyvista.UnstructuredGrid

extract_edges(feature_angle=30, boundary_edges=True, non_manifold_edges=True, feature_edges=True, manifold_edges=True, inplace=False)

Extracts edges from the surface of the mesh. If the given mesh is not PolyData, the external surface of the given mesh is extracted and used. From vtk documentation, the edges are one of the following

  1. boundary (used by one polygon) or a line cell

  2. non-manifold (used by three or more polygons)

  3. feature edges (edges used by two triangles and whose dihedral angle > feature_angle)

  4. manifold edges (edges used by exactly two polygons).

Parameters
  • feature_angle (float, optional) – Defaults to 30 degrees.

  • boundary_edges (bool, optional) – Defaults to True

  • non_manifold_edges (bool, optional) – Defaults to True

  • feature_edges (bool, optional) – Defaults to True

  • manifold_edges (bool, optional) – Defaults to True

  • inplace (bool, optional) – Return new mesh or overwrite input.

Returns

edges – Extracted edges. None if inplace=True.

Return type

pyvista.vtkPolyData

extract_geometry()

Extract the outer surface of a volume or structured grid dataset as PolyData. This will extract all 0D, 1D, and 2D cells producing the boundary faces of the dataset.

extract_largest(inplace=False)

Extract largest connected set in mesh.

Can be used to reduce residues obtained when generating an isosurface. Works only if residues are not connected (share at least one point with) the main component of the image.

Parameters

inplace (bool, optional) – Updates mesh in-place while returning nothing.

Returns

mesh – Largest connected set in mesh

Return type

pyvista.PolyData

extract_points(ind)

Returns a subset of the grid (with cells) that contains the points that contain any of the given point indices.

Parameters

ind (np.ndarray, list, or iterable) – Numpy array of point indices to be extracted.

Returns

subgrid – Subselected grid.

Return type

pyvista.UnstructuredGrid

extract_selection_points(ind)
extract_surface(pass_pointid=True, pass_cellid=True, inplace=False)

Extract surface mesh of the grid

Parameters
  • pass_pointid (bool, optional) – Adds a point scalar “vtkOriginalPointIds” that idenfities which original points these surface points correspond to

  • pass_cellid (bool, optional) – Adds a cell scalar “vtkOriginalPointIds” that idenfities which original cells these surface cells correspond to

  • inplace (bool, optional) – Return new mesh or overwrite input.

Returns

extsurf – Surface mesh of the grid

Return type

pyvista.PolyData

glyph(orient=True, scale=True, factor=1.0, geom=None, tolerance=0.0, absolute=False)

Copies a geometric representation (called a glyph) to every point in the input dataset. The glyph may be oriented along the input vectors, and it may be scaled according to scalar data or vector magnitude.

Parameters
  • orient (bool) – Use the active vectors array to orient the the glyphs

  • scale (bool) – Use the active scalars to scale the glyphs

  • factor (float) – Scale factor applied to sclaing array

  • geom (vtk.vtkDataSet) – The geometry to use for the glyph

  • tolerance (float, optional) – Specify tolerance in terms of fraction of bounding box length. Float value is between 0 and 1. Default is 0.0. If absolute is True then the tolerance can be an absolute distance.

  • absolute (bool, optional) – Control if tolerance is an absolute distance or a fraction.

interpolate(points, sharpness=2, radius=1.0, dimensions=(101, 101, 101), pass_cell_arrays=True, pass_point_arrays=True, null_value=0.0)

Interpolate values onto this mesh from the point data of a given pyvista.PolyData object (typically a point cloud).

This uses a guassian interpolation kernel. Use the sharpness and radius parameters to adjust this kernel.

Please note that the source dataset is first interpolated onto a fine UniformGrid which is then sampled to this mesh. The interpolation grid’s dimensions will likely need to be tweaked for each individual use case.

Parameters
  • points (pyvista.PolyData) – The points whose values will be interpolated onto this mesh.

  • sharpness (float) – Set / Get the sharpness (i.e., falloff) of the Gaussian. By default Sharpness=2. As the sharpness increases the effects of distant points are reduced.

  • radius (float) – Specify the radius within which the basis points must lie.

  • dimensions (tuple(int)) – When interpolating the points, they are first interpolating on to a pyvista.UniformGrid with the same spatial extent - dimensions is number of points along each axis for that grid.

  • pass_cell_arrays (bool, optional) – Preserve source mesh’s original cell data arrays

  • pass_point_arrays (bool, optional) – Preserve source mesh’s original point data arrays

  • null_value (float, optional) – Specify the null point value. When a null point is encountered then all components of each null tuple are set to this value. By default the null value is set to zero.

merge(grid=None, merge_points=True, inplace=False, main_has_priority=True)

Join one or many other grids to this grid. Grid is updated in-place by default.

Can be used to merge points of adjcent cells when no grids are input.

Parameters
  • grid (vtk.UnstructuredGrid or list of vtk.UnstructuredGrids) – Grids to merge to this grid.

  • merge_points (bool, optional) – Points in exactly the same location will be merged between the two meshes. Warning: this can leave degenerate point data.

  • inplace (bool, optional) – Updates grid inplace when True if the input type is an pyvista.UnstructuredGrid.

  • main_has_priority (bool, optional) – When this parameter is true and merge_points is true, the scalar arrays of the merging grids will be overwritten by the original main mesh.

Returns

merged_grid – Merged grid. Returned when inplace is False.

Return type

vtk.UnstructuredGrid

Notes

When two or more grids are joined, the type and name of each scalar array must match or the arrays will be ignored and not included in the final merged mesh.

outline(generate_faces=False)

Produces an outline of the full extent for the input dataset.

Parameters

generate_faces (bool, optional) – Generate solid faces for the box. This is off by default

outline_corners(factor=0.2)

Produces an outline of the corners for the input dataset.

Parameters

factor (float, optional) – controls the relative size of the corners to the length of the corresponding bounds

plot_over_line(pointa, pointb, resolution=None, scalars=None, title=None, ylabel=None, figsize=None, figure=True, show=True)

Sample a dataset along a high resolution line and plot the variables of interest in 2D where the X-axis is distance from Point A and the Y-axis is the varaible of interest. Note that this filter returns None.

Parameters
  • pointa (np.ndarray or list) – Location in [x, y, z].

  • pointb (np.ndarray or list) – Location in [x, y, z].

  • resolution (int) – number of pieces to divide line into. Defaults to number of cells in the input mesh. Must be a positive integer.

  • scalars (str) – The string name of the variable in the input dataset to probe. The active scalar is used by default.

  • title (str) – The string title of the matplotlib figure

  • ylabel (str) – The string label of the Y-axis. Defaults to variable name

  • figsize (tuple(int)) – the size of the new figure

  • figure (bool) – flag on whether or not to create a new figure

  • show (bool) – Shows the matplotlib figure

point_data_to_cell_data(pass_point_data=False)

Transforms point data (i.e., data specified per node) into cell data (i.e., data specified within cells). Optionally, the input point data can be passed through to the output.

See aslo: pyvista.DataSetFilters.cell_data_to_point_data()

Parameters

pass_point_data (bool) – If enabled, pass the input point data through to the output

ptc(pass_point_data=False)

An alias/shortcut for point_data_to_cell_data

sample(target, tolerance=None, pass_cell_arrays=True, pass_point_arrays=True)

Resample scalar data from a passed mesh onto this mesh using vtk.vtkResampleWithDataSet.

Parameters
  • dataset (pyvista.Common) – The source vtk data object as the mesh to sample values on to

  • target (pyvista.Common) – The vtk data object to sample from - point and cell arrays from this object are sampled onto the nodes of the dataset mesh

  • tolerance (flaot, optional) – tolerance used to compute whether a point in the source is in a cell of the input. If not given, tolerance automatically generated.

  • pass_cell_arrays (bool, optional) – Preserve source mesh’s original cell data arrays

  • pass_point_arrays (bool, optional) – Preserve source mesh’s original point data arrays

select_enclosed_points(surface, tolerance=0.001, inside_out=False, check_surface=True)

Mark points as to whether they are inside a closed surface. This evaluates all the input points to determine whether they are in an enclosed surface. The filter produces a (0,1) mask (in the form of a vtkDataArray) that indicates whether points are outside (mask value=0) or inside (mask value=1) a provided surface. (The name of the output vtkDataArray is “SelectedPoints”.)

This filter produces and output data array, but does not modify the input dataset. If you wish to extract cells or poinrs, various threshold filters are available (i.e., threshold the output array).

Warning

The filter assumes that the surface is closed and manifold. A boolean flag can be set to force the filter to first check whether this is true. If false, all points will be marked outside. Note that if this check is not performed and the surface is not closed, the results are undefined.

Parameters
  • surface (pyvista.PolyData) – Set the surface to be used to test for containment. This must be a pyvista.PolyData object.

  • tolerance (float) – The tolerance on the intersection. The tolerance is expressed as a fraction of the bounding box of the enclosing surface.

  • inside_out (bool) – By default, points inside the surface are marked inside or sent to the output. If inside_out is True, then the points outside the surface are marked inside.

  • check_surface (bool) – Specify whether to check the surface for closure. If on, then the algorithm first checks to see if the surface is closed and manifold. If the surface is not closed and manifold, a runtime error is raised.

slice(normal='x', origin=None, generate_triangles=False, contour=False)

Slice a dataset by a plane at the specified origin and normal vector orientation. If no origin is specified, the center of the input dataset will be used.

Parameters
  • normal (tuple(float) or str) – Length 3 tuple for the normal vector direction. Can also be specified as a string conventional direction such as 'x' for (1,0,0) or '-x' for (-1,0,0)`, etc.

  • origin (tuple(float)) – The center (x,y,z) coordinate of the plane on which the slice occurs

  • generate_triangles (bool, optional) – If this is enabled (False by default), the output will be triangles otherwise, the output will be the intersection polygons.

  • contour (bool, optional) – If True, apply a contour filter after slicing

slice_along_axis(n=5, axis='x', tolerance=None, generate_triangles=False, contour=False, bounds=None, center=None)

Create many slices of the input dataset along a specified axis.

Parameters
  • n (int) – The number of slices to create

  • axis (str or int) – The axis to generate the slices along. Perpendicular to the slices. Can be string name ('x', 'y', or 'z') or axis index (0, 1, or 2).

  • tolerance (float, optional) – The toleranceerance to the edge of the dataset bounds to create the slices

  • generate_triangles (bool, optional) – If this is enabled (False by default), the output will be triangles otherwise, the output will be the intersection polygons.

  • contour (bool, optional) – If True, apply a contour filter after slicing

slice_along_line(line, generate_triangles=False, contour=False)

Slices a dataset using a polyline/spline as the path. This also works for lines generated with pyvista.Line()

Parameters
  • line (pyvista.PolyData) – A PolyData object containing one single PolyLine cell.

  • generate_triangles (bool, optional) – If this is enabled (False by default), the output will be triangles otherwise, the output will be the intersection polygons.

  • contour (bool, optional) – If True, apply a contour filter after slicing

slice_orthogonal(x=None, y=None, z=None, generate_triangles=False, contour=False)

Creates three orthogonal slices through the dataset on the three caresian planes. Yields a MutliBlock dataset of the three slices.

Parameters
  • x (float) – The X location of the YZ slice

  • y (float) – The Y location of the XZ slice

  • z (float) – The Z location of the XY slice

  • generate_triangles (bool, optional) – If this is enabled (False by default), the output will be triangles otherwise, the output will be the intersection polygons.

  • contour (bool, optional) – If True, apply a contour filter after slicing

split_bodies(label=False)

Find, label, and split connected bodies/volumes. This splits different connected bodies into blocks in a MultiBlock dataset.

Parameters

label (bool) – A flag on whether to keep the ID arrays given by the connectivity filter.

streamlines(vectors=None, source_center=None, source_radius=None, n_points=100, integrator_type=45, integration_direction='both', surface_streamlines=False, initial_step_length=0.5, step_unit='cl', min_step_length=0.01, max_step_length=1.0, max_steps=2000, terminal_speed=1e-12, max_error=1e-06, max_time=None, compute_vorticity=True, rotation_scale=1.0, interpolator_type='point', start_position=(0.0, 0.0, 0.0), return_source=False, pointa=None, pointb=None)

Integrate a vector field to generate streamlines. The integration is performed using a specified integrator, by default Runge-Kutta2. This supports integration through any type of dataset. Thus if the dataset contains 2D cells like polygons or triangles, the integration is constrained to lie on the surface defined by 2D cells.

This produces polylines as the output, with each cell (i.e., polyline) representing a streamline. The attribute values associated with each streamline are stored in the cell data, whereas those associated with streamline-points are stored in the point data.

This uses a Sphere as the source - set it’s location and radius via the source_center and source_radius keyword arguments. You can retrieve the source as pyvista.PolyData by specifying return_source=True.

Parameters
  • vectors (str) – The string name of the active vector field to integrate across

  • source_center (tuple(float)) – Length 3 tuple of floats defining the center of the source particles. Defaults to the center of the dataset

  • source_radius (float) – Float radius of the source particle cloud. Defaults to one-tenth of the diagonal of the dataset’s spatial extent

  • n_points (int) – Number of particles present in source sphere

  • integrator_type (int) – The integrator type to be used for streamline generation. The default is Runge-Kutta45. The recognized solvers are: RUNGE_KUTTA2 (2), RUNGE_KUTTA4 (4), and RUNGE_KUTTA45 (45). Options are 2, 4, or 45. Default is 45.

  • integration_direction (str) – Specify whether the streamline is integrated in the upstream or downstream directions (or both). Options are 'both', 'backward', or 'forward'.

  • surface_streamlines (bool) – Compute streamlines on a surface. Default False

  • initial_step_length (float) – Initial step size used for line integration, expressed ib length unitsL or cell length units (see step_unit parameter). either the starting size for an adaptive integrator, e.g., RK45, or the constant / fixed size for non-adaptive ones, i.e., RK2 and RK4)

  • step_unit (str) – Uniform integration step unit. The valid unit is now limited to only LENGTH_UNIT ('l') and CELL_LENGTH_UNIT ('cl'). Default is CELL_LENGTH_UNIT: 'cl'.

  • min_step_length (float) – Minimum step size used for line integration, expressed in length or cell length units. Only valid for an adaptive integrator, e.g., RK45

  • max_step_length (float) – Maxmimum step size used for line integration, expressed in length or cell length units. Only valid for an adaptive integrator, e.g., RK45

  • max_steps (int) – Maximum number of steps for integrating a streamline. Defaults to 2000

  • terminal_speed (float) – Terminal speed value, below which integration is terminated.

  • max_error (float) – Maximum error tolerated throughout streamline integration.

  • max_time (float) – Specify the maximum length of a streamline expressed in LENGTH_UNIT.

  • compute_vorticity (bool) – Vorticity computation at streamline points (necessary for generating proper stream-ribbons using the vtkRibbonFilter.

  • interpolator_type (str) – Set the type of the velocity field interpolator to locate cells during streamline integration either by points or cells. The cell locator is more robust then the point locator. Options are 'point' or 'cell' (abreviations of 'p' and 'c' are also supported).

  • rotation_scale (float) – This can be used to scale the rate with which the streamribbons twist. The default is 1.

  • start_position (tuple(float)) – Set the start position. Default is (0.0, 0.0, 0.0)

  • return_source (bool) – Return the source particles as pyvista.PolyData as well as the streamlines. This will be the second value returned if True.

  • pointb (pointa,) – The coordinates of a start and end point for a line source. This will override the sphere point source.

surface_indices()

The surface indices of a grid.

Returns

surf_ind – Indices of the surface points.

Return type

np.ndarray

texture_map_to_plane(origin=None, point_u=None, point_v=None, inplace=False, name='Texture Coordinates', use_bounds=False)

Texture map this dataset to a user defined plane. This is often used to define a plane to texture map an image to this dataset. The plane defines the spatial reference and extent of that image.

Parameters
  • origin (tuple(float)) – Length 3 iterable of floats defining the XYZ coordinates of the BOTTOM LEFT CORNER of the plane

  • point_u (tuple(float)) – Length 3 iterable of floats defining the XYZ coordinates of the BOTTOM RIGHT CORNER of the plane

  • point_v (tuple(float)) – Length 3 iterable of floats defining the XYZ coordinates of the TOP LEFT CORNER of the plane

  • inplace (bool, optional) – If True, the new texture coordinates will be added to the dataset inplace. If False (default), a new dataset is returned with the textures coordinates

  • name (str, optional) – The string name to give the new texture coordinates if applying the filter inplace.

  • use_bounds (bool) – Use the bounds to set the mapping plane by default (bottom plane of the bounding box).

threshold(value=None, scalars=None, invert=False, continuous=False, preference='cell')

This filter will apply a vtkThreshold filter to the input dataset and return the resulting object. This extracts cells where scalar value in each cell satisfies threshold criterion. If scalars is None, the inputs active_scalar is used.

Parameters
  • value (float or iterable, optional) – Single value or (min, max) to be used for the data threshold. If iterable, then length must be 2. If no value is specified, the non-NaN data range will be used to remove any NaN values.

  • scalars (str, optional) – Name of scalars to threshold on. Defaults to currently active scalars.

  • invert (bool, optional) – If value is a single value, when invert is True cells are kept when their values are below parameter “value”. When invert is False cells are kept when their value is above the threshold “value”. Default is False: yielding above the threshold “value”.

  • continuous (bool, optional) – When True, the continuous interval [minimum cell scalar, maxmimum cell scalar] will be used to intersect the threshold bound, rather than the set of discrete scalar values from the vertices.

  • preference (str, optional) – When scalars is specified, this is the perfered scalar type to search for in the dataset. Must be either 'point' or 'cell'

threshold_percent(percent=0.5, scalars=None, invert=False, continuous=False, preference='cell')

Thresholds the dataset by a percentage of its range on the active scalar array or as specified

Parameters
  • percent (float or tuple(float), optional) – The percentage (0,1) to threshold. If value is out of 0 to 1 range, then it will be divided by 100 and checked to be in that range.

  • scalars (str, optional) – Name of scalars to threshold on. Defaults to currently active scalars.

  • invert (bool, optional) – When invert is True cells are kept when their values are below the percentage of the range. When invert is False, cells are kept when their value is above the percentage of the range. Default is False: yielding above the threshold “value”.

  • continuous (bool, optional) – When True, the continuous interval [minimum cell scalar, maxmimum cell scalar] will be used to intersect the threshold bound, rather than the set of discrete scalar values from the vertices.

  • preference (str, optional) – When scalars is specified, this is the perfered scalar type to search for in the dataset. Must be either 'point' or 'cell'

triangulate(inplace=False)

Returns an all triangle mesh. More complex polygons will be broken down into triangles.

Parameters

inplace (bool, optional) – Updates mesh in-place while returning None.

Returns

mesh – Mesh containing only triangles. None when inplace=True

Return type

pyvista.UnstructuredGrid

warp_by_scalar(scalars=None, factor=1.0, normal=None, inplace=False, **kwargs)

Warp the dataset’s points by a point data scalar array’s values. This modifies point coordinates by moving points along point normals by the scalar amount times the scale factor.

Parameters
  • scalars (str, optional) – Name of scalars to warb by. Defaults to currently active scalars.

  • factor (float, optional) – A scalaing factor to increase the scaling effect. Alias scale_factor also accepted - if present, overrides factor.

  • normal (np.array, list, tuple of length 3) – User specified normal. If given, data normals will be ignored and the given normal will be used to project the warp.

  • inplace (bool) – If True, the points of the give dataset will be updated.

wireframe()

Extract all the internal/external edges of the dataset as PolyData. This produces a full wireframe representation of the input dataset.

PolyData Filters

The pyvista.PolyDataFilters is inherited by pyvista.PolyData making all the the following filters available as callable methods directly from any PolyData mesh.

Methods

boolean_add(mesh[, inplace])

Add a mesh to the current mesh.

boolean_cut(cut[, tolerance, inplace])

Performs a Boolean cut using another mesh.

boolean_difference(mesh[, inplace])

Combines two meshes and retains only the volume in common between the meshes.

boolean_union(mesh[, inplace])

Combines two meshes and attempts to create a manifold mesh.

clean([point_merging, tolerance, …])

Cleans mesh by merging duplicate points, remove unused points, and/or remove degenerate cells.

clip_with_plane(origin, normal[, value, …])

DEPRECATED: Use .clip instead.

compute_arc_length()

Computes the arc length over the length of the probed line.

compute_normals([cell_normals, …])

Compute point and/or cell normals for a mesh.

curvature([curv_type])

Returns the pointwise curvature of a mesh

decimate(target_reduction[, …])

Reduces the number of triangles in a triangular mesh using vtkQuadricDecimation.

decimate_pro(reduction[, feature_angle, …])

Reduce the number of triangles in a triangular mesh, forming a good approximation to the original geometry.

delaunay_2d([tol, alpha, offset, bound, inplace])

Apply a delaunay 2D filter along the best fitting plane

delauney_2d()

DEPRECATED.

edge_mask(angle)

Returns a mask of the points of a surface mesh that have a surface angle greater than angle

fill_holes(hole_size[, inplace])

Fill holes in a pyvista.PolyData or vtk.vtkPolyData object.

flip_normals()

Flip normals of a triangular mesh by reversing the point ordering.

geodesic(start_vertex, end_vertex[, inplace])

Calculates the geodesic path betweeen two vertices using Dijkstra’s algorithm.

geodesic_distance(start_vertex, end_vertex)

Calculates the geodesic distance betweeen two vertices using Dijkstra’s algorithm.

plot_boundaries(**kwargs)

Plots boundaries of a mesh

plot_curvature([curv_type])

Plots curvature

plot_normals([show_mesh, mag, flip, use_every])

Plot the point normals of a mesh.

project_points_to_plane([origin, normal, …])

Project points of this mesh to a plane

ray_trace(origin, end_point[, first_point, …])

Performs a single ray trace calculation given a mesh and a line segment defined by an origin and end_point.

remove_points(remove[, mode, keep_scalars, …])

Rebuild a mesh by removing points.

ribbon([width, scalars, angle, factor, …])

Create a ribbon of the lines in this dataset.

smooth([n_iter, relaxation_factor, …])

Adjust point coordinates using Laplacian smoothing.

subdivide(nsub[, subfilter, inplace])

Increase the number of triangles in a single, connected triangular mesh.

tri_filter([inplace])

DEPRECATED: use .triangulate instead

triangulate([inplace])

Returns an all triangle mesh.

tube([radius, scalars, capping, n_sides, …])

Generate a tube around each input line.

class pyvista.PolyDataFilters

Bases: pyvista.core.filters.DataSetFilters

boolean_add(mesh, inplace=False)

Add a mesh to the current mesh. Does not attempt to “join” the meshes.

Parameters
  • mesh (pyvista.PolyData) – The mesh to add.

  • inplace (bool, optional) – Updates mesh in-place while returning nothing.

Returns

joinedmesh – Initial mesh and the new mesh when inplace=False.

Return type

pyvista.PolyData

boolean_cut(cut, tolerance=1e-05, inplace=False)

Performs a Boolean cut using another mesh.

Parameters
  • cut (pyvista.PolyData) – Mesh making the cut

  • inplace (bool, optional) – Updates mesh in-place while returning nothing.

Returns

mesh – The cut mesh when inplace=False

Return type

pyvista.PolyData

boolean_difference(mesh, inplace=False)

Combines two meshes and retains only the volume in common between the meshes.

Parameters
  • mesh (pyvista.PolyData) – The mesh to perform a union against.

  • inplace (bool, optional) – Updates mesh in-place while returning nothing.

Returns

union – The union mesh when inplace=False.

Return type

pyvista.PolyData

boolean_union(mesh, inplace=False)

Combines two meshes and attempts to create a manifold mesh.

Parameters
  • mesh (pyvista.PolyData) – The mesh to perform a union against.

  • inplace (bool, optional) – Updates mesh in-place while returning nothing.

Returns

union – The union mesh when inplace=False.

Return type

pyvista.PolyData

clean(point_merging=True, tolerance=None, lines_to_points=True, polys_to_lines=True, strips_to_polys=True, inplace=False, absolute=True, **kwargs)

Cleans mesh by merging duplicate points, remove unused points, and/or remove degenerate cells.

Parameters
  • point_merging (bool, optional) – Enables point merging. On by default.

  • tolerance (float, optional) – Set merging tolerance. When enabled merging is set to absolute distance. If absolute is False, then the merging tolerance is a fraction of the bounding box legnth. The alias merge_tol is also excepted.

  • lines_to_points (bool, optional) – Turn on/off conversion of degenerate lines to points. Enabled by default.

  • polys_to_lines (bool, optional) – Turn on/off conversion of degenerate polys to lines. Enabled by default.

  • strips_to_polys (bool, optional) – Turn on/off conversion of degenerate strips to polys.

  • inplace (bool, optional) – Updates mesh in-place while returning nothing. Default True.

  • absolute (bool, optional) – Control if tolerance is an absolute distance or a fraction.

Returns

mesh – Cleaned mesh. None when inplace=True

Return type

pyvista.PolyData

clip_with_plane(origin, normal, value=0, invert=False, inplace=False)

DEPRECATED: Use .clip instead.

compute_arc_length()

Computes the arc length over the length of the probed line. It adds a new point-data array named “arc_length” with the computed arc length for each of the polylines in the input. For all other cell types, the arc length is set to 0.

compute_normals(cell_normals=True, point_normals=True, split_vertices=False, flip_normals=False, consistent_normals=True, auto_orient_normals=False, non_manifold_traversal=True, feature_angle=30.0, inplace=False)

Compute point and/or cell normals for a mesh.

The filter can reorder polygons to insure consistent orientation across polygon neighbors. Sharp edges can be split and points duplicated with separate normals to give crisp (rendered) surface definition. It is also possible to globally flip the normal orientation.

The algorithm works by determining normals for each polygon and then averaging them at shared points. When sharp edges are present, the edges are split and new points generated to prevent blurry edges (due to Gouraud shading).

Parameters
  • cell_normals (bool, optional) – Calculation of cell normals. Defaults to True.

  • point_normals (bool, optional) – Calculation of point normals. Defaults to True.

  • split_vertices (bool, optional) – Splitting of sharp edges. Defaults to False.

  • flip_normals (bool, optional) – Set global flipping of normal orientation. Flipping modifies both the normal direction and the order of a cell’s points. Defaults to False.

  • consistent_normals (bool, optional) – Enforcement of consistent polygon ordering. Defaults to True.

  • auto_orient_normals (bool, optional) – Turn on/off the automatic determination of correct normal orientation. NOTE: This assumes a completely closed surface (i.e. no boundary edges) and no non-manifold edges. If these constraints do not hold, all bets are off. This option adds some computational complexity, and is useful if you don’t want to have to inspect the rendered image to determine whether to turn on the FlipNormals flag. However, this flag can work with the FlipNormals flag, and if both are set, all the normals in the output will point “inward”. Defaults to False.

  • non_manifold_traversal (bool, optional) – Turn on/off traversal across non-manifold edges. Changing this may prevent problems where the consistency of polygonal ordering is corrupted due to topological loops. Defaults to True.

  • feature_angle (float, optional) – The angle that defines a sharp edge. If the difference in angle across neighboring polygons is greater than this value, the shared edge is considered “sharp”. Defaults to 30.0.

  • inplace (bool, optional) – Updates mesh in-place while returning nothing. Defaults to False.

Returns

mesh – Updated mesh with cell and point normals if inplace=False

Return type

pyvista.PolyData

Notes

Previous arrays named “Normals” will be overwritten.

Normals are computed only for polygons and triangle strips. Normals are not computed for lines or vertices.

Triangle strips are broken up into triangle polygons. You may want to restrip the triangles.

May be easier to run mesh.point_normals or mesh.cell_normals

curvature(curv_type='mean')

Returns the pointwise curvature of a mesh

Parameters
  • mesh (vtk.polydata) – vtk polydata mesh

  • string, optional (curvature) – One of the following strings Mean Gaussian Maximum Minimum

Returns

curvature – Curvature values

Return type

np.ndarray

decimate(target_reduction, volume_preservation=False, attribute_error=False, scalars=True, vectors=True, normals=False, tcoords=True, tensors=True, scalars_weight=0.1, vectors_weight=0.1, normals_weight=0.1, tcoords_weight=0.1, tensors_weight=0.1, inplace=False)

Reduces the number of triangles in a triangular mesh using vtkQuadricDecimation.

Parameters
  • mesh (vtk.PolyData) – Mesh to decimate

  • target_reduction (float) – Fraction of the original mesh to remove. TargetReduction is set to 0.9, this filter will try to reduce the data set to 10% of its original size and will remove 90% of the input triangles.

  • volume_preservation (bool, optional) – Decide whether to activate volume preservation which greatly reduces errors in triangle normal direction. If off, volume preservation is disabled and if AttributeErrorMetric is active, these errors can be large. Defaults to False.

  • attribute_error (bool, optional) – Decide whether to include data attributes in the error metric. If off, then only geometric error is used to control the decimation. Defaults to False.

  • scalars (bool, optional) – If attribute errors are to be included in the metric (i.e., AttributeErrorMetric is on), then the following flags control which attributes are to be included in the error calculation. Defaults to True.

  • vectors (bool, optional) – See scalars parameter. Defaults to True.

  • normals (bool, optional) – See scalars parameter. Defaults to False.

  • tcoords (bool, optional) – See scalars parameter. Defaults to True.

  • tensors (bool, optional) – See scalars parameter. Defaults to True.

  • scalars_weight (float, optional) – The scaling weight contribution of the scalar attribute. These values are used to weight the contribution of the attributes towards the error metric. Defaults to 0.1.

  • vectors_weight (float, optional) – See scalars weight parameter. Defaults to 0.1.

  • normals_weight (float, optional) – See scalars weight parameter. Defaults to 0.1.

  • tcoords_weight (float, optional) – See scalars weight parameter. Defaults to 0.1.

  • tensors_weight (float, optional) – See scalars weight parameter. Defaults to 0.1.

  • inplace (bool, optional) – Updates mesh in-place while returning nothing.

Returns

outmesh – Decimated mesh. None when inplace=True.

Return type

pyvista.PolyData

decimate_pro(reduction, feature_angle=45.0, split_angle=75.0, splitting=True, pre_split_mesh=False, preserve_topology=False, inplace=False)

Reduce the number of triangles in a triangular mesh, forming a good approximation to the original geometry. Based on the algorithm originally described in “Decimation of Triangle Meshes”, Proc Siggraph 92.

Parameters
  • reduction (float) – Reduction factor. A value of 0.9 will leave 10 % of the original number of vertices.

  • feature_angle (float, optional) – Angle used to define what an edge is (i.e., if the surface normal between two adjacent triangles is >= feature_angle, an edge exists).

  • split_angle (float, optional) – Angle used to control the splitting of the mesh. A split line exists when the surface normals between two edge connected triangles are >= split_angle.

  • splitting (bool, optional) – Controls the splitting of the mesh at corners, along edges, at non-manifold points, or anywhere else a split is required. Turning splitting off will better preserve the original topology of the mesh, but may not necessarily give the exact requested decimation.

  • pre_split_mesh (bool, optional) – Separates the mesh into semi-planar patches, which are disconnected from each other. This can give superior results in some cases. If pre_split_mesh is set to True, the mesh is split with the specified split_angle. Otherwise mesh splitting is deferred as long as possible.

  • preserve_topology (bool, optional) – Controls topology preservation. If on, mesh splitting and hole elimination will not occur. This may limit the maximum reduction that may be achieved.

  • inplace (bool, optional) – Updates mesh in-place while returning nothing.

Returns

mesh – Decimated mesh. None when inplace=True.

Return type

pyvista.PolyData

delaunay_2d(tol=1e-05, alpha=0.0, offset=1.0, bound=False, inplace=False)

Apply a delaunay 2D filter along the best fitting plane

delauney_2d()

DEPRECATED. Please see pyvista.PolyData.delaunay_2d()

edge_mask(angle)

Returns a mask of the points of a surface mesh that have a surface angle greater than angle

Parameters

angle (float) – Angle to consider an edge.

fill_holes(hole_size, inplace=False)

Fill holes in a pyvista.PolyData or vtk.vtkPolyData object.

Holes are identified by locating boundary edges, linking them together into loops, and then triangulating the resulting loops. Note that you can specify an approximate limit to the size of the hole that can be filled.

Parameters
  • hole_size (float) – Specifies the maximum hole size to fill. This is represented as a radius to the bounding circumsphere containing the hole. Note that this is an approximate area; the actual area cannot be computed without first triangulating the hole.

  • inplace (bool, optional) – Return new mesh or overwrite input.

Returns

mesh – Mesh with holes filled. None when inplace=True

Return type

pyvista.PolyData

flip_normals()

Flip normals of a triangular mesh by reversing the point ordering.

geodesic(start_vertex, end_vertex, inplace=False)

Calculates the geodesic path betweeen two vertices using Dijkstra’s algorithm.

Parameters
  • start_vertex (int) – Vertex index indicating the start point of the geodesic segment.

  • end_vertex (int) – Vertex index indicating the end point of the geodesic segment.

Returns

output – PolyData object consisting of the line segment between the two given vertices.

Return type

pyvista.PolyData

geodesic_distance(start_vertex, end_vertex)

Calculates the geodesic distance betweeen two vertices using Dijkstra’s algorithm.

Parameters
  • start_vertex (int) – Vertex index indicating the start point of the geodesic segment.

  • end_vertex (int) – Vertex index indicating the end point of the geodesic segment.

Returns

length – Length of the geodesic segment.

Return type

float

plot_boundaries(**kwargs)

Plots boundaries of a mesh

plot_curvature(curv_type='mean', **kwargs)

Plots curvature

Parameters
  • curvtype (str, optional) –

    One of the following strings indicating curvature type

    • Mean

    • Gaussian

    • Maximum

    • Minimum

  • **kwargs (optional) – See help(pyvista.plot)

Returns

cpos – List of camera position, focal point, and view up

Return type

list

plot_normals(show_mesh=True, mag=1.0, flip=False, use_every=1, **kwargs)

Plot the point normals of a mesh.

project_points_to_plane(origin=None, normal=(0, 0, 1), inplace=False)

Project points of this mesh to a plane

ray_trace(origin, end_point, first_point=False, plot=False, off_screen=False)

Performs a single ray trace calculation given a mesh and a line segment defined by an origin and end_point.

Parameters
  • origin (np.ndarray or list) – Start of the line segment.

  • end_point (np.ndarray or list) – End of the line segment.

  • first_point (bool, optional) – Returns intersection of first point only.

  • plot (bool, optional) – Plots ray trace results

  • off_screen (bool, optional) – Plots off screen. Used for unit testing.

Returns

  • intersection_points (np.ndarray) – Location of the intersection points. Empty array if no intersections.

  • intersection_cells (np.ndarray) – Indices of the intersection cells. Empty array if no intersections.

remove_points(remove, mode='any', keep_scalars=True, inplace=False)

Rebuild a mesh by removing points. Only valid for all-triangle meshes.

Parameters
  • remove (np.ndarray) – If remove is a bool array, points that are True will be removed. Otherwise, it is treated as a list of indices.

  • mode (str, optional) – When ‘all’, only faces containing all points flagged for removal will be removed. Default ‘all’

  • keep_scalars (bool, optional) – When True, point and cell scalars will be passed on to the new mesh.

  • inplace (bool, optional) – Updates mesh in-place while returning nothing.

Returns

  • mesh (pyvista.PolyData) – Mesh without the points flagged for removal. Not returned when inplace=False.

  • ridx (np.ndarray) – Indices of new points relative to the original mesh. Not returned when inplace=False.

ribbon(width=None, scalars=None, angle=0.0, factor=2.0, normal=None, tcoords=False, preference='points')

Create a ribbon of the lines in this dataset.

Note

If there are no lines in the input dataset, then the output will be an empty PolyData mesh.

Parameters
  • width (float) – Set the “half” width of the ribbon. If the width is allowed to vary, this is the minimum width. The default is 10% the length

  • scalars (str, optional) – String name of the scalars array to use to vary the ribbon width. This is only used if a scalars array is specified.

  • angle (float) – Set the offset angle of the ribbon from the line normal. (The angle is expressed in degrees.) The default is 0.0

  • factor (float) – Set the maximum ribbon width in terms of a multiple of the minimum width. The default is 2.0

  • normal (tuple(float), optional) – Normal to use as default

  • tcoords (bool, str, optional) – If True, generate texture coordinates along the ribbon. This can also be specified to generate the texture coordinates in the following ways: 'length', 'normalized',

smooth(n_iter=20, relaxation_factor=0.01, convergence=0.0, edge_angle=15, feature_angle=45, boundary_smoothing=True, feature_smoothing=False, inplace=False)

Adjust point coordinates using Laplacian smoothing. The effect is to “relax” the mesh, making the cells better shaped and the vertices more evenly distributed.

Parameters
  • n_iter (int) – Number of iterations for Laplacian smoothing.

  • relaxation_factor (float, optional) – Relaxation factor controls the amount of displacement in a single iteration. Generally a lower relaxation factor and higher number of iterations is numerically more stable.

  • convergence (float, optional) – Convergence criterion for the iteration process. Smaller numbers result in more smoothing iterations. Range from (0 to 1).

  • edge_angle (float, optional) – Edge angle to control smoothing along edges (either interior or boundary).

  • feature_angle (float, optional) – Feature angle for sharp edge identification.

  • boundary_smoothing (bool, optional) – Boolean flag to control smoothing of boundary edges.

  • feature_smoothing (bool, optional) – Boolean flag to control smoothing of feature edges.

  • inplace (bool, optional) – Updates mesh in-place while returning nothing.

Returns

mesh – Decimated mesh. None when inplace=True.

Return type

pyvista.PolyData

subdivide(nsub, subfilter='linear', inplace=False)

Increase the number of triangles in a single, connected triangular mesh.

Uses one of the following vtk subdivision filters to subdivide a mesh. vtkButterflySubdivisionFilter vtkLoopSubdivisionFilter vtkLinearSubdivisionFilter

Linear subdivision results in the fastest mesh subdivision, but it does not smooth mesh edges, but rather splits each triangle into 4 smaller triangles.

Butterfly and loop subdivision perform smoothing when dividing, and may introduce artifacts into the mesh when dividing.

Subdivision filter appears to fail for multiple part meshes. Should be one single mesh.

Parameters
  • nsub (int) – Number of subdivisions. Each subdivision creates 4 new triangles, so the number of resulting triangles is nface*4**nsub where nface is the current number of faces.

  • subfilter (string, optional) – Can be one of the following: ‘butterfly’, ‘loop’, ‘linear’

  • inplace (bool, optional) – Updates mesh in-place while returning nothing.

Returns

mesh – pyvista polydata object. None when inplace=True

Return type

Polydata object

Examples

>>> from pyvista import examples
>>> import pyvista
>>> mesh = pyvista.PolyData(examples.planefile)
>>> submesh = mesh.subdivide(1, 'loop') 

alternatively, update mesh in-place

>>> mesh.subdivide(1, 'loop', inplace=True) 
tri_filter(inplace=False)

DEPRECATED: use .triangulate instead

triangulate(inplace=False)

Returns an all triangle mesh. More complex polygons will be broken down into triangles.

Parameters

inplace (bool, optional) – Updates mesh in-place while returning nothing.

Returns

mesh – Mesh containing only triangles. None when inplace=True

Return type

pyvista.PolyData

tube(radius=None, scalars=None, capping=True, n_sides=20, radius_factor=10, preference='point', inplace=False)

Generate a tube around each input line. The radius of the tube can be set to linearly vary with a scalar value.

Parameters
  • radius (float) – Minimum tube radius (minimum because the tube radius may vary).

  • scalars (str, optional) – Scalar array by which the radius varies

  • capping (bool) – Turn on/off whether to cap the ends with polygons. Default True.

  • n_sides (int) – Set the number of sides for the tube. Minimum of 3.

  • radius_factor (float) – Maximum tube radius in terms of a multiple of the minimum radius.

  • preference (str) – The field preference when searching for the scalar array by name

  • inplace (bool, optional) – Updates mesh in-place while returning nothing.

Returns

mesh – Tube-filtered mesh. None when inplace=True.

Return type

pyvista.PolyData

UnstructuredGrid Filters

The pyvista.UnstructuredGridFilters is inherited by pyvista.UnstructuredGrid making all the the following filters available as callable methods directly from any UnstructuredGrid mesh.

Methods

delaunay_2d([tol, alpha, offset, bound])

Apply a delaunay 2D filter along the best fitting plane.

class pyvista.UnstructuredGridFilters

Bases: pyvista.core.filters.DataSetFilters

delaunay_2d(tol=1e-05, alpha=0.0, offset=1.0, bound=False)

Apply a delaunay 2D filter along the best fitting plane. This extracts the grid’s points and perfoms the triangulation on those alone.

Composite Filters

These are filters that can be applied to composite datasets, i.e. pyvista.MultiBlock. The pyvista.CompositeFilters class inherits many but not all of the filters from pyvista.DataSetFilters.

Methods

cell_centers([vertex])

Generate points at the center of the cells in this dataset.

cell_data_to_point_data([pass_cell_data])

Transforms cell data (i.e., data specified per cell) into point data (i.e., data specified at cell points).

clip([normal, origin, invert, value, inplace])

Clip a dataset by a plane by specifying the origin and normal.

clip_box([bounds, invert, factor])

Clips a dataset by a bounding box defined by the bounds.

combine([merge_points])

Appends all blocks into a single unstructured grid.

compute_cell_sizes([length, area, volume])

This filter computes sizes for 1D (length), 2D (area) and 3D (volume) cells.

elevation([low_point, high_point, …])

Generate scalar values on a dataset.

extract_geometry()

Combines the geomertry of all blocks into a single PolyData object.

outline([generate_faces, nested])

Produces an outline of the full extent for the all blocks in this composite dataset.

outline_corners([factor, nested])

Produces an outline of the corners for the all blocks in this composite dataset.

point_data_to_cell_data([pass_point_data])

Transforms point data (i.e., data specified per node) into cell data (i.e., data specified within cells).

slice([normal, origin, generate_triangles, …])

Slice a dataset by a plane at the specified origin and normal vector orientation.

slice_along_axis([n, axis, tolerance, …])

Create many slices of the input dataset along a specified axis.

slice_along_line(line[, generate_triangles, …])

Slices a dataset using a polyline/spline as the path.

slice_orthogonal([x, y, z, …])

Creates three orthogonal slices through the dataset on the three caresian planes.

triangulate([inplace])

Returns an all triangle mesh.

wireframe()

Extract all the internal/external edges of the dataset as PolyData.

class pyvista.CompositeFilters

Bases: object

An internal class to manage filtes/algorithms for composite datasets.

cell_centers(vertex=True)

Generate points at the center of the cells in this dataset. These points can be used for placing glyphs / vectors.

Parameters

vertex (bool) – Enable/disable the generation of vertex cells.

cell_data_to_point_data(pass_cell_data=False)

Transforms cell data (i.e., data specified per cell) into point data (i.e., data specified at cell points). The method of transformation is based on averaging the data values of all cells using a particular point. Optionally, the input cell data can be passed through to the output as well.

See aslo: pyvista.DataSetFilters.point_data_to_cell_data()

Parameters

pass_cell_data (bool) – If enabled, pass the input cell data through to the output

clip(normal='x', origin=None, invert=True, value=0.0, inplace=False)

Clip a dataset by a plane by specifying the origin and normal. If no parameters are given the clip will occur in the center of that dataset

Parameters
  • normal (tuple(float) or str) – Length 3 tuple for the normal vector direction. Can also be specified as a string conventional direction such as 'x' for (1,0,0) or '-x' for (-1,0,0), etc.

  • origin (tuple(float)) – The center (x,y,z) coordinate of the plane on which the clip occurs

  • invert (bool) – Flag on whether to flip/invert the clip

  • value (float:) – Set the clipping value of the implicit function (if clipping with implicit function) or scalar value (if clipping with scalars). The default value is 0.0.

  • inplace (bool, optional) – Updates mesh in-place while returning nothing.

clip_box(bounds=None, invert=True, factor=0.35)

Clips a dataset by a bounding box defined by the bounds. If no bounds are given, a corner of the dataset bounds will be removed.

Parameters
  • bounds (tuple(float)) – Length 6 iterable of floats: (xmin, xmax, ymin, ymax, zmin, zmax)

  • invert (bool) – Flag on whether to flip/invert the clip

  • factor (float, optional) – If bounds are not given this is the factor along each axis to extract the default box.

combine(merge_points=False)

Appends all blocks into a single unstructured grid.

Parameters

merge_points (bool, optional) – Merge coincidental points.

compute_cell_sizes(length=True, area=True, volume=True)

This filter computes sizes for 1D (length), 2D (area) and 3D (volume) cells.

Parameters
  • length (bool) – Specify whether or not to compute the length of 1D cells.

  • area (bool) – Specify whether or not to compute the area of 2D cells.

  • volume (bool) – Specify whether or not to compute the volume of 3D cells.

elevation(low_point=None, high_point=None, scalar_range=None, preference='point', set_active=True)

Generate scalar values on a dataset. The scalar values lie within a user specified range, and are generated by computing a projection of each dataset point onto a line. The line can be oriented arbitrarily. A typical example is to generate scalars based on elevation or height above a plane.

Parameters
  • low_point (tuple(float), optional) – The low point of the projection line in 3D space. Default is bottom center of the dataset. Otherwise pass a length 3 tuple(float).

  • high_point (tuple(float), optional) – The high point of the projection line in 3D space. Default is top center of the dataset. Otherwise pass a length 3 tuple(float).

  • scalar_range (str or tuple(float), optional) – The scalar range to project to the low and high points on the line that will be mapped to the dataset. If None given, the values will be computed from the elevation (Z component) range between the high and low points. Min and max of a range can be given as a length 2 tuple(float). If str name of scalara array present in the dataset given, the valid range of that array will be used.

  • preference (str, optional) – When a scalar name is specified for scalar_range, this is the perfered scalar type to search for in the dataset. Must be either ‘point’ or ‘cell’.

  • set_active (bool, optional) – A boolean flag on whethter or not to set the new Elevation scalar as the active scalar array on the output dataset.

Warning

This will create a scalar array named Elevation on the point data of the input dataset and overasdf write an array named Elevation if present.

extract_geometry()

Combines the geomertry of all blocks into a single PolyData object. Place this filter at the end of a pipeline before a polydata consumer such as a polydata mapper to extract geometry from all blocks and append them to one polydata object.

outline(generate_faces=False, nested=False)

Produces an outline of the full extent for the all blocks in this composite dataset.

Parameters
  • generate_faces (bool, optional) – Generate solid faces for the box. This is off by default

  • nested (bool, optional) – If True, these creates individual outlines for each nested dataset

outline_corners(factor=0.2, nested=False)

Produces an outline of the corners for the all blocks in this composite dataset.

Parameters
  • factor (float, optional) – controls the relative size of the corners to the length of the corresponding bounds

  • ested (bool, optional) – If True, these creates individual outlines for each nested dataset

point_data_to_cell_data(pass_point_data=False)

Transforms point data (i.e., data specified per node) into cell data (i.e., data specified within cells). Optionally, the input point data can be passed through to the output.

See aslo: pyvista.DataSetFilters.cell_data_to_point_data()

Parameters

pass_point_data (bool) – If enabled, pass the input point data through to the output

slice(normal='x', origin=None, generate_triangles=False, contour=False)

Slice a dataset by a plane at the specified origin and normal vector orientation. If no origin is specified, the center of the input dataset will be used.

Parameters
  • normal (tuple(float) or str) – Length 3 tuple for the normal vector direction. Can also be specified as a string conventional direction such as 'x' for (1,0,0) or '-x' for (-1,0,0)`, etc.

  • origin (tuple(float)) – The center (x,y,z) coordinate of the plane on which the slice occurs

  • generate_triangles (bool, optional) – If this is enabled (False by default), the output will be triangles otherwise, the output will be the intersection polygons.

  • contour (bool, optional) – If True, apply a contour filter after slicing

slice_along_axis(n=5, axis='x', tolerance=None, generate_triangles=False, contour=False, bounds=None, center=None)

Create many slices of the input dataset along a specified axis.

Parameters
  • n (int) – The number of slices to create

  • axis (str or int) – The axis to generate the slices along. Perpendicular to the slices. Can be string name ('x', 'y', or 'z') or axis index (0, 1, or 2).

  • tolerance (float, optional) – The toleranceerance to the edge of the dataset bounds to create the slices

  • generate_triangles (bool, optional) – If this is enabled (False by default), the output will be triangles otherwise, the output will be the intersection polygons.

  • contour (bool, optional) – If True, apply a contour filter after slicing

slice_along_line(line, generate_triangles=False, contour=False)

Slices a dataset using a polyline/spline as the path. This also works for lines generated with pyvista.Line()

Parameters
  • line (pyvista.PolyData) – A PolyData object containing one single PolyLine cell.

  • generate_triangles (bool, optional) – If this is enabled (False by default), the output will be triangles otherwise, the output will be the intersection polygons.

  • contour (bool, optional) – If True, apply a contour filter after slicing

slice_orthogonal(x=None, y=None, z=None, generate_triangles=False, contour=False)

Creates three orthogonal slices through the dataset on the three caresian planes. Yields a MutliBlock dataset of the three slices.

Parameters
  • x (float) – The X location of the YZ slice

  • y (float) – The Y location of the XZ slice

  • z (float) – The Z location of the XY slice

  • generate_triangles (bool, optional) – If this is enabled (False by default), the output will be triangles otherwise, the output will be the intersection polygons.

  • contour (bool, optional) – If True, apply a contour filter after slicing

triangulate(inplace=False)

Returns an all triangle mesh. More complex polygons will be broken down into triangles.

Parameters

inplace (bool, optional) – Updates mesh in-place while returning None.

Returns

mesh – Mesh containing only triangles. None when inplace=True

Return type

pyvista.UnstructuredGrid

wireframe()

Extract all the internal/external edges of the dataset as PolyData. This produces a full wireframe representation of the input dataset.