NumPy Utilities¶

Low-level array helpers used throughout TPTBox for label extraction, morphological operations, connected components, centre-of-mass computation, and more.

TPTBox.core.np_utils ¶

np_isin ¶

np_isin(arr: ndarray, labels, invert: bool = False) -> np.ndarray

Fast np.isin for non-negative integer label arrays via a boolean lookup table.

For unsigned-integer segmentation masks this is ~3-6x faster than np.isin when testing membership in more than one label, because it replaces the general algorithm with a single lut[arr] gather. Falls back to np.isin for non-unsigned dtypes, negative labels, or very large label ranges; uses arr == label for the single-label case.

Parameters:

Name	Type	Description	Default
`arr`	`ndarray`	Input array.	required
`labels`		A label or iterable of labels to test membership against.	required
`invert`	`bool`	If True, return the complement (equivalent to `np.isin(arr, labels, invert=True)`). Defaults to False.	`False`

Returns:

Type	Description
`ndarray`	np.ndarray: Boolean mask, same shape as `arr`.

Source code in TPTBox/core/np_utils.py

def np_isin(arr: np.ndarray, labels, invert: bool = False) -> np.ndarray:
    """Fast ``np.isin`` for non-negative integer label arrays via a boolean lookup table.

    For unsigned-integer segmentation masks this is ~3-6x faster than ``np.isin`` when testing
    membership in more than one label, because it replaces the general algorithm with a single
    ``lut[arr]`` gather. Falls back to ``np.isin`` for non-unsigned dtypes, negative labels, or
    very large label ranges; uses ``arr == label`` for the single-label case.

    Args:
        arr (np.ndarray): Input array.
        labels: A label or iterable of labels to test membership against.
        invert (bool, optional): If True, return the complement (equivalent to
            ``np.isin(arr, labels, invert=True)``). Defaults to False.

    Returns:
        np.ndarray: Boolean mask, same shape as ``arr``.
    """
    if not isinstance(labels, (list, tuple, np.ndarray)):
        labels = [labels]
    if len(labels) == 0:
        return np.ones(arr.shape, dtype=bool) if invert else np.zeros(arr.shape, dtype=bool)
    if len(labels) == 1:
        res = arr == labels[0]
        return ~res if invert else res
    if np.issubdtype(arr.dtype, np.unsignedinteger) and min(int(x) for x in labels) >= 0:
        m = max(int(arr.max()), int(max(labels))) + 1
        if m < 2**20:  # keep the lookup table small (same threshold as np_unique's bincount path)
            lut = np.zeros(m, dtype=bool)
            lut[np.asarray(labels)] = True
            res = lut[arr]
            return ~res if invert else res
    return np.isin(arr, labels, invert=invert)

np_extract_label ¶

np_extract_label(arr: ndarray, label: int | list[int], to_label: int = 1, inplace: bool = True) -> np.ndarray

Extracts a label from an given arr (works with zero as well!).

Parameters:

Name	Type	Description	Default
`arr`	`ndarray`	input arr	required
`label`	`int`	label to be extracted (all other values are set to zero, label will be set to one, even if label==0!)	required
`to_label`	`int`	the value of the entries that had the value. Defaults to 1.	`1`
`inplace`	`bool`	If False, will make a copy of the arr. Defaults to True.	`True`

Returns:

Type	Description
`ndarray`	np.ndarray: Binary array where the selected label is set to `to_label` and all other entries are zero.

Source code in TPTBox/core/np_utils.py

def np_extract_label(
    arr: np.ndarray,
    label: int | list[int],
    to_label: int = 1,
    inplace: bool = True,
) -> np.ndarray:
    """Extracts a label from an given arr (works with zero as well!).

    Args:
        arr (np.ndarray): input arr
        label (int): label to be extracted (all other values are set to zero,
            label will be set to one, even if label==0!)
        to_label (int): the value of the entries that had the <label> value. Defaults to 1.
        inplace (bool, optional): If False, will make a copy of the arr. Defaults to True.

    Returns:
        np.ndarray: Binary array where the selected label is set to ``to_label``
            and all other entries are zero.
    """
    if isinstance(label, int) and to_label == 1:
        return arr == label

    if to_label == 0:
        warnings.warn(
            "np_extract_label: to_label is zero, this can have unforeseen consequences!",
            UserWarning,
            stacklevel=4,
        )
    if not inplace:
        arr = arr.copy()

    if isinstance(label, list):
        assert 0 not in label, "label 0 is not supported in list mode"
        arr_msk = np_isin(arr, label)
        arr[arr_msk] = to_label
        arr[~arr_msk] = 0
        return arr

    if label != 0:
        arr[arr != label] = 0
        arr[arr == label] = to_label
        return arr
    # label == 0
    arr[arr != 0] = to_label + 1
    arr[arr == 0] = to_label
    arr[arr != to_label] = 0
    return arr

cc3dstatistics ¶

cc3dstatistics(arr: UINTARRAY, use_crop: bool = True) -> dict

Computes connected component statistics for a labeled array using connected components 3D (cc3d).

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	A 3D array of unsigned integers or booleans where each connected component is labeled with a unique integer. Typically output from a labeling function.	required
`use_crop`	`bool`	If True, the function attempts to crop the input array around non-zero regions to improve performance and focus statistics on the area of interest. Defaults to True.	`True`

Returns:

Name	Type	Description
`dict`	`dict`	A dictionary containing statistics of the connected components, such as their sizes, bounding boxes, and possibly centroids, depending on implementation of `_cc3dstats`.

Raises:

Type	Description
`AssertionError`	If the input array is not of an unsigned integer or boolean dtype.

Source code in TPTBox/core/np_utils.py

def cc3dstatistics(arr: UINTARRAY, use_crop: bool = True) -> dict:
    """Computes connected component statistics for a labeled array using connected components 3D (cc3d).

    Args:
        arr (UINTARRAY): A 3D array of unsigned integers or booleans where each connected component
                         is labeled with a unique integer. Typically output from a labeling function.
        use_crop (bool): If True, the function attempts to crop the input array around non-zero regions
                         to improve performance and focus statistics on the area of interest. Defaults to True.

    Returns:
        dict: A dictionary containing statistics of the connected components, such as their sizes,
              bounding boxes, and possibly centroids, depending on implementation of `_cc3dstats`.

    Raises:
        AssertionError: If the input array is not of an unsigned integer or boolean dtype.
    """
    assert np.issubdtype(arr.dtype, np.unsignedinteger) or np.issubdtype(arr.dtype, np.int32) or np.issubdtype(arr.dtype, np.bool_), (
        f"cc3dstatistics expects uint type, got {arr.dtype}"
    )
    try:
        if use_crop:
            crop = np_bbox_binary(arr, raise_error=False, px_dist=2)
            arrc = arr[crop]
            return _cc3dstats(arrc)
    except ValueError as e:
        print(e)
    return _cc3dstats(arr)

np_volume ¶

np_volume(arr: UINTARRAY, include_zero: bool = False) -> dict[int, int]

Returns a dictionary mapping each label in the array to its voxel count.

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	Input unsigned-integer label array.	required
`include_zero`	`bool`	If True, also counts voxels with label 0 (background). Defaults to False.	`False`

Returns:

Type	Description
`dict[int, int]`	dict[int, int]: Mapping from label value to number of voxels with that label.

Source code in TPTBox/core/np_utils.py

def np_volume(arr: UINTARRAY, include_zero: bool = False) -> dict[int, int]:
    """Returns a dictionary mapping each label in the array to its voxel count.

    Args:
        arr (UINTARRAY): Input unsigned-integer label array.
        include_zero (bool, optional): If True, also counts voxels with label 0
            (background). Defaults to False.

    Returns:
        dict[int, int]: Mapping from label value to number of voxels with that label.
    """
    # np.bincount wins decisively when there are many labels (e.g. connected-component maps);
    # cc3d statistics is faster for the few-label case typical of anatomical segmentations.
    counts = np.bincount(arr.ravel()) if int(arr.max()) > 256 else cc3dstatistics(arr, use_crop=not include_zero)["voxel_counts"]
    if include_zero:
        return {idx: i for idx, i in enumerate(counts) if i > 0}
    return {idx: i for idx, i in enumerate(counts) if i > 0 and idx != 0}

np_is_empty ¶

np_is_empty(arr: UINTARRAY | INTARRAY) -> bool

Returns true if the array is empty (only zeros).

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	input uint array	required

Returns:

Name	Type	Description
`bool`	`bool`	True if array is empty

ON UINT and INT:¶

is faster than np_count_nonzero(arr) > 0¶

is faster than arr.nonzero()[0].size == 0¶

is faster than arr.sum() > 0¶

Source code in TPTBox/core/np_utils.py

def np_is_empty(arr: UINTARRAY | INTARRAY) -> bool:
    """Returns true if the array is empty (only zeros).

    Args:
        arr (UINTARRAY): input uint array

    Returns:
        bool: True if array is empty

    #### ON UINT and INT:
    #### is faster than np_count_nonzero(arr) > 0
    #### is faster than arr.nonzero()[0].size == 0
    #### is faster than arr.sum() > 0
    """
    return arr.max() == 0

np_count_nonzero ¶

np_count_nonzero(arr: ndarray) -> int

Returns number of nonzero entries in the array.

Parameters:

Name	Type	Description	Default
`arr`	`ndarray`	Input array.	required

Returns:

Name	Type	Description
`int`	`int`	Number of elements in `arr` that are not equal to zero.

Source code in TPTBox/core/np_utils.py

def np_count_nonzero(arr: np.ndarray) -> int:
    """Returns number of nonzero entries in the array.

    Args:
        arr (np.ndarray): Input array.

    Returns:
        int: Number of elements in ``arr`` that are not equal to zero.
    """
    return np.count_nonzero(arr)

old_np_unique ¶

old_np_unique(arr: ndarray) -> list[int]

Returns each existing label in the array (including zero!).

Uses cc3d statistics for unsigned-integer arrays for speed, and falls back to numpy.unique for other dtypes.

Parameters:

Name	Type	Description	Default
`arr`	`ndarray`	Input label array.	required

Returns:

Type	Description
`list[int]`	list[int]: Sorted list of every distinct label value present in `arr`, including 0 (background).

Source code in TPTBox/core/np_utils.py

def old_np_unique(arr: np.ndarray) -> list[int]:
    """Returns each existing label in the array (including zero!).

    Uses cc3d statistics for unsigned-integer arrays for speed, and falls back
    to ``numpy.unique`` for other dtypes.

    Args:
        arr (np.ndarray): Input label array.

    Returns:
        list[int]: Sorted list of every distinct label value present in ``arr``,
            including 0 (background).
    """
    if np.issubdtype(arr.dtype, np.unsignedinteger):
        try:
            return [idx for idx, i in enumerate(cc3dstatistics(arr)["voxel_counts"]) if i > 0]
        except Exception:
            pass
    return list(np.unique(arr))

np_unique ¶

np_unique(arr: ndarray) -> list[int]

Returns each existing label in the array (including zero!).

Uses cc3d statistics for unsigned-integer arrays for speed, and falls back to numpy.unique for other dtypes.

Parameters:

Name	Type	Description	Default
`arr`	`ndarray`	Input label array.	required

Returns:

Type	Description
`list[int]`	list[int]: Sorted list of every distinct label value present in `arr`, including 0 (background).

Source code in TPTBox/core/np_utils.py

def np_unique(arr: np.ndarray) -> list[int]:
    """Returns each existing label in the array (including zero!).

    Uses cc3d statistics for unsigned-integer arrays for speed, and falls back
    to ``numpy.unique`` for other dtypes.

    Args:
        arr (np.ndarray): Input label array.

    Returns:
        list[int]: Sorted list of every distinct label value present in ``arr``,
            including 0 (background).
    """
    if np.issubdtype(arr.dtype, np.unsignedinteger):
        # bincount is O(max_val) but ~5-10x faster than np.unique for dense label arrays
        max_val = int(arr.max())
        if max_val < 2**20:  # ~1M labels threshold — bincount stays fast
            counts = np.bincount(arr.ravel())
            return np.where(counts > 0)[0].tolist()
        # For sparse label spaces fall back to np.unique
    return old_np_unique(arr)

np_unique_withoutzero ¶

np_unique_withoutzero(arr: UINTARRAY) -> list[int]

Returns each existing non-zero label in the array (excluding background zero).

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	Input unsigned-integer label array.	required

Returns:

Type	Description
`list[int]`	list[int]: Sorted list of every distinct label value present in `arr`, excluding 0 (background).

Source code in TPTBox/core/np_utils.py

def np_unique_withoutzero(arr: UINTARRAY) -> list[int]:
    """Returns each existing non-zero label in the array (excluding background zero).

    Args:
        arr (UINTARRAY): Input unsigned-integer label array.

    Returns:
        list[int]: Sorted list of every distinct label value present in ``arr``,
            excluding 0 (background).
    """
    if np.issubdtype(arr.dtype, np.unsignedinteger):
        max_val = int(arr.max())
        if max_val == 0:
            return []
        if max_val < 2**20:
            counts = np.bincount(arr.ravel())
            return list(np.where(counts[1:] > 0)[0] + 1)
    return [i for i in np.unique(arr) if i != 0]

old_np_unique_withoutzero ¶

old_np_unique_withoutzero(arr: UINTARRAY) -> list[int]

Returns each existing non-zero label in the array (excluding background zero).

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	Input unsigned-integer label array.	required

Returns:

Type	Description
`list[int]`	list[int]: Sorted list of every distinct label value present in `arr`, excluding 0 (background).

Source code in TPTBox/core/np_utils.py

def old_np_unique_withoutzero(arr: UINTARRAY) -> list[int]:
    """Returns each existing non-zero label in the array (excluding background zero).

    Args:
        arr (UINTARRAY): Input unsigned-integer label array.

    Returns:
        list[int]: Sorted list of every distinct label value present in ``arr``,
            excluding 0 (background).
    """
    try:
        return [idx for idx, i in enumerate(cc3dstatistics(arr)["voxel_counts"]) if i > 0 and idx != 0]
    except Exception:
        pass
    return [i for i in np_unique(arr) if i != 0]

np_center_of_mass ¶

np_center_of_mass(arr: UINTARRAY) -> dict[int, COORDINATE]

Calculates center of mass for each non-zero label in the array.

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	Input unsigned-integer label array.	required

Returns:

Type	Description
`dict[int, COORDINATE]`	dict[int, COORDINATE]: Mapping from each non-zero label to its (x, y, z) center-of-mass coordinate as floats.

Source code in TPTBox/core/np_utils.py

def np_center_of_mass(arr: UINTARRAY) -> dict[int, COORDINATE]:
    """Calculates center of mass for each non-zero label in the array.

    Args:
        arr (UINTARRAY): Input unsigned-integer label array.

    Returns:
        dict[int, COORDINATE]: Mapping from each non-zero label to its
            (x, y, z) center-of-mass coordinate as floats.
    """
    stats = cc3dstatistics(arr, use_crop=False)
    # Does not use the other calls for speed reasons
    vc = stats["voxel_counts"]
    return {idx: v for idx, v in enumerate(stats["centroids"]) if idx != 0 and vc[idx] > 0}

np_bounding_boxes ¶

np_bounding_boxes(arr: UINTARRAY) -> dict[int, tuple[slice, slice, slice]]

Calculates tight axis-aligned bounding boxes for each non-zero label in the array.

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	Input unsigned-integer label array.	required

Returns:

Type	Description
`dict[int, tuple[slice, slice, slice]]`	dict[int, tuple[slice, slice, slice]]: Mapping from each non-zero label to a 3-tuple of slices representing the bounding box of that label in each spatial dimension.

Source code in TPTBox/core/np_utils.py

def np_bounding_boxes(arr: UINTARRAY) -> dict[int, tuple[slice, slice, slice]]:
    """Calculates tight axis-aligned bounding boxes for each non-zero label in the array.

    Args:
        arr (UINTARRAY): Input unsigned-integer label array.

    Returns:
        dict[int, tuple[slice, slice, slice]]: Mapping from each non-zero label
            to a 3-tuple of slices representing the bounding box of that label
            in each spatial dimension.
    """
    stats = cc3dstatistics(arr)
    # Does not use the other calls for speed reasons
    vc = stats["voxel_counts"]
    return {idx: v for idx, v in enumerate(stats["bounding_boxes"]) if idx != 0 and vc[idx] > 0}

np_contacts ¶

np_contacts(arr: UINTARRAY, connectivity: int) -> dict[tuple[int, int], int]

Calculates the contacting labels and the amount of touching voxels based on connectivity.

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	Input 2D or 3D label array.	required
`connectivity`	`int`	Connectivity level in range [1, 3]. 1 = face-only, 2 = face+edge, 3 = face+edge+corner adjacency.	required

Returns:

Type	Description
`dict[tuple[int, int], int]`	dict[tuple[int, int], int]: Mapping from a pair of touching labels to the number of voxels where they touch.

Source code in TPTBox/core/np_utils.py

def np_contacts(arr: UINTARRAY, connectivity: int) -> dict[tuple[int, int], int]:
    """Calculates the contacting labels and the amount of touching voxels based on connectivity.

    Args:
        arr (UINTARRAY): Input 2D or 3D label array.
        connectivity (int): Connectivity level in range [1, 3]. 1 = face-only,
            2 = face+edge, 3 = face+edge+corner adjacency.

    Returns:
        dict[tuple[int, int], int]: Mapping from a pair of touching labels to the
            number of voxels where they touch.
    """
    assert 2 <= arr.ndim <= 3, f"expected 2D or 3D, but got {arr.ndim}"
    assert 1 <= connectivity <= 3, f"expected connectivity in [1,3], but got {connectivity}"
    connectivity = min(connectivity * 4, 8) if arr.ndim == 2 else 6 if connectivity == 1 else 18 if connectivity == 2 else 26
    return _contacts(arr, connectivity=connectivity)

np_region_graph ¶

np_region_graph(arr: UINTARRAY, connectivity: int) -> set[tuple[int, int]]

Returns the unique pairs of different labels that are adjacent in the array.

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	Input 2D or 3D label array.	required
`connectivity`	`int`	Connectivity level in range [1, 3]. 1 = face-only, 2 = face+edge, 3 = face+edge+corner adjacency.	required

Returns:

Type	Description
`set[tuple[int, int]]`	set[tuple[int, int]]: Set of (label_a, label_b) pairs where each pair indicates two labels that share at least one adjacent voxel.

Source code in TPTBox/core/np_utils.py

def np_region_graph(arr: UINTARRAY, connectivity: int) -> set[tuple[int, int]]:
    """Returns the unique pairs of different labels that are adjacent in the array.

    Args:
        arr (UINTARRAY): Input 2D or 3D label array.
        connectivity (int): Connectivity level in range [1, 3]. 1 = face-only,
            2 = face+edge, 3 = face+edge+corner adjacency.

    Returns:
        set[tuple[int, int]]: Set of (label_a, label_b) pairs where each pair
            indicates two labels that share at least one adjacent voxel.
    """
    assert 2 <= arr.ndim <= 3, f"expected 2D or 3D, but got {arr.ndim}"
    assert 1 <= connectivity <= 3, f"expected connectivity in [1,3], but got {connectivity}"
    connectivity = min(connectivity * 4, 8) if arr.ndim == 2 else 6 if connectivity == 1 else 18 if connectivity == 2 else 26
    return _region_graph(arr, connectivity=connectivity)

np_voxel_connectivity_graph ¶

np_voxel_connectivity_graph(arr: UINTARRAY, connectivity: int) -> np.ndarray

Returns a voxel connectivity graph of the input array.

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

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.

faces (6,18,26 way)

7-19: edges (18,26 way) 18-26: corners (26 way) 26-32: unused (zeroed)

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	Input 2D or 3D label array.	required
`connectivity`	`int`	Connectivity level in range [1, 3]. 1 = face-only, 2 = face+edge, 3 = face+edge+corner adjacency.	required

Returns:

Type	Description
`ndarray`	np.ndarray: uint8 or uint32 array the same shape as the input, where each value encodes which neighbors share the same label as that voxel.

Source code in TPTBox/core/np_utils.py

def np_voxel_connectivity_graph(arr: UINTARRAY, connectivity: int) -> np.ndarray:
    """Returns a voxel connectivity graph of the input array.

    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)

    Args:
        arr (UINTARRAY): Input 2D or 3D label array.
        connectivity (int): Connectivity level in range [1, 3]. 1 = face-only,
            2 = face+edge, 3 = face+edge+corner adjacency.

    Returns:
        np.ndarray: uint8 or uint32 array the same shape as the input, where
            each value encodes which neighbors share the same label as that voxel.
    """
    assert 2 <= arr.ndim <= 3, f"expected 2D or 3D, but got {arr.ndim}"
    assert 1 <= connectivity <= 3, f"expected connectivity in [1,3], but got {connectivity}"
    connectivity = min(connectivity * 4, 8) if arr.ndim == 2 else 6 if connectivity == 1 else 18 if connectivity == 2 else 26
    return _voxel_connectivity_graph(arr, connectivity=connectivity)

np_dice ¶

np_dice(seg: ndarray, gt: ndarray, binary_compare: bool = False, label: int = 1) -> float

Calculates the dice similarity between two numpy arrays.

Parameters:

Name	Type	Description	Default
`seg`	`ndarray`	segmentation array	required
`gt`	`ndarray`	other segmentation array	required
`binary_compare`	`bool`	if the should be binarized before (0/1)	`False`
`label`	`int`	if not binary_compare, use this label for dice score	`1`

Returns:

Name	Type	Description
`float`	`float`	dice value

Source code in TPTBox/core/np_utils.py

def np_dice(seg: np.ndarray, gt: np.ndarray, binary_compare: bool = False, label: int = 1) -> float:
    """Calculates the dice similarity between two numpy arrays.

    Args:
        seg: segmentation array
        gt: other segmentation array
        binary_compare: if the should be binarized before (0/1)
        label: if not binary_compare, use this label for dice score

    Returns:
        float: dice value
    """
    assert seg.shape == gt.shape, f"shape mismatch, got {seg.shape}, and {gt.shape}"

    with warnings.catch_warnings():
        warnings.filterwarnings("ignore", r"invalid value encountered in double_scalars")
        if binary_compare:
            seg_l = seg != 0
            gt_l = gt != 0
        else:
            seg_l = seg == label  # predicted mask for this label
            gt_l = gt == label  # ground-truth mask for this label
        intersect = np.logical_and(seg_l, gt_l).sum()
        denom = seg_l.sum() + gt_l.sum()
        dice = (2.0 * intersect) / (denom)
    if np.isnan(dice):
        return 1.0
    return dice

np_erode_msk_euclid ¶

np_erode_msk_euclid(arr: ndarray, n_pixel: int = 3, use_crop=True, labels=None, mask=None) -> np.ndarray

Euclidean erosion: shrink each foreground label by n_pixel voxels via distance transform.

Removes voxels whose Euclidean distance to background is ≤ n_pixel.

Source code in TPTBox/core/np_utils.py

def np_erode_msk_euclid(arr: np.ndarray, n_pixel: int = 3, use_crop=True, labels=None, mask=None) -> np.ndarray:
    """Euclidean erosion: shrink each foreground label by ``n_pixel`` voxels via distance transform.

    Removes voxels whose Euclidean distance to background is ≤ ``n_pixel``.
    """
    if use_crop:
        arr_bin = arr.copy()
        if labels is not None:
            arr_bin[np_isin(arr_bin, labels, invert=True)] = 0
        crop = np_bbox_binary(arr_bin, px_dist=1 + n_pixel, raise_error=False)
        arrc = arr[crop]
    else:
        arrc = arr
        if labels is not None:
            arrc = arrc.copy()
            arrc[np_isin(arrc, labels, invert=True)] = 0

    if mask is not None:
        mask = mask.copy()
        mask[mask != 0] = 1
        if use_crop:
            mask = mask[crop]

    foreground = arrc > 0

    # distance inside foreground to nearest background
    dist = distance_transform_edt(foreground)

    # copy original
    out = arrc.copy()

    # remove voxels within erosion distance
    erode_mask = (dist <= n_pixel) & foreground
    out[erode_mask] = 0

    if mask is not None:
        out[mask == 0] = 0

    if use_crop:
        arr[crop][arrc != 0] = out[arrc != 0]
        return arr

    arr[arrc != 0] = out[arrc != 0]
    return arr

np_dilate_msk_euclid ¶

np_dilate_msk_euclid(arr: ndarray, n_pixel: int = 3, use_crop=True, labels=None, mask=None) -> np.ndarray

Euclidean dilation: expand each foreground label by n_pixel voxels via distance transform.

Assigns each newly covered voxel to the nearest existing label.

Source code in TPTBox/core/np_utils.py

def np_dilate_msk_euclid(arr: np.ndarray, n_pixel: int = 3, use_crop=True, labels=None, mask=None) -> np.ndarray:
    """Euclidean dilation: expand each foreground label by ``n_pixel`` voxels via distance transform.

    Assigns each newly covered voxel to the nearest existing label.
    """
    arr_bin = arr.copy()
    if labels is not None:
        arr_bin[np_isin(arr_bin, labels, invert=True)] = 0

    if use_crop:
        crop = np_bbox_binary(arr_bin, px_dist=1 + n_pixel, raise_error=False)
        arrc = arr[crop]
    else:
        arrc = arr
        if labels is not None:
            arrc = arrc.copy()
            arrc[np_isin(arr_bin, labels, invert=True)] = 0
    if mask is not None:
        mask[mask != 0] = 1
        if use_crop:
            mask = mask[crop]
    foreground = arrc > 0

    # distance + nearest label indices
    dist, indices = distance_transform_edt(~foreground, return_indices=True)

    # copy original
    out = arrc.copy()

    # mask of voxels within dilation range
    dist_mask = (dist <= n_pixel) & (~foreground)

    # assign nearest label
    nearest_labels = arrc[tuple(indices)]
    out[dist_mask] = nearest_labels[dist_mask]
    if mask is not None:
        out[mask == 0] = 0
    if use_crop:
        arr[crop][out != 0] = out[out != 0]
        return arr
    arr[out != 0] = out[out != 0]
    return arr

np_dilate_msk ¶

np_dilate_msk(arr: ndarray, label_ref: LABEL_REFERENCE = None, n_pixel: int = 5, connectivity: int = 3, use_crop: bool = True, mask: ndarray | None = None, ignore_axis: int | None = None) -> np.ndarray

Dilates the given array by the specified number of voxels (not including the zero label).

Parameters:

Name	Type	Description	Default
`arr`	`ndarray`	Input label array.	required
`label_ref`	`LABEL_REFERENCE`	Label or list of labels to dilate. If None, all non-zero labels are dilated. Defaults to None.	`None`
`n_pixel`	`int`	Number of voxels to dilate by. Defaults to 5.	`5`
`connectivity`	`int`	Elements up to a squared distance of `connectivity` from the center are considered neighbors. Ranges from 1 (no diagonal neighbors) to 3 (all neighbors). Defaults to 3.	`3`
`use_crop`	`bool`	If True, crops to a bounding box before dilating for speed. Defaults to True.	`True`
`mask`	`ndarray \| None`	If set, after each iteration all voxels outside this mask are zeroed out. Defaults to None.	`None`
`ignore_axis`	`int \| None`	If set, dilation is performed in 2D along all slices of this axis (e.g., 0 for slice-wise axial dilation). Defaults to None.	`None`

Returns:

Type	Description
`ndarray`	np.ndarray: The dilated label array.

Source code in TPTBox/core/np_utils.py

def np_dilate_msk(
    arr: np.ndarray,
    label_ref: LABEL_REFERENCE = None,
    n_pixel: int = 5,
    connectivity: int = 3,
    use_crop: bool = True,
    mask: np.ndarray | None = None,
    ignore_axis: int | None = None,
) -> np.ndarray:
    """Dilates the given array by the specified number of voxels (not including the zero label).

    Args:
        arr (np.ndarray): Input label array.
        label_ref (LABEL_REFERENCE, optional): Label or list of labels to dilate.
            If None, all non-zero labels are dilated. Defaults to None.
        n_pixel (int, optional): Number of voxels to dilate by. Defaults to 5.
        connectivity (int, optional): Elements up to a squared distance of
            ``connectivity`` from the center are considered neighbors.
            Ranges from 1 (no diagonal neighbors) to 3 (all neighbors). Defaults to 3.
        use_crop (bool, optional): If True, crops to a bounding box before dilating
            for speed. Defaults to True.
        mask (np.ndarray | None, optional): If set, after each iteration all voxels
            outside this mask are zeroed out. Defaults to None.
        ignore_axis (int | None, optional): If set, dilation is performed in 2D
            along all slices of this axis (e.g., 0 for slice-wise axial dilation).
            Defaults to None.

    Returns:
        np.ndarray: The dilated label array.
    """
    labels: list[int] = _to_labels(arr, label_ref)
    # present_labels = np_unique(arr)

    if use_crop:
        # try:
        arr_bin = arr.copy()
        arr_bin[np_isin(arr_bin, labels, invert=True)] = 0
        crop = np_bbox_binary(arr_bin, px_dist=1 + n_pixel, raise_error=False)
        arrc = arr[crop]
    else:
        arrc = arr

    if mask is not None:
        mask[mask != 0] = 1
        if use_crop:
            mask = mask[crop]
    if ignore_axis is None:
        struct = generate_binary_structure(arr.ndim, connectivity)
    else:
        struct = generate_binary_structure(arr.ndim - 1, connectivity)
        struct = np.expand_dims(struct, ignore_axis)

    labels: list[int] = [l for l in labels if l != 0]  # and l in present_labels]

    out = arrc
    for _ in range(n_pixel):
        for i in labels:
            data = out == i  # boolean mask; _binary_dilation casts to bool anyway, so this is exact and avoids a full copy
            if use_crop:
                lcrop = np_bbox_binary(data, px_dist=2 + n_pixel, raise_error=False)
                data = data[lcrop]
            msk_ibe_data = _binary_dilation(data, struct=struct)

            if use_crop:
                oc = out[lcrop] == 0
                out[lcrop][oc] = msk_ibe_data[oc] * i
                if mask is not None:
                    out[lcrop][mask == 0] = 0
            else:
                out[out == 0] = msk_ibe_data[out == 0] * i
                if mask is not None:
                    out[mask == 0] = 0
    if use_crop:
        arr[crop] = out
        return arr
    return out

np_erode_msk ¶

np_erode_msk(arr: ndarray, label_ref: LABEL_REFERENCE = None, n_pixel: int = 5, use_crop: bool = True, connectivity: int = 3, border_value=0, ignore_axis: int | None = None) -> np.ndarray

Erodes the given array by the specified number of voxels.

Parameters:

Name	Type	Description	Default
`arr`	`ndarray`	Input label array.	required
`label_ref`	`LABEL_REFERENCE`	Label or list of labels to erode. If None, all non-zero labels are eroded. Defaults to None.	`None`
`n_pixel`	`int`	Number of voxels to erode by. Defaults to 5.	`5`
`use_crop`	`bool`	If True, crops to a bounding box before eroding for speed. Defaults to True.	`True`
`connectivity`	`int`	Elements up to a squared distance of `connectivity` from the center are considered neighbors. Ranges from 1 (no diagonal neighbors) to 3 (all neighbors). Defaults to 3.	`3`
`border_value`	`int`	Value to pad the border with during erosion. Defaults to 0.	`0`
`ignore_axis`	`int \| None`	If set, erosion is performed in 2D along all slices of this axis. Defaults to None.	`None`

Returns:

Type	Description
`ndarray`	np.ndarray: The eroded label array.

Source code in TPTBox/core/np_utils.py

def np_erode_msk(
    arr: np.ndarray,
    label_ref: LABEL_REFERENCE = None,
    n_pixel: int = 5,
    use_crop: bool = True,
    connectivity: int = 3,
    border_value=0,
    ignore_axis: int | None = None,
) -> np.ndarray:
    """Erodes the given array by the specified number of voxels.

    Args:
        arr (np.ndarray): Input label array.
        label_ref (LABEL_REFERENCE, optional): Label or list of labels to erode.
            If None, all non-zero labels are eroded. Defaults to None.
        n_pixel (int, optional): Number of voxels to erode by. Defaults to 5.
        use_crop (bool, optional): If True, crops to a bounding box before eroding
            for speed. Defaults to True.
        connectivity (int, optional): Elements up to a squared distance of
            ``connectivity`` from the center are considered neighbors.
            Ranges from 1 (no diagonal neighbors) to 3 (all neighbors). Defaults to 3.
        border_value (int, optional): Value to pad the border with during erosion.
            Defaults to 0.
        ignore_axis (int | None, optional): If set, erosion is performed in 2D
            along all slices of this axis. Defaults to None.

    Returns:
        np.ndarray: The eroded label array.
    """
    labels: list[int] = _to_labels(arr, label_ref)

    if use_crop:
        crop = np_bbox_binary(np_isin(arr, labels, invert=False), px_dist=1 + n_pixel, raise_error=False)
        arrc = arr[crop]
    else:
        arrc = arr

    if ignore_axis is None:
        struct = generate_binary_structure(arr.ndim, connectivity)
    else:
        struct = generate_binary_structure(arr.ndim - 1, connectivity)
        struct = np.expand_dims(struct, ignore_axis)
    msk_i_data = arrc.copy()
    out = arrc
    for i in labels:
        if i == 0:  # or i not in present_labels:
            continue
        data = msk_i_data.copy()
        data[i != data] = 0
        if use_crop:
            lcrop = np_bbox_binary(data, px_dist=1, raise_error=False)
            data = data[lcrop]
        msk_ibe_data = binary_erosion(data, structure=struct, iterations=n_pixel, border_value=border_value)
        data[~msk_ibe_data] = 0  # type: ignore
        if use_crop:
            out[lcrop][(msk_i_data[lcrop] == i) & (data == 0)] = 0
        else:
            out[(msk_i_data == i) & (data == 0)] = 0
    if use_crop:
        arr[crop] = out
        return arr
    return out

np_map_labels ¶

np_map_labels(arr: UINTARRAY, label_map: LABEL_MAP) -> np.ndarray

Maps labels in the given array according to a label-map dictionary.

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	Input unsigned-integer label array to remap.	required
`label_map`	`LABEL_MAP`	Dictionary mapping original label values (int or str) to new label values (int or str). Labels not present in the map are left unchanged.	required

Returns:

Type	Description
`ndarray`	np.ndarray: A new array with labels remapped according to `label_map`.

Source code in TPTBox/core/np_utils.py

def np_map_labels(arr: UINTARRAY, label_map: LABEL_MAP) -> np.ndarray:
    """Maps labels in the given array according to a label-map dictionary.

    Args:
        arr (UINTARRAY): Input unsigned-integer label array to remap.
        label_map (LABEL_MAP): Dictionary mapping original label values (int or str)
            to new label values (int or str). Labels not present in the map are
            left unchanged.

    Returns:
        np.ndarray: A new array with labels remapped according to ``label_map``.
    """
    k = np.array(list(label_map.keys()))
    v = np.array(list(label_map.values()))

    assert len(k) == len(v)
    if len(k) == 0:
        return arr

    max_value = max(arr.max(), *k, *v) + 1

    mapping_ar = np.arange(max_value, dtype=arr.dtype)
    mapping_ar[k] = v
    return mapping_ar[arr]

np_calc_crop_around_centerpoint ¶

np_calc_crop_around_centerpoint(poi: tuple[int, ...] | tuple[float, ...], arr: ndarray, cutout_size: tuple[int, ...], pad_to_size: Sequence[int] | ndarray | int = 0) -> tuple[np.ndarray, tuple[slice, slice, slice], tuple]

Crops a fixed-size region centred on a given point, optionally padding near-edge regions.

Parameters:

Name	Type	Description	Default
`poi`	`tuple[int, ...] \| tuple[float, ...]`	Center point of the cutout, one coordinate per dimension.	required
`arr`	`ndarray`	Input array to crop.	required
`cutout_size`	`tuple[int, ...]`	Desired size of the cutout in each dimension.	required
`pad_to_size`	`Sequence[int] \| ndarray \| int`	Additional symmetric padding to add around the cutout. Can be a single int (same for all dims) or a per-dim sequence. Defaults to 0.	`0`

Returns:

Name	Type	Description
`tuple`	`tuple[ndarray, tuple[slice, slice, slice], tuple]`	A 3-element tuple containing: - np.ndarray: The cropped (and padded) sub-array. - tuple[slice, ...]: Slices used to extract the cutout from `arr`. - tuple: Per-dimension padding amounts applied as `(pad_before, pad_after)`.

Source code in TPTBox/core/np_utils.py

def np_calc_crop_around_centerpoint(
    poi: tuple[int, ...] | tuple[float, ...],
    arr: np.ndarray,
    cutout_size: tuple[int, ...],
    pad_to_size: Sequence[int] | np.ndarray | int = 0,
) -> tuple[np.ndarray, tuple[slice, slice, slice], tuple]:
    """Crops a fixed-size region centred on a given point, optionally padding near-edge regions.

    Args:
        poi: Center point of the cutout, one coordinate per dimension.
        arr: Input array to crop.
        cutout_size: Desired size of the cutout in each dimension.
        pad_to_size: Additional symmetric padding to add around the cutout.
            Can be a single int (same for all dims) or a per-dim sequence.
            Defaults to 0.

    Returns:
        tuple: A 3-element tuple containing:
            - np.ndarray: The cropped (and padded) sub-array.
            - tuple[slice, ...]: Slices used to extract the cutout from ``arr``.
            - tuple: Per-dimension padding amounts applied as ``(pad_before, pad_after)``.
    """
    n_dim = len(poi)
    if isinstance(pad_to_size, int):
        pad_to_size = np.ones(n_dim) * pad_to_size
    assert n_dim == len(arr.shape) == len(cutout_size) == len(pad_to_size), (
        f"dimension mismatch, got dim {n_dim}, poi {poi}, arr shape {arr.shape}, cutout {cutout_size}, pad_to_size {pad_to_size}"
    )

    poi = tuple(int(i) for i in poi)
    shape = arr.shape
    # Get cutout range
    cutout_coords = []
    padding = []
    for d in range(n_dim):
        _min, _max, _pad_min, _pad_max = _np_get_min_max_pad(poi[d], shape[d], cutout_size[d] // 2, pad_to_size[d] // 2)
        cutout_coords += [_min, _max]
        padding.append((int(_pad_min), int(_pad_max)))
    # cutout_coords = (x_min, x_max, y_min, y_max, z_min, z_max)
    # padding = ((x_pad_min, x_pad_max), (y_pad_min, y_pad_max), (z_pad_min, z_pad_max))

    cutout_coords_slices = tuple([slice(cutout_coords[i], cutout_coords[i + 1]) for i in range(0, n_dim * 2, 2)])
    arr_cut = arr[cutout_coords_slices]
    arr_cut = np.pad(arr_cut, tuple(padding))
    return (arr_cut, cutout_coords_slices, tuple(padding))

np_bbox_binary ¶

np_bbox_binary(img: ndarray, px_dist: int | Sequence[int] | ndarray = 0, raise_error=True) -> tuple[slice, ...]

Calculates a bounding box in n dimensions given a image (factor ~2 times faster than compute_crop).

Parameters:

Name	Type	Description	Default
`img`	`ndarray`	input array	required
`px_dist`	`int \| Sequence[int] \| ndarray`	int \| tuple[int]: dist (int): The amount of padding to be added to the cropped image. If int, will apply the same padding to each dim. Default value is 0.	`0`

Returns:

Type	Description
`tuple[slice, ...]`	list of boundary coordinates as slices tuple

Source code in TPTBox/core/np_utils.py

def np_bbox_binary(img: np.ndarray, px_dist: int | Sequence[int] | np.ndarray = 0, raise_error=True) -> tuple[slice, ...]:
    """Calculates a bounding box in n dimensions given a image (factor ~2 times faster than compute_crop).

    Args:
        img: input array
        px_dist: int | tuple[int]: dist (int): The amount of padding to be added to the cropped image. If int, will apply the same padding to each dim. Default value is 0.

    Returns:
        list of boundary coordinates as slices tuple
    """
    assert img is not None, "bbox_nd: received None as image"
    if np_is_empty(img):
        if raise_error:
            raise ValueError("bbox_nd: img is empty, cannot calculate a bbox")
        return tuple([slice(None)] * img.ndim)

    n = img.ndim
    shp = img.shape
    if isinstance(px_dist, int):
        px_dist = np.ones(n, dtype=np.uint8) * px_dist
    assert len(px_dist) == n, f"dimension mismatch, got img shape {shp} and px_dist {px_dist}"

    bbox: list[float] = []
    if n == 3:
        # 2 full passes instead of 3: two axis extents come from a shared 2D projection (cheap),
        # only the third axis needs a second full reduction.
        p = np.any(img, axis=2)
        for nonzero in (np.any(p, axis=1), np.any(p, axis=0), np.any(img, axis=(0, 1))):
            bbox.extend(np.where(nonzero)[0][[0, -1]])  # type: ignore
    else:
        for ax in itertools.combinations(reversed(range(n)), n - 1):
            nonzero = np.any(a=img, axis=ax)
            bbox.extend(np.where(nonzero)[0][[0, -1]])  # type: ignore
    out: tuple[slice, ...] = tuple(
        slice(
            max(bbox[i] - px_dist[i // 2], 0),
            min(bbox[i + 1] + px_dist[i // 2], shp[i // 2]) + 1,
        )
        for i in range(0, len(bbox), 2)
    )
    return out

np_center_of_bbox_binary ¶

np_center_of_bbox_binary(img: ndarray, px_dist: int | Sequence[int] | ndarray = 0) -> list[int]

Calculates the center coordinates of the bounding box around non-zero regions in a binary image.

This function determines the bounding box of non-zero regions in a binary image, optionally expanding it by a specified pixel distance. It then computes and returns the center coordinates of each dimension of the bounding box.

Parameters:

Name	Type	Description	Default
`img`	`ndarray`	A binary image represented as a NumPy array, where non-zero values indicate points of interest.	required
`px_dist`	`int \| Sequence[int] \| ndarray`	The pixel distance by which to expand the bounding box in each dimension. Can be a single integer or a sequence of integers corresponding to each dimension. Default is 0, meaning no expansion.	`0`

Returns:

Type	Description
`list[int]`	list[int]: A list of center coordinates for each dimension of the bounding box.

Raises:

Type	Description
`ValueError`	If the input image is empty or not a valid binary array.

Source code in TPTBox/core/np_utils.py

def np_center_of_bbox_binary(img: np.ndarray, px_dist: int | Sequence[int] | np.ndarray = 0) -> list[int]:
    """Calculates the center coordinates of the bounding box around non-zero regions in a binary image.

    This function determines the bounding box of non-zero regions in a binary image,
    optionally expanding it by a specified pixel distance. It then computes and returns
    the center coordinates of each dimension of the bounding box.

    Args:
        img (np.ndarray): A binary image represented as a NumPy array, where non-zero values indicate
            points of interest.
        px_dist (int | Sequence[int] | np.ndarray, optional): The pixel distance by which to expand
            the bounding box in each dimension. Can be a single integer or a sequence of integers
            corresponding to each dimension. Default is 0, meaning no expansion.

    Returns:
        list[int]: A list of center coordinates for each dimension of the bounding box.

    Raises:
        ValueError: If the input image is empty or not a valid binary array.
    """
    bbox_nd = np_bbox_binary(img, px_dist=px_dist)
    ctd_bbox = []
    for i in range(len(bbox_nd)):
        size_t = bbox_nd[i].stop - bbox_nd[i].start
        # print(i, size_t)
        ctd_bbox.append(bbox_nd[i].start + (size_t // 2))
    return ctd_bbox

np_find_index_of_k_max_values ¶

np_find_index_of_k_max_values(arr: ndarray, k: int = 2) -> list[int]

Calculates the indices of the k-highest values in the given arr.

Parameters:

Name	Type	Description	Default
`arr`	`ndarray`	input array	required
`k`	`int`	number of higest values to calculate the index for	`2`

Returns:

Type	Description
`list[int]`	list[int]: list of indices sorted. First entry corresponds to the index of the highest value in arr, ...

Source code in TPTBox/core/np_utils.py

def np_find_index_of_k_max_values(arr: np.ndarray, k: int = 2) -> list[int]:
    """Calculates the indices of the k-highest values in the given arr.

    Args:
        arr: input array
        k: number of higest values to calculate the index for

    Returns:
        list[int]: list of indices sorted. First entry corresponds to the index of the highest value in arr, ...
    """
    idx = np.argpartition(arr, -k)[-k:]
    indices = idx[np.argsort((-arr)[idx])]
    return list(indices)

np_compute_surface ¶

np_compute_surface(arr: UINTARRAY, connectivity: int = 3, dilated_surface: bool = False) -> UINTARRAY

Computes the surface of a binary array based on connectivity and dilation options.

This function identifies the surface voxels of a binary array. If dilated_surface is True, it computes a dilated surface by expanding the array and subtracting the original. Otherwise, it computes a contracted surface by eroding the array and subtracting the result from the original.

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	A binary array representing the segmentation or mask.	required
`connectivity`	`int`	The connectivity used to define neighbors for surface computation, where 1 represents face-connectivity, and 3 represents full connectivity. Default is 3.	`3`
`dilated_surface`	`bool`	Whether to compute a dilated surface. If True, expands the surface; if False, contracts the surface. Default is False.	`False`

Returns:

Name	Type	Description
`UINTARRAY`	`UINTARRAY`	An array representing the computed surface voxels.

Source code in TPTBox/core/np_utils.py

def np_compute_surface(arr: UINTARRAY, connectivity: int = 3, dilated_surface: bool = False) -> UINTARRAY:
    """Computes the surface of a binary array based on connectivity and dilation options.

    This function identifies the surface voxels of a binary array. If `dilated_surface`
    is True, it computes a dilated surface by expanding the array and subtracting the
    original. Otherwise, it computes a contracted surface by eroding the array and
    subtracting the result from the original.

    Args:
        arr (UINTARRAY): A binary array representing the segmentation or mask.
        connectivity (int, optional): The connectivity used to define neighbors for
            surface computation, where 1 represents face-connectivity, and 3 represents
            full connectivity. Default is 3.
        dilated_surface (bool, optional): Whether to compute a dilated surface. If True,
            expands the surface; if False, contracts the surface. Default is False.

    Returns:
        UINTARRAY: An array representing the computed surface voxels.
    """
    assert 1 <= connectivity <= 3, f"expected connectivity in [1,3], but got {connectivity}"
    if dilated_surface:
        dil = np_dilate_msk(arr.copy(), n_pixel=1, connectivity=connectivity)
        dil[arr != 0] = 0  # remove all non-zero entries
        return dil
    else:
        ero = np_erode_msk(arr.copy(), n_pixel=1, connectivity=connectivity)
        arr = arr.copy()
        arr[ero != 0] = 0  # remove all non-zero entries
        return arr

np_point_coordinates ¶

np_point_coordinates(arr: UINTARRAY) -> list[tuple[int, int, int]]

Extracts the coordinates of non-zero points from a 3D binary array.

This function locates all non-zero voxels within a 3D binary array and returns their coordinates as a list of tuples.

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	A 3-dimensional binary array representing the segmentation or mask.	required

Returns:

Type	Description
`list[tuple[int, int, int]]`	list[tuple[int, int, int]]: A list of (X, Y, Z) coordinate tuples for each non-zero
`list[tuple[int, int, int]]`	point in the array.

Raises:

Type	Description
`AssertionError`	If the input array does not have three dimensions.

Source code in TPTBox/core/np_utils.py

def np_point_coordinates(
    arr: UINTARRAY,
) -> list[tuple[int, int, int]]:
    """Extracts the coordinates of non-zero points from a 3D binary array.

    This function locates all non-zero voxels within a 3D binary array and returns
    their coordinates as a list of tuples.

    Args:
        arr (UINTARRAY): A 3-dimensional binary array representing the segmentation or mask.

    Returns:
        list[tuple[int, int, int]]: A list of (X, Y, Z) coordinate tuples for each non-zero
        point in the array.

    Raises:
        AssertionError: If the input array does not have three dimensions.
    """
    assert arr.ndim == 3, arr.ndim
    x, y, z = np.where(arr)
    surface_points = [(x[i], y[i], z[i]) for i in range(len(x))]
    return surface_points

np_connected_components ¶

np_connected_components(arr: UINTARRAY, label_ref: LABEL_REFERENCE | None = None, connectivity: int = 3, include_zero: bool = False) -> tuple[UINTARRAY, int]

Calculates the connected components of a given array (works with zeros as well!).

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	input arr	required
`connectivity`	`int`	in range [1,3]. For 2D images, 2 and 3 is the same.	`3`
`include_zero`	`bool`	If true, will treat the background (0) as another label to calculate connected components from. Significantly slower! Defaults to False.	`False`
`verbose`		If true, will print out if the array does not have any CC	required

Returns:

Name	Type	Description
`arr_cc`	`tuple[UINTARRAY, int]`	UINTARRAY, N: number of cc

Source code in TPTBox/core/np_utils.py

def np_connected_components(
    arr: UINTARRAY,
    label_ref: LABEL_REFERENCE | None = None,
    connectivity: int = 3,
    include_zero: bool = False,
) -> tuple[UINTARRAY, int]:
    """Calculates the connected components of a given array (works with zeros as well!).

    Args:
        arr: input arr
        connectivity: in range [1,3]. For 2D images, 2 and 3 is the same.
        include_zero (bool): If true, will treat the background (0) as another label to calculate connected components from. Significantly slower! Defaults to False.
        verbose: If true, will print out if the array does not have any CC

    Returns:
        arr_cc: UINTARRAY, N: number of cc
    """
    assert np.min(arr) == 0, f"min value of mask not zero, got {np.min(arr)}"
    assert np.max(arr) >= 0, f"wrong normalization, max value is not >= 0, got {np_unique(arr)}"
    assert 2 <= arr.ndim <= 3, f"expected 2D or 3D, but got {arr.ndim}"
    assert 1 <= connectivity <= 3, f"expected connectivity in [1,3], but got {connectivity}"
    connectivity = min((connectivity + 1) * 2, 8) if arr.ndim == 2 else 6 if connectivity == 1 else 18 if connectivity == 2 else 26

    labels: Sequence[int] = _to_labels(arr, label_ref)
    if include_zero:
        arr[arr == 0] = arr.max() + 1
    arr[np_isin(arr, labels, invert=True)] = 0
    cc_map, n = _connected_components(arr, connectivity=connectivity, return_N=True)
    return cc_map, n

np_connected_components_per_label ¶

np_connected_components_per_label(arr: UINTARRAY, connectivity: int = 3, label_ref: LABEL_REFERENCE = None, include_zero: bool = False) -> dict[int, UINTARRAY]

Calculates the connected components for each label in label_ref.

Returns a dictionary mapping each label to its connected-component mask. Supports zero labels when include_zero=True.

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	input arr	required
`connectivity`	`int`	in range [1,3]. For 2D images, 2 and 3 is the same.	`3`
`labels`	`int \| list[int] \| None`	Labels that the connected components algorithm should be applied to. If none, applies on all labels found in arr. Defaults to None.	required
`include_zero`	`bool`	If true, will treat the background (0) as another label to calculate connected components from. Significantly slower! Defaults to False.	`False`

Returns:

Name	Type	Description
`subreg_cc`	`dict[int, UINTARRAY]`	dict[label, cc_idx, arr], subreg_cc_N: dict[label, n_connected_components]

Source code in TPTBox/core/np_utils.py

def np_connected_components_per_label(
    arr: UINTARRAY,
    connectivity: int = 3,
    label_ref: LABEL_REFERENCE = None,
    include_zero: bool = False,
) -> dict[int, UINTARRAY]:
    """Calculates the connected components for each label in label_ref.

    Returns a dictionary mapping each label to its connected-component mask.
    Supports zero labels when ``include_zero=True``.

    Args:
        arr: input arr
        connectivity: in range [1,3]. For 2D images, 2 and 3 is the same.
        labels (int | list[int] | None, optional): Labels that the connected components algorithm should be applied to. If none, applies on all labels found in arr. Defaults to None.
        include_zero (bool): If true, will treat the background (0) as another label to calculate connected components from. Significantly slower! Defaults to False.

    Returns:
        subreg_cc: dict[label, cc_idx, arr], subreg_cc_N: dict[label, n_connected_components]
    """
    assert np.min(arr) == 0, f"min value of mask not zero, got {np.min(arr)}"
    assert np.max(arr) >= 0, f"wrong normalization, max value is not >= 0, got {np_unique(arr)}"
    assert 2 <= arr.ndim <= 3, f"expected 2D or 3D, but got {arr.ndim}"
    assert 1 <= connectivity <= 3, f"expected connectivity in [1,3], but got {connectivity}"
    connectivity = min((connectivity + 1) * 2, 8) if arr.ndim == 2 else 6 if connectivity == 1 else 18 if connectivity == 2 else 26

    present_labels = np_unique(arr)
    labels: Sequence[int] = present_labels if label_ref is None else [i for i in _to_labels(arr, label_ref) if i in present_labels]
    # if zero, map it to unused label
    if include_zero:
        zero_label = arr.max() + 1
        arr[arr == 0] = zero_label
        labels = list(labels)
        labels.append(0)
    # call connected components
    labels_out = _connected_components(arr, connectivity=connectivity, return_N=False)
    # if zero, map it back for assignment
    if include_zero:
        arr[arr == zero_label] = 0
    # assign the cc according to original label
    subreg_cc = {}
    for subreg in labels:  # type:ignore
        subreg_cc[subreg] = labels_out * (arr == subreg)

    return subreg_cc

np_filter_connected_components ¶

np_filter_connected_components(arr: UINTARRAY, largest_k_components: int | None = None, label_ref: LABEL_REFERENCE = None, connectivity: int = 3, return_original_labels: bool = True, min_volume: float = 0, max_volume: float | None = None, removed_to_label=0, k_larges_global=False) -> UINTARRAY

Finds the largest k connected components in a given array (does NOT work with zero as label!).

Parameters:

Name	Type	Description	Default
`arr`	`ndarray`	input array	required
`k`	`int \| None`	finds the k-largest components. If k is None, will find all connected components and still sort them by size	required
`labels`	`int \| list[int] \| None`	Labels that the algorithm should be applied to. If none, applies on all labels found in arr. Defaults to None.	required
`connectivity`	`int`	in range [1,3]. For 2D images, 2 and 3 is the same.	`3`
`return_original_labels`	`bool`	If set to False, will label the components from 1 to k. Defaults to True	`True`
`k_larges_global`	`bool`	If true largest_k_components is filterd over all labels instead of each lable individualy	`False`

Returns: np.ndarray: array with the largest k connected components

Source code in TPTBox/core/np_utils.py

def np_filter_connected_components(
    arr: UINTARRAY,
    largest_k_components: int | None = None,
    label_ref: LABEL_REFERENCE = None,
    connectivity: int = 3,
    return_original_labels: bool = True,
    min_volume: float = 0,
    max_volume: float | None = None,
    removed_to_label=0,
    k_larges_global=False,
) -> UINTARRAY:
    """Finds the largest k connected components in a given array (does NOT work with zero as label!).

    Args:
        arr (np.ndarray): input array
        k (int | None): finds the k-largest components. If k is None, will find all connected components and still sort them by size
        labels (int | list[int] | None, optional): Labels that the algorithm should be applied to. If none, applies on all labels found in arr. Defaults to None.
        connectivity: in range [1,3]. For 2D images, 2 and 3 is the same.
        return_original_labels (bool): If set to False, will label the components from 1 to k. Defaults to True
        k_larges_global(bool): If true largest_k_components is filterd over all labels instead of each lable individualy
    Returns:
        np.ndarray: array with the largest k connected components
    """
    assert largest_k_components is None or largest_k_components > 0
    assert 2 <= arr.ndim <= 3, f"expected 2D or 3D, but got {arr.ndim}"
    assert 1 <= connectivity <= 3, f"expected connectivity in [1,3], but got {connectivity}"
    if arr.ndim == 2:  # noqa: SIM108
        connectivity = min(connectivity * 2, 8)  # 1:4, 2:8, 3:8
    else:
        connectivity = 6 if connectivity == 1 else 18 if connectivity == 2 else 26

    arr2 = arr.copy()
    labels: Sequence[int] = _to_labels(arr, label_ref)
    arr2[np_isin(arr2, labels, invert=True)] = 0  # type:ignore

    labels_out, n = _connected_components(arr2, connectivity=connectivity, return_N=True)
    largest_k_components_org = largest_k_components
    if largest_k_components is None:
        largest_k_components = n
    assert largest_k_components is not None
    largest_k_components = min(largest_k_components, n)  # if k > N, will return all N but still sorted
    label_volume_pairs = [
        (i, vol) for i, vol in np_volume(labels_out).items() if vol >= min_volume and (max_volume is None or vol <= max_volume)
    ]
    largest_k_components = min(largest_k_components, len(label_volume_pairs))
    label_volume_pairs.sort(key=lambda x: x[1], reverse=True)

    if len(labels) == 1 or label_volume_pairs == largest_k_components or largest_k_components_org is None or k_larges_global:
        preserve: list[int] = [x[0] for x in label_volume_pairs[:largest_k_components]]
    else:
        counter = dict.fromkeys(labels, 0)
        preserve = []
        for preserve_label, _ in label_volume_pairs:
            idx = arr[labels_out == preserve_label].max()
            if counter.get(idx, largest_k_components + 1) <= largest_k_components_org:
                preserve.append(preserve_label)
                counter[idx] += 1
                # print("add perserve", idx)
            if counter.get(idx, largest_k_components + 1) == largest_k_components_org:
                del counter[idx]
                # print("del perserve", idx)
            if len(counter) == 0:
                break
    cc_out = np.zeros(arr.shape, dtype=arr.dtype)
    i = 1
    for preserve_label in preserve:
        cc_out[labels_out == preserve_label] = i
        i += 1

    if return_original_labels:
        arr *= cc_out > 0  # to get original labels
        if removed_to_label != 0:
            arr[np.logical_and(labels_out != 0, arr == 0)] = removed_to_label
        return arr
    if removed_to_label != 0:
        arr[np.logical_and(labels_out != 0, arr == 0)] = removed_to_label

    return cc_out

np_get_connected_components_center_of_mass ¶

np_get_connected_components_center_of_mass(arr: UINTARRAY, label: int, connectivity: int = 3, sort_by_axis: int | None = None) -> list[COORDINATE]

Calculates the center of mass of each connected component of a given label.

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	Input label array.	required
`label`	`int`	The label whose connected components are analysed.	required
`connectivity`	`int`	Connectivity for connected components in range [1, 3]. Defaults to 3.	`3`
`sort_by_axis`	`int \| None`	If not None, the returned list is sorted in ascending order of the coordinate along this axis. Defaults to None.	`None`

Returns:

Type	Description
`list[COORDINATE]`	list[COORDINATE]: List of (x, y, z) center-of-mass coordinates, one per connected component of `label`.

Source code in TPTBox/core/np_utils.py

def np_get_connected_components_center_of_mass(
    arr: UINTARRAY, label: int, connectivity: int = 3, sort_by_axis: int | None = None
) -> list[COORDINATE]:
    """Calculates the center of mass of each connected component of a given label.

    Args:
        arr (UINTARRAY): Input label array.
        label (int): The label whose connected components are analysed.
        connectivity (int, optional): Connectivity for connected components in range
            [1, 3]. Defaults to 3.
        sort_by_axis (int | None, optional): If not None, the returned list is sorted
            in ascending order of the coordinate along this axis. Defaults to None.

    Returns:
        list[COORDINATE]: List of (x, y, z) center-of-mass coordinates, one per
            connected component of ``label``.
    """
    # Per label argument true/false
    #
    if sort_by_axis is not None:
        assert 0 <= sort_by_axis <= len(arr.shape) - 1, f"sort_by_axis {sort_by_axis} invalid with an array of shape {arr.shape}"  # type:ignore
    subreg_cc = np_connected_components_per_label(
        arr.copy(),
        connectivity=connectivity,
        label_ref=label,
    )
    coms = list(np_center_of_mass(subreg_cc[label]).values()) if label in subreg_cc else []

    if sort_by_axis is not None:
        coms.sort(key=lambda a: a[sort_by_axis])
    return coms

np_translate_to_center_of_array ¶

np_translate_to_center_of_array(image: ndarray) -> np.ndarray

Moves the nonzero values of an array so its center of mass is in the center of the array shape.

Parameters:

Name	Type	Description	Default
`image`	`ndarray`	input array	required

Returns:

Type	Description
`ndarray`	np.ndarray: array of the same shape translated to the center

Source code in TPTBox/core/np_utils.py

def np_translate_to_center_of_array(image: np.ndarray) -> np.ndarray:
    """Moves the nonzero values of an array so its center of mass is in the center of the array shape.

    Args:
        image: input array

    Returns:
        np.ndarray: array of the same shape translated to the center
    """
    shape = image.shape
    shape_center = tuple(i // 2 for i in shape)
    com = center_of_mass(image)
    translation_vector: tuple[int, int] | tuple[int, int, int] = tuple(np.int32(np.asarray(shape_center) - np.asarray(com)))
    return np_translate_arr(image, translation_vector)

np_translate_arr ¶

np_translate_arr(arr: ndarray, translation_vector: tuple[int, int] | tuple[int, int, int]) -> np.ndarray

Translates values of an input array according to a 2D or 3D translation vector. Values that would be shifted beyond the boundary are removed!

Parameters:

Name	Type	Description	Default
`arr`	`ndarray`	input array	required
`translation_vector`	`tuple[int, int] \| tuple[int, int, int]`	vector to translated the array with (2D or 3D)	required

Returns:

Type	Description
`ndarray`	np.ndarray: the translated array

Examples:

>>> a = np.array([[0, 1, 0], [0, 2, 1], [1, 0, 0]])
>>> b = np_translate_arr(a, translation_vector=(1, 0))
>>> print(b)
>>> [[0 0 0],[0 1 0],[0 2 1]]

Source code in TPTBox/core/np_utils.py

def np_translate_arr(arr: np.ndarray, translation_vector: tuple[int, int] | tuple[int, int, int]) -> np.ndarray:
    """Translates values of an input array according to a 2D or 3D translation vector. Values that would be shifted beyond the boundary are removed!

    Args:
        arr: input array
        translation_vector: vector to translated the array with (2D or 3D)

    Returns:
        np.ndarray: the translated array

    Examples:
        >>> a = np.array([[0, 1, 0], [0, 2, 1], [1, 0, 0]])
        >>> b = np_translate_arr(a, translation_vector=(1, 0))
        >>> print(b)
        >>> [[0 0 0],[0 1 0],[0 2 1]]
    """
    assert 2 <= len(translation_vector) <= 3, f"expected translation vector to be 2D or 3D, but got {translation_vector}"
    assert len(arr.shape) == len(translation_vector), f"mismatch dimensions, got arr shape {arr.shape} and vector {translation_vector}"
    arr_translated = np.zeros_like(arr)
    if len(translation_vector) == 3:
        tx, ty, tz = translation_vector  # type:ignore
        H, W, D = arr.shape  # noqa: N806
        arr_translated[
            max(tx, 0) : H + min(tx, 0),
            max(ty, 0) : W + min(ty, 0),
            max(tz, 0) : D + min(tz, 0),
        ] = arr[
            -min(tx, 0) : H - max(tx, 0),
            -min(ty, 0) : W - max(ty, 0),
            -min(tz, 0) : D - max(tz, 0),
        ]
    else:
        tx, ty = translation_vector  # type:ignore
        H, W = arr.shape  # noqa: N806
        arr_translated[max(tx, 0) : H + min(tx, 0), max(ty, 0) : W + min(ty, 0)] = arr[
            -min(tx, 0) : H - max(tx, 0), -min(ty, 0) : W - max(ty, 0)
        ]
    return arr_translated

np_fill_holes ¶

np_fill_holes(arr: ndarray, label_ref: LABEL_REFERENCE = None, slice_wise_dim: int | None = None, use_crop: bool = True, pbar: bool = False) -> np.ndarray

Fills holes in segmentations.

Parameters:

Name	Type	Description	Default
`arr`	`ndarray`	Input segmentation array	required
`labels`	`int \| list[int] \| None`	Labels that the hole-filling should be applied to. If none, applies on all labels found in arr. Defaults to None.	required
`slice_wise_dim`	`int \| None`	If the input is 3D, the specified dimension here cna be used for 2D slice-wise filling. Defaults to None.	`None`

Returns:

Type	Description
`ndarray`	np.ndarray: The array with holes filled

Source code in TPTBox/core/np_utils.py

def np_fill_holes(
    arr: np.ndarray,
    label_ref: LABEL_REFERENCE = None,
    slice_wise_dim: int | None = None,
    use_crop: bool = True,
    pbar: bool = False,
) -> np.ndarray:
    """Fills holes in segmentations.

    Args:
        arr (np.ndarray): Input segmentation array
        labels (int | list[int] | None, optional): Labels that the hole-filling should be applied to. If none, applies on all labels found in arr. Defaults to None.
        slice_wise_dim (int | None, optional): If the input is 3D, the specified dimension here cna be used for 2D slice-wise filling. Defaults to None.

    Returns:
        np.ndarray: The array with holes filled
    """
    assert 2 <= arr.ndim <= 3
    assert arr.ndim == 3 or slice_wise_dim is None, "slice_wise_dim set but array is 3D"
    labels: Sequence[int] = _to_labels(arr, label_ref)

    if use_crop:
        gcrop = np_bbox_binary(arr, px_dist=1, raise_error=False)
        arrc = arr[gcrop]
    else:
        arrc = arr
    if pbar:
        from tqdm import tqdm

        labels = tqdm(labels, desc="fill_holes")  # type: ignore
    for l in labels:  # type:ignore
        arr_l = arrc == l
        # arr_l = np_extract_label(arr_l, l)
        if use_crop:
            crop = np_bbox_binary(arr_l, px_dist=1, raise_error=False)
            arr_lc = arr_l[crop]
        else:
            arr_lc = arr_l
        if slice_wise_dim is None:
            filled = _fill(arr_lc).astype(arr.dtype)
        else:
            assert 0 <= slice_wise_dim <= arr.ndim - 1, f"slice_wise_dim needs to be in range [0, {arr.ndim - 1}]"
            filled = np.swapaxes(arr_lc.copy(), 0, slice_wise_dim)
            filled = np.stack([_fill(x).astype(arr.dtype) for x in filled])
            filled = np.swapaxes(filled, 0, slice_wise_dim)
        filled[filled != 0] = l
        if use_crop:
            arrc[crop][arrc[crop] == 0] = filled[arrc[crop] == 0]
        else:
            arrc[arrc == 0] = filled[arrc == 0]

    if use_crop:
        arr[gcrop] = arrc
    else:
        arr = arrc
    return arr

np_smooth_gaussian_labelwise ¶

np_smooth_gaussian_labelwise(arr: UINTARRAY, label_to_smooth: list[int] | int, label_weights: dict[int, float] | None = None, sigma: float = 3.0, radius: int = 6, truncate: int = 4, boundary_mode: str = 'nearest', dilate_prior: int = 0, dilate_connectivity: int = 3, dilate_channelwise: bool = False, smooth_background: bool = True, background_threshold: float | None = None) -> UINTARRAY

Smooth selected labels in a segmentation mask using Gaussian filtering, leaving other labels unaffected.

Internal Description

Ensures label(s) to be smoothed are present in the segmentation.
Optionally dilates specified labels prior to smoothing (if dilate_prior > 0).
Iterates over each label:
- Creates a binary mask for that label.
- Applies Gaussian smoothing only if the label is in label_to_smooth.
- Optionally applies a weight from label_weights.
Adds background as a separate smoothed or fixed mask depending on smooth_background.
Stacks all label probability-like maps and computes a new segmentation by taking the argmax over the stacked array, i.e., the label with the highest value wins per voxel.
Replaces the indices in the argmax map with the original label values to preserve semantics.

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	Input Segmentation Mask Array	required
`label_to_smooth`	`list[int] \| int`	Which labels to smooth in the mask. Every other label will be untouched	required
`sigma`	`float`	Sigma of the gaussian blur. Defaults to 3.0.	`3.0`
`radius`	`int`	Radius of the gaussian blur. Defaults to 6.	`6`
`truncate`	`int`	Truncate of the gaussian blur. Defaults to 4.	`4`
`boundary_mode`	`str`	Boundary Mode of the gaussian blur. Defaults to "nearest".	`'nearest'`
`dilate_prior`	`int`	Dilate this many voxels before starting the gaussian blur algorithm. Defaults to 0.	`0`
`dilate_connectivity`	`int`	Connectivity of the dilation process, if applied. Defaults to 3.	`3`
`smooth_background`	`bool`	If true, will also smooth the background. If False, the background voxels stay the same and the segmentation cannot add voxels. Defaults to True.	`True`

Returns:

Name	Type	Description
`UINTARRAY`	`UINTARRAY`	The resulting smoothed array of the segmentation (with the same labels as the input)

Source code in TPTBox/core/np_utils.py

def np_smooth_gaussian_labelwise(
    arr: UINTARRAY,
    label_to_smooth: list[int] | int,
    label_weights: dict[int, float] | None = None,
    sigma: float = 3.0,
    radius: int = 6,
    truncate: int = 4,
    boundary_mode: str = "nearest",
    dilate_prior: int = 0,
    dilate_connectivity: int = 3,
    dilate_channelwise: bool = False,
    smooth_background: bool = True,
    background_threshold: float | None = None,
) -> UINTARRAY:
    """Smooth selected labels in a segmentation mask using Gaussian filtering, leaving other labels unaffected.

    Internal Description:
        1. Ensures label(s) to be smoothed are present in the segmentation.
        2. Optionally dilates specified labels prior to smoothing (if `dilate_prior > 0`).
        3. Iterates over each label:
            - Creates a binary mask for that label.
            - Applies Gaussian smoothing only if the label is in `label_to_smooth`.
            - Optionally applies a weight from `label_weights`.
        4. Adds background as a separate smoothed or fixed mask depending on `smooth_background`.
        5. Stacks all label probability-like maps and computes a new segmentation by taking the
           `argmax` over the stacked array, i.e., the label with the highest value wins per voxel.
        6. Replaces the indices in the argmax map with the original label values to preserve semantics.

    Args:
        arr (UINTARRAY): Input Segmentation Mask Array
        label_to_smooth (list[int] | int): Which labels to smooth in the mask. Every other label will be untouched
        sigma (float, optional): Sigma of the gaussian blur. Defaults to 3.0.
        radius (int, optional): Radius of the gaussian blur. Defaults to 6.
        truncate (int, optional): Truncate of the gaussian blur. Defaults to 4.
        boundary_mode (str, optional): Boundary Mode of the gaussian blur. Defaults to "nearest".
        dilate_prior (int, optional): Dilate this many voxels before starting the gaussian blur algorithm. Defaults to 0.
        dilate_connectivity (int, optional): Connectivity of the dilation process, if applied. Defaults to 3.
        smooth_background (bool, optional): If true, will also smooth the background. If False, the background voxels stay the same and the segmentation cannot add voxels. Defaults to True.

    Returns:
        UINTARRAY: The resulting smoothed array of the segmentation (with the same labels as the input)
    """
    if label_weights is None:
        label_weights = {}
    sem_labels = np_unique_withoutzero(arr)

    if isinstance(label_to_smooth, int):
        label_to_smooth = [label_to_smooth]

    if dilate_prior > 0 and not dilate_channelwise:
        arr = np_dilate_msk(
            arr,
            n_pixel=dilate_prior,
            label_ref=label_to_smooth,
            connectivity=dilate_connectivity,
        )

    smoothed_arrs = []
    sem_labels_plus_background = sem_labels.copy()
    sem_labels_plus_background.append(0)
    for l in sem_labels_plus_background[:-1]:
        arr_l = (arr == l).astype(float)
        if dilate_prior > 0 and dilate_channelwise:
            arr_l = np_dilate_msk(
                arr_l,
                n_pixel=dilate_prior,
                label_ref=1,
                connectivity=dilate_connectivity,
            )
        if l in label_to_smooth:
            arr_l = gaussian_filter(
                arr_l,
                sigma=sigma,
                mode=boundary_mode,
                truncate=truncate,
                radius=radius,
            )
        if l in label_weights:
            arr_l = np.multiply(arr_l, label_weights[l])
        smoothed_arrs.append(arr_l)

    # background
    arr_bg = np_extract_label(arr, label=0, inplace=False).astype(float)
    if smooth_background:
        arr_bg = gaussian_filter(
            arr_bg,
            sigma=sigma,
            mode=boundary_mode,
            truncate=truncate,
            radius=radius,
        )
    if 0 in label_weights:
        arr_bg = np.multiply(arr_bg, label_weights[0])
    smoothed_arrs.append(arr_bg)

    arr_stack = np.stack(smoothed_arrs)
    seg_arr_smoothed = np.argmax(arr_stack, axis=0)
    seg_arr_s = seg_arr_smoothed.copy()

    if background_threshold is not None:
        seg_arr_smoothed[seg_arr_smoothed < background_threshold] = len(sem_labels_plus_background) - 1  # background label

    for idx, l in enumerate(sem_labels_plus_background):
        seg_arr_s[seg_arr_smoothed == idx] = l

    return seg_arr_s

np_calc_convex_hull ¶

np_calc_convex_hull(arr: INTARRAY, axis: int | None = None, verbose: bool = False) -> INTARRAY

Calculates the convex hull of a given array and returns a filled binary mask.

Parameters:

Name	Type	Description	Default
`arr`	`INTARRAY`	Input integer array (non-zero voxels define the point set).	required
`axis`	`int \| None`	If given, computes the convex hull slice-by-slice along this axis (remaining dimensions must be at least 2D). If None, computes the hull over the full 2D or 3D volume. Defaults to None.	`None`
`verbose`	`bool`	If True, prints warnings for degenerate cases. Defaults to False.	`False`

Returns:

Name	Type	Description
`INTARRAY`	`INTARRAY`	Binary array of the same shape as `arr` with 1 inside the convex hull and 0 outside.

Source code in TPTBox/core/np_utils.py

def np_calc_convex_hull(
    arr: INTARRAY,
    axis: int | None = None,
    verbose: bool = False,
) -> INTARRAY:
    """Calculates the convex hull of a given array and returns a filled binary mask.

    Args:
        arr (INTARRAY): Input integer array (non-zero voxels define the point set).
        axis (int | None, optional): If given, computes the convex hull slice-by-slice
            along this axis (remaining dimensions must be at least 2D). If None,
            computes the hull over the full 2D or 3D volume. Defaults to None.
        verbose (bool, optional): If True, prints warnings for degenerate cases.
            Defaults to False.

    Returns:
        INTARRAY: Binary array of the same shape as ``arr`` with 1 inside the
            convex hull and 0 outside.
    """
    n_dims = arr.ndim
    if axis is None:
        assert 2 <= n_dims <= 3, f"If axis is none, array must be 2- or 3-dimensional, but got {n_dims} with shape {arr.shape}"
        return _convex_hull(arr, verbose=verbose)[0]
    else:
        assert 3 <= n_dims <= 4, f"If axis is given, the array must be 3- or 4-dimensional, but got {n_dims} with shape {arr.shape}"
        assert 0 <= axis <= n_dims, f"Specified axis must be in range of dimension, but got axis={axis} and n_dims={n_dims}"
        h = arr * 0
        for i in range(arr.shape[axis]):
            slices = _select_axis_dynamically(axis=axis, index=i, n_dims=n_dims)
            if np_is_empty(arr[slices]):
                continue
            try:
                convex_hull_slice = _convex_hull(arr[slices], verbose=verbose)[0].astype(arr.dtype)
                h[slices] += convex_hull_slice
            except Exception:
                pass
        return h

np_calc_boundary_mask ¶

np_calc_boundary_mask(img: ndarray, threshold: float = 0, adjust_intensity_for_ct=False) -> np.ndarray

Calculate a boundary mask based on the input image.

Parameters: - img (NII): The image used to create the boundary mask. - threshold(float): threshold - adjust_intensity_for_ct (bool): If True, adjust the image intensity by adding 1000.

Returns: NII: A segmentation of the boundary.

This function takes a NII and generates a boundary mask by marking specific regions. The intensity of the image can be adjusted for CT scans by adding 1000. The boundary mask is created by initializing corner points and using an "infect" process to mark neighboring points. The boundary mask is initiated with zeros, and specific boundary points are set to 1. The "infect" function iteratively marks neighboring points in the mask. The process starts from the initial points and corner points of the image. The infection process continues until the infect_list is empty. The resulting boundary mask is modified by subtracting 1 from all non-zero values and setting the remaining zeros to 2. The sum of the boundary mask values is printed before returning the modified NII object.

Source code in TPTBox/core/np_utils.py

def np_calc_boundary_mask(
    img: np.ndarray,
    threshold: float = 0,
    adjust_intensity_for_ct=False,
) -> np.ndarray:
    """Calculate a boundary mask based on the input image.

    Parameters:
    - img (NII): The image used to create the boundary mask.
    - threshold(float): threshold
    - adjust_intensity_for_ct (bool): If True, adjust the image intensity by adding 1000.

    Returns:
    NII: A segmentation of the boundary.


    This function takes a NII and generates a boundary mask by marking specific regions.
    The intensity of the image can be adjusted for CT scans by adding 1000. The boundary mask is created by initializing
    corner points and using an "infect" process to mark neighboring points. The boundary mask is initiated with
    zeros, and specific boundary points are set to 1. The "infect" function iteratively marks neighboring points in the mask.
    The process starts from the initial points and corner points of the image. The infection process continues until the
    infect_list is empty. The resulting boundary mask is modified by subtracting 1 from all non-zero values and setting
    the remaining zeros to 2. The sum of the boundary mask values is printed before returning the modified NII object.

    """
    if adjust_intensity_for_ct:
        img = img + 1000
    boundary = img.copy()
    boundary[boundary > threshold] = 2
    boundary[boundary <= threshold] = 0
    infect_list = []

    def infect(x, y, z):
        if any(
            [
                x < 0,
                y < 0,
                z < 0,
                x == boundary.shape[0],
                y == boundary.shape[1],
                z == boundary.shape[2],
            ]
        ):
            return
        if boundary[x, y, z] == 0:
            boundary[x, y, z] = 1
            for a, b, c in [
                (1, 0, 0),
                (-1, 0, 0),
                (0, 1, 0),
                (0, -1, 0),
                (0, 1, 0),
                (0, 0, 1),
                (0, 0, -1),
            ]:
                infect_list.append((x + a, y + b, z + c))

        else:
            pass

    infect(0, 0, 0)
    infect(boundary.shape[0] - 1, 0, 0)
    infect(0, boundary.shape[1] - 1, 0)
    infect(boundary.shape[0] - 1, boundary.shape[1] - 1, 0)

    infect(0, 0, boundary.shape[2] - 1)
    infect(boundary.shape[0] - 1, 0, boundary.shape[2] - 1)
    infect(0, boundary.shape[1] - 1, boundary.shape[2] - 1)
    infect(boundary.shape[0] - 1, boundary.shape[1] - 1, boundary.shape[2] - 1)
    while len(infect_list) != 0:
        infect(*infect_list.pop())
    boundary[boundary == 0] = 2
    boundary -= 1
    print(boundary.sum())
    return boundary

np_betti_numbers ¶

np_betti_numbers(img: ndarray, verbose=False) -> tuple[int, int, int]

Calculates the Betti numbers B0, B1, and B2 for a 3D binary image.

Uses the Euler characteristic to derive the counts from connected-component analysis of both the foreground (26-connected) and background (6-connected).

B0: Number of connected components. B1: Number of loops / handles (tunnels). B2: Number of fully enclosed voids.

Code prototyped by Martin Menten (Imperial College), Suprosanna Shit (TU Munich), and Johannes C. Paetzold (Imperial College). Source: https://github.com/CoWBenchmark/TopCoW_Eval_Metrics/blob/master/metric_functions.py

Parameters:

Name	Type	Description	Default
`img`	`ndarray`	3D binary array (values must be 0 or 1).	required
`verbose`	`bool`	If True, prints the Betti numbers. Defaults to False.	`False`

Returns:

Type	Description
`tuple[int, int, int]`	tuple[int, int, int]: `(B0, B1, B2)` — connected components, holes, and voids.

Source code in TPTBox/core/np_utils.py

def np_betti_numbers(img: np.ndarray, verbose=False) -> tuple[int, int, int]:
    """Calculates the Betti numbers B0, B1, and B2 for a 3D binary image.

    Uses the Euler characteristic to derive the counts from connected-component
    analysis of both the foreground (26-connected) and background (6-connected).

    B0: Number of connected components.
    B1: Number of loops / handles (tunnels).
    B2: Number of fully enclosed voids.

    Code prototyped by Martin Menten (Imperial College), Suprosanna Shit (TU Munich),
    and Johannes C. Paetzold (Imperial College).
    Source: https://github.com/CoWBenchmark/TopCoW_Eval_Metrics/blob/master/metric_functions.py

    Args:
        img (np.ndarray): 3D binary array (values must be 0 or 1).
        verbose (bool, optional): If True, prints the Betti numbers. Defaults to False.

    Returns:
        tuple[int, int, int]: ``(B0, B1, B2)`` — connected components, holes, and voids.
    """
    # make sure the image is 3D (for connectivity settings)
    assert len(img.shape) == 3
    # 6 or 26 neighborhoods are defined for 3D images,
    # (connectivity 1 and 3, respectively)
    # If foreground is 26-connected, then background is 6-connected, and conversely
    N6 = 1  # noqa: N806
    N26 = 3  # noqa: N806
    # important first step is to
    # pad the image with background (0) around the border!
    padded = np.pad(img, pad_width=1)
    # make sure the image is binary with
    assert set(np_unique(padded)).issubset({0, 1})
    # calculate the Betti numbers B0, B2
    # then use Euler characteristic to get B1
    # get the label connected regions for foreground
    _, b0 = _label(padded, return_num=True, connectivity=N26)  # 26 neighborhoods for foreground
    euler_char_num = _euler_number(padded, connectivity=N26)  # 26 neighborhoods for foreground
    # get the label connected regions for background
    _, b2 = _label(1 - padded, return_num=True, connectivity=N6)  # 6 neighborhoods for background
    # NOTE: need to subtract 1 from b2
    b2 -= 1
    b1 = b0 + b2 - euler_char_num  # Euler number = Betti:0 - Betti:1 + Betti:2
    if verbose:
        print(f"Betti number: b0 = {b0}, b1 = {b1}, b2 = {b2}")
    return b0, b1, b2

np_calc_overlapping_labels ¶

np_calc_overlapping_labels(reference_arr: ndarray, prediction_arr: ndarray) -> list[tuple[int, int]]

Calculates the pairs of labels that are overlapping in at least one voxel (fast).

Parameters:

Name	Type	Description	Default
`prediction_arr`	`ndarray`	Numpy array containing the prediction labels.	required
`reference_arr`	`ndarray`	Numpy array containing the reference labels.	required
`ref_labels`	`list[int]`	List of unique reference labels.	required

Returns:

Type	Description
`list[tuple[int, int]]`	list[tuple[int, int]]: List of tuples of labels that overlap in at least one voxel

Source code in TPTBox/core/np_utils.py

def np_calc_overlapping_labels(
    reference_arr: np.ndarray,
    prediction_arr: np.ndarray,
) -> list[tuple[int, int]]:
    """Calculates the pairs of labels that are overlapping in at least one voxel (fast).

    Args:
        prediction_arr (np.ndarray): Numpy array containing the prediction labels.
        reference_arr (np.ndarray): Numpy array containing the reference labels.
        ref_labels (list[int]): List of unique reference labels.

    Returns:
        list[tuple[int, int]]: List of tuples of labels that overlap in at least one voxel
    """
    ref_labels = np_unique_withoutzero(reference_arr)
    overlap_arr = prediction_arr.astype(np.uint32)
    max_ref = max(ref_labels) + 1
    overlap_arr = (overlap_arr * max_ref) + reference_arr
    overlap_arr[reference_arr == 0] = 0
    # overlapping_indices = [(i % (max_ref), i // (max_ref)) for i in np.unique(overlap_arr) if i > max_ref]
    # instance_pairs = [(reference_arr, prediction_arr, i, j) for i, j in overlapping_indices]

    # (ref, pred)
    return [(int(i % (max_ref)), int(i // (max_ref))) for i in np_unique(overlap_arr) if i > max_ref]

np_normalize_to_range ¶

np_normalize_to_range(arr: ndarray, min_value: float = 0, max_value: float = 1500) -> np.ndarray

Normalize array values so the minimum maps to min_value and the maximum is capped at max_value.

Parameters:

Name	Type	Description	Default
`arr`	`ndarray`	Input array to normalize. Modified in-place.	required
`min_value`	`float`	Target minimum value after shift. Defaults to 0.	`0`
`max_value`	`float`	Upper bound; if the original maximum exceeds this, values are scaled down proportionally. Defaults to 1500.	`1500`

Returns:

Type	Description
`ndarray`	np.ndarray: The normalized array (same object as input, modified in-place).

Source code in TPTBox/core/np_utils.py

def np_normalize_to_range(arr: np.ndarray, min_value: float = 0, max_value: float = 1500) -> np.ndarray:
    """Normalize array values so the minimum maps to ``min_value`` and the maximum is capped at ``max_value``.

    Args:
        arr (np.ndarray): Input array to normalize. Modified in-place.
        min_value (float, optional): Target minimum value after shift. Defaults to 0.
        max_value (float, optional): Upper bound; if the original maximum exceeds
            this, values are scaled down proportionally. Defaults to 1500.

    Returns:
        np.ndarray: The normalized array (same object as input, modified in-place).
    """
    mi, ma = arr.min(), arr.max()
    arr += -mi + min_value  # min = 0
    max_value2 = ma
    self_dtype = arr.dtype
    if max_value2 > max_value:
        arr *= max_value / max_value2
        arr = arr.astype(self_dtype)
    return arr

np_fill_holes_global_with_majority_voting ¶

np_fill_holes_global_with_majority_voting(arr: UINTARRAY, connectivity: int = 3, inplace: bool = False, verbose=False) -> UINTARRAY

Fill holes globaly (across labels) and resolves inter-label conflicts with majority voting of neighbors.

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	input array	required
`connectivity`	`int`	connectivity of connected components of the holes. Defaults to 3.	`3`
`inplace`	`bool`	Defaults to False.	`False`

Returns:

Name	Type	Description
`arr`	`UINTARRAY`	Array with all global holes filled

Source code in TPTBox/core/np_utils.py

def np_fill_holes_global_with_majority_voting(arr: UINTARRAY, connectivity: int = 3, inplace: bool = False, verbose=False) -> UINTARRAY:  # noqa: ARG001
    """Fill holes globaly (across labels) and resolves inter-label conflicts with majority voting of neighbors.

    Args:
        arr (UINTARRAY): input array
        connectivity (int, optional): connectivity of connected components of the holes. Defaults to 3.
        inplace (bool, optional): Defaults to False.

    Returns:
        arr: Array with all global holes filled
    """
    arr_c = arr if inplace else arr.copy()
    # Fill simple holes
    arr_c = np_fill_holes(arr_c)
    # Make binary mask
    seg_nii_bin = arr_c.copy()
    seg_nii_bin[seg_nii_bin != 0] = 1
    seg_nii_bin_fh = np_fill_holes(seg_nii_bin.copy())
    # Only proceed if there were holes filled
    if np_volume(seg_nii_bin_fh)[1] > np_volume(seg_nii_bin)[1]:
        # go for each fill holed CC
        seg_nii_bin_fh[seg_nii_bin == 1] = 0
        cc_msk, _ = np_connected_components(seg_nii_bin_fh, connectivity=connectivity)
        # delete voxels that are already labeled
        cc_msk[seg_nii_bin != 0] = 0
        seg_nii_new = np_map_labels_based_on_majority_label_mask_overlap(
            cc_msk,
            label_mask=arr_c,
            dilate_pixel=1,
            inplace=False,
        )
        arr_c[seg_nii_new != 0] = seg_nii_new[seg_nii_new != 0]
    return arr_c

np_map_labels_based_on_majority_label_mask_overlap ¶

np_map_labels_based_on_majority_label_mask_overlap(arr: UINTARRAY, label_mask: ndarray, label_ref: LABEL_REFERENCE = None, dilate_pixel: int = 1, inplace: bool = False, no_match_label=0) -> UINTARRAY

Relabels all individual labels from input array to the majority labels of a given label_mask.

Parameters:

Name	Type	Description	Default
`arr`	`UINTARRAY`	input array to be relabeled	required
`label_mask`	`ndarray`	the mask from which to pull the target labels.	required
`labels`	`int \| list[int] \| None`	Which labels in the input to process. Defaults to None.	required
`dilate_pixel`	`int`	If true, will dilate the input to calculate the overlap. Defaults to 1.	`1`
`inplace`	`bool`	Defaults to False.	`False`

Returns:

Name	Type	Description
`arr`	`UINTARRAY`	input array with all labels in labels relabeled

Source code in TPTBox/core/np_utils.py

def np_map_labels_based_on_majority_label_mask_overlap(
    arr: UINTARRAY,
    label_mask: np.ndarray,
    label_ref: LABEL_REFERENCE = None,
    dilate_pixel: int = 1,
    inplace: bool = False,
    no_match_label=0,
) -> UINTARRAY:
    """Relabels all individual labels from input array to the majority labels of a given label_mask.

    Args:
        arr (UINTARRAY): input array to be relabeled
        label_mask (np.ndarray): the mask from which to pull the target labels.
        labels (int | list[int] | None, optional): Which labels in the input to process. Defaults to None.
        dilate_pixel (int, optional): If true, will dilate the input to calculate the overlap. Defaults to 1.
        inplace (bool, optional): Defaults to False.

    Returns:
        arr: input array with all labels in labels relabeled
    """
    arr_cc = arr if inplace else arr.copy()

    labels = _to_labels(arr, label_ref)

    label_list: list[int] = [label for label in np_unique(arr) if label in labels]

    for label in label_list:
        arr_l = np_extract_label(arr, label, inplace=False)
        arr_ld = np_dilate_msk(arr_l.copy(), n_pixel=dilate_pixel, label_ref=1, connectivity=3) if dilate_pixel > 0 else arr_l
        # crop speed up by factor 6
        crop = np_bbox_binary(arr_ld, px_dist=0, raise_error=False)

        mult = label_mask[crop] * arr_ld[crop]
        label_ref, count = np.unique(mult, return_counts=True)
        if 0 in label_ref:
            label_ref = label_ref[1:]
            count = count[1:]
        try:
            new_label = label_ref[np.argmax(count)]
        except ValueError:  # should never happen if called from np_fill_holes_global_with_majority_voting
            new_label = no_match_label
        arr_cc[arr_l != 0] = new_label
    return arr_cc