feat(dog): ✨ take the decon voxel sizes from the image calibration

dxdata/dzdata describe the image, and the image already records its own
voxel size in the NGFF metadata -- so keeping a second copy in the config was
a chance for the two to drift apart. A deconvolution given the wrong
sampling does not fail; it returns a subtly wrong result, which makes the
duplication worse than merely redundant.

The lateral sizes now come from X/Y and the axial ones from Z, filled in only
where the config left them out, so an explicitly set dxpsf (a PSF sampled
differently from the data) still wins. read_pixel_size() exposes the
calibration for API callers.

The wiring is not DoG-specific: any custom function that declares a
voxel_size parameter receives {"z", "y", "x"} from the store, so a method
needing physical units -- a diameter in micrometers, say -- can ask for them
rather than have them configured. An uncalibrated store passes nothing and
says so.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: lguerard

docs/api/plugins/ome_zarr.md

@@ -25,6 +25,10 @@ resolution, matching anisotropic microscopy stacks.
 
 ::: patchworks.plugins.ome_zarr.register_labels
 
+## read_pixel_size
+
+::: patchworks.plugins.ome_zarr.read_pixel_size
+
 ## NGFF metadata layout
 
 NGFF 0.4 is defined over zarr v2 and puts its keys at the top level; 0.5 is

docs/examples/dog.md

@@ -65,18 +65,36 @@ Requires `cupy` (matching your CUDA version, e.g. `pip install cupy-cuda12x`)
 
 ## With deconvolution first
 
+Let the voxel sizes come from the image rather than retyping them — the
+lateral ones from X/Y, the axial ones from Z:
+
 ```python
+from patchworks.plugins.ome_zarr import read_pixel_size
+
 fn = dog_label_fn(
     low_sigma=1.0, high_sigma=3.0, threshold=0.02,
-    decon_kwargs=dict(
-        psf=psf, dxpsf=xy_scale, dxdata=xy_scale,
-        dzpsf=z_scale, dzdata=z_scale,
-        wavelength=525, na=1.4, nimm=1.515,
-    ),
+    decon_kwargs=dict(psf=psf, wavelength=525, na=1.4, nimm=1.515),
+    voxel_size=read_pixel_size(IMAGE),   # -> dxdata/dzdata/dxpsf/dzpsf
 )
 result = tile_process(IMAGE, fn, tile_shape=(1, 1024, 1024), overlap=32)
 ```
 
+Anything you set in `decon_kwargs` yourself wins, so a PSF sampled
+differently from the data keeps its own sizes:
+
+```python
+decon_kwargs=dict(psf=psf, dxpsf=0.05, dzpsf=0.1, wavelength=525, ...)
+```
+
+!!! warning "A wrong voxel size does not fail loudly"
+    Deconvolution given the wrong sampling still runs and still returns an
+    image — just a subtly wrong one. That is the reason to derive these from
+    the store's own calibration instead of keeping a second copy in a config
+    that can drift.
+
+    `read_pixel_size` returns `{}` for an uncalibrated store; then nothing is
+    filled in and you must supply the sizes yourself.
+
 !!! note "Deconvolution always needs a GPU"
     `pycudadecon` is CUDA-only, independent of `dog_label_fn`'s own `use_gpu`
     flag (which only picks the backend for the blur/label steps). A SLURM job
@@ -146,15 +164,27 @@ custom:
     threshold: 0.02
     decon_kwargs:
       psf: "/path/to/psf.tif"
-      dxpsf: 0.1
-      dxdata: 0.1
-      dzpsf: 0.2
-      dzdata: 0.2
       wavelength: 525
       na: 1.4
       nimm: 1.515
 ```
 
+No voxel sizes: the workflow reads `image.zarr`'s own calibration and fills
+in `dxdata`/`dxpsf` from X/Y and `dzdata`/`dzpsf` from Z. Set any of them in
+`decon_kwargs` to override — for instance a PSF sampled finer than the data:
+
+```yaml
+      dxpsf: 0.05
+      dzpsf: 0.1
+```
+
+!!! tip "This works for your own methods too"
+    The injection is not DoG-specific. Any `custom` function that declares a
+    `voxel_size` parameter receives `{"z": .., "y": .., "x": ..}` from the
+    store, so a method needing physical units never has to keep a second copy
+    of the calibration in its config. If the store is uncalibrated the
+    workflow says so and passes nothing.
+
 Run it exactly like a Cellpose config:
 
 ```bash

docs/guide/custom_segmentation.md

@@ -118,6 +118,22 @@ def segment(tile: np.ndarray, prob_thresh: float = 0.5) -> np.ndarray:
 
 Using a GPU? Just let your framework see it — nothing extra needed.
 
+!!! tip "Ask for the voxel size instead of configuring it"
+    Declare a `voxel_size` parameter and the workflow passes the image's own
+    NGFF calibration, `{"z": .., "y": .., "x": ..}` in micrometers:
+
+    ```python
+    def segment(tile, *, voxel_size=None, min_diameter_um=5.0):
+        min_px = min_diameter_um / voxel_size["x"]   # µm -> pixels
+        ...
+    ```
+
+    That keeps physical parameters tied to the image rather than duplicated
+    in a config that can drift away from it. Setting `voxel_size` in
+    `custom.kwargs` overrides it; an uncalibrated store passes nothing and
+    logs a warning. This is how the DoG plugin gets its deconvolution voxel
+    sizes.
+
 !!! tip "You do not need to modify patchworks"
     `method: "custom"` imports any `(tile) -> labels` callable, so a new
     method is a module of your own and a config block — nothing in the

src/patchworks/plugins/dog.py

@@ -34,13 +34,16 @@
 
 from __future__ import annotations
 
+import logging
 from functools import partial
 from typing import Any, Callable
 
 import numpy as np
 
 from .._gpu import free_gpu_caches, retry_on_oom
 
+logger = logging.getLogger(__name__)
+
 
 def _require_cupy():
     """Raise an actionable ImportError if cupy is not installed.
@@ -77,13 +80,72 @@ def _require_pycudadecon():
         ) from exc
 
 
+def decon_voxel_kwargs(
+    voxel_size: dict[str, float], psf_voxel_size: dict[str, float] | None = None
+) -> dict[str, float]:
+    """pycudadecon's voxel-size arguments, derived from a calibration.
+
+    ``dxdata``/``dzdata`` describe the **image**, so they come straight from
+    its calibration. ``dxpsf``/``dzpsf`` describe the **PSF file**, which is
+    only the same when the PSF was acquired on the same system at the same
+    sampling -- pass *psf_voxel_size* when it was not.
+
+    Getting these wrong does not fail loudly: deconvolution just returns a
+    subtly wrong result, which is why deriving them beats retyping them.
+
+    Parameters
+    ----------
+    voxel_size : dict
+        Image calibration, e.g. from
+        :func:`patchworks.plugins.ome_zarr.read_pixel_size`. Needs ``x`` (or
+        ``y``) for the lateral size and ``z`` for the axial one.
+    psf_voxel_size : dict, optional
+        The PSF's own calibration. Defaults to *voxel_size*.
+
+    Returns
+    -------
+    dict
+        ``dxdata``/``dzdata``/``dxpsf``/``dzpsf``, omitting any the
+        calibration cannot supply.
+
+    Examples
+    --------
+    >>> decon_voxel_kwargs({"z": 0.2, "y": 0.1, "x": 0.1})
+    {'dxdata': 0.1, 'dzdata': 0.2, 'dxpsf': 0.1, 'dzpsf': 0.2}
+    """
+
+    def _lateral(cal):
+        x, y = cal.get("x"), cal.get("y")
+        if x and y and abs(x - y) > 1e-9 * max(x, y):
+            logger.warning(
+                "anisotropic lateral calibration (x=%s, y=%s); pycudadecon "
+                "takes a single lateral size, using x.",
+                x,
+                y,
+            )
+        return x or y
+
+    psf_cal = psf_voxel_size if psf_voxel_size is not None else voxel_size
+    out: dict[str, float] = {}
+    for key, value in (
+        ("dxdata", _lateral(voxel_size)),
+        ("dzdata", voxel_size.get("z")),
+        ("dxpsf", _lateral(psf_cal)),
+        ("dzpsf", psf_cal.get("z")),
+    ):
+        if value:
+            out[key] = float(value)
+    return out
+
+
 def dog_label_fn(
     low_sigma: float | tuple[float, ...],
     high_sigma: float | tuple[float, ...],
     threshold: float,
     *,
     use_gpu: bool = False,
     decon_kwargs: dict[str, Any] | None = None,
+    voxel_size: dict[str, float] | None = None,
 ) -> Callable[[np.ndarray], np.ndarray]:
     """Return a ready-to-use DoG labeler for ``tile_process``.
 
@@ -108,6 +170,15 @@ def dog_label_fn(
         PSF support when deconvolving, so edge tiles don't get truncated
         context.
 
+        ``dxdata``/``dzdata``/``dxpsf``/``dzpsf`` are filled in from
+        *voxel_size* when you leave them out, so the voxel sizes cannot drift
+        away from the image they describe. Anything you set explicitly wins.
+    voxel_size:
+        Physical voxel size as ``{"z": .., "y": .., "x": ..}``. The Snakemake
+        workflow passes the image's own calibration automatically; from the
+        API, :func:`patchworks.plugins.ome_zarr.read_pixel_size` reads it from
+        a store.
+
     Returns
     -------
     Callable[[ndarray], ndarray]
@@ -117,6 +188,19 @@ def dog_label_fn(
         _require_cupy()
     if decon_kwargs is not None:
         _require_pycudadecon()
+        if voxel_size:
+            # Derived values fill gaps only -- an explicit dxpsf for a PSF
+            # sampled differently from the data must not be overwritten.
+            derived = decon_voxel_kwargs(voxel_size)
+            missing = {
+                k: v for k, v in derived.items() if k not in decon_kwargs
+            }
+            if missing:
+                logger.info(
+                    "decon voxel sizes taken from the image calibration: %s",
+                    missing,
+                )
+                decon_kwargs = {**decon_kwargs, **missing}
     cfg = {
         "low_sigma": low_sigma,
         "high_sigma": high_sigma,

src/patchworks/plugins/ome_zarr.py

@@ -743,6 +743,35 @@ def _write_multiscales(
     write_ngff_attrs(zarr.open_group(group_path, mode="a"), multiscales=[entry])
 
 
+def read_pixel_size(store: Union[str, Path]) -> PixelSize:
+    """Physical voxel size recorded in an OME-ZARR's level-0 metadata.
+
+    The calibration the conversion carried over from the source file, as
+    ``{"z": .., "y": .., "x": ..}`` in micrometers. Axes left at scale 1.0
+    (uncalibrated) are omitted, so an empty dict means the store carries no
+    usable calibration.
+
+    Use this instead of retyping voxel sizes into a config: a deconvolution
+    told the wrong voxel size produces a plausible-looking but wrong result.
+
+    Parameters
+    ----------
+    store : str or Path
+        Path of the OME-ZARR group.
+
+    Returns
+    -------
+    dict
+        ``{axis: size}`` for calibrated spatial axes.
+
+    Examples
+    --------
+    >>> read_pixel_size("scan.zarr")  # doctest: +SKIP
+    {'z': 0.2, 'y': 0.1, 'x': 0.1}
+    """
+    return _read_zarr_calibration(store, "")
+
+
 def _read_zarr_calibration(store: Union[str, Path], axes: str) -> PixelSize:
     """Read level-0 spatial scale from an existing OME-ZARR, if any.
 

tests/test_dog.py

@@ -47,3 +47,63 @@ def test_dog_label_fn_with_tile_process():
 
     assert result.shape == (1, 64, 64)
     assert result.max() >= 1
+
+
+def test_decon_voxel_kwargs_from_calibration():
+    """Voxel sizes come from the image, not from retyped config values.
+
+    A deconvolution told the wrong voxel size does not fail -- it returns a
+    subtly wrong result -- so deriving them is the point.
+    """
+    from patchworks.plugins.dog import decon_voxel_kwargs
+
+    assert decon_voxel_kwargs({"z": 0.2, "y": 0.1, "x": 0.1}) == {
+        "dxdata": 0.1,
+        "dzdata": 0.2,
+        "dxpsf": 0.1,
+        "dzpsf": 0.2,
+    }
+    # A PSF sampled differently from the data keeps its own sizes.
+    assert decon_voxel_kwargs(
+        {"z": 0.2, "y": 0.1, "x": 0.1}, {"z": 0.1, "y": 0.05, "x": 0.05}
+    ) == {"dxdata": 0.1, "dzdata": 0.2, "dxpsf": 0.05, "dzpsf": 0.1}
+    # An uncalibrated axis is simply omitted rather than guessed.
+    assert decon_voxel_kwargs({"y": 0.1, "x": 0.1}) == {
+        "dxdata": 0.1,
+        "dxpsf": 0.1,
+    }
+    assert decon_voxel_kwargs({}) == {}
+
+
+def test_explicit_decon_kwargs_win_over_the_calibration(monkeypatch):
+    """Anything set by hand must survive; only gaps are filled."""
+    import sys
+    import types
+
+    from patchworks.plugins import dog
+
+    captured = {}
+
+    def _decon(images, **kwargs):
+        captured.update(kwargs)
+        return images
+
+    monkeypatch.setitem(
+        sys.modules, "pycudadecon", types.SimpleNamespace(decon=_decon)
+    )
+    monkeypatch.setattr(dog, "_require_pycudadecon", lambda: None)
+
+    fn = dog.dog_label_fn(
+        low_sigma=1.0,
+        high_sigma=3.0,
+        threshold=0.5,
+        # dxpsf set by hand: the PSF was sampled finer than the data
+        decon_kwargs={"psf": "psf.tif", "dxpsf": 0.05},
+        voxel_size={"z": 0.2, "y": 0.1, "x": 0.1},
+    )
+    fn(np.zeros((4, 8, 8), "uint16"))
+
+    assert captured["dxpsf"] == 0.05, "an explicit value must not be replaced"
+    assert captured["dxdata"] == 0.1  # filled from the calibration
+    assert captured["dzdata"] == 0.2
+    assert captured["dzpsf"] == 0.2

workflow/config/config_cilia.yaml

@@ -47,10 +47,14 @@ custom:
     # use_gpu: true          # optional: also run the blur/label step on GPU
     decon_kwargs:
       psf: "/path/to/psf.tif"
-      dxpsf: 0.1
-      dxdata: 0.1
-      dzpsf: 0.2
-      dzdata: 0.2
+      # dxdata/dzdata (and dxpsf/dzpsf) are filled from image.zarr's own
+      # calibration -- the lateral size from X/Y, the axial one from Z -- so
+      # they cannot drift away from the image they describe. A wrong voxel
+      # size does not fail loudly; it just deconvolves incorrectly.
+      # Set any of them here only to override, e.g. when the PSF was sampled
+      # differently from the data:
+      #   dxpsf: 0.05
+      #   dzpsf: 0.1
       wavelength: 525
       na: 1.4
       nimm: 1.515