API

DimensionError

Bases: Exception

The array has the wrong number of dimensions.

color_connectivity_graph

color_connectivity_graph(
    vcg: NDArray[VcgT],
    connectivity: Literal[4, 6, 8, 18, 26] = 26,
    return_N: bool = False,
) -> Union[NDArray[VcgT], tuple[NDArray[VcgT], int]]

Color the connectivity graph of a voxel connectivity graph.

Given a voxel connectivity graph following the same bit convention as cc3d.voxel_connectivity_graph (see docstring), assuming an undirected graph (the format supports directed graphs, but this is not implemented for the sake of efficiency), this function will return a uint32 image that contains connected components labeled according to the boundaries described in the voxel connectivity graph (vcg).

connected_components

connected_components(
    data: NDArray[Any],
    max_labels: int = -1,
    connectivity: Literal[4, 6, 8, 18, 26] = 26,
    return_N: bool = False,
    delta: float = 0,
    out_dtype: DTypeLike = None,
    out_file: Union[str, BinaryIO, None] = None,
    periodic_boundary: bool = False,
    binary_image: bool = False,
) -> Union[
    NDArray[Union[np.uint16, np.uint32, np.uint64]],
    tuple[NDArray[Union[np.uint16, np.uint32, np.uint64]], int],
]

Connected components applied to 3D images with handling for multiple labels.

Parameters:

Name	Type	Description	Default
`data`	`NDArray[Any]`	Input weights in a 2D or 3D numpy array.	required
`max_labels`	`int`	Save memory by predicting the maximum number of possible labels that might be output. Defaults to number of voxels.	`-1`
`connectivity`	`int`	For 3D images, 6 (voxel faces), 18 (+edges), or 26 (+corners) If the input image is 2D, you may specify 4 (pixel faces) or 8 (+corners).	`26`
`return_N`	`bool`	If True, also return the number of connected components as the second argument of a return tuple.	`False`
`delta`	`same as data`	Must be greater than or equal 0. Connect together values whose difference in value is <= delta. Useful for rough segmentations of continuously valued images.	`0`
`out_dtype`	`DTypeLike`	If specified, must be one of np.uint16, np.uint32, np.uint64. If not specified, it will be automatically determined. Most of the time, you should leave this off so that the smallest safe dtype will be used. However, in some applications you can save an up-conversion in the next operation by outputting the appropriately sized type instead.	`None`
`out_file`	`Union[str, BinaryIO, None]`	If specified, the output array will be an mmapped file. Can be a file-name or a file-like object.	`None`
`periodic_boundary`	`bool`	The boundary edges wrap around.	`False`
`binary_image`	`bool`	If True, regardless of the input type, treat as a binary image (foreground > 0, background == 0). Certain inputs will always be treated as a binary image (e.g. bool dtype, delta == max int or max float etc.).	`False`

Returns:

Type Description

Union[NDArray[Union[uint16, uint32, uint64]], tuple[NDArray[Union[uint16, uint32, uint64]], int]]

Returns either a tuple (out, N) if return_N is True, or just out otherwise, where out is a 1D, 2D, or 3D NumPy array representing the input remapped to reflect connected components sequentially numbered from 1 to N. The data type of out is automatically selected as uint16, uint32, or uint64 based on the estimated number of provisional labels required. N denotes the total number of connected components identified.

connected_components_stack

connected_components_stack(
    stacked_images: Iterable[NDArray[Any]],
    connectivity: Literal[6, 26] = 26,
    return_N: bool = False,
    binary_image: bool = False,
) -> Union[CrackleArray, tuple[CrackleArray, int]]

This is for performing connected component labeling on an array larger than RAM.

stacked_images is a sequence of 3D images that are of equal width and height (x, y) and arbitrary depth (z). For example, you might define a generator that produces a tenth of your data at a time. The data must be sequenced in z order from z = 0 to z = depth - 1.

Each 3D image will have CCL run on it and then compressed into crackle format (https://github.com/seung-lab/crackle) which is highly compressed but still usable and randomly accessible by z-slice.

The bottom previous slice and top current slice will be analyzed to produce a merged image.

The final output will be a CrackleArray. You can access parts of the image using standard array operations, write the array data to disk using arr.binary or fully decompressing the array using arr.decompress() to obtain a numpy array (but presumably this will blow out your RAM since the image is so big).

Parameters:

Name	Type	Description	Default
`stacked_images`	`Iterable[NDArray[Any]]`	A sequence of images to process.	required
`connectivity`	`Literal[6, 26]`	(2d) 6 [faces], 26 [faces + edges + corners]	`26`
`return_N`	`bool`	Change return value to (CrackleArray, N).	`False`
`binary_image`	`bool`	Treat the input images as binary images.	`False`

Returns:

Type	Description
`Union[CrackleArray, tuple[CrackleArray, int]]`	A CrackleArray containing the connected components
`Union[CrackleArray, tuple[CrackleArray, int]]`	of the input images and optionally the number of
`Union[CrackleArray, tuple[CrackleArray, int]]`	connected components in the image.

contacts

contacts(
    labels: NDArray[Any],
    connectivity: Literal[4, 6, 8, 18, 26] = 26,
    surface_area: bool = True,
    anisotropy: tuple[
        Union[int, float], Union[int, float], Union[int, float]
    ] = (1, 1, 1),
) -> dict[tuple[int, int], Union[int, float]]

Get the N-connected region adjacancy graph of a 3D image and the contact area between two regions.

Parameters:

Name	Type	Description	Default
`labels`	`NDArray[Any]`	3D numpy array of integer segmentation labels.	required
`connectivity`	`Literal[4, 6, 8, 18, 26]`	6, 18, or 26 (default).	`26`
`surface_area`	`bool`	Should the returned value be the contact surface area or a simple count of neighboring voxels? Surface area only counts face contact as edges and corners have zero area.	`True`
`anisotropy`	`tuple[Union[int, float], Union[int, float], Union[int, float]]`	Weights for x, y, and z dimensions for computing surface area.	`(1, 1, 1)`

Returns:

Type	Description
`dict[tuple[int, int], Union[int, float]]`	A dictionary resembling `{ (label_1, label_2): float, ... }`.

dust

dust(
    img: NDArray[Any],
    threshold: Union[
        int, float, tuple[int, int], tuple[float, float], list[int], list[float]
    ],
    connectivity: Literal[4, 6, 8, 18, 26] = 26,
    in_place: bool = False,
    binary_image: bool = False,
    precomputed_ccl: bool = False,
    invert: bool = False,
    return_N: bool = False,
) -> Union[NDArray[typing.Any], tuple[NDArray[typing.Any], int]]

Remove from the input image connected components smaller than threshold ("dust").

The name of the function can be read as a verb "to dust" the image.

Parameters:

Name	Type	Description	Default
`img`	`NDArray[Any]`	A 2D or 3D image.	required
`threshold`	`Union[int, float, tuple[int, int], tuple[float, float], list[int], list[float]]`	(int) discard components smaller than this in voxels (tuple/list) discard components outside this range [lower, upper)	required
`connectivity`	`Literal[4, 6, 8, 18, 26]`	A cc3d connectivity to use.	`26`
`in_place`	`bool`	Whether to modify the input image or perform dust.	`False`
`precomputed_ccl`	`bool`	For performance, avoid computing a CCL pass since the input is already a CCL output from this library.	`False`
`invert`	`bool`	Switch the threshold direction. For scalar input, this means less than converts to greater than or equal to, for ranged input, switch from between to outside of range.	`False`

Returns:

Type	Description
`Union[NDArray[Any], tuple[NDArray[Any], int]]`	The dusted image.

each

each(
    labels: NDArray[UnsignedIntegerT],
    binary: bool = False,
    in_place: bool = False,
) -> Iterator[tuple[int, NDArray[UnsignedIntegerT]]]

Returns an iterator that extracts each label from a dense labeling.

Parameters:

Name	Type	Description	Default
`binary`	`bool`	Create a binary image from each component (otherwise use the same dtype and label value for the mask).	`False`
`in_place`	`bool`	Much faster but the resulting image will be read-only.	`False`

Examples:

>>> for label, img in cc3d.each(labels, binary=False, in_place=False):
        process(img)

Returns:

Type	Description
`Iterator[tuple[int, NDArray[UnsignedIntegerT]]]`	An iterator.

estimate_provisional_labels

estimate_provisional_labels(data: NDArray[Any]) -> tuple[int, int, int]

Estimate the number of provisional labels required for connected components.

largest_k

largest_k(
    img: NDArray[Any],
    k: int,
    connectivity: Literal[4, 6, 8, 18, 26] = 26,
    delta: Union[int, float] = 0,
    return_N: bool = False,
    binary_image: bool = False,
    precomputed_ccl: bool = False,
) -> Union[
    NDArray[Union[np.bool_, np.uint16, np.uint32, np.uint64]],
    tuple[NDArray[Union[np.bool_, np.uint16, np.uint32, np.uint64]], int],
]

Returns the k largest connected components in the image.

NOTE

Performance may increase if you have the fastremap library installed. This may also change the numbering of the output.

Parameters:

Name	Type	Description	Default
`k`	`int`	The number of components to return (>= 0).	required
`connectivity`	`Literal[4, 6, 8, 18, 26]`	(2d) 4 [edges], 8 [edges + corners] (3d) 6 [faces], 18 [faces + edges], or 26 [faces + edges + corners]	`26`
`delta`	`Union[int, float]`	If using a continuous image, the allowed difference in adjacent voxel values.	`0`
`return_N`	`bool`	Change return value to (image, N).	`False`
`binary_image`	`bool`	Treat the input image as a binary image.	`False`
`precomputed_ccl`	`bool`	For performance, avoid computing a CCL pass since the input is already a CCL output from this library.	`False`

region_graph

region_graph(
    labels: NDArray[integer], connectivity: Literal[4, 6, 8, 18, 26] = 26
) -> set[tuple[int, int]]

Get the N-connected region adjacancy graph of a 3D image.

For backwards compatibility. "contacts" may be more useful.

Supports 26, 18, and 6 connectivities.

Parameters:

Name	Type	Description	Default
`labels`	`NDArray[integer]`	3D numpy array of integer segmentation labels.	required
`connectivity`	`Literal[4, 6, 8, 18, 26]`	6, 18, or 26 (default).	`26`

Returns:

Type	Description
`set[tuple[int, int]]`	A set of edges between labels.

statistics

statistics(
    out_labels: NDArray[Any], no_slice_conversion: bool = False
) -> Union[StatisticsDict, StatisticsSlicesDict]

Compute basic statistics on the regions in the image.

These are the voxel counts per label, the axis-aligned bounding box, and the centroid of each label.

LIMITATION

Input must be >=0 and < num voxels.

Parameters:

Name	Type	Description	Default
`out_labels`	`NDArray[Any]`	A numpy array of labels.	required
`no_slice_conversion`	`bool`	if True, return the bounding_boxes as a numpy array. This can save memory and time.	`False`

Returns:

Type Description

Union[StatisticsDict, StatisticsSlicesDict]

A dictionary with the following structure.

N = np.max(out_labels)
# Index into array is the CCL label.
{
    voxel_counts: NDArray[np.uint32], # (index is label) (N+1)
    # Structure is xmin, xmax, ymin, ymax, zmin, zmax by label
    bounding_boxes: NDArray[np.uint16] | list[tuple(slice, slice, slice)],
    # Index into list is the connected component ID, the tuple of
    # slices can be directly used to extract the region of interest
    # from out_labels using slice notation.
    # Structure is x,y,z
    centroids: NDArray[np.float64], # (N+1,3)
}

voxel_connectivity_graph

voxel_connectivity_graph(
    data: NDArray[IntegerT], connectivity: Literal[4, 6, 8, 18, 26] = 26
) -> NDArray[IntegerT]

Extracts the voxel connectivity graph from a multi-label image.

A voxel is considered connected if the adjacent voxel is the same label.

This output is a bitfield that represents a directed graph of the allowed directions for transit between voxels. If a connection is allowed, the respective direction is set to 1 else it set to 0.

For 2D connectivity, the output is an 8-bit unsigned integer.

Bits 1-4: edges     (4,8 way)
     5-8: corners   (8 way only, zeroed in 4 way)

    8       7      6      5      4      3      2      1
------ ------ ------ ------ ------ ------ ------ ------
  -x-y    x-y    -xy     xy     -x     +y     -x     +x

For a 3D 26 and 18 connectivity, the output requires 32-bit unsigned integers, for 6-way the output are 8-bit unsigned integers.

Bits 1-6: faces     (6,18,26 way)
    7-19: edges     (18,26 way)
   18-26: corners   (26 way)
   26-32: unused (zeroed)

6x unused, 8 corners, 12 edges, 6 faces

    32     31     30     29     28     27     26     25     24     23
------ ------ ------ ------ ------ ------ ------ ------ ------ ------
unused unused unused unused unused unused -x-y-z  x-y-z -x+y-z +x+y-z
    22     21     20     19     18     17     16     15     14     13
------ ------ ------ ------ ------ ------ ------ ------ ------ ------
-x-y+z +x-y+z -x+y+z    xyz   -y-z    y-z   -x-z    x-z    -yz     yz
    12     11     10      9      8      7      6      5      4      3
------ ------ ------ ------ ------ ------ ------ ------ ------ ------
   -xz     xz   -x-y    x-y    -xy     xy     -z     +z     -y     +y
     2      1
------ ------
    -x     +x

Parameters:

Name	Type	Description	Default
`data`	`NDArray[IntegerT]`	A numpy array.	required
`connectivity`	`Literal[4, 6, 8, 18, 26]`	The connectivity to use.	`26`

Returns:

Type	Description
`NDArray[IntegerT]`	A uint8 or uint32 numpy array the same size as the input.