merge dev into main

Splits the cluster-workflow guide into focused pages (custom
segmentation, measurements, label relations) and trims snakemake.md
down to SLURM/cluster-specific content.

Author: lguerard

docs/examples/dog.md

@@ -97,12 +97,12 @@ tile_process(IMAGE, fn, tile_shape=(1, 1024, 1024), overlap=8, write_to=OUTPUT)
 
 On the cluster, set `dilate: 2` in the YAML config instead — it applies to
 `method: "custom"` (this plugin) the same way it does for `cellpose`/
-`threshold`, see [Growing labels after segmentation](../guide/snakemake.md#growing-labels-afterwards-dilation).
+`threshold`, see [Growing labels afterwards](../guide/custom_segmentation.md#growing-labels-afterwards-dilation).
 
 ## Using it in the Snakemake workflow
 
 No dedicated wiring needed — `patchworks.plugins.dog` exposes a `segment(tile, **kwargs)`
-adapter for the documented [`"custom"` method](../guide/snakemake.md#custom-segmentation-function):
+adapter for the documented [`"custom"` method](../guide/custom_segmentation.md):
 
 ```yaml
 method: "custom"
@@ -185,6 +185,6 @@ Checklist specific to this config:
 
 Segment the cell body with Cellpose and the cilia with `dog_label_fn` as two
 separate `tile_process` runs (same image, same `tile_shape`), then use
-[`label_relations`](../guide/snakemake.md#relating-labels-across-segmentations)
+[`label_relations`](../guide/label_relations.md)
 to map each cilium to the cell it belongs to — see
 `workflow/config/multi.yaml` for the same thing wired up as a cluster job.

docs/guide/custom_segmentation.md

@@ -0,0 +1,154 @@
+# Custom segmentation function
+
+Not using Cellpose? Run **your own** per-tile function — no need to edit the
+package. You write one function; patchworks handles everything around it
+(tiling, halos, skipping empty tiles, the zarr-native merge, global
+relabelling, resume, logs).
+
+This applies the same whether you call the API directly (`tile_process`) or
+run via the [Snakemake cluster workflow](snakemake.md) — see [Wiring it into
+the cluster workflow](#wiring-it-into-the-cluster-workflow) below for the
+config side.
+
+## The contract
+
+Your function is called **once per tile**:
+
+```python
+labels = segment(tile)          # plus any kwargs you configure
+```
+
+| | What you get / must return |
+| --- | --- |
+| **Input `tile`** | A NumPy array of **one** tile, with the overlap halo already included. The channel and pyramid level are already selected, so it is purely spatial: `(z, y, x)` for a 3-D run, `(y, x)` for 2-D. Dtype is the image's (e.g. `uint16`). |
+| **Return** | An integer **label** array (not a boolean mask), **same shape** as `tile`. `0` = background; each object a distinct positive integer. |
+| **Labels** | Only need to be unique **within the tile**. Don't try to make them globally unique — the merge step stitches objects across tile borders and renumbers everything to a contiguous `1..N` (`sequential_labels: true`). |
+| **Shape** | Must match the input exactly — patchworks trims the halo off your output, so a wrong shape is an error. Don't crop or resize inside the function. |
+
+That is the whole interface. Anything that turns an image tile into a label
+image works: classic image processing, StarDist, a trained model, an external
+binary you shell out to, …
+
+## Minimal example (no GPU, no deps beyond scikit-image)
+
+```python
+# my_seg.py
+import numpy as np
+from skimage.measure import label
+
+def segment(tile: np.ndarray, sigma: float = 2.0) -> np.ndarray:
+    """Threshold + connected components. Returns int32 labels (0 = bg)."""
+    from skimage.filters import gaussian, threshold_otsu
+
+    smooth = gaussian(tile, sigma=sigma, preserve_range=True)
+    thr = threshold_otsu(smooth) if smooth.max() > smooth.min() else np.inf
+    return label(smooth > thr).astype("int32")
+```
+
+```python
+from patchworks import tile_process
+from my_seg import segment
+
+tile_process("image.zarr", segment, write_to="labels.zarr")
+```
+
+## Growing labels afterwards (dilation)
+
+To grow every label by a few pixels after segmentation, wrap your function
+with [`patchworks.dilate_labels`](../api/postprocess.md):
+
+```python
+from patchworks import tile_process, dilate_labels
+from patchworks.plugins.dog import dog_label_fn
+
+fn = dog_label_fn(low_sigma=1.0, high_sigma=3.0, threshold=0.02)
+fn = dilate_labels(fn, iterations=2)   # grow each label by 2 px, then run
+result = tile_process("image.zarr", fn, tile_shape=(1, 2048, 2048),
+                       overlap=8, write_to="labels.zarr")
+```
+
+`dilate_labels` wraps any `(tile) -> labels` function — the same contract
+above — so it works with `dog_label_fn`, `cellpose_fn`, or your own
+`segment`. It dilates each tile's labels before the halo is trimmed and
+tiles are merged, so `overlap` must still cover the dilation amount. On the
+cluster, set `dilate: N` in the config instead — see [Configure the
+run](snakemake.md#3-configure-the-run).
+
+## Real example: StarDist 3-D, with model caching
+
+Heavy models must be loaded **once**, not per tile. On SLURM each tile is its
+own process so this matters less, but for local runs one process segments many
+tiles — cache the model at module level (or with `functools.lru_cache`):
+
+```python
+# stardist_seg.py
+import numpy as np
+
+_MODEL = None
+
+def _model():
+    global _MODEL
+    if _MODEL is None:                       # loaded once per worker process
+        from stardist.models import StarDist3D
+        _MODEL = StarDist3D.from_pretrained("3D_demo")
+    return _MODEL
+
+def segment(tile: np.ndarray, prob_thresh: float = 0.5) -> np.ndarray:
+    from csbdeep.utils import normalize
+
+    labels, _ = _model().predict_instances(
+        normalize(tile), prob_thresh=prob_thresh
+    )
+    return labels.astype("int32")
+```
+
+Using a GPU? Just let your framework see it — nothing extra needed.
+
+## Test it before you submit
+
+Run your function on one real tile first — it catches shape/dtype bugs in
+seconds instead of after a queue wait (or a long local run). Output must be
+integer, same shape, `0` for background:
+
+```python
+from patchworks import load_ome_zarr
+from my_seg import segment
+
+img = load_ome_zarr("results/image.zarr", channel=0, level=0)
+tile = img[:, :512, :512].compute()      # a small spatial block
+out = segment(tile)
+
+assert out.shape == tile.shape, (out.shape, tile.shape)
+assert out.dtype.kind in "iu"            # integer labels, not a float mask
+print("objects in tile:", int(out.max()))
+```
+
+## Wiring it into the cluster workflow
+
+Point the config at your module and function:
+
+```yaml
+method: "custom"
+label_name: "my_labels"
+custom:
+  module: "my_seg"        # import name
+  function: "segment"     # default is "segment"
+  kwargs:                 # optional — forwarded as segment(tile, **kwargs)
+    sigma: 1.5
+```
+
+Same for the StarDist example above:
+
+```yaml
+method: "custom"
+label_name: "stardist"
+custom:
+  module: "stardist_seg"
+  function: "segment"
+  kwargs:
+    prob_thresh: 0.5
+```
+
+For getting the module importable on a compute node, dependency/GPU
+checklist, and troubleshooting, see [Custom functions on the
+cluster](snakemake.md#custom-segmentation-function) in the cluster guide.

docs/guide/label_relations.md

@@ -0,0 +1,44 @@
+# Relating labels across segmentations
+
+Once you have two segmentations of the same image (e.g. nuclei inside cells),
+`label_relations()` maps each label in one to the label it overlaps most in
+the other — by streaming both arrays chunk by chunk, so it scales to
+hundreds of thousands of objects without loading anything fully into RAM.
+
+Both label arrays must share the exact same chunk layout — same
+`tile_shape`/pyramid `level` when they were produced.
+
+```python
+import dask.array as da
+from patchworks import label_relations
+
+nuclei = da.from_zarr("results/image.zarr", component="labels/nuclei_labels/0")
+cells = da.from_zarr("results/image.zarr", component="labels/cyto_labels/0")
+
+table = label_relations(nuclei, cells)
+table[2]
+# {'match': 3, 'overlap_voxels': 4821, 'overlap_fraction': 0.94}
+# -> nucleus 2 belongs to cell 3, 94% of its voxels fall inside it
+```
+
+`table` only contains matched `a` labels (nuclei with at least one
+overlapping voxel in `cells`) — unmatched labels and full per-`b` coverage
+need a bit more bookkeeping (the [cluster workflow's `run_multi.py`
+script](snakemake.md#one-command-multiple-segmentations--relations) does
+this for you and writes it as a two-sheet workbook).
+
+Save it as a table yourself:
+
+```python
+import csv
+
+with open("nuclei_to_cell.csv", "w", newline="") as f:
+    w = csv.writer(f)
+    w.writerow(["nucleus_id", "cell_id", "overlap_voxels", "overlap_fraction"])
+    for nucleus_id, m in table.items():
+        w.writerow([nucleus_id, m["match"], m["overlap_voxels"], m["overlap_fraction"]])
+```
+
+On the cluster, producing the two label stores in the first place is a
+matter of running the workflow twice against the same `work_dir` — see
+[Running two segmentations](snakemake.md#running-two-segmentations-eg-nuclei--cytoplasm).

docs/guide/measurements.md

@@ -0,0 +1,48 @@
+# Measurements (fast, whole-volume regionprops)
+
+`skimage.measure.regionprops` needs the full labelled + intensity array in
+RAM — fine for one tile, not for a hundred-thousand-object OME-ZARR.
+
+## Interactively, in napari
+
+[napari-chunked-regionprops](https://github.com/imcf/napari-chunked-regionprops)
+is built for this — its "Measure" dock widget computes area/centroid/intensity
+stats directly off a Labels layer's dask/zarr-backed array, out-of-core, and
+scales with chunk count rather than object count. It's the best fit for
+measuring *every* object in a store this size, not just a cropped region —
+see [View image + labels in napari](ome_zarr_napari.md#view-image--labels-in-napari).
+Bundled in `patchworks[napari]`.
+
+For interactively inspecting individual cells by clicking in the viewer (not
+all objects at once), the
+[napari-skimage-regionprops](https://github.com/haesleinhuepf/napari-skimage-regionprops)
+plugin's table widget also works well — point it at a cropped region rather
+than the full volume, since it loads its input fully into memory.
+
+## Headless / scripted
+
+Use [`dask-image`](https://image.dask.org)'s `ndmeasure`, which computes
+directly on the dask/zarr-backed arrays, chunk-parallel, without
+materializing the volume:
+
+```bash
+pip install dask-image
+```
+
+```python
+import dask.array as da
+from dask_image.ndmeasure import area, center_of_mass, mean, standard_deviation
+
+labels = da.from_zarr("results/image.zarr", component="labels/cyto_labels/0")
+image = da.from_zarr("results/image.zarr", component="0")[0]  # channel 0, level 0
+
+ids = da.unique(labels[labels > 0]).compute()
+areas = area(image, labels, ids).compute()               # voxel counts
+means = mean(image, labels, ids).compute()                # mean intensity
+stds = standard_deviation(image, labels, ids).compute()
+centroids = center_of_mass(image, labels, ids).compute()  # voxel coords (z, y, x)
+```
+
+Multiply `areas` by the voxel's physical volume and `centroids` by the pixel
+size (both read straight from the OME-ZARR's own `multiscales` metadata) to
+get µm-scale measurements.

docs/guide/ome_zarr_napari.md

@@ -159,7 +159,7 @@ just one channel instead: `view_in_napari("scan.zarr", channel=0)`.
     out-of-core straight off the Labels layer's backing dask/zarr array, so
     it scales to the same huge label images `tile_process` writes, unlike
     plain `skimage.measure.regionprops`. Bundled in `patchworks[napari]`. See
-    [Measurements](snakemake.md#measurements-fast-whole-volume-regionprops)
+    [Measurements](measurements.md)
     for the non-interactive/headless equivalent.
 
 ## End-to-end