Skip to content

cellects.image.skeletonize

cellects.image.skeletonize

Medial-axis and Lee skeletonization for 2-D and 3-D binary images.

This module provides two public algorithms:

  • medial_axis computes the 2-D medial axis from a binary image.
  • skeletonize computes a Lee skeleton of a 2-D or 3-D binary image.

Both functions accept array-like binary images. Nonzero values are treated as foreground, and returned arrays use boolean dtype.

Functions:

Name Description
medial_axis : Compute a 2-D medial axis and optional distance transform.
skeletonize : Compute a Lee skeleton of a 2-D or 3-D binary image.
Notes

The medial-axis implementation targets scikit-image 0.26.0 with mask=None and rng=0. The Lee implementation targets scikit-image 0.26.0's Lee method. Numba-compiled helpers are used for inner loops.

medial_axis(image, return_distance=False)

Summary

Compute the 2-D medial axis of a binary image.

Extended Description

The medial axis is obtained by deleting foreground pixels whose removal does not change local connectivity and whose 3x3 neighborhood contains at least three foreground pixels. Pixels are visited in order of increasing distance to background, then cornerness, then a fixed random tie-breaker.

Parameters:

Name Type Description Default
image array_like

2-D binary image. Nonzero values are foreground.

required
return_distance bool

If True, also return the Euclidean distance transform. The default is False.

False

Returns:

Name Type Description
skeleton ndarray of bool

Medial axis with the same shape as image.

distance ndarray of float64

Euclidean distance transform of image. This object is returned only when return_distance is True. When return_distance is False, only skeleton is returned.

Raises:

Type Description
ValueError

If image is not a 2-D array.

Notes

This implementation targets scikit-image 0.26.0 with mask=None and rng=0. The random tie-breaker is deterministic because the random generator is seeded with 0. Numba-compiled helpers are used for the corner score and deletion loop.

Examples:

>>> skeleton, distance = medial_axis(image, return_distance=True)
>>> skeleton = medial_axis(image)
>>> print(skeleton.shape)
# (3, 5)
Source code in src/cellects/image/skeletonize.py
def medial_axis(image, return_distance=False):
    """
    Summary
    -------
    Compute the 2-D medial axis of a binary image.

    Extended Description
    --------------------
    The medial axis is obtained by deleting foreground pixels whose removal
    does not change local connectivity and whose 3x3 neighborhood contains
    at least three foreground pixels. Pixels are visited in order of
    increasing distance to background, then cornerness, then a fixed random
    tie-breaker.

    Parameters
    ----------
    image : array_like
        2-D binary image. Nonzero values are foreground.
    return_distance : bool
        If ``True``, also return the Euclidean distance transform.
        The default is ``False``.

    Returns
    -------
    skeleton : ndarray of bool
        Medial axis with the same shape as `image`.
    distance : ndarray of float64
        Euclidean distance transform of `image`. This object is returned
        only when `return_distance` is ``True``. When `return_distance`
        is ``False``, only `skeleton` is returned.

    Raises
    ------
    ValueError
        If `image` is not a 2-D array.

    Notes
    -----
    This implementation targets scikit-image 0.26.0 with ``mask=None``
    and ``rng=0``. The random tie-breaker is deterministic because the
    random generator is seeded with 0. Numba-compiled helpers are used for
    the corner score and deletion loop.

    Examples
    --------
    >>> skeleton, distance = medial_axis(image, return_distance=True)
    >>> skeleton = medial_axis(image)
    >>> print(skeleton.shape)
    # (3, 5)
    """
    image = np.asarray(image)

    if image.ndim != 2:
        raise ValueError("image must be a 2-D array")

    image = np.ascontiguousarray(
        image.astype(bool, copy=False)
    )

    distance_full = distance_transform_edt(image)

    if not image.any():
        result = np.zeros_like(image, dtype=bool)

        if return_distance:
            return result, distance_full

        return result

    corner_score = _ma_corner_score(image)

    ii, jj = np.nonzero(image)

    ii = np.ascontiguousarray(ii, dtype=np.intp)
    jj = np.ascontiguousarray(jj, dtype=np.intp)

    distance = np.ascontiguousarray(
        distance_full[image],
        dtype=np.float64,
    )

    n = ii.size

    # Fixed compatibility target: rng=0.
    rng = np.random.default_rng(0)

    tiebreaker = rng.permutation(
        np.arange(n)
    )

    # Primary: distance
    # Secondary: cornerness
    # Tertiary: random tiebreaker
    order = np.lexsort(
        (
            tiebreaker,
            corner_score[image],
            distance,
        )
    )

    order = np.ascontiguousarray(
        order,
        dtype=np.intp,
    )

    result = np.ascontiguousarray(
        image,
        dtype=np.uint8,
    )

    _ma_skeletonize_loop(
        result,
        ii,
        jj,
        order,
        _MEDIAL_AXIS_TABLE,
    )

    result = result.astype(bool)

    if return_distance:
        return result, distance_full

    return result

skeletonize(image)

Summary

Skeletonize a 2-D or 3-D binary image using Lee thinning.

Extended Description

2-D images are promoted to a one-voxel-thick 3-D volume before thinning. The input is padded with a one-voxel zero border, thinned, and the padding is removed before the result is returned.

Parameters:

Name Type Description Default
image array_like

2-D or 3-D binary image. Nonzero values are foreground.

required

Returns:

Type Description
ndarray of bool

Lee skeleton with the same shape as image.

Raises:

Type Description
ValueError

If image has fewer than 2 dimensions or more than 3 dimensions.

Notes

This implementation targets scikit-image 0.26.0's Lee method. It uses Numba-compiled loops for directional sweeps, endpoint tests, Euler invariance tests, and N(v)-labeling simple-point tests.

Examples:

>>> image2d = [[0, 1, 1, 0], [0, 1, 1, 0], [0, 0, 0, 0]]
>>> skeleton = skeletonize(image2d)
>>> print(skeleton.shape)
# (3, 4)
>>> image3d = [
>>>     [[0, 1, 0], [0, 1, 0], [0, 0, 0]],
>>>     [[0, 1, 0], [0, 1, 0], [0, 0, 0]],
>>>     [[0, 0, 0], [0, 0, 0], [0, 0, 0]]]
>>> skeleton = skeletonize(image3d)
>>> print(skeleton.shape)
# (3, 3, 3)
Source code in src/cellects/image/skeletonize.py
def skeletonize(image):
    """
    Summary
    -------
    Skeletonize a 2-D or 3-D binary image using Lee thinning.

    Extended Description
    --------------------
    2-D images are promoted to a one-voxel-thick 3-D volume before
    thinning. The input is padded with a one-voxel zero border, thinned,
    and the padding is removed before the result is returned.

    Parameters
    ----------
    image : array_like
        2-D or 3-D binary image. Nonzero values are foreground.

    Returns
    -------
    ndarray of bool
        Lee skeleton with the same shape as `image`.

    Raises
    ------
    ValueError
        If `image` has fewer than 2 dimensions or more than 3 dimensions.

    Notes
    -----
    This implementation targets scikit-image 0.26.0's Lee method. It uses
    Numba-compiled loops for directional sweeps, endpoint tests, Euler
    invariance tests, and N(v)-labeling simple-point tests.

    Examples
    --------
    >>> image2d = [[0, 1, 1, 0], [0, 1, 1, 0], [0, 0, 0, 0]]
    >>> skeleton = skeletonize(image2d)
    >>> print(skeleton.shape)
    # (3, 4)

    >>> image3d = [
    >>>     [[0, 1, 0], [0, 1, 0], [0, 0, 0]],
    >>>     [[0, 1, 0], [0, 1, 0], [0, 0, 0]],
    >>>     [[0, 0, 0], [0, 0, 0], [0, 0, 0]]]
    >>> skeleton = skeletonize(image3d)
    >>> print(skeleton.shape)
    # (3, 3, 3)
    """
    image = np.asarray(image)

    if image.ndim < 2 or image.ndim > 3:
        raise ValueError(
            "skeletonize can only handle 2D or 3D images; "
            f"got image.ndim = {image.ndim} instead."
        )

    image = np.ascontiguousarray(
        image.astype(bool, copy=False)
    )

    was_2d = image.ndim == 2

    if was_2d:
        image = image[np.newaxis, ...]

    image = np.pad(
        image,
        pad_width=1,
        mode="constant",
    )

    image = np.ascontiguousarray(
        image,
        dtype=np.uint8,
    )

    result = _lee_compute_thin_image(image)

    result = result[
        1:-1,
        1:-1,
        1:-1,
    ]

    if was_2d:
        result = result[0]

    return result.astype(bool)