scikit-ops 0.1.0.dev0__py3-none-any.whl

skop/ops/edges.py

@@ -0,0 +1,382 @@
+"""Derivative filters: edges, ridges, and the sharpening they enable.
+
+Where :mod:`skop.ops.smooth` averages a neighborhood, everything here
+*differences* one. The first group -- :func:`sobel` and its relatives -- are
+first-derivative operators, and answer "how fast is intensity changing here",
+which is large at a boundary and near zero inside an object. They differ only
+in the small kernel they use to estimate that derivative, and the differences
+between them matter mainly on noisy or anisotropic data.
+
+The second group works on the second derivative, which is what separates a
+*ridge* -- a line, a filament, a vessel -- from a step edge. :func:`frangi`
+and friends examine the Hessian's eigenvalues over a range of scales, so they
+respond to structures of a given thickness rather than to contrast alone.
+scikit-image's fourth ridge filter, ``hessian``, is deliberately not wrapped:
+it is ``frangi`` with every non-positive response replaced by 1, so the
+background comes back reading as a maximal detection, and nothing sensible
+happens when a front end hands that to a threshold.
+
+:func:`unsharp_mask` is the third thing derivatives are good for: adding an
+image's own detail back to it.
+
+Every op takes an image and returns a response map of the same shape, as
+float32 -- these are filters, and their output is meant to be thresholded or
+fed onward, not read as intensities. A trailing RGB(A) axis is filtered
+channel by channel.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import numpy as np
+
+from opspec.op import Axes, op
+from opspec.types import ImageOf
+
+from ._util import channel_axis, per_channel, to_gray
+
+#: An op happy with any number of axes, RGB(A) handled channel by channel.
+_Image = Annotated[ImageOf[np.ndarray], Axes(variadic=True)]
+
+#: An op that only knows about planes, with or without colour.
+_Plane = Annotated[ImageOf[np.ndarray], Axes("y", "x", "c?")]
+
+#: An op that handles a plane or a volume, and nothing else.
+_Volume = Annotated[ImageOf[np.ndarray], Axes("z?", "y", "x")]
+
+
+def _sigmas(sigma_min: float, sigma_max: float, sigma_step: float) -> np.ndarray:
+    """The scales a ridge filter sweeps, from three numbers a GUI can offer."""
+    if sigma_step <= 0:
+        raise ValueError(f"sigma_step must be positive, got {sigma_step}")
+    if sigma_max < sigma_min:
+        raise ValueError(f"sigma_max {sigma_max} is below sigma_min {sigma_min}")
+    return np.arange(sigma_min, sigma_max + sigma_step / 2, sigma_step)
+
+
+def _apply(image: np.ndarray, fn) -> np.ndarray:
+    return per_channel(np.asarray(image, dtype=np.float32), fn).astype(np.float32)
+
+
+@op(env="skimage")
+def sobel(image: _Image) -> ImageOf[np.ndarray]:
+    """Find edges with the Sobel operator.
+
+    A central difference along each axis, smoothed across the others, with
+    the per-axis responses combined into one magnitude. The default edge
+    filter, and the one to reach for absent a reason not to: it is cheap,
+    and the smoothing built into its kernel makes it far steadier on noisy
+    data than a bare difference.
+
+    Args:
+        image: Image to filter. Any number of axes; a trailing RGB(A) axis is
+            filtered channel by channel.
+
+    Returns:
+        Edge magnitude, as float32.
+    """
+    from skimage import filters
+
+    return _apply(image, filters.sobel)
+
+
+@op(env="skimage")
+def scharr(image: _Image) -> ImageOf[np.ndarray]:
+    """Find edges with the Scharr operator.
+
+    Sobel's kernel, with the weights rebalanced so that the operator's
+    response is as close to rotationally symmetric as a 3x3 kernel can be. A
+    diagonal edge therefore reads at the same strength as an axis-aligned
+    one, which matters when the magnitude is going to be compared against a
+    threshold or an orientation read off it.
+
+    Args:
+        image: Image to filter. Any number of axes; a trailing RGB(A) axis is
+            filtered channel by channel.
+
+    Returns:
+        Edge magnitude, as float32.
+    """
+    from skimage import filters
+
+    return _apply(image, filters.scharr)
+
+
+@op(env="skimage")
+def prewitt(image: _Image) -> ImageOf[np.ndarray]:
+    """Find edges with the Prewitt operator.
+
+    Sobel without the extra weight on the centre row: the smoothing across
+    the perpendicular axis is a plain box mean rather than a triangular one.
+    Marginally cheaper, marginally noisier, and included because a good deal
+    of older literature specifies it.
+
+    Args:
+        image: Image to filter. Any number of axes; a trailing RGB(A) axis is
+            filtered channel by channel.
+
+    Returns:
+        Edge magnitude, as float32.
+    """
+    from skimage import filters
+
+    return _apply(image, filters.prewitt)
+
+
+@op(env="skimage")
+def farid(image: _Plane) -> ImageOf[np.ndarray]:
+    """Find edges with the Farid-Simoncelli operator.
+
+    A larger kernel, fitted so that the derivative it computes is as accurate
+    as possible rather than merely symmetric. Worth its extra cost when the
+    gradient's *value* is being used -- for orientation, or optical flow --
+    rather than just thresholded.
+
+    Args:
+        image: Image to filter, as a plane with an optional RGB(A) axis.
+
+    Returns:
+        Edge magnitude, as float32.
+    """
+    from skimage import filters
+
+    return _apply(image, filters.farid)
+
+
+@op(env="skimage")
+def roberts(image: _Plane) -> ImageOf[np.ndarray]:
+    """Find edges with the Roberts cross operator.
+
+    The smallest edge filter there is: two 2x2 diagonal differences. It
+    localizes an edge to within a pixel, which no larger kernel does, and it
+    has no noise rejection whatsoever -- so it belongs on clean, high
+    contrast images and nowhere else.
+
+    Args:
+        image: Image to filter, as a plane. A trailing RGB(A) axis is
+            filtered channel by channel.
+
+    Returns:
+        Edge magnitude, as float32.
+    """
+    from skimage import filters
+
+    return _apply(image, filters.roberts)
+
+
+@op(env="skimage")
+def laplace(image: _Image, ksize: int = 3) -> ImageOf[np.ndarray]:
+    """Find edges with the Laplacian, the sum of the second derivatives.
+
+    Unlike the gradient filters, this is not directional: it responds to
+    curvature, so it peaks on *either* side of an edge and crosses zero at
+    the edge itself. Those zero crossings, not the peaks, are the edge --
+    which is why the Laplacian is usually a step toward something else
+    rather than an answer. It amplifies noise sharply; smooth first.
+
+    Args:
+        image: Image to filter. Any number of axes; a trailing RGB(A) axis is
+            filtered channel by channel.
+        ksize: Width of the discrete Laplacian kernel, in pixels.
+
+    Returns:
+        The Laplacian, as float32. Signed, unlike the gradient filters.
+    """
+    from skimage import filters
+
+    return _apply(image, lambda plane: filters.laplace(plane, ksize=ksize))
+
+
+@op(env="skimage")
+def difference_of_gaussians(
+    image: _Image,
+    low_sigma: float = 1.0,
+    high_sigma: float = 4.0,
+) -> ImageOf[np.ndarray]:
+    """Band-pass an image, by subtracting one Gaussian blur from another.
+
+    Blurring at two scales and taking the difference keeps exactly the
+    structure that falls between them: finer detail is in both blurs and
+    cancels, coarser shading is in neither. That makes this the standard way
+    to find blobs of a known size, and equally the standard way to flatten
+    uneven illumination while keeping the objects.
+
+    Args:
+        image: Image to filter. Any number of axes; a trailing RGB(A) axis is
+            filtered channel by channel.
+        low_sigma: Standard deviation of the finer blur, in pixels. Sets the
+            smallest detail kept.
+        high_sigma: Standard deviation of the coarser blur, in pixels. Sets
+            the largest. Must exceed ``low_sigma``.
+
+    Returns:
+        The band-passed image, as float32. Signed.
+    """
+    from skimage import filters
+
+    if high_sigma <= low_sigma:
+        raise ValueError(f"high_sigma {high_sigma} must exceed low_sigma {low_sigma}")
+    filtered = filters.difference_of_gaussians(
+        np.asarray(image, dtype=np.float32),
+        low_sigma=low_sigma,
+        high_sigma=high_sigma,
+        channel_axis=channel_axis(image),
+    )
+    return filtered.astype(np.float32)
+
+
+@op(env="skimage")
+def unsharp_mask(
+    image: _Image,
+    radius: float = 1.0,
+    amount: float = 1.0,
+) -> ImageOf[np.ndarray]:
+    """Sharpen an image by adding back what blurring it removes.
+
+    Blur the image, subtract that from the original to get the detail, then
+    add a multiple of the detail back. Older than digital imaging -- the name
+    is from the darkroom -- and still the sharpening every tool implements.
+    It creates no information, so overdoing it produces halos around edges
+    rather than more detail.
+
+    Args:
+        image: Image to sharpen. Any number of axes; a trailing RGB(A) axis
+            is sharpened channel by channel.
+        radius: Standard deviation of the blur that defines "detail", in
+            pixels. Larger radii sharpen coarser structure.
+        amount: How much of the detail to add back. 0 is a no-op, 1 is the
+            usual starting point, and much above 2 halos.
+
+    Returns:
+        The sharpened image, as float32.
+    """
+    from skimage import filters
+
+    sharpened = filters.unsharp_mask(
+        np.asarray(image, dtype=np.float32),
+        radius=radius,
+        amount=amount,
+        preserve_range=True,
+        channel_axis=channel_axis(image),
+    )
+    return sharpened.astype(np.float32)
+
+
+@op(env="skimage")
+def frangi(
+    image: _Volume,
+    sigma_min: float = 1.0,
+    sigma_max: float = 10.0,
+    sigma_step: float = 2.0,
+    black_ridges: bool = True,
+    alpha: float = 0.5,
+    beta: float = 0.5,
+) -> ImageOf[np.ndarray]:
+    """Enhance tubular structures, by Frangi's vesselness measure.
+
+    Written for angiograms and used ever since for anything filamentous --
+    vessels, neurites, cytoskeleton. At each scale it takes the Hessian's
+    eigenvalues and asks whether they look like a tube: one small eigenvalue
+    along the structure, large ones across it. The strongest response over
+    all the scales is kept, so a range of ``sigmas`` covering the thicknesses
+    present is the parameter that matters.
+
+    Args:
+        image: Image to filter, as a plane or a volume. RGB(A) is collapsed
+            to grayscale, since a vesselness has no per-channel meaning.
+        sigma_min: Smallest structure thickness to look for, as a Gaussian
+            sigma in pixels.
+        sigma_max: Largest, inclusive.
+        sigma_step: Spacing between the scales swept.
+        black_ridges: Whether to find dark structures on a light background,
+            as in a brightfield image, rather than the reverse.
+        alpha: Sensitivity to plate-like rather than tube-like structure.
+        beta: Sensitivity to blob-like rather than tube-like structure.
+
+    Returns:
+        Vesselness in [0, 1], as float32.
+    """
+    from skimage import filters
+
+    return filters.frangi(
+        to_gray(np.asarray(image, dtype=np.float32)),
+        sigmas=_sigmas(sigma_min, sigma_max, sigma_step),
+        alpha=alpha,
+        beta=beta,
+        black_ridges=black_ridges,
+    ).astype(np.float32)
+
+
+@op(env="skimage")
+def sato(
+    image: _Volume,
+    sigma_min: float = 1.0,
+    sigma_max: float = 10.0,
+    sigma_step: float = 2.0,
+    black_ridges: bool = True,
+) -> ImageOf[np.ndarray]:
+    """Enhance tubular structures, by Sato's tubeness measure.
+
+    The same Hessian sweep as :func:`frangi` with a simpler combination of
+    the eigenvalues, and no free sensitivity parameters. That makes it the
+    easier of the two to use, and the less selective: it responds more
+    readily at junctions and to structures that are not quite tubes.
+
+    Args:
+        image: Image to filter, as a plane or a volume. RGB(A) is collapsed
+            to grayscale.
+        sigma_min: Smallest structure thickness to look for, as a Gaussian
+            sigma in pixels.
+        sigma_max: Largest, inclusive.
+        sigma_step: Spacing between the scales swept.
+        black_ridges: Whether to find dark structures on a light background
+            rather than the reverse.
+
+    Returns:
+        Tubeness, as float32.
+    """
+    from skimage import filters
+
+    return filters.sato(
+        to_gray(np.asarray(image, dtype=np.float32)),
+        sigmas=_sigmas(sigma_min, sigma_max, sigma_step),
+        black_ridges=black_ridges,
+    ).astype(np.float32)
+
+
+@op(env="skimage")
+def meijering(
+    image: _Volume,
+    sigma_min: float = 1.0,
+    sigma_max: float = 10.0,
+    sigma_step: float = 2.0,
+    black_ridges: bool = True,
+) -> ImageOf[np.ndarray]:
+    """Enhance neurite-like structures, by Meijering's neuriteness measure.
+
+    A Hessian filter tuned for thin, low-contrast, branching structures --
+    it was written for tracing neurites in noisy microscopy. It holds up
+    better than :func:`frangi` where the structure is barely above the
+    background, and is correspondingly noisier where it is not.
+
+    Args:
+        image: Image to filter, as a plane or a volume. RGB(A) is collapsed
+            to grayscale.
+        sigma_min: Smallest structure thickness to look for, as a Gaussian
+            sigma in pixels.
+        sigma_max: Largest, inclusive.
+        sigma_step: Spacing between the scales swept.
+        black_ridges: Whether to find dark structures on a light background
+            rather than the reverse.
+
+    Returns:
+        Neuriteness, as float32.
+    """
+    from skimage import filters
+
+    return filters.meijering(
+        to_gray(np.asarray(image, dtype=np.float32)),
+        sigmas=_sigmas(sigma_min, sigma_max, sigma_step),
+        black_ridges=black_ridges,
+    ).astype(np.float32)

skop/ops/generate.py

@@ -0,0 +1,77 @@
+"""Synthetic data, for exercising ops that have nothing to segment yet.
+
+Kept out of ``skop.ops.segment`` because generating a volume is not
+segmenting one, and because these ops run in a light environment rather than
+the deep learning stacks the segmenters need.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from opspec.op import op
+from opspec.runtime import progress
+from opspec.types import ImageOf
+
+
+@op(env="skimage")
+def synthetic_nuclei(
+    size_z: int = 64,
+    size_y: int = 256,
+    size_x: int = 256,
+    n_nuclei: int = 8,
+    radius_z_min: float = 2.5,
+    radius_z_max: float = 4.5,
+    radius_xy_min: float = 16.0,
+    radius_xy_max: float = 22.0,
+    noise_level: int = 6553,
+    seed: int | None = None,
+) -> ImageOf[np.ndarray]:
+    """Generate a synthetic 3D volume of anisotropic Gaussian blob nuclei.
+
+    The default radii are centered on the confocal model's training data, so
+    the result is something ``skop.ops.segment.segment_nuclei`` should be
+    able to find.
+
+    Args:
+        size_z: Volume extent along Z.
+        size_y: Volume extent along Y.
+        size_x: Volume extent along X.
+        n_nuclei: How many nuclei to place.
+        radius_z_min: Smallest nucleus radius along Z, as a Gaussian sigma.
+        radius_z_max: Largest nucleus radius along Z.
+        radius_xy_min: Smallest nucleus radius in XY.
+        radius_xy_max: Largest nucleus radius in XY.
+        noise_level: Amplitude of the uniform background noise.
+        seed: Seed for the placement of nuclei. None places them at random,
+            which means the number that can actually be told apart varies.
+
+    Returns:
+        A uint16 volume in (Z, Y, X) order.
+    """
+    from scipy.ndimage import gaussian_filter
+
+    shape = (size_z, size_y, size_x)
+    rng = np.random.default_rng(seed)
+    volume = (rng.random(shape) * noise_level).astype(np.uint16)
+
+    zz, yy, xx = np.mgrid[0 : shape[0], 0 : shape[1], 0 : shape[2]]
+
+    for i in range(n_nuclei):
+        progress(f"Placing nucleus {i + 1} of {n_nuclei}", i, n_nuclei)
+        z = rng.integers(0, shape[0])
+        y = rng.integers(0, shape[1])
+        x = rng.integers(0, shape[2])
+        radius_z = rng.uniform(radius_z_min, radius_z_max)
+        radius_xy = rng.uniform(radius_xy_min, radius_xy_max)
+        intensity = rng.uniform(32768, 65535)
+
+        dist_sq = (
+            (zz - z) ** 2 / (2 * radius_z**2)
+            + (yy - y) ** 2 / (2 * radius_xy**2)
+            + (xx - x) ** 2 / (2 * radius_xy**2)
+        )
+        blob = intensity * np.exp(-dist_sq)
+        volume = np.clip(np.maximum(volume, blob), 0, 65535).astype(np.uint16)
+
+    return gaussian_filter(volume.astype(np.float32), sigma=0.5).astype(np.uint16)

skop/ops/kernels/__init__.py

@@ -0,0 +1,39 @@
+"""Kernels: generate something to convolve an image with.
+
+A PSF is as much a forward-simulation tool as a deconvolution one, so it lives
+here rather than under ``skop.ops.deconvolve``.
+
+Three models, in increasing order of what they know about the microscope:
+
+``gaussian_psf``    no optics at all, just a width you pick
+``paraxial_psf``    wavelength, NA and pixel size -- the textbook, in focus
+``gibson_lanni``    the above plus immersion medium, sample index and depth,
+                    so it can be axially asymmetric
+
+Everything here is a *theoretical* PSF, computed from optical parameters with
+no measurement involved. Extracting a PSF from a bead image is deliberately
+elsewhere: it composes a deconvolution op whose backend depends on the
+machine, which makes it a workflow op rather than a plain one. See
+docs/spec/workflow-ops.md.
+
+This namespace spans two environments -- ``gibson_lanni`` needs sdeconv, the
+rest are content with ``skimage`` -- which is the README's rule for a
+namespace being a package rather than a module.
+"""
+
+from __future__ import annotations
+
+from ._fluorophore import Fluorophore
+from ._recenter import recenter_psf_axial
+from .gibson_lanni import gibson_lanni
+from .paraxial import paraxial_otf, paraxial_psf
+from .psf import gaussian_psf
+
+__all__ = [
+    "Fluorophore",
+    "gaussian_psf",
+    "gibson_lanni",
+    "paraxial_otf",
+    "paraxial_psf",
+    "recenter_psf_axial",
+]

skop/ops/kernels/_fluorophore.py

@@ -0,0 +1,42 @@
+"""Emission wavelengths for common fluorophores.
+
+Every PSF model here takes a wavelength in microns, and in practice nobody
+knows one off the top of their head -- they know they imaged DAPI. This is
+that lookup, ported from tnia-python's ``wave_dictionary``.
+
+A ``float`` mixin rather than a plain ``Enum``, so a member *is* its
+wavelength: ``gibson_lanni(wavelength=Fluorophore.DAPI)`` works with no
+conversion, and the parameter stays a plain ``float`` that also accepts the
+647.1 nm line of whatever laser is actually on the bench.
+
+Stdlib only, so any environment holding a PSF op can import it.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+__all__ = ["Fluorophore"]
+
+
+class Fluorophore(float, Enum):
+    """Peak emission wavelength, in microns.
+
+    The source dictionary paired an excitation with each emission. Only
+    emission is kept: it is what forms the image, and so what every PSF model
+    here asks for. Excitation is noted in the comments rather than carried,
+    since nothing computes with it.
+    """
+
+    DAPI = 0.461  # excitation 358 nm, blue
+    Cy2 = 0.506  # excitation 489 nm, green
+    FITC = 0.519  # excitation 495 nm, green
+    TexasRed = 0.610  # excitation 561 nm, orange-red
+    AF594 = 0.617  # excitation 590 nm, red
+    Cy5 = 0.670  # excitation 649 nm, far-red / NIR
+
+    # NB: the original spelled Texas Red "Texa", which reads as a typo rather
+    # than an abbreviation -- these were dictionary keys, so nothing depended
+    # on the spelling. Ordered by emission here rather than alphabetically,
+    # because a wavelength list that runs blue to red is the one a microscopist
+    # can scan.

skop/ops/kernels/_recenter.py

@@ -0,0 +1,60 @@
+"""Putting an off-centre PSF back on centre.
+
+A theoretical PSF computed at a non-zero focal depth is not centred on the
+middle plane -- that asymmetry is the spherical aberration being modelled, and
+it is the point. But a deconvolution kernel has to be centred, or the result
+comes out shifted along Z by however far the peak sat from the middle.
+
+sdeconv in particular does not centre its output at all, which is the reason
+this exists. Compute taller than needed, find the peak, crop back around it.
+
+numpy and the standard library only, so any environment holding a PSF op can
+import it.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["recenter_psf_axial"]
+
+
+def recenter_psf_axial(psf: np.ndarray, new_z: int) -> np.ndarray:
+    """Crop a 3-D PSF to ``new_z`` planes, centred on its brightest plane.
+
+    Args:
+        psf: A ``(Z, Y, X)`` PSF, generally taller than ``new_z``.
+        new_z: Number of planes to return.
+
+    Returns:
+        A ``(new_z, Y, X)`` view-derived copy whose peak sits on the centre
+        plane, at index ``new_z // 2``.
+
+    Raises:
+        ValueError: If the crop would run off either end of ``psf`` -- which
+            means the PSF was not computed with enough headroom for this
+            ``pz``, and the honest answer is to compute a taller one.
+    """
+    if psf.ndim != 3:
+        raise ValueError(f"expected a 3-D PSF, got {psf.ndim}-D")
+    if new_z > psf.shape[0]:
+        raise ValueError(
+            f"cannot crop {psf.shape[0]} planes down to {new_z}: nothing to crop"
+        )
+
+    peak_z = int(np.unravel_index(int(psf.argmax()), psf.shape)[0])
+    start = peak_z - new_z // 2
+
+    # NB: the original sliced without checking, and Python's slicing is
+    # forgiving in exactly the wrong way here -- a negative start counts from
+    # the far end and an overlong stop silently truncates, so a PSF whose peak
+    # sits near an edge came back with the wrong number of planes and no
+    # complaint. The caller cannot recover from that; it can from an error.
+    if start < 0 or start + new_z > psf.shape[0]:
+        raise ValueError(
+            f"peak at plane {peak_z} is too close to the edge to crop "
+            f"{new_z} planes around it, from {psf.shape[0]}: compute the PSF "
+            f"with more Z headroom, or reduce pz"
+        )
+
+    return psf[start : start + new_z].copy()