pyvista.DataSetFilters.connectivity

DataSetFilters.connectivity(

extraction_mode: Literal['all', 'largest', 'specified', 'cell_seed', 'point_seed', 'closest'] = 'all',

variable_input: float | VectorLike[float] | None = None,

scalar_range: VectorLike[float] | None = None,

scalars: str | None = None,

label_regions: bool = True,

region_ids: VectorLike[int] | None = None,

point_ids: VectorLike[int] | None = None,

cell_ids: VectorLike[int] | None = None,

closest_point: VectorLike[float] | None = None,

inplace: bool = False,

progress_bar: bool = False,

**kwargs,

)

Find and label connected regions.

This filter extracts cell regions based on a specified connectivity criterion. The extraction criterion can be controlled with extraction_mode to extract the largest region or the closest region to a seed point, for example.

In general, cells are considered to be connected if they share a point. However, if a scalar_range is provided, cells must also have at least one point with scalar values in the specified range to be considered connected.

See Connectivity and Volumetric Analysis for more examples using this filter.

Added in version 0.43.0:

• New extraction modes: 'specified', 'cell_seed', 'point_seed', and 'closest'.

• Extracted regions are now sorted in descending order by cell count.

• Region connectivity can be controlled using scalar_range.

Deprecated since version 0.43.0: Parameter largest is deprecated. Use 'largest' or extraction_mode='largest' instead.

Parameters:

extraction_modestr, default: “all”

• 'all': Extract all connected regions.

• 'largest' : Extract the largest connected region (by cell count).

• 'specified': Extract specific region IDs. Use region_ids to specify the region IDs to extract.

• 'cell_seed': Extract all regions sharing the specified cell ids. Use cell_ids to specify the cell ids.

• 'point_seed' : Extract all regions sharing the specified point ids. Use point_ids to specify the point ids.

• 'closest' : Extract the region closest to the specified point. Use closest_point to specify the point.

variable_inputfloat | sequence[float], optional

The convenience parameter used for specifying any required input values for some values of extraction_mode. Setting variable_input is equivalent to setting:

• 'region_ids' if mode is 'specified'.

• 'cell_ids' if mode is 'cell_seed'.

• 'point_ids' if mode is 'point_seed'.

• 'closest_point' if mode is 'closest'.

It has no effect if the mode is 'all' or 'largest'.

scalar_rangesequence[float], optional

Scalar range in the form [min, max]. If set, the connectivity is restricted to cells with at least one point with scalar values in the specified range.

scalarsstr, optional

Name of scalars to use if scalar_range is specified. Defaults to currently active scalars.

Note

This filter requires point scalars to determine region connectivity. If cell scalars are provided, they are first converted to point scalars with cell_data_to_point_data() before applying the filter. The converted point scalars are removed from the output after applying the filter.

label_regionsbool, default: True

If True, 'RegionId' point and cell scalar arrays are stored. Each region is assigned a unique ID. IDs are zero-indexed and are assigned by region cell count in descending order (i.e. the largest region has ID 0).

region_idssequence[int], optional

Region ids to extract. Only used if extraction_mode is specified.

point_idssequence[int], optional

Point ids to use as seeds. Only used if extraction_mode is point_seed.

cell_idssequence[int], optional

Cell ids to use as seeds. Only used if extraction_mode is cell_seed.

closest_pointsequence[int], optional

Point coordinates in (x, y, z). Only used if extraction_mode is closest.

inplacebool, default: False

If True the mesh is updated in-place, otherwise a copy is returned. A copy is always returned if the input type is not pyvista.PolyData or pyvista.UnstructuredGrid.

progress_barbool, default: False

Display a progress bar.

**kwargsdict, optional

Used for handling deprecated parameters.

Returns:

pyvista.DataSet

Dataset with labeled connected regions. Return type is pyvista.PolyData if input type is pyvista.PolyData and pyvista.UnstructuredGrid otherwise.

See also

extract_largest, split_bodies, threshold, extract_values

Examples

Create a single mesh with three disconnected regions where each region has a different cell count.

>>> import pyvista as pv
>>> large = pv.Sphere(
...     center=(-4, 0, 0), phi_resolution=40, theta_resolution=40
... )
>>> medium = pv.Sphere(
...     center=(-2, 0, 0), phi_resolution=15, theta_resolution=15
... )
>>> small = pv.Sphere(center=(0, 0, 0), phi_resolution=7, theta_resolution=7)
>>> mesh = large + medium + small

Plot their connectivity.

>>> conn = mesh.connectivity('all')
>>> conn.plot(cmap=['red', 'green', 'blue'], show_edges=True)

Static Scene

Interactive Scene

Restrict connectivity to a scalar range.

>>> mesh['y_coordinates'] = mesh.points[:, 1]
>>> conn = mesh.connectivity('all', scalar_range=[-1, 0])
>>> conn.plot(cmap=['red', 'green', 'blue'], show_edges=True)

Static Scene

Interactive Scene

Extract the region closest to the origin.

>>> conn = mesh.connectivity('closest', (0, 0, 0))
>>> conn.plot(color='blue', show_edges=True)

Static Scene

Interactive Scene

Extract a region using a cell ID 100 as a seed.

>>> conn = mesh.connectivity('cell_seed', 100)
>>> conn.plot(color='green', show_edges=True)

Static Scene

Interactive Scene

Extract the largest region.

>>> conn = mesh.connectivity('largest')
>>> conn.plot(color='red', show_edges=True)

Static Scene

Interactive Scene

Extract the largest and smallest regions by specifying their region IDs. Note that the region IDs of the output differ from the specified IDs since the input has three regions but the output only has two.

>>> large_id = 0  # largest always has ID '0'
>>> small_id = 2  # smallest has ID 'N-1' with N=3 regions
>>> conn = mesh.connectivity('specified', (small_id, large_id))
>>> conn.plot(cmap=['red', 'blue'], show_edges=True)

Static Scene

Interactive Scene