patchworks 3.0.0__tar.gz → 3.2.0__tar.gz

{patchworks-3.0.0 → patchworks-3.2.0}/.github/min-versions.txt

@@ -4,3 +4,4 @@ dask==2024.10.0
 numpy==1.26.0
 zarr==3.1.3
 scipy==1.11.1
+pandas==2.0.3

{patchworks-3.0.0 → patchworks-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchworks
-Version: 3.0.0
+Version: 3.2.0
 Summary: Tiled processing of arbitrarily large images with globally consistent labels
 Project-URL: Homepage, https://github.com/imcf/patchworks
 Project-URL: Issues, https://github.com/imcf/patchworks/issues
@@ -52,6 +52,8 @@ Requires-Dist: bioio-lif; extra == 'bioio'
 Requires-Dist: bioio-nd2; extra == 'bioio'
 Requires-Dist: bioio-ome-tiff; extra == 'bioio'
 Requires-Dist: bioio-tifffile; extra == 'bioio'
+Provides-Extra: careamics
+Requires-Dist: careamics>=0.3; extra == 'careamics'
 Provides-Extra: cellpose
 Requires-Dist: cellpose>=3.0; extra == 'cellpose'
 Provides-Extra: cellpose3
@@ -62,6 +64,7 @@ Provides-Extra: dev
 Requires-Dist: jsonschema>=4.18; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: openpyxl; extra == 'dev'
+Requires-Dist: pandas>=2.0; extra == 'dev'
 Requires-Dist: psutil; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
@@ -92,8 +95,13 @@ Requires-Dist: numpy<2.5; extra == 'napari'
 Requires-Dist: pyqt6<6.10; extra == 'napari'
 Provides-Extra: remote
 Requires-Dist: fsspec[gcs,http,s3]; extra == 'remote'
+Provides-Extra: review
+Requires-Dist: openpyxl; extra == 'review'
+Requires-Dist: pandas>=2.0; extra == 'review'
 Provides-Extra: workflow
 Requires-Dist: openpyxl; extra == 'workflow'
+Requires-Dist: pandas>=2.0; extra == 'workflow'
+Requires-Dist: scikit-image; extra == 'workflow'
 Requires-Dist: snakemake-executor-plugin-slurm; extra == 'workflow'
 Requires-Dist: snakemake>=8; extra == 'workflow'
 Description-Content-Type: text/markdown
@@ -149,6 +157,7 @@ pip install "patchworks[cellpose]"  # Cellpose plugin (>=3.0, v3 or v4)
 pip install "patchworks[cellpose3]" # Cellpose plugin, pinned to v3.x
 pip install "patchworks[cellpose4]" # Cellpose plugin, pinned to v4+
 pip install "patchworks[dog]"       # deconvolution + DoG plugin (pycudadecon)
+pip install "patchworks[careamics]" # Noise2Void denoising before segmenting
 pip install "patchworks[bioio]"     # convert any image format to OME-ZARR
 pip install "patchworks[imaris]"    # convert Imaris .ims files to OME-ZARR
 pip install "patchworks[napari]"    # interactive napari viewer plugin
@@ -284,6 +293,16 @@ Pyramids downsample **X/Y only** (Z kept full-res) and are built level-by-level
 from disk, so terabyte volumes convert in bounded RAM. See the
 [OME-ZARR & napari guide](https://imcf.one/patchworks/guide/ome_zarr_napari/).
 
+### Check and correct the result
+
+Every label image comes with an object table (size, position, which cell
+each nucleus or cilium is in). `patchworks review scan.zarr` opens napari on
+the objects most likely to be wrong — a cilium in no cell, a cell with two
+nuclei, a nucleus cut in two at a tile seam — one at a time; one key
+accepts, rejects, reassigns or joins. The corrections flow into the tables
+and workbooks. See
+[Reviewing and correcting results](https://imcf.one/patchworks/guide/review/).
+
 ---
 
 ## From the command line
@@ -442,6 +461,13 @@ Optional:
 - `cellpose` — Cellpose plugin, v3 or v4 (`patchworks[cellpose]`);
   pin with `[cellpose3]` or `[cellpose4]`
 - `pycudadecon` — deconvolution step of the `dog` plugin (`patchworks[dog]`)
+- `careamics` — denoise tiles before segmenting them (Noise2Void),
+  `patchworks[careamics]`
+- `plant-seg` — PlantSeg plugin (boundary U-Net + GASP/multicut), from
+  conda-forge only (`conda install -c conda-forge plant-seg`, or the
+  workflow's `pixi install -e plantseg`). The nuclei-seeded watershed plugin
+  needs only scikit-image. See the
+  [membrane cells guide](https://imcf.one/patchworks/guide/membrane_cells/).
 - `bioio` + readers — convert CZI/LIF/ND2/OME-TIFF/… to OME-ZARR
   (`patchworks[bioio]`)
 - `imaris-ims-file-reader` — convert Imaris `.ims` (`patchworks[imaris]`)

{patchworks-3.0.0 → patchworks-3.2.0}/README.md

@@ -49,6 +49,7 @@ pip install "patchworks[cellpose]"  # Cellpose plugin (>=3.0, v3 or v4)
 pip install "patchworks[cellpose3]" # Cellpose plugin, pinned to v3.x
 pip install "patchworks[cellpose4]" # Cellpose plugin, pinned to v4+
 pip install "patchworks[dog]"       # deconvolution + DoG plugin (pycudadecon)
+pip install "patchworks[careamics]" # Noise2Void denoising before segmenting
 pip install "patchworks[bioio]"     # convert any image format to OME-ZARR
 pip install "patchworks[imaris]"    # convert Imaris .ims files to OME-ZARR
 pip install "patchworks[napari]"    # interactive napari viewer plugin
@@ -184,6 +185,16 @@ Pyramids downsample **X/Y only** (Z kept full-res) and are built level-by-level
 from disk, so terabyte volumes convert in bounded RAM. See the
 [OME-ZARR & napari guide](https://imcf.one/patchworks/guide/ome_zarr_napari/).
 
+### Check and correct the result
+
+Every label image comes with an object table (size, position, which cell
+each nucleus or cilium is in). `patchworks review scan.zarr` opens napari on
+the objects most likely to be wrong — a cilium in no cell, a cell with two
+nuclei, a nucleus cut in two at a tile seam — one at a time; one key
+accepts, rejects, reassigns or joins. The corrections flow into the tables
+and workbooks. See
+[Reviewing and correcting results](https://imcf.one/patchworks/guide/review/).
+
 ---
 
 ## From the command line
@@ -342,6 +353,13 @@ Optional:
 - `cellpose` — Cellpose plugin, v3 or v4 (`patchworks[cellpose]`);
   pin with `[cellpose3]` or `[cellpose4]`
 - `pycudadecon` — deconvolution step of the `dog` plugin (`patchworks[dog]`)
+- `careamics` — denoise tiles before segmenting them (Noise2Void),
+  `patchworks[careamics]`
+- `plant-seg` — PlantSeg plugin (boundary U-Net + GASP/multicut), from
+  conda-forge only (`conda install -c conda-forge plant-seg`, or the
+  workflow's `pixi install -e plantseg`). The nuclei-seeded watershed plugin
+  needs only scikit-image. See the
+  [membrane cells guide](https://imcf.one/patchworks/guide/membrane_cells/).
 - `bioio` + readers — convert CZI/LIF/ND2/OME-TIFF/… to OME-ZARR
   (`patchworks[bioio]`)
 - `imaris-ims-file-reader` — convert Imaris `.ims` (`patchworks[imaris]`)

patchworks-3.2.0/docs/api/plugins/careamics.md

@@ -0,0 +1,11 @@
+# CAREamics denoising plugin
+
+See [Denoising first](../../guide/membrane_cells.md#denoising-first-careamics).
+
+::: patchworks.plugins.careamics.denoise_fn
+
+::: patchworks.plugins.careamics.denoise
+
+::: patchworks.plugins.careamics.train_n2v
+
+::: patchworks.plugins.careamics.training_crops

patchworks-3.2.0/docs/api/plugins/plantseg.md

@@ -0,0 +1,11 @@
+# PlantSeg plugin
+
+See [Cells from a membrane stain](../../guide/membrane_cells.md#plantseg).
+
+::: patchworks.plugins.plantseg.plantseg_fn
+
+::: patchworks.plugins.plantseg.fetch_model
+
+::: patchworks.plugins.plantseg.available_models
+
+::: patchworks.plugins.plantseg.rescale_factors

patchworks-3.2.0/docs/api/plugins/watershed.md

@@ -0,0 +1,11 @@
+# Nuclei-seeded watershed plugin
+
+See [Cells from a membrane stain](../../guide/membrane_cells.md).
+
+::: patchworks.plugins.watershed.watershed_fn
+
+::: patchworks.plugins.watershed.nuclei_seeds
+
+::: patchworks.plugins.watershed.foreground_mask
+
+::: patchworks.plugins.watershed.seeded_watershed

patchworks-3.2.0/docs/api/review.md

@@ -0,0 +1,19 @@
+# Object tables and review
+
+See [Reviewing and correcting results](../guide/review.md) for the workflow.
+
+::: patchworks.measure_objects
+
+::: patchworks.compute_table
+
+::: patchworks.relate_tables
+
+::: patchworks._tables.nearest_parents
+
+::: patchworks._tables.shape_columns
+
+::: patchworks.read_table
+
+::: patchworks.Review
+
+::: patchworks.plugins.review.review_in_napari

{patchworks-3.0.0 → patchworks-3.2.0}/docs/guide/cli.md

@@ -19,8 +19,23 @@ patchworks seams scan.zarr/labels/labels --tile-shape 16,1024,1024
 
 # Look at the result (needs patchworks[napari])
 patchworks view scan.zarr
+
+# One row per object; which cell each nucleus is in
+patchworks tables scan.zarr --relate nuclei:cells
+
+# Look at the likely mistakes one by one and fix them (napari)
+patchworks review scan.zarr --expect cells:nuclei=1
 ```
 
+`patchworks review` without a window: `--summary` (counts and error
+estimate), `--export DIR --format csv|xlsx|parquet` (corrected tables),
+`--workbooks DIR` (relation workbooks), `--write-labels NAME` (a label image
+with the corrections applied). `--position CHILD:PARENT=APICAL` classifies
+children as apical/basal/lateral/central (APICAL: `+z`, or a label image to
+point away from, such as the nuclei); `patchworks tables --max-distance UM`
+gives a child touching no parent the nearest one. See
+[Reviewing and correcting results](review.md).
+
 ## Segmentation methods
 
 | `--method` | What it does | Main flags |
@@ -31,7 +46,16 @@ patchworks view scan.zarr
 | `custom` | any importable function | `--fn module:function`, `--fn-kwargs '{"k": 1}'` |
 
 Cellpose's anisotropy and the DoG plugin's voxel size are read from the
-store's own calibration, at the level being segmented.
+store's own calibration, at the level being segmented -- as is `voxel_size`
+for a custom function that takes one, such as the PlantSeg and watershed
+plugins: `--method custom --fn patchworks.plugins.plantseg:segment
+--fn-kwargs '{"segmentation": "gasp"}' --stitch iou` (`iou`: these fill
+space, so neighbouring cells touch at every seam).
+
+`--denoise MODEL` denoises every tile with a CAREamics model before any
+method segments it; `patchworks denoise-train STORE --channel 0 --out
+n2v.ckpt` trains one (Noise2Void, no ground truth). See
+[Cells from a membrane stain](membrane_cells.md).
 
 Tiling and stitching take the same options as
 [`tile_process`](../api/tile_process.md): `--tile-shape` (`z,y,x`, `auto` or

{patchworks-3.0.0 → patchworks-3.2.0}/docs/guide/custom_segmentation.md

@@ -29,6 +29,14 @@ 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, …
 
+Ready-made ones ship with patchworks: `patchworks.plugins.dog` (spots,
+cilia), and for cells from a membrane stain `patchworks.plugins.watershed`
+(nuclei-seeded watershed) and `patchworks.plugins.plantseg` (PlantSeg) --
+see [Cells from a membrane stain](membrane_cells.md). With
+`nuclei_channel` set, the tile is `(2, z, y, x)`: `[channel,
+nuclei_channel]` on the first axis. Any method can also run on
+[denoised tiles](membrane_cells.md#denoising-first-careamics).
+
 ## Minimal example (no GPU, no deps beyond scikit-image)
 
 ```python

{patchworks-3.0.0 → patchworks-3.2.0}/docs/guide/label_relations.md

@@ -53,6 +53,14 @@ with open("nuclei_to_cell.csv", "w", newline="") as f:
         w.writerow([nucleus_id, m["match"], m["overlap_voxels"], m["overlap_fraction"]])
 ```
 
+To keep the result with the labels instead, as columns of the object
+tables (the corrections made in
+[`patchworks review`](review.md) then apply to it):
+
+```bash
+patchworks tables results/image.zarr --relate nuclei_labels:cyto_labels
+```
+
 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).

{patchworks-3.0.0 → patchworks-3.2.0}/docs/guide/measurements.md

@@ -3,6 +3,26 @@
 `skimage.measure.regionprops` needs the full labelled + intensity array in
 RAM — fine for one tile, not for a hundred-thousand-object OME-ZARR.
 
+## Already measured: the object tables
+
+The workflow measures every object once, right after the merge: size
+(`area_voxels`, `area_um3`), centroid, bounding box and spread (second
+moments, from which the corrected view derives `length_um`, `elongation`
+and the main axis), plus mean/std intensity for the channels listed in
+`table_channels`. The table is stored
+with the labels (`image.zarr/labels/<name>/table`):
+
+```python
+from patchworks import read_table
+
+cells = read_table("results/image.zarr/labels/cyto_labels")  # pandas
+```
+
+For a store without one, `patchworks tables results/image.zarr --channels 0,1`
+adds them. With review corrections applied, and as csv files that
+napari-chunked-regionprops loads directly: `patchworks review
+results/image.zarr --export tables/` (see [Reviewing](review.md)).
+
 ## Interactively, in napari
 
 [napari-chunked-regionprops](https://github.com/imcf/napari-chunked-regionprops)

patchworks-3.2.0/docs/guide/membrane_cells.md

@@ -0,0 +1,253 @@
+# Cells from a membrane stain
+
+Epithelia, organoids and tissues are often imaged with a **membrane** (or
+cortex) marker plus a **nuclear** dye. Cellpose struggles there in a
+recognisable way: Cellpose 4 (`cpsam`) reads every channel it is given
+without a "cytoplasm" or "nucleus" role, so with a bright nuclear channel
+next to a faint membrane it segments the **nuclei**; and on the membrane
+alone, a wall that is faint in places merges two cells. Patchworks ships
+three plugins for this case, plus an optional denoising step in front of any
+method.
+
+| | Needs | Cells come from | Best when |
+| --- | --- | --- | --- |
+| [Nuclei-seeded watershed](#nuclei-seeded-watershed) | scikit-image | the membrane, flooded from the nuclei | every cell has one nucleus; start here |
+| [PlantSeg](#plantseg) | `plant-seg` (conda-forge) | a boundary U-Net, then GASP / multicut | the membrane is uneven or noisy |
+| [PlantSeg + nuclei](#plantseg) | same | the U-Net's boundaries and the nuclei | both of the above |
+| Cellpose, membrane only | cellpose | Cellpose | `nuclei_channel: null`, `do_3D: true` |
+| [Denoising first](#denoising-first-careamics) | `careamics` | any of these, on denoised tiles | noisy acquisitions |
+
+All of them are ordinary [custom functions](custom_segmentation.md): one
+config block, the same tiling, merge, tables and review as any other run.
+
+## Nuclei-seeded watershed
+
+The nuclei are the easy part of the image: bright, compact, separated. They
+say how many cells there are and where; flooding the membrane image from
+them grows each nucleus out to its cell's walls. A cell can then not be
+split (one seed each) or merged with its neighbour (two seeds never join),
+even across a gap in the wall.
+
+```yaml
+channel: 0              # membrane
+nuclei_channel: 1       # stacked onto each tile as [membrane, nuclei]
+method: "custom"
+label_name: "cyto_labels"
+stitch: "iou"           # required: see below
+custom:
+  module: "patchworks.plugins.watershed"
+  kwargs:
+    nuclei_min_size: 200    # voxels: specks smaller than a nucleus
+    foreground: "otsu"      # stop at the tissue edge
+    # max_radius_um: 15     # or: no further than this from the nucleus
+    # nuclei_threshold: 800 # intensity, if Otsu misses dim nuclei
+```
+
+`stitch: "iou"` is required with this plugin and with PlantSeg, and
+`prepare` refuses the config without it. They give every voxel to some
+cell, so neighbouring cells touch at every tile seam, and the default
+`"touch"` stitching would join each such pair: on a test grid of 12 cells
+cut by six tiles, 5 came out. `"iou"` joins two pieces only where both tiles
+agree on their overlap, and gives the 12. (From the command line, pass
+`--stitch iou` yourself: nothing checks it there.)
+
+Two nuclei touching each other give one seed, so one cell for two: raise
+`nuclei_threshold` if that happens -- or grow the cells from nuclei you have
+already segmented, with `seed_labels` instead of `nuclei_channel` (see
+[the example below](#how-seed_labels-works)). Each tile's halo (`overlap`) must hold a
+whole cell, as for any method.
+
+## PlantSeg
+
+[PlantSeg](https://github.com/kreshuklab/plant-seg) predicts cell
+boundaries with a 3-D U-Net trained on membrane stains, then partitions the
+boundary map into cells (supervoxels by a distance-transform watershed,
+merged by GASP, mutex watershed or multicut). A wall the U-Net sees at all
+gets closed by the partitioning, where Cellpose would merge across it.
+
+PlantSeg is on conda-forge only, so it has its own pixi environment:
+
+```bash
+pixi install -e plantseg
+pixi run -e plantseg plantseg-fetch generic_confocal_3D_unet   # once, with internet
+pixi run -e plantseg multi-slurm
+```
+
+```yaml
+method: "custom"
+stitch: "iou"                           # required, as for the watershed
+custom:
+  module: "patchworks.plugins.plantseg"
+  kwargs:
+    model: "generic_confocal_3D_unet"   # or generic_light_sheet_3D_unet, ...
+    segmentation: "gasp"                # gasp | mutex_ws | multicut | dt_watershed
+    beta: 0.6                           # lower merges more, higher splits more
+    foreground: "otsu"                  # a boundary U-Net puts cells everywhere
+```
+
+With `nuclei_channel` set, two more `segmentation` modes use the nuclei:
+
+- `"nuclei_watershed"` -- the U-Net's boundary map flooded from the nuclei:
+  the watershed above, on a much cleaner boundary image.
+- `"lifted_multicut"` -- PlantSeg's lifted multicut: supervoxels in one
+  nucleus pulled together, in different nuclei pushed apart.
+
+Each tile is resampled to the voxel size the model was trained at (from the
+image's own calibration, `rescale: true`), which matters more than any other
+setting for a pretrained U-Net; the prediction is resampled back.
+
+## Example: Cellpose nuclei + PlantSeg cells in one run
+
+The workflow ships this pairing ready to edit: Cellpose segments the nuclei,
+then PlantSeg grows the cells from **exactly those nuclei** -- one cell per
+nucleus Cellpose found -- and the two are related. Three files, next to
+`config/multi.yaml`:
+
+```yaml
+# config/multi_plantseg.yaml
+common: config/common.yaml           # input, work_dir, tile_shape, level: shared
+
+segmentations:
+- config/config_nuclei.yaml          # Cellpose "nuclei" model on channel 1
+- config/config_cyto_plantseg.yaml   # PlantSeg on channel 0, seeded by nuclei_labels
+
+relations:
+- a: nuclei_labels
+  b: cyto_labels
+  output: nuclei_to_cyto.xlsx
+
+review:                              # a sanity check: one nucleus per cell
+  expect:
+    cyto_labels:
+      nuclei_labels: 1
+```
+
+```yaml
+# config/config_nuclei.yaml (unchanged)
+channel: 1
+overlap: [4, 30, 30]
+method: "cellpose"
+label_name: "nuclei_labels"
+cellpose:
+  model: "nuclei"
+  diameter: 15
+  do_3D: true
+  gpu: true
+```
+
+```yaml
+# config/config_cyto_plantseg.yaml
+channel: 0                  # membrane
+seed_labels: "nuclei_labels" # each tile becomes [membrane, nuclei labels]
+overlap: [4, 40, 40]        # the halo must hold a whole cell
+stitch: "iou"               # cells touch at every seam: join on agreement only
+method: "custom"
+label_name: "cyto_labels"
+custom:
+  module: "patchworks.plugins.plantseg"
+  function: "segment"
+  kwargs:
+    model: "generic_confocal_3D_unet"   # generic_light_sheet_3D_unet for light-sheet
+    segmentation: "nuclei_watershed"    # U-Net boundaries flooded from the nuclei
+    foreground: "otsu"                  # keep the tissue only
+    # max_radius_um: 15
+```
+
+Set `input` and `work_dir` in `config/common.yaml`, then, from `workflow/`:
+
+```bash
+pixi install -e plantseg
+pixi run -e plantseg plantseg-fetch generic_confocal_3D_unet   # once, with internet
+pixi run -e plantseg multi-plantseg-dry                        # check the plan
+pixi run -e plantseg multi-plantseg-slurm                      # submit
+```
+
+The `plantseg` environment is the default one plus PlantSeg, so the
+Cellpose run comes from it too. Afterwards, `nuclei_to_cyto.xlsx` gives
+each nucleus its cell, and `pixi run -e viewer review <work_dir>/image.zarr`
+lists any cell not holding exactly one nucleus.
+
+### How `seed_labels` works
+
+- **Order.** `run_multi` starts the cells' config only once the config
+  producing `nuclei_labels` has finished; everything else listed (cilia,
+  say) runs alongside. If the nuclei fail, the cells are skipped, not run
+  without seeds. Two configs seeding each other are refused up front. A
+  dry run (`-n`) waits for nothing.
+- **Tiles.** The nuclei label image is stacked onto the membrane as each
+  tile's second channel, halo included, so neighbouring tiles see the same
+  nuclei and a cell crossing a seam is grown from the same nucleus on both
+  sides. Both runs must use the same `level`, which `run_multi` already
+  enforces; the plugin is told `seeds: "labels"` automatically.
+- **Seeds as given.** Two touching nuclei that Cellpose split stay two
+  cells; a dim nucleus Cellpose found still gets its cell. Cellpose's
+  mistakes carry over the same way: a nucleus split in two makes two
+  cells. Correcting the nuclei first (`patchworks review`, then
+  `--write-labels nuclei_labels` and `seed_labels: nuclei_labels_reviewed`)
+  gives the cells the corrected nuclei.
+- **On its own**, outside `run_multi`, the cells' config needs
+  `labels/nuclei_labels` already in `image.zarr`: `prepare` checks, and
+  stops with a message rather than segmenting without seeds.
+- **Re-segmenting the nuclei** does not re-run the cells by itself: delete
+  `<work_dir>/cyto_labels` and `image.zarr/labels/cyto_labels` to grow them
+  again from the new nuclei.
+
+`nuclei_channel: 1` instead of `seed_labels` makes the plugin find the
+nuclei itself, in the nuclear stain (Otsu per tile, `nuclei_*` options),
+independently of Cellpose -- both segmentations then run at the same time.
+
+Without PlantSeg, the same works with the plain
+[nuclei-seeded watershed](#nuclei-seeded-watershed): set `module:
+"patchworks.plugins.watershed"` with only the `foreground` and
+`max_radius_um` keys, and use the default environment (`pixi run
+multi-slurm` with this pair listed in `config/multi.yaml`).
+
+## Cellpose: membrane only, in 3-D
+
+If you stay with Cellpose on such images:
+
+- Give it **only the membrane** (`nuclei_channel: null`): `cpsam` then has
+  nothing brighter to lock onto.
+- `do_3D: true` combines the three orthogonal views, so a wall faint in one
+  plane is found in the others. `stitch_threshold` instead joins
+  independent 2-D masks across z and fixes nothing in the masks
+  themselves. A GPU (`gpu: true`) only changes the speed.
+
+## Denoising first (CAREamics)
+
+Noise breaks segmentations: a wall lost in the noise merges two cells.
+[Noise2Void](https://careamics.github.io) learns to remove the noise from
+the image itself (no clean ground truth, no annotation), so a model trained
+once on a few crops of the store denoises every tile before any method sees
+it.
+
+```bash
+pixi install -e careamics
+# on a GPU node: the brightest crops of the channel, ~30 epochs
+pixi run -e careamics denoise-train <work_dir>/image.zarr --channel 0 --out n2v_membrane.ckpt
+pixi run -e careamics denoise-train <work_dir>/image.zarr --channel 1 --out n2v_nuclei.ckpt
+```
+
+then, in the segmentation config, with any `method`:
+
+```yaml
+denoise:
+  model: "/path/to/n2v_membrane.ckpt"      # .ckpt, or a BioImage.IO .zip
+  nuclei_model: "/path/to/n2v_nuclei.ckpt" # optional, for nuclei_channel
+  # tile_size: [16, 256, 256]              # CAREamics' tiling inside a tile (VRAM)
+```
+
+and run from the `careamics` environment (`plantseg-careamics` for both).
+The model paths are checked during `prepare`; the denoised image is not
+stored, only used for segmenting. From the command line, `patchworks segment
+... --denoise n2v_membrane.ckpt` does the same.
+
+Look at a denoised tile before a full run:
+
+```python
+from patchworks import load_ome_zarr
+from patchworks.plugins.careamics import denoise
+
+tile = load_ome_zarr("image.zarr", channel=0)[20:44, 1000:1512, 1000:1512]
+clean = denoise(tile.compute(), model="n2v_membrane.ckpt")
+```