DataObjectFilters.extract_surface

DataObjectFilters.extract_surface#

DataObjectFilters.extract_surface(
pass_pointid: bool = True,
pass_cellid: bool = True,
nonlinear_subdivision: int | None = None,
algorithm: _ExtractSurfaceOptions | type[_SENTINEL] = <class 'pyvista.core.filters.data_object._SENTINEL'>,
progress_bar: bool = False,
) → PolyData[source]#

Extract surface geometry of the mesh as PolyData.

Note

The underlying VTK algorithm can be selected for surface extraction. Using algorithm=None is recommended, and the appropriate algorithm will automatically be selected. The current default is 'dataset_surface', but this will change to None in a future version.

Changed in version 0.47: This filter is now generalized to also work with MultiBlock.

Parameters:
pass_pointidbool, default: True

Adds a point array "vtkOriginalPointIds" that identifies which original points these surface points correspond to.

pass_cellidbool, default: True

Adds a cell array "vtkOriginalCellIds" that identifies which original cells these surface cells correspond to.

nonlinear_subdivisionint, default: 1

Determines how many times the faces of non-linear cells are subdivided into linear faces. This option is only relevant when the input is an UnstructuredGrid with non-linear cells, and cannot be used with the 'geometry' algorithm.

If 0, the output is the equivalent to its linear counterpart (and the midpoints determining the non-linear interpolation are discarded). If 1 (the default), the non-linear face is triangulated based on the midpoints. If greater than 1, the triangulated pieces are recursively subdivided to reach the desired subdivision. Setting the value to greater than 1 may cause some point data to not be passed even if no nonlinear faces exist.

algorithm‘auto’ | ‘geometry’ | ‘dataset_surface’

VTK algorithm to use internally.

  • 'geometry': use vtkGeometryFilter.

  • 'dataset_surface': use vtkDataSetSurfaceFilter.

  • None: The algorithm is automatically selected based on the input. For most cases, the 'geometry' algorithm is selected by default. The 'dataset_surface' algorithm is only selected for cases where the input is an UnstructuredGrid with non-linear cells.

Using algorithm=None is recommended. The current default is 'dataset_surface', but this will change to None in a future version.

Both algorithms produce similar surfaces, but 'geometry' is more performant. The 'geometry' algorithm also

  • merges points by default,

  • tends to preserve the original mesh’s point order and connectivity, and

  • generates closed surfaces where closed surfaces would normally be expected.

See Compare Surface Extraction Algorithms for some examples of differences.

In general, users should not need to select the specific algorithm. This option is mostly provided for backwards-compatibility or specific use cases. For example, if working with both linear and non-linear meshes, it may be preferable to use 'dataset_surface' explicitly so that the generated surfaces may be more directly comparable.

Added in version 0.47.

progress_barbool, default: False

Display a progress bar to indicate progress.

Returns:
pyvista.PolyData

Surface mesh of the grid.

Warning

Both "vtkOriginalPointIds" and "vtkOriginalCellIds" may be affected by other VTK operations. See issue 1164 for recommendations on tracking indices across operations.

Examples

Extract the surface of an UnstructuredGrid.

>>> import pyvista as pv
>>> from pyvista import examples
>>> grid = examples.load_hexbeam()
>>> surf = grid.extract_surface(algorithm=None)
>>> type(surf)
<class 'pyvista.core.pointset.PolyData'>
>>> surf['vtkOriginalPointIds']
pyvista_ndarray([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13,
                 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27,
                 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41,
                 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55,
                 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69,
                 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83,
                 84, 85, 86, 87, 88, 89])
>>> surf['vtkOriginalCellIds']
pyvista_ndarray([ 0,  0,  0,  1,  1,  1,  3,  3,  3,  2,  2,  2, 36, 36,
                 36, 37, 37, 37, 39, 39, 39, 38, 38, 38,  5,  5,  9,  9,
                 13, 13, 17, 17, 21, 21, 25, 25, 29, 29, 33, 33,  4,  4,
                  8,  8, 12, 12, 16, 16, 20, 20, 24, 24, 28, 28, 32, 32,
                  7,  7, 11, 11, 15, 15, 19, 19, 23, 23, 27, 27, 31, 31,
                 35, 35,  6,  6, 10, 10, 14, 14, 18, 18, 22, 22, 26, 26,
                 30, 30, 34, 34])

Note that in the “vtkOriginalCellIds” array, the same original cells appears multiple times since this array represents the original cell of each surface cell extracted.

See the Extract Surface and Surface Smoothing for more examples using this filter.

Contents