pyvista.CompositeFilters.sample#

CompositeFilters.sample(
target,
tolerance=None,
pass_cell_data=True,
pass_point_data=True,
categorical=False,
progress_bar=False,
locator=None,
pass_field_data=True,
mark_blank=True,
snap_to_closest_point=False,
)[source]#

Resample array data from a passed mesh onto this mesh.

For mesh1.sample(mesh2), the arrays from mesh2 are sampled onto the points of mesh1. This function interpolates within an enclosing cell. This contrasts with :function`pyvista.DataSetFilters.interpolate` that uses a distance weighting for nearby points. If there is cell topology, sample is usually preferred.

The point data ‘vtkValidPointMask’ stores whether the point could be sampled with a value of 1 meaning successful sampling. And a value of 0 means unsuccessful.

This uses vtk.vtkResampleWithDataSet.

Parameters:
targetpyvista.DataSet

The vtk data object to sample from - point and cell arrays from this object are sampled onto the nodes of the dataset mesh.

tolerancefloat, optional

Tolerance used to compute whether a point in the source is in a cell of the input. If not given, tolerance is automatically generated.

pass_cell_databool, default: True

Preserve source mesh’s original cell data arrays.

pass_point_databool, default: True

Preserve source mesh’s original point data arrays.

categoricalbool, default: False

Control whether the source point data is to be treated as categorical. If the data is categorical, then the resultant data will be determined by a nearest neighbor interpolation scheme.

progress_barbool, default: False

Display a progress bar to indicate progress.

locatorvtkAbstractCellLocator or str, optional

Prototype cell locator to perform the FindCell() operation. Default uses the DataSet FindCell method. Valid strings with mapping to vtk cell locators are

  • ‘cell’ - vtkCellLocator

  • ‘cell_tree’ - vtkCellTreeLocator

  • ‘obb_tree’ - vtkOBBTree

  • ‘static_cell’ - vtkStaticCellLocator

pass_field_databool, default: True

Preserve source mesh’s original field data arrays.

mark_blankbool, default: True

Whether to mark blank points and cells in “vtkGhostType”.

snap_to_closest_pointbool, default: False

Whether to snap to cell with closest point if no cell is found. Useful when sampling from data with vertex cells. Requires vtk >=9.3.0.

Added in version 0.43.

Returns:
pyvista.DataSet

Dataset containing resampled data.

Examples

Resample data from another dataset onto a sphere.

>>> import pyvista as pv
>>> from pyvista import examples
>>> mesh = pv.Sphere(center=(4.5, 4.5, 4.5), radius=4.5)
>>> data_to_probe = examples.load_uniform()
>>> result = mesh.sample(data_to_probe)
>>> result.plot(scalars="Spatial Point Data")
../../../_images/pyvista-CompositeFilters-sample-1_00_00.png

If sampling from a set of points represented by a (n, 3) shaped numpy.ndarray, they need to be converted to a PyVista DataSet, e.g. pyvista.PolyData, first.

>>> import numpy as np
>>> points = np.array([[1.5, 5.0, 6.2], [6.7, 4.2, 8.0]])
>>> mesh = pv.PolyData(points)
>>> result = mesh.sample(data_to_probe)
>>> result["Spatial Point Data"]
pyvista_ndarray([ 46.5 , 225.12])

See Resampling for more examples using this filter.