Skip to content

cellects.image.filters

cellects.image.filters

2-D image filters with Numba-accelerated helper kernels.

This module provides 2-D grayscale image filtering functions for sharpening, smoothing, edge detection, median filtering, Hessian-based vesselness, and masked filtering. Public functions accept integer or floating-point images and return NumPy arrays.

The filters include classical linear filters, scale-space tubeness and vesselness filters, a frequency-domain Butterworth filter, and helper functions for masked Sato or Frangi filtering.

Functions:

Name Description
sharpen_filter : Apply a 3x3 sharpen kernel.
mexican_hat_filter : Apply a 5x5 Mexican-hat kernel.
gaussian_filter : Apply Gaussian smoothing.
butterworth_filter : Apply a Butterworth filter.
farid_filter : Compute Farid edge magnitude.
hessian_filter : Compute a Hessian vesselness response.
laplace_filter : Apply Laplacian convolution.
median_filter : Apply median filtering.
meijering_filter : Compute a Meijering vesselness response.
prewitt_filter : Compute Prewitt edge magnitude.
roberts_filter : Compute Roberts edge magnitude.
scharr_filter : Compute Scharr edge magnitude.
sobel_filter : Compute Sobel edge magnitude.
sato_filter : Apply the Sato tubeness filter.
frangi_filter : Apply the Frangi vesselness filter.
masked_vessel_filters : Apply Sato or Frangi inside a mask.
Notes

Boundary handling is specific to each filter. Some functions use Numba-compiled loops for per-pixel Hessian and mask reflection work.

butterworth_filter(image, cutoff_frequency_ratio=0.005, high_pass=False, order=2.0, squared_butterworth=True, npad=0, preserve_range=False)

Summary

Apply a Butterworth low-pass or high-pass filter to a 2-D image.

Extended Description

The filter is applied in the frequency domain. Integer input is converted to float64 without range scaling. preserve_range is accepted for interface compatibility but does not affect this function.

Parameters:

Name Type Description Default
image array_like

2-D grayscale image.

required
cutoff_frequency_ratio float

Cutoff ratio relative to each image dimension. Must be greater than 0.0 and less than or equal to 0.5.

0.005
high_pass bool

If True, apply a high-pass response; if False, apply a low-pass response.

False
order float

Butterworth filter order.

2.0
squared_butterworth bool

If True, use the squared Butterworth response; if False, use the square-root response.

True
npad int

Number of edge pixels to pad before filtering and crop after filtering.

0
preserve_range bool

Accepted for compatibility; this function does not change behavior.

False

Returns:

Type Description
ndarray of float64

Filtered image with the same shape as image.

Raises:

Type Description
ValueError

If cutoff_frequency_ratio is not in (0.0, 0.5], if order is not positive, if npad is negative, or if image is not a 2-D array.

Examples:

>>> result = butterworth_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8))
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
def butterworth_filter(image, cutoff_frequency_ratio=0.005, high_pass=False, order=2.0, squared_butterworth=True, npad=0, preserve_range=False):
    """
    Summary
    -------
    Apply a Butterworth low-pass or high-pass filter to a 2-D image.

    Extended Description
    --------------------
    The filter is applied in the frequency domain. Integer input is
    converted to `float64` without range scaling. `preserve_range` is
    accepted for interface compatibility but does not affect this function.

    Parameters
    ----------
    image : array_like
        2-D grayscale image.
    cutoff_frequency_ratio : float
        Cutoff ratio relative to each image dimension. Must be greater than
        0.0 and less than or equal to 0.5.
    high_pass : bool
        If ``True``, apply a high-pass response; if ``False``, apply a
        low-pass response.
    order : float
        Butterworth filter order.
    squared_butterworth : bool
        If ``True``, use the squared Butterworth response; if ``False``, use
        the square-root response.
    npad : int
        Number of edge pixels to pad before filtering and crop after
        filtering.
    preserve_range : bool
        Accepted for compatibility; this function does not change behavior.

    Returns
    -------
    ndarray of float64
        Filtered image with the same shape as `image`.

    Raises
    ------
    ValueError
        If `cutoff_frequency_ratio` is not in (0.0, 0.5], if `order` is
        not positive, if `npad` is negative, or if `image` is not a 2-D
        array.

    Examples
    --------
    >>> result = butterworth_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8))
    >>> print(result.shape)
    # (2, 2)
    """

    image = _float_image(image)
    cutoff_frequency_ratio = float(cutoff_frequency_ratio)
    order = float(order)
    npad = int(npad)

    if cutoff_frequency_ratio <= 0 or cutoff_frequency_ratio > 0.5:
        raise ValueError("cutoff_frequency_ratio must be in (0, 0.5].")
    if order <= 0:
        raise ValueError("order must be positive.")
    if npad < 0:
        raise ValueError("npad must be >= 0.")

    if npad:
        crop = (slice(npad, -npad), slice(npad, -npad))
        image = np.pad(image, npad, mode="edge")
    else:
        crop = None

    h, w = image.shape

    fy = np.arange(-(h - 1) // 2, (h - 1) // 2 + 1, dtype=np.float64) / (h * cutoff_frequency_ratio)
    fx = np.arange(-(w - 1) // 2, (w - 1) // 2 + 1, dtype=np.float64) / (w * cutoff_frequency_ratio)

    fy = np.fft.ifftshift(fy * fy)
    fx = np.fft.ifftshift(fx * fx)

    q2 = (fy[:, None] + fx[None, :]) ** order

    if high_pass:
        response = q2 / (1.0 + q2)
    else:
        response = 1.0 / (1.0 + q2)

    if not squared_butterworth:
        response = np.sqrt(response)

    result = np.fft.irfftn(
        np.fft.rfftn(image) * response[:, :w // 2 + 1],
        s=image.shape,
        axes=(0, 1),
    )

    if crop is not None:
        result = result[crop]

    return np.ascontiguousarray(result, dtype=np.float64)

farid_filter(image, mode='reflect', cval=0.0)

Summary

Compute Farid edge magnitude for a 2-D image.

Parameters:

Name Type Description Default
image array_like

2-D grayscale image.

required
mode str

Boundary mode used for convolution.

'reflect'
cval float

Constant value used for boundary extension.

0.0

Returns:

Type Description
ndarray of float64

Edge magnitude with the same shape as image.

Raises:

Type Description
ValueError

If image is not a 2-D array.

Notes

Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is scaled by the largest absolute endpoint. The two directional responses are combined and divided by sqrt(2).

Examples:

>>> result = farid_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8))
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
def farid_filter(image, mode="reflect", cval=0.0):
    """
    Summary
    -------
    Compute Farid edge magnitude for a 2-D image.

    Parameters
    ----------
    image : array_like
        2-D grayscale image.
    mode : str
        Boundary mode used for convolution.
    cval : float
        Constant value used for boundary extension.

    Returns
    -------
    ndarray of float64
        Edge magnitude with the same shape as `image`.

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

    Notes
    -----
    Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is
    scaled by the largest absolute endpoint. The two directional responses
    are combined and divided by sqrt(2).

    Examples
    --------
    >>> result = farid_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8))
    >>> print(result.shape)
    # (2, 2)
    """
    return _edge_filter(image, _FARID_E, _FARID_S, mode, cval)

frangi_filter(greyscale_image, sigmas)

Summary

Apply the 2-D Frangi vesselness filter.

Parameters:

Name Type Description Default
greyscale_image ndarray

2-D grayscale image. Integer and floating-point images are accepted.

required
sigmas list[float]

Positive Gaussian scales in pixel units.

required

Returns:

Type Description
ndarray of float64

Floating-point Frangi response in [0.0, 1.0] with the same shape as greyscale_image.

Raises:

Type Description
ValueError

If greyscale_image is not a 2-D array. If sigmas is not a non-empty 1-D sequence. If any value in sigmas is not positive.

Notes

The filter targets dark tubular structures and uses "reflect" image boundary handling. It matches the scikit-image 0.26.0 2-D formulation with black ridges. The structuredness parameter is chosen automatically from the largest Hessian norm of the first scale.

Examples:

>>> image = [[0.0, 1.0, 1.0, 0.0]]
>>> sigmas = [1.0, 2.0]
>>> result = frangi_filter(image, sigmas)
>>> print(result.shape)
(1, 4)
Source code in src/cellects/image/filters.py
def frangi_filter(greyscale_image, sigmas):
    """Summary
    -------
    Apply the 2-D Frangi vesselness filter.

    Parameters
    ----------
    greyscale_image : ndarray
        2-D grayscale image. Integer and floating-point images are accepted.
    sigmas : list[float]
        Positive Gaussian scales in pixel units.

    Returns
    -------
    ndarray of float64
        Floating-point Frangi response in `[0.0, 1.0]` with the same
        shape as `greyscale_image`.

    Raises
    ------
    ValueError
        If `greyscale_image` is not a 2-D array.
        If `sigmas` is not a non-empty 1-D sequence.
        If any value in `sigmas` is not positive.

    Notes
    -----
    The filter targets dark tubular structures and uses `"reflect"` image
    boundary handling. It matches the scikit-image 0.26.0 2-D formulation
    with black ridges. The structuredness parameter is chosen automatically
    from the largest Hessian norm of the first scale.

    Examples
    --------
    >>> image = [[0.0, 1.0, 1.0, 0.0]]
    >>> sigmas = [1.0, 2.0]
    >>> result = frangi_filter(image, sigmas)
    >>> print(result.shape)
    (1, 4)
    """
    image = np.asarray(greyscale_image)

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

    sigmas = np.asarray(sigmas, dtype=np.float64)

    if sigmas.ndim != 1 or sigmas.size == 0:
        raise ValueError("sigmas must be a non-empty 1-D sequence.")

    if np.any(sigmas <= 0):
        raise ValueError("all sigmas must be positive.")

    image = image.astype(np.float64, copy=False)

    alpha = 0.5
    beta = 0.5

    result = np.zeros_like(image, dtype=np.float64)

    gamma = None

    for sigma in sigmas:
        hrr, hrc, hcc = _hessian(image, sigma, mode="reflect")

        eig0, eig1 = _hessian_eigenvalues_2d(hrr, hrc, hcc)

        if gamma is None:
            s = np.sqrt(eig0 * eig0 + eig1 * eig1)

            gamma = 0.5 * np.max(s)

            if gamma == 0.0:
                gamma = 1.0

        response = _frangi_response(eig0, eig1, alpha, beta, gamma)

        np.maximum(result, response, out=result)

    return result

gaussian_filter(image, sigma=1.0, preserve_range=False, mode='nearest', cval=0.0, truncate=4.0)

Summary

Apply Gaussian smoothing to a 2-D image.

Extended Description

When preserve_range is False, unsigned integer input is scaled to [0.0, 1.0], signed integer input is scaled by the largest absolute endpoint, and floating-point input is unchanged. When preserve_range is True, integer input is converted to float64 without range scaling.

Parameters:

Name Type Description Default
image array_like

2-D grayscale image.

required
sigma float

Gaussian standard deviation.

1.0
preserve_range bool

If True, integer input is not rescaled; if False, integer input is rescaled before filtering.

False
mode str

Boundary mode passed to the Gaussian filter.

'nearest'
cval float

Constant value used for boundary extension.

0.0
truncate float

Gaussian kernel truncation parameter.

4.0

Returns:

Type Description
ndarray of float64

Smoothed image with the same shape as image.

Raises:

Type Description
ValueError

If image is not a 2-D array.

Examples:

>>> result = gaussian_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8), 1.0)
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
def gaussian_filter(image, sigma=1.0, preserve_range=False, mode="nearest", cval=0.0, truncate=4.0):
    """
    Summary
    -------
    Apply Gaussian smoothing to a 2-D image.

    Extended Description
    --------------------
    When `preserve_range` is ``False``, unsigned integer input is scaled to
    [0.0, 1.0], signed integer input is scaled by the largest absolute
    endpoint, and floating-point input is unchanged. When `preserve_range`
    is ``True``, integer input is converted to `float64` without range
    scaling.

    Parameters
    ----------
    image : array_like
        2-D grayscale image.
    sigma : float
        Gaussian standard deviation.
    preserve_range : bool
        If ``True``, integer input is not rescaled; if ``False``, integer
        input is rescaled before filtering.
    mode : str
        Boundary mode passed to the Gaussian filter.
    cval : float
        Constant value used for boundary extension.
    truncate : float
        Gaussian kernel truncation parameter.

    Returns
    -------
    ndarray of float64
        Smoothed image with the same shape as `image`.

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

    Examples
    --------
    >>> result = gaussian_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8), 1.0)
    >>> print(result.shape)
    # (2, 2)
    """
    image = _float_image(image) if preserve_range else _image01(image)
    return np.ascontiguousarray(
        ndimage.gaussian_filter(image, sigma=sigma, mode=mode, cval=cval, truncate=truncate),
        dtype=np.float64,
    )

hessian_filter(image, sigmas=(1, 3, 5), alpha=0.5, beta=0.5, gamma=15.0, black_ridges=True)

Summary

Compute a Hessian-based vesselness response over multiple scales.

Extended Description

For black_ridges=``True``, dark linear structures produce positive responses. Forblack_ridges=False, the input is negated before filtering so that bright structures are detected. Responses are combined by taking the maximum over sigmas. Locations with no positive response are set to 1.0.

Parameters:

Name Type Description Default
image array_like

2-D grayscale image.

required
sigmas float or sequence[float]

Positive Gaussian scales.

(1, 3, 5)
alpha float

Accepted for compatibility; this parameter has no effect in this 2-D implementation.

0.5
beta float

Smoothing parameter for the ridge/blob ratio term.

0.5
gamma float

Structuredness threshold.

15.0
black_ridges bool

If True, filter dark ridges; if False, filter bright ridges.

True

Returns:

Type Description
ndarray of float64

Vesselness-like response with the same shape as image. Vessel locations contain values in [0.0, 1.0], and background locations are 1.0.

Raises:

Type Description
ValueError

If image is not a 2-D array or if sigmas is invalid.

Notes

Uses a Numba-compiled helper for per-pixel eigenvalue computation.

Examples:

>>> result = hessian_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8), [1.0])
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
def hessian_filter(image, sigmas=(1, 3, 5), alpha=0.5, beta=0.5, gamma=15.0, black_ridges=True):
    """
    Summary
    -------
    Compute a Hessian-based vesselness response over multiple scales.

    Extended Description
    --------------------
    For `black_ridges=``True``, dark linear structures produce positive
    responses. For `black_ridges=``False``, the input is negated before
    filtering so that bright structures are detected. Responses are combined
    by taking the maximum over `sigmas`. Locations with no positive response
    are set to 1.0.

    Parameters
    ----------
    image : array_like
        2-D grayscale image.
    sigmas : float or sequence[float]
        Positive Gaussian scales.
    alpha : float
        Accepted for compatibility; this parameter has no effect in this
        2-D implementation.
    beta : float
        Smoothing parameter for the ridge/blob ratio term.
    gamma : float
        Structuredness threshold.
    black_ridges : bool
        If ``True``, filter dark ridges; if ``False``, filter bright ridges.

    Returns
    -------
    ndarray of float64
        Vesselness-like response with the same shape as `image`. Vessel
        locations contain values in [0.0, 1.0], and background locations are
        1.0.

    Raises
    ------
    ValueError
        If `image` is not a 2-D array or if `sigmas` is invalid.

    Notes
    -----
    Uses a Numba-compiled helper for per-pixel eigenvalue computation.

    Examples
    --------
    >>> result = hessian_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8), [1.0])
    >>> print(result.shape)
    # (2, 2)
    """

    image = _float_image(image)

    if not black_ridges:
        image = -image

    sigmas = _sigmas(sigmas)
    result = np.zeros_like(image)

    for sigma in sigmas:
        hrr, hrc, hcc = _hessian(image, sigma)
        e0, e1 = _hessian_eigenvalues_2d(hrr, hrc, hcc)

        if np.all(np.abs(e0) < np.abs(e1)):
            e0, e1 = e1, e0

        # Sort by absolute eigenvalue per pixel.
        a = np.abs(e0) <= np.abs(e1)
        lambda1 = np.where(a, e0, e1)
        lambda2 = np.where(a, e1, e0)

        lambda2 = np.maximum(lambda2, 1e-10)
        rb = np.abs(lambda1) / lambda2
        s2 = e0 * e0 + e1 * e1

        response = np.exp(-(rb * rb) / (2.0 * beta * beta))
        response *= 1.0 - np.exp(-s2 / (2.0 * gamma * gamma))

        if black_ridges:
            response[lambda2 <= 0] = 0.0
        else:
            response[lambda2 >= 0] = 0.0

        np.maximum(result, response, out=result)

    result[result <= 0] = 1.0
    return result

laplace_filter(image, ksize=3)

Summary

Apply Laplacian convolution to a 2-D image.

Parameters:

Name Type Description Default
image array_like

2-D grayscale image.

required
ksize int

Odd convolution kernel size.

3

Returns:

Type Description
ndarray of float64

Laplacian response with the same shape as image.

Raises:

Type Description
ValueError

If image is not a 2-D array or if ksize is not a positive odd integer.

Notes

ksize=3 uses the standard 3x3 Laplacian. Larger odd values use a cross-shaped kernel. Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is scaled by the largest absolute endpoint.

Examples:

>>> result = laplace_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8))
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
def laplace_filter(image, ksize=3):
    """
    Summary
    -------
    Apply Laplacian convolution to a 2-D image.

    Parameters
    ----------
    image : array_like
        2-D grayscale image.
    ksize : int
        Odd convolution kernel size.

    Returns
    -------
    ndarray of float64
        Laplacian response with the same shape as `image`.

    Raises
    ------
    ValueError
        If `image` is not a 2-D array or if `ksize` is not a positive odd
        integer.

    Notes
    -----
    `ksize=3` uses the standard 3x3 Laplacian. Larger odd values use a
    cross-shaped kernel. Unsigned integer input is scaled to [0.0, 1.0];
    signed integer input is scaled by the largest absolute endpoint.

    Examples
    --------
    >>> result = laplace_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8))
    >>> print(result.shape)
    # (2, 2)
    """

    image = _image01(image)
    ksize = int(ksize)

    if ksize <= 0 or ksize % 2 == 0:
        raise ValueError("ksize must be a positive odd integer.")

    if ksize == 3:
        kernel = np.array([
            [0.0, 1.0, 0.0],
            [1.0, -4.0, 1.0],
            [0.0, 1.0, 0.0],
        ])
    else:
        kernel = np.zeros((ksize, ksize), dtype=np.float64)
        c = ksize // 2
        kernel[c, :] = 1.0
        kernel[:, c] = 1.0
        kernel[c, c] = -2.0 * (ksize - 1)

    return np.ascontiguousarray(
        ndimage.convolve(image, kernel, mode="reflect"),
        dtype=np.float64,
    )

masked_vessel_filters(greyscale_image, filter_name, sigmas, mask_bool)

Summary

Apply a Sato or Frangi vesselness filter inside a 2-D mask.

Parameters:

Name Type Description Default
greyscale_image ndarray

2-D grayscale image. Integer and floating-point images are accepted.

required
filter_name str

Filter to apply. Must be "Frangi" or "Sato".

required
sigmas list[float]

Positive Gaussian scales in pixel units.

required
mask_bool ndarray of bool

2-D binary mask. True pixels define the filtering domain.

required

Returns:

Type Description
ndarray of float64

Floating-point vesselness response with the same shape as greyscale_image. Values outside mask_bool are 0.0.

Raises:

Type Description
ValueError

If greyscale_image is not a 2-D array. If mask_bool is not a 2-D array. If greyscale_image and mask_bool do not have identical shapes. If filter_name is not "Frangi" or "Sato". If sigmas is not a non-empty 1-D sequence. If any value in sigmas is not positive. If mask_bool contains no True pixels.

Notes

Image borders use reflective boundary handling. The mask boundary is extended by reflection before computing the Gaussian Hessian. Repeated reflections are used for concave or thin mask regions. The reflection mapping uses Numba-compiled helpers for performance.

Examples:

>>> image = [[0.0, 1.0, 1.0, 0.0]]
>>> mask = [[False, True, True, False]]
>>> result = masked_vessel_filters(image, "Frangi", [1.0, 2.0], mask)
>>> print(result.shape)
(1, 4)
>>> print(result[0, 0])
0.0
Source code in src/cellects/image/filters.py
def masked_vessel_filters(greyscale_image, filter_name, sigmas, mask_bool):
    """Summary
    -------
    Apply a Sato or Frangi vesselness filter inside a 2-D mask.

    Parameters
    ----------
    greyscale_image : ndarray
        2-D grayscale image. Integer and floating-point images are accepted.
    filter_name : str
        Filter to apply. Must be `"Frangi"` or `"Sato"`.
    sigmas : list[float]
        Positive Gaussian scales in pixel units.
    mask_bool : ndarray of bool
        2-D binary mask. `True` pixels define the filtering domain.

    Returns
    -------
    ndarray of float64
        Floating-point vesselness response with the same shape as
        `greyscale_image`. Values outside `mask_bool` are `0.0`.

    Raises
    ------
    ValueError
        If `greyscale_image` is not a 2-D array.
        If `mask_bool` is not a 2-D array.
        If `greyscale_image` and `mask_bool` do not have identical shapes.
        If `filter_name` is not `"Frangi"` or `"Sato"`.
        If `sigmas` is not a non-empty 1-D sequence.
        If any value in `sigmas` is not positive.
        If `mask_bool` contains no `True` pixels.

    Notes
    -----
    Image borders use reflective boundary handling. The mask boundary is
    extended by reflection before computing the Gaussian Hessian. Repeated
    reflections are used for concave or thin mask regions. The reflection
    mapping uses Numba-compiled helpers for performance.

    Examples
    --------
    >>> image = [[0.0, 1.0, 1.0, 0.0]]
    >>> mask = [[False, True, True, False]]
    >>> result = masked_vessel_filters(image, "Frangi", [1.0, 2.0], mask)
    >>> print(result.shape)
    (1, 4)
    >>> print(result[0, 0])
    0.0
    """
    image = np.asarray(greyscale_image)
    mask_bool = np.asarray(mask_bool)

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

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

    if image.shape != mask_bool.shape:
        raise ValueError("greyscale_image and mask must have identical shapes.")

    if filter_name not in ("Frangi", "Sato"):
        raise ValueError('filter_name must be either "Frangi" or "Sato".')

    sigmas = np.asarray(sigmas, dtype=np.float64)

    if sigmas.ndim != 1 or sigmas.size == 0:
        raise ValueError("sigmas must be a non-empty 1-D sequence.")

    if np.any(sigmas <= 0):
        raise ValueError("all sigmas must be positive.")

    if not np.any(mask_bool):
        raise ValueError("mask contains no non-zero pixels.")

    image_float = image.astype(np.float64, copy=False)

    if np.any(sigmas <= 1.0):
        truncate = 100.0
    else:
        truncate = 8.0

    radius = np.ceil(truncate * float(np.max(sigmas)))

    extended = _reflect_mask_image(image_float, mask_bool, radius)

    if filter_name == "Frangi":
        result = frangi_filter(extended, sigmas)
    else:
        result = sato_filter(extended, sigmas)

    result[~mask_bool] = 0.0

    return result

median_filter(image, footprint=None, mode='nearest', cval=0.0)

Summary

Apply median filtering to a 2-D image.

Parameters:

Name Type Description Default
image array_like

2-D grayscale image.

required
footprint ndarray of bool or None

Median filter footprint. If None, a 3x3 all-True footprint is used.

None
mode str

Boundary mode passed to the median filter.

'nearest'
cval float

Constant value used for boundary extension.

0.0

Returns:

Type Description
ndarray

Median-filtered image with the same shape as image. The returned dtype follows the input dtype and the underlying median filter.

Raises:

Type Description
ValueError

If image is not a 2-D array.

Examples:

>>> result = median_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8))
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
def median_filter(image, footprint=None, mode="nearest", cval=0.0):
    """
    Summary
    -------
    Apply median filtering to a 2-D image.

    Parameters
    ----------
    image : array_like
        2-D grayscale image.
    footprint : ndarray of bool or None
        Median filter footprint. If ``None``, a 3x3 all-`True` footprint is
        used.
    mode : str
        Boundary mode passed to the median filter.
    cval : float
        Constant value used for boundary extension.

    Returns
    -------
    ndarray
        Median-filtered image with the same shape as `image`. The returned
        dtype follows the input dtype and the underlying median filter.

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

    Examples
    --------
    >>> result = median_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8))
    >>> print(result.shape)
    # (2, 2)
    """
    image = np.asarray(image)

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

    if footprint is None:
        footprint = np.ones((3, 3), dtype=bool)

    return ndimage.median_filter(
        image,
        footprint=np.asarray(footprint, dtype=bool),
        mode=mode,
        cval=float(cval),
    )

meijering_filter(image, sigmas=(1, 3, 5), alpha=None, black_ridges=True)

Summary

Compute a Meijering vesselness response over multiple scales.

Extended Description

For black_ridges=``True``, dark linear structures produce positive responses. Forblack_ridges=False, the input is negated before filtering so that bright structures are detected. Each scale response is normalized by its maximum before combining scales by maximum.

Parameters:

Name Type Description Default
image array_like

2-D grayscale image.

required
sigmas float or sequence[float]

Positive Gaussian scales.

(1, 3, 5)
alpha float or None

Meijering weighting parameter. If None, 1.0/3.0 is used.

None
black_ridges bool

If True, filter dark ridges; if False, filter bright ridges.

True

Returns:

Type Description
ndarray of float64

Vesselness response in [0.0, 1.0] with the same shape as image.

Raises:

Type Description
ValueError

If image is not a 2-D array or if sigmas is invalid.

Examples:

>>> result = meijering_filter([[0.0, 1.0], [1.0, 0.0]], [1.0])
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
def meijering_filter(image, sigmas=(1, 3, 5), alpha=None, black_ridges=True):
    """
    Summary
    -------
    Compute a Meijering vesselness response over multiple scales.

    Extended Description
    --------------------
    For `black_ridges=``True``, dark linear structures produce positive
    responses. For `black_ridges=``False``, the input is negated before
    filtering so that bright structures are detected. Each scale response is
    normalized by its maximum before combining scales by maximum.

    Parameters
    ----------
    image : array_like
        2-D grayscale image.
    sigmas : float or sequence[float]
        Positive Gaussian scales.
    alpha : float or None
        Meijering weighting parameter. If ``None``, `1.0/3.0` is used.
    black_ridges : bool
        If ``True``, filter dark ridges; if ``False``, filter bright ridges.

    Returns
    -------
    ndarray of float64
        Vesselness response in [0.0, 1.0] with the same shape as `image`.

    Raises
    ------
    ValueError
        If `image` is not a 2-D array or if `sigmas` is invalid.

    Examples
    --------
    >>> result = meijering_filter([[0.0, 1.0], [1.0, 0.0]], [1.0])
    >>> print(result.shape)
    # (2, 2)
    """
    image = _float_image(image)

    if not black_ridges:
        image = -image

    sigmas = _sigmas(sigmas)

    if alpha is None:
        alpha = 1.0 / 3.0

    result = np.zeros_like(image)

    for sigma in sigmas:
        hrr, hrc, hcc = _hessian(image, sigma)
        e0, e1 = _hessian_eigenvalues_2d(hrr, hrc, hcc)

        a = e0 + alpha * e1
        b = alpha * e0 + e1

        response = np.where(
            np.abs(a) >= np.abs(b),
            a,
            b,
        )

        response = np.maximum(response, 0.0)

        maximum = response.max()
        if maximum > 0:
            response /= maximum

        np.maximum(result, response, out=result)

    return result

prewitt_filter(image, mode='reflect', cval=0.0)

Summary

Compute Prewitt edge magnitude for a 2-D image.

Parameters:

Name Type Description Default
image array_like

2-D grayscale image.

required
mode str

Boundary mode used for convolution.

'reflect'
cval float

Constant value used for boundary extension.

0.0

Returns:

Type Description
ndarray of float64

Edge magnitude with the same shape as image.

Raises:

Type Description
ValueError

If image is not a 2-D array.

Notes

Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is scaled by the largest absolute endpoint. The two directional responses are combined and divided by sqrt(2).

Examples:

>>> result = prewitt_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8)
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
def prewitt_filter(image, mode="reflect", cval=0.0):
    """
    Summary
    -------
    Compute Prewitt edge magnitude for a 2-D image.

    Parameters
    ----------
    image : array_like
        2-D grayscale image.
    mode : str
        Boundary mode used for convolution.
    cval : float
        Constant value used for boundary extension.

    Returns
    -------
    ndarray of float64
        Edge magnitude with the same shape as `image`.

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

    Notes
    -----
    Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is
    scaled by the largest absolute endpoint. The two directional responses
    are combined and divided by sqrt(2).

    Examples
    --------
    >>> result = prewitt_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8)
    >>> print(result.shape)
    # (2, 2)
    """
    return _edge_filter(image, _PREWITT_E, _PREWITT_S, mode, cval)

roberts_filter(image, mode='reflect', cval=0.0)

Summary

Compute Roberts edge magnitude for a 2-D image.

Parameters:

Name Type Description Default
image array_like

2-D grayscale image.

required
mode str

Boundary mode used for convolution.

'reflect'
cval float

Constant value used for boundary extension.

0.0

Returns:

Type Description
ndarray of float64

Edge magnitude with the same shape as image.

Raises:

Type Description
ValueError

If image is not a 2-D array.

Notes

Uses two 2x2 diagonal difference kernels. Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is scaled by the largest absolute endpoint. The two directional responses are combined and divided by sqrt(2).

Examples:

>>> result = roberts_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8)
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
def roberts_filter(image, mode="reflect", cval=0.0):
    """
    Summary
    -------
    Compute Roberts edge magnitude for a 2-D image.

    Parameters
    ----------
    image : array_like
        2-D grayscale image.
    mode : str
        Boundary mode used for convolution.
    cval : float
        Constant value used for boundary extension.

    Returns
    -------
    ndarray of float64
        Edge magnitude with the same shape as `image`.

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

    Notes
    -----
    Uses two 2x2 diagonal difference kernels. Unsigned integer input is
    scaled to [0.0, 1.0]; signed integer input is scaled by the largest
    absolute endpoint. The two directional responses are combined and divided
    by sqrt(2).

    Examples
    --------
    >>> result = roberts_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8)
    >>> print(result.shape)
    # (2, 2)
    """
    image = _image01(image)

    a = ndimage.convolve(image, _ROBERTS_A, mode=mode, cval=float(cval))
    b = ndimage.convolve(image, _ROBERTS_B, mode=mode, cval=float(cval))

    return np.ascontiguousarray(
        np.sqrt(a * a + b * b) / math.sqrt(2.0),
        dtype=np.float64,
    )

sato_filter(greyscale_image, sigmas)

Summary

Apply the 2-D Sato tubeness filter.

Parameters:

Name Type Description Default
greyscale_image ndarray

2-D grayscale image. Integer and floating-point images are accepted.

required
sigmas list[float]

Positive Gaussian scales in pixel units.

required

Returns:

Type Description
ndarray of float64

Floating-point Sato response with the same shape as greyscale_image.

Raises:

Type Description
ValueError

If greyscale_image is not a 2-D array. If sigmas is not a non-empty 1-D sequence. If any value in sigmas is not positive.

Notes

The filter targets dark tubular structures and uses "reflect" image boundary handling. It matches the scikit-image 0.26.0 2-D formulation with black ridges. The per-pixel helper computations use Numba-compiled functions for performance.

Examples:

>>> image = [[0.0, 1.0, 1.0, 0.0]]
>>> sigmas = [1.0, 2.0]
>>> result = sato_filter(image, sigmas)
>>> print(result.shape)
(1, 4)
Source code in src/cellects/image/filters.py
def sato_filter(greyscale_image, sigmas):
    """Summary
    -------
    Apply the 2-D Sato tubeness filter.

    Parameters
    ----------
    greyscale_image : ndarray
        2-D grayscale image. Integer and floating-point images are accepted.
    sigmas : list[float]
        Positive Gaussian scales in pixel units.

    Returns
    -------
    ndarray of float64
        Floating-point Sato response with the same shape as
        `greyscale_image`.

    Raises
    ------
    ValueError
        If `greyscale_image` is not a 2-D array.
        If `sigmas` is not a non-empty 1-D sequence.
        If any value in `sigmas` is not positive.

    Notes
    -----
    The filter targets dark tubular structures and uses `"reflect"` image
    boundary handling. It matches the scikit-image 0.26.0 2-D formulation
    with black ridges. The per-pixel helper computations use Numba-compiled
    functions for performance.

    Examples
    --------
    >>> image = [[0.0, 1.0, 1.0, 0.0]]
    >>> sigmas = [1.0, 2.0]
    >>> result = sato_filter(image, sigmas)
    >>> print(result.shape)
    (1, 4)
    """
    image = np.asarray(greyscale_image)

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

    sigmas = np.asarray(sigmas, dtype=np.float64)

    if sigmas.ndim != 1 or sigmas.size == 0:
        raise ValueError("sigmas must be a non-empty 1-D sequence.")

    if np.any(sigmas <= 0):
        raise ValueError("all sigmas must be positive.")

    image = image.astype(np.float64, copy=False)

    result = np.zeros_like(image)

    for sigma in sigmas:
        hrr, hrc, hcc = _hessian(image, sigma, mode="reflect")
        eig0, _ = _hessian_eigenvalues_2d(hrr, hrc, hcc)
        response = _sato_response(eig0, sigma)
        np.maximum(result, response, out=result)

    return result

scharr_filter(image, mode='reflect', cval=0.0)

Summary

Compute Scharr edge magnitude for a 2-D image.

Parameters:

Name Type Description Default
image array_like

2-D grayscale image.

required
mode str

Boundary mode used for convolution.

'reflect'
cval float

Constant value used for boundary extension.

0.0

Returns:

Type Description
ndarray of float64

Edge magnitude with the same shape as image.

Raises:

Type Description
ValueError

If image is not a 2-D array.

Notes

Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is scaled by the largest absolute endpoint. The two directional responses are combined and divided by sqrt(2).

Examples:

>>> result = scharr_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8)
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
def scharr_filter(image, mode="reflect", cval=0.0):
    """
    Summary
    -------
    Compute Scharr edge magnitude for a 2-D image.

    Parameters
    ----------
    image : array_like
        2-D grayscale image.
    mode : str
        Boundary mode used for convolution.
    cval : float
        Constant value used for boundary extension.

    Returns
    -------
    ndarray of float64
        Edge magnitude with the same shape as `image`.

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

    Notes
    -----
    Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is
    scaled by the largest absolute endpoint. The two directional responses
    are combined and divided by sqrt(2).

    Examples
    --------
    >>> result = scharr_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8)
    >>> print(result.shape)
    # (2, 2)
    """
    return _edge_filter(image, _SCHARR_E, _SCHARR_S, mode, cval)

sobel_filter(image, mode='reflect', cval=0.0)

Summary

Compute Sobel edge magnitude for a 2-D image.

Parameters:

Name Type Description Default
image array_like

2-D grayscale image.

required
mode str

Boundary mode used for convolution.

'reflect'
cval float

Constant value used for boundary extension.

0.0

Returns:

Type Description
ndarray of float64

Edge magnitude with the same shape as image.

Raises:

Type Description
ValueError

If image is not a 2-D array.

Notes

Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is scaled by the largest absolute endpoint. The two directional responses are combined and divided by sqrt(2).

Examples:

>>> result = sobel_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8)
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
def sobel_filter(image, mode="reflect", cval=0.0):
    """
    Summary
    -------
    Compute Sobel edge magnitude for a 2-D image.

    Parameters
    ----------
    image : array_like
        2-D grayscale image.
    mode : str
        Boundary mode used for convolution.
    cval : float
        Constant value used for boundary extension.

    Returns
    -------
    ndarray of float64
        Edge magnitude with the same shape as `image`.

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

    Notes
    -----
    Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is
    scaled by the largest absolute endpoint. The two directional responses
    are combined and divided by sqrt(2).

    Examples
    --------
    >>> result = sobel_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8)
    >>> print(result.shape)
    # (2, 2)
    """
    return _edge_filter(image, _SOBEL_E, _SOBEL_S, mode, cval)