find_trapped_regions

find_trapped_regions(im: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], seq: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], outlets: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], return_mask: bool = True, conn: Literal['min', 'max'] = 'min', method: Literal['queue', 'cluster'] = 'cluster', min_size: int = 0)[source]

Find the trapped regions given an invasion sequence map and specified outlets

Parameters:

  • im (ndarray) – The boolean image of the porous material with True indicating the phase of interest.

  • seq (ndarray) – An image with invasion sequence values in each voxel. Regions labelled -1 are considered uninvaded, and regions labelled 0 are considered solid. Because sequence values are used, this function is agnostic to whether the invasion followed drainage or imbibition.

  • outlets (ndarray) – An image the same size as im with True indicating outlets and False elsewhere.

  • return_mask (bool) – If True (default) then the returned image is a boolean mask indicating which voxels are trapped. If False, then a copy of seq is returned with the trapped voxels set to uninvaded (-1) and the remaining invasion sequence values adjusted accordingly.

  • conn (str) –

    Controls the shape of the structuring element used to determin if voxels are connected. Options are:

    Option

    Description

    ’min’

    This corresponds to a cross with 4 neighbors in 2D and 6 neighbors in 3D.

    ’max’

    This corresponds to a square or cube with 8 neighbors in 2D and 26 neighbors in 3D.

  • method (str) –

    Controls which method is used to analyze the invasion sequence. Options are:

    Option

    Description

    ’cluster’

    Uses scipy.ndimage.label to find all clusters of invading phase connected to the outlet at each value of sequence found on the outlet face. This method is faster if ibop was used for the simulation.

    ’queue’

    Uses a priority queue and walks the invasion process in reverse to find all trapped voxels. This method is faster if ibip or qbip was used for the simulation.

  • min_size (int) – Any clusters of trapped voxels smaller than this size will be set to not trapped. This is useful to prevent small voxels along edges of the void space from being set to trapped. These can appear to be trapped due to the jagged nature of the digital image. The default is 0, meaning this adjustment is not applied, but a value of 3 or 4 is recommended to activate this adjustment.

Returns:

trapped – An image, the same size as seq. If return_mask is True, then the image has True values indicating the trapped voxels. If return_mask is False, then a copy of seq is returned with trapped voxels set to -1.

Return type:

ND-image

Examples

Click here to view online example.