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

skop/envs/sdeconv/pixi.toml

@@ -0,0 +1,85 @@
+[workspace]
+name = "skop-sdeconv"
+description = "sdeconv, for the Gibson-Lanni PSF model."
+channels = ["conda-forge"]
+platforms = ["osx-arm64", "linux-64", "win-64"]
+version = "0.1.0"
+
+# This environment exists only because sdeconv is not on conda-forge at a
+# usable version: the channel carries 0.1.0, a py38 build, and the API this op
+# needs (`sdeconv.psfs.SPSFGibsonLanni`) arrived in 1.x. So sdeconv comes from
+# PyPI, and everything it depends on comes from conda -- see the note on
+# [pypi-dependencies] below.
+#
+# It is deliberately NOT its own torch stack. Every conda dependency here is
+# stated exactly as envs/pytorch states it -- same channel, same python, same
+# torch packages, same CUDA -- so that the two environments solve to the same
+# builds and pixi hard-links one copy out of the shared package cache instead
+# of unpacking a second multi-gigabyte torch.
+#
+# That is a deliberate reversal of what design 0010 first proposed. The spec
+# suggested pinning a CPU-only torch, reasoning that generating a PSF is small
+# work and needs no GPU. True, but conda package identity is
+# name-version-buildstring, and `pytorch-cpu ... cpu_py311_*` and
+# `pytorch-gpu ... cuda129_mkl_py311_*` share no bytes at all. A CPU pin saves
+# space only on a machine that has no other torch environment, and costs a
+# full extra copy on any machine that does -- which, since fastsam lives in
+# envs/pytorch, is the machine a developer here actually has.
+#
+# Keeping it aligned is also what makes the merge cheap. If sdeconv earns its
+# way into the canonical environment later, folding it in is deleting this
+# file and adding one line to envs/pytorch's [pypi-dependencies]; nothing
+# about the conda half has to be reconciled first.
+#
+# The one thing to keep in step by hand: envs/pytorch leaves torch unpinned
+# (`pytorch-gpu = "*"`), so two environments solved months apart can land on
+# different versions and share nothing. If that starts to bite, pin both to
+# the same version rather than pinning only this one.
+
+[system-requirements]
+cuda = "12.0"
+
+[dependencies]
+python = "3.11.*"
+numpy = "*"
+# NB: appose is not listed as a conda dependency here, unlike in
+# envs/unseg-cv, and this is temporary. A conda appose does satisfy the
+# pinned scikit-ops' PyPI dependency on it -- but only once the pin is new
+# enough to have dropped scikit-ops' [tool.uv.sources] git source for
+# appose, which uv honors transitively and which makes the solve
+# unsatisfiable. So this goes back to `appose = ">=0.12"` above as soon as
+# the rev below is bumped past that change and conda-forge carries 0.12.
+
+# sdeconv's own declared dependencies, satisfied from conda rather than left
+# to PyPI. This is the same lesson envs/segment-everything records: left to
+# resolve them itself, uv matches `torchvision` against the torch the conda
+# solve already pinned, finds no published wheel that fits, and the solve
+# fails outright. Stating them here leaves uv nothing to resolve but sdeconv.
+scipy = "*"
+scikit-image = "*"
+torchvision = "*"
+
+[pypi-dependencies]
+# Note: pinned deliberately -- this is part of the environment's identity,
+# so bumping it rebuilds every environment. A checkout still shadows it,
+# because skop.host.INIT puts src at sys.path[0]. See
+# docs/spec/fiji-front-end.md; it becomes an ordinary version constraint
+# once scikit-ops is released.
+scikit-ops = { git = "https://github.com/apposed/scikit-ops.git", rev = "00925fea3d92f3c974b7b1ec67d6633307d27bcc" }
+sdeconv = ">=1,<2"
+
+# Torch, stated exactly as envs/pytorch states it: CUDA builds where there are
+# GPUs, and the plain package on Apple Silicon where MPS is built in. Nothing
+# here uses a GPU -- a Gibson-Lanni PSF is a small FFT -- but matching the
+# canonical environment is worth more than the GPU build being unnecessary.
+[target.linux-64.dependencies]
+pytorch-gpu = "*"
+cudnn = "*"
+cuda-version = "12.2"
+
+[target.win-64.dependencies]
+pytorch-gpu = "*"
+cudnn = "*"
+
+[target.osx-arm64.dependencies]
+pytorch = "*"

skop/envs/segment-everything/pixi.toml

@@ -0,0 +1,96 @@
+[workspace]
+name = "skop-segment-everything"
+description = "segment-everything, for MobileSAMv2's object-aware YOLO."
+channels = ["conda-forge"]
+platforms = ["osx-arm64", "linux-64", "win-64"]
+version = "0.1.0"
+
+[system-requirements]
+cuda = "12.0"
+
+# NB: segment-everything's own dependencies are listed here as conda packages,
+# even though it declares them itself on PyPI. That is what makes this
+# environment solve at all.
+#
+# Left to PyPI, uv resolves `torchvision` against whatever `torch` the conda
+# solve pinned, and no published torchvision matches a current one -- the solve
+# fails outright. Satisfying them from conda first leaves uv only the leaves it
+# is the only source for (onnxsim, torchpack). The recipe is lifted from a
+# working environment: ../napari-ai-lab/pixi/microsam_cellposesam_czi, where
+# micro_sam and cellpose happened to drag the same packages in from conda.
+[dependencies]
+python = "3.11.*"
+numpy = "*"
+# NB: appose is not listed as a conda dependency here, unlike in
+# envs/unseg-cv, and this is temporary. A conda appose does satisfy the
+# pinned scikit-ops' PyPI dependency on it -- but only once the pin is new
+# enough to have dropped scikit-ops' [tool.uv.sources] git source for
+# appose, which uv honors transitively and which makes the solve
+# unsatisfiable. So this goes back to `appose = ">=0.12"` above as soon as
+# the rev below is bumped past that change and conda-forge carries 0.12.
+scikit-image = "*"
+py-opencv = "*"
+timm = "*"
+onnx = "*"
+segment-anything = "*"
+gdown = "*"
+magicgui = "*"
+
+# The vendored ultralytics 8.0.120's own runtime dependencies, which
+# segment-everything does not declare either -- it only lists what its own
+# modules import. `pandas` is the one that bites first: AutoBackend calls
+# export_formats() to sniff the weights file, and that imports pandas at the
+# top of exporter.py before any model loads.
+pandas = "*"
+matplotlib-base = "*"
+seaborn-base = "*"
+psutil = "*"
+py-cpuinfo = "*"
+requests = "*"
+pyyaml = "*"
+tqdm = "*"
+scipy = "*"
+pillow = "*"
+
+# NB: setuptools is pinned below 81 because that is where `pkg_resources` was
+# removed, and the vendored ultralytics 8.0.120 imports it
+# (yolo/utils/checks.py) while building its settings at import time. Without
+# the pin pixi installs setuptools 83 and the op dies on
+# `ModuleNotFoundError: No module named 'pkg_resources'` before it loads a
+# model. The working environment this recipe came from has 80.9.0, but by
+# lock date rather than by constraint.
+setuptools = "<81"
+
+# NB: ultralytics is deliberately absent, and must stay absent.
+#
+# segment-everything vendors its own ultralytics 8.0.120 fork and puts it on
+# sys.path when loading the object-aware model. A second ultralytics in this
+# environment would shadow, or be shadowed by, that one depending on import
+# order. The maintained ultralytics lives in envs/pytorch instead, which is
+# why these are two environments and not one. See docs/design/0007.
+[pypi-dependencies]
+# Note: pinned deliberately -- this is part of the environment's identity,
+# so bumping it rebuilds every environment. A checkout still shadows it,
+# because skop.host.INIT puts src at sys.path[0]. See
+# docs/spec/fiji-front-end.md; it becomes an ordinary version constraint
+# once scikit-ops is released.
+scikit-ops = { git = "https://github.com/apposed/scikit-ops.git", rev = "00925fea3d92f3c974b7b1ec67d6633307d27bcc" }
+segment-everything = "==0.3"
+
+# Torch is pinned to the 2.9 series rather than left free. The vendored fork is
+# an ultralytics 8.0.120 from 2023 that already needed patching for a torch
+# API change (weights_only), so tracking the newest torch is a liability here.
+# 2.9.1 is what the working environment above runs.
+[target.linux-64.dependencies]
+pytorch-gpu = "2.9.*"
+torchvision = "*"
+cudnn = "*"
+
+[target.win-64.dependencies]
+pytorch-gpu = "2.9.*"
+torchvision = "*"
+cudnn = "*"
+
+[target.osx-arm64.dependencies]
+pytorch = "2.9.*"
+torchvision = "*"

skop/envs/skimage/pixi.toml

@@ -0,0 +1,28 @@
+[workspace]
+name = "skop-skimage"
+description = "Classical image processing: scikit-image and friends."
+channels = ["conda-forge"]
+platforms = ["osx-arm64", "osx-64", "linux-64", "win-64"]
+version = "0.1.0"
+
+[dependencies]
+python = "3.11.*"
+numpy = "*"
+scipy = "*"
+scikit-image = "*"
+pywavelets = "*"  # Note: an optional scikit-image dep, needed by smooth:wavelet.
+# NB: appose is not listed as a conda dependency here, unlike in
+# envs/unseg-cv, and this is temporary. A conda appose does satisfy the
+# pinned scikit-ops' PyPI dependency on it -- but only once the pin is new
+# enough to have dropped scikit-ops' [tool.uv.sources] git source for
+# appose, which uv honors transitively and which makes the solve
+# unsatisfiable. So this goes back to `appose = ">=0.12"` above as soon as
+# the rev below is bumped past that change and conda-forge carries 0.12.
+
+[pypi-dependencies]
+# Note: pinned deliberately -- this is part of the environment's identity,
+# so bumping it rebuilds every environment. A checkout still shadows it,
+# because skop.host.INIT puts src at sys.path[0]. See
+# docs/spec/fiji-front-end.md; it becomes an ordinary version constraint
+# once scikit-ops is released.
+scikit-ops = { git = "https://github.com/apposed/scikit-ops.git", rev = "00925fea3d92f3c974b7b1ec67d6633307d27bcc" }

skop/envs/stardist-tf/pixi.toml

@@ -0,0 +1,91 @@
+[workspace]
+name = "skop-stardist-tf"
+description = "StarDist on TensorFlow, in 2D and 3D."
+channels = ["conda-forge"]
+platforms = ["osx-arm64", "osx-64", "linux-64", "win-64"]
+version = "0.1.0"
+
+# Shared by ops/stardist2d.py and ops/starfun3d.py: same stack, one build.
+#
+# The per-platform TensorFlow split is inherited from starfun3d, where it is
+# known to work. TF 2.10 is the last release with GPU support on Windows, and
+# Apple Silicon needs the tensorflow-macos/tensorflow-metal pair rather than
+# plain tensorflow.
+
+[dependencies]
+python = "==3.10"
+numpy = "<2"
+scipy = "*"
+pip = "*"
+# NB: appose is not listed as a conda dependency here, unlike in
+# envs/unseg-cv, and this is temporary. A conda appose does satisfy the
+# pinned scikit-ops' PyPI dependency on it -- but only once the pin is new
+# enough to have dropped scikit-ops' [tool.uv.sources] git source for
+# appose, which uv honors transitively and which makes the solve
+# unsatisfiable. So this goes back to `appose = ">=0.12"` above as soon as
+# the rev below is bumped past that change and conda-forge carries 0.12.
+# NB: stardist 0.9.1 imports pkg_resources, which setuptools dropped in 81.
+setuptools = "<81"
+
+[pypi-dependencies]
+# Note: pinned deliberately -- this is part of the environment's identity,
+# so bumping it rebuilds every environment. A checkout still shadows it,
+# because skop.host.INIT puts src at sys.path[0]. See
+# docs/spec/fiji-front-end.md; it becomes an ordinary version constraint
+# once scikit-ops is released.
+scikit-ops = { git = "https://github.com/apposed/scikit-ops.git", rev = "00925fea3d92f3c974b7b1ec67d6633307d27bcc" }
+stardist = "==0.9.1"
+csbdeep = "*"
+
+[target.osx-64.dependencies]
+python = "==3.10"
+
+[target.osx-arm64.dependencies]
+# NB: inherited from starfun3d, which leaves Python unpinned here so the
+# resolver can pick whatever tensorflow-macos currently ships wheels for.
+# In practice that means Apple Silicon runs a newer Python than the other
+# platforms -- 3.12 with TF 2.16, rather than 3.10 with TF 2.10.
+python = "*"
+
+# CUDA on Windows only. TF 2.10 predates the CUDA-carrying wheels and ships no
+# CUDA of its own, so on win-64 it has to come from conda. Nothing else is
+# needed: pixi's activation already puts %CONDA_PREFIX%\Library\bin on PATH,
+# which is how Windows finds DLLs.
+#
+# Linux needs none of this: tensorflow[and-cuda] below brings its own CUDA in
+# site-packages, where TensorFlow finds it without help. macOS has no CUDA at
+# all; Apple Silicon uses tensorflow-metal.
+[target.win-64.dependencies]
+cudatoolkit = "11.2.*"
+cudnn = "8.1.*"
+
+[target.win-64.pypi-dependencies]
+tensorflow = "==2.10.1"
+
+# 2.15 is the ceiling, not a preference: 2.16 defaults to Keras 3, which
+# csbdeep and stardist 0.9.1 do not work with. The [and-cuda] extra pulls
+# NVIDIA's own pip wheels, so this is the whole CUDA story on Linux.
+[target.linux-64.pypi-dependencies]
+tensorflow = { version = "==2.15.*", extras = ["and-cuda"] }
+
+[target.osx-64.pypi-dependencies]
+tensorflow = "*"
+
+[target.osx-arm64.pypi-dependencies]
+tensorflow-macos = "*"
+tensorflow-metal = "*"
+
+# Variant: Apple Silicon without the Metal plugin, which some models trip over.
+[feature.nometal]
+channels = ["conda-forge"]
+
+[feature.nometal.target.osx-arm64.pypi-dependencies]
+tensorflow = "*"
+
+# NB: Only 'default' is installed on build; 'nometal' is materialized on
+# demand via Runner.run(..., variant="nometal"). There is no longer a 'cuda'
+# variant -- CUDA rides with the wheel on Linux and comes from conda on
+# Windows, both in the default.
+[environments]
+default = { solve-group = "default" }
+nometal = { features = ["nometal"], solve-group = "default" }

skop/envs/unseg-cv/pixi.toml

@@ -0,0 +1,27 @@
+[workspace]
+name = "skop-unseg-cv"
+description = "UNSEG's stack: an older scikit-image, scikit-learn and OpenCV."
+channels = ["conda-forge"]
+platforms = ["osx-arm64", "osx-64", "linux-64", "linux-aarch64", "win-64"]
+version = "0.1.0"
+
+# Pins are inherited from unseg-fiji, where the algorithm is known to produce
+# correct results. They are old enough that this env can share nothing with
+# the others -- which is precisely why environments are per-stack.
+
+[dependencies]
+python = "3.9.*"
+numpy = "==1.24.3"
+scipy = "==1.9.1"
+scikit-image = "==0.20.0"
+scikit-learn = "==1.2.2"
+# NB: unseg-fiji pinned appose 0.7.2, but skop's worker adapter needs the
+# service init script support added later.
+appose = ">=0.11"
+
+[pypi-dependencies]
+# NB: the one environment with no pinned scikit-ops. Every other one installs
+# it, so that a worker needs no checkout; this one cannot, because scikit-ops
+# requires Python 3.10 and UNSEG's pins 3.9. It runs off the sys.path
+# injection alone, which is what got it working in the first place.
+opencv-python-headless = "==4.7.0.72"

skop/models.py

@@ -0,0 +1,145 @@
+"""Which Cellpose a model is for, answered without loading it.
+
+A trained Cellpose model is a bare ``torch.save`` of a state dict under a name
+its author chose, so the file says nothing about which Cellpose it belongs to.
+Handing a Cellpose 3 model to the ``cellpose4`` op, or the reverse, fails deep
+inside torch with an error about unexpected keys.
+
+The architecture is legible in the key names, though, and a torch checkpoint
+is a zip whose pickled header lists them. Reading that header is a ~50 KB read
+even when the weights beside it are 600 MB, and it needs only the standard
+library -- so the *host* can route a model to the right op before dispatching
+it, which is the point. ``cellpose4`` and ``cellpose3`` live in environments
+that cannot both exist, and the host has neither.
+
+Built-in models are answered from a name instead, so that a caller with a
+mixed list -- some built-ins, some files of its own -- can ask the same
+question of every entry.
+
+Standard library only, like ``ophelper.boxes`` and ``ophelper.masks``, so the host, a
+worker and a front end can all import it.
+"""
+
+from __future__ import annotations
+
+import zipfile
+from enum import Enum
+from pathlib import Path
+
+__all__ = ["BUILTIN_MODELS", "CellposeFlavor", "cellpose_flavor"]
+
+
+class CellposeFlavor(Enum):
+    """Which Cellpose can load a file, and so which op runs it. Not which
+    backbone -- Cellpose 4 picks between its own two, and cannot load a
+    Cellpose 3 model at all."""
+
+    cellpose4 = "cellpose4"
+    cellpose3 = "cellpose3"
+
+
+#: A key prefix in one architecture and not the others. ``diam_mean`` and
+#: ``diam_labels`` are in all of them and tell you nothing.
+_SIGNATURES = (
+    (b"encoder.blocks.", CellposeFlavor.cellpose4),
+    (b"encoder.cls_token", CellposeFlavor.cellpose4),
+    (b"downsample.down.res_down_", CellposeFlavor.cellpose3),
+)
+
+
+#: The models each Cellpose ships with, by the name you pass it. Cellpose 4
+#: replaced the whole zoo with one model, so no name is in both versions and a
+#: name alone settles the architecture. The Cellpose 3 list is its full model
+#: zoo, older ``cyto``/``cyto2`` included -- they still load there, and a
+#: published result may name one.
+BUILTIN_MODELS: dict[str, CellposeFlavor] = {
+    "cpsam": CellposeFlavor.cellpose4,
+    "cpsam_v2": CellposeFlavor.cellpose4,
+    "cpdino": CellposeFlavor.cellpose4,
+    "cpdino-vitb": CellposeFlavor.cellpose4,
+    **dict.fromkeys(
+        (
+            "cyto",
+            "cyto2",
+            "cyto3",
+            "nuclei",
+            "cyto2_cp3",
+            "tissuenet_cp3",
+            "livecell_cp3",
+            "yeast_PhC_cp3",
+            "yeast_BF_cp3",
+            "bact_phase_cp3",
+            "bact_fluor_cp3",
+            "deepbacs_cp3",
+            "transformer_cp3",
+            "neurips_cellpose_default",
+            "neurips_cellpose_transformer",
+            "neurips_grayscale_cyto2",
+            "CP",
+            "CPx",
+            "TN1",
+            "TN2",
+            "TN3",
+            "LC1",
+            "LC2",
+            "LC3",
+            "LC4",
+        ),
+        CellposeFlavor.cellpose3,
+    ),
+}
+
+
+def cellpose_flavor(model: str | Path) -> CellposeFlavor:
+    """Identify which Cellpose a model is for.
+
+    Args:
+        model: Either the name of a built-in model, such as ``"cyto3"`` or
+            ``"cpsam"``, or the path of one saved by ``torch.save``. A name
+            is looked up; a path is read.
+
+    Returns:
+        Which architecture it is, and so which op can run it.
+
+    Raises:
+        ValueError: If the name is not a built-in, or the file is not a torch
+            checkpoint, or is one whose keys match neither architecture.
+            Guessing here would send the model to an environment that dies on
+            it, so this reports rather than picks.
+    """
+    # A plain string is a name first and a path second, so that "cyto3" means
+    # the built-in even when run beside a file of that name. Spell it as a
+    # Path to mean the file.
+    if isinstance(model, str) and model in BUILTIN_MODELS:
+        return BUILTIN_MODELS[model]
+
+    path = Path(model)
+    if not path.exists():
+        raise ValueError(
+            f"{model} is neither a built-in Cellpose model nor an existing file"
+        )
+    if not zipfile.is_zipfile(path):
+        # Either not a checkpoint at all, or one from torch before 1.6. No
+        # Cellpose that skop can run wrote the latter.
+        raise ValueError(f"{path} is not a torch checkpoint")
+
+    header = _header(path)
+    for signature, flavor in _SIGNATURES:
+        if signature in header:
+            return flavor
+    raise ValueError(f"{path} is not a recognized Cellpose model")
+
+
+def _header(path: Path) -> bytes:
+    """The pickled state dict header, without the tensors it points at.
+
+    A torch checkpoint is a zip holding ``<name>/data.pkl`` -- the state dict
+    with its storages replaced by references -- beside one entry per tensor.
+    The root name is whatever the model was called when it was saved, so the
+    entry is found by suffix.
+    """
+    with zipfile.ZipFile(path) as archive:
+        names = [n for n in archive.namelist() if n.endswith("data.pkl")]
+        if not names:
+            raise ValueError(f"{path} is a zip, but not a torch checkpoint")
+        return archive.read(names[0])

skop/ops/__init__.py

@@ -0,0 +1,19 @@
+"""The bundled op collection.
+
+Ops are grouped into namespaces by what they do -- ``skop.ops.threshold``,
+``skop.ops.segment`` -- and are imported from the namespace regardless of how
+it is laid out inside::
+
+    from skop.ops.threshold import otsu
+    from skop.ops.segment import cellpose4
+
+A namespace whose ops are variations on one call sharing one environment is a
+single module (``threshold.py``). A namespace whose ops span environments and
+carry their own models and types is a package with a module per op
+(``segment/``), re-exporting them in its ``__init__.py``. Both read the same
+from the outside, so a namespace can grow from one into the other without
+breaking a caller's import.
+
+Discovery walks this package recursively, skipping underscore-prefixed
+modules; see ``oprunner.discovery``.
+"""

skop/ops/_util.py

@@ -0,0 +1,115 @@
+"""Helpers shared between ops.
+
+Kept as light as an op module, since it is imported alongside them during
+discovery.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from enum import Enum
+
+import numpy as np
+
+
+class Footprint(Enum):
+    """Shape of a structuring element, as the metric its radius measures in.
+
+    ``ball`` is Euclidean and the usual choice: it is isotropic, so an
+    operation does not depend on how the object happens to be oriented.
+    ``box`` is Chebyshev and the fastest, at the cost of favouring the
+    diagonals. ``diamond`` is Manhattan, the tightest of the three.
+    """
+
+    ball = "ball"
+    box = "box"
+    diamond = "diamond"
+
+
+def footprint(ndim: int, radius: int, shape: Footprint = Footprint.ball) -> np.ndarray:
+    """A structuring element of the given radius, in the given dimension.
+
+    Generated rather than taken from ``skimage.morphology``, whose generators
+    are one function per dimension -- ``disk`` for 2-D, ``ball`` for 3-D and
+    nothing beyond. The three shapes are the three usual metrics, so each is a
+    distance from the centre thresholded at ``radius``.
+    """
+    grid = np.indices((2 * radius + 1,) * ndim) - radius
+    if shape is Footprint.ball:
+        distance = np.sqrt((grid.astype(np.float64) ** 2).sum(axis=0))
+    elif shape is Footprint.box:
+        distance = np.abs(grid).max(axis=0)
+    else:
+        distance = np.abs(grid).sum(axis=0)
+    return (distance <= radius).astype(np.uint8)
+
+
+def channel_axis(image: np.ndarray) -> int | None:
+    """``-1`` when a trailing axis looks like RGB(A), else ``None``.
+
+    The same guess :func:`to_gray` makes, for ops that keep the channels
+    rather than collapsing them.
+    """
+    if image.ndim >= 3 and image.shape[-1] in (3, 4):
+        return -1
+    return None
+
+
+def per_channel(
+    image: np.ndarray, fn: Callable[[np.ndarray], np.ndarray]
+) -> np.ndarray:
+    """Apply a spatial filter to each RGB(A) channel, or to the whole array.
+
+    A neighborhood is a spatial notion, and mixing red into green is never
+    what a filter meant. Arrays without a trailing channel axis go through
+    untouched, so an op needs no branch of its own.
+    """
+    if channel_axis(image) is None:
+        return fn(image)
+    return np.stack(
+        [fn(image[..., c]) for c in range(image.shape[-1])],
+        axis=-1,
+    )
+
+
+def to_gray(image: np.ndarray) -> np.ndarray:
+    """Collapse a small trailing channel axis, leaving other axes alone.
+
+    A trailing extent of 3 or 4 is taken to be RGB(A); anything else is
+    assumed to be spatial and returned untouched.
+    """
+    if image.ndim >= 3 and image.shape[-1] in (3, 4):
+        return image[..., :3].mean(axis=-1)
+    return image
+
+
+def to_rgb(image: np.ndarray) -> np.ndarray:
+    """Promote an image to the ``(H, W, 3)`` uint8 an RGB model expects.
+
+    The other direction from :func:`to_gray`, and the thing every detector
+    ported from natural-image work needs: a 16-bit microscopy plane means
+    nothing to a model trained on photographs until it is contrast-stretched
+    into 8-bit and given three channels.
+
+    Percentile-stretched rather than min-max scaled, so a single hot pixel
+    cannot flatten everything else to black. Already-uint8 RGB is returned
+    untouched, since that is exactly what the model wants.
+    """
+    if image.ndim == 3 and image.shape[-1] == 4:
+        image = image[..., :3]
+    if image.ndim == 3 and image.shape[-1] == 3 and image.dtype == np.uint8:
+        return image
+    if image.ndim > 2 and not (image.ndim == 3 and image.shape[-1] == 3):
+        raise ValueError(f"expected a 2-D image or (H, W, 3), got shape {image.shape}")
+
+    x = image.astype(np.float32)
+    low, high = np.percentile(x, (1.0, 99.8))
+    if high <= low:
+        # A blank or single-valued image: stretching it would divide by zero.
+        high = low + 1.0
+    x = np.clip((x - low) / (high - low), 0.0, 1.0)
+    x = (x * 255).astype(np.uint8)
+
+    if x.ndim == 2:
+        x = np.repeat(x[:, :, None], 3, axis=2)
+    return np.ascontiguousarray(x)

skop/ops/deconvolve/__init__.py

@@ -0,0 +1,18 @@
+"""Deconvolution: undo the blur a microscope's PSF imposed.
+
+One op per backend, because ``@op(env=...)`` is fixed per function and the
+backends need different environments -- ``richardson_lucy`` runs anywhere,
+``richardson_lucy_cupy`` needs an NVIDIA GPU. They implement the same
+iteration and are held numerically equivalent by a test, so a caller that can
+choose is choosing on speed alone.
+
+PSFs to feed them live in ``skop.ops.kernels``, and the workflow that pairs
+one with a deconvolver is ``skop.ops.workflows.deconvolve``.
+"""
+
+from __future__ import annotations
+
+from .richardson_lucy import richardson_lucy
+from .richardson_lucy_cupy import richardson_lucy_cupy
+
+__all__ = ["richardson_lucy", "richardson_lucy_cupy"]