merge dev into main

Clarifies that cupy always needs a manual install (README, getting
started, custom segmentation guide) and adds the dog extra to both
install lists.

Author: lguerard

README.md

@@ -40,6 +40,7 @@ pip install "patchworks[gpu]"       # GPU VRAM querying (nvidia-ml-py)
 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[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
@@ -52,6 +53,14 @@ pip install "patchworks[all]"       # Everything, incl. the napari viewer
 > `[imaris]` adds native `.ims` support (HDF5, no JVM). Physical pixel
 > calibration is read from the input and written into the OME-ZARR.
 
+> **`cupy` is never installed automatically**, unlike Cellpose's GPU support
+> (which comes for free via PyTorch's self-contained CUDA wheels). Any
+> `use_gpu=True`/`dilate_gpu: true` option (the `dog` plugin, `dilate_labels`)
+> needs `cupy` installed separately, matching your CUDA version — e.g.
+> `pip install cupy-cuda12x`. Not bundled because cupy ships one wheel per
+> CUDA major version; a generic pin would resolve to the wrong build (or fail
+> to resolve) depending on the machine.
+
 ---
 
 ## Quick start — 5 lines
@@ -307,10 +316,14 @@ Optional:
 - `tqdm` — progress bars
 - `cellpose` — Cellpose plugin, v3 or v4 (`patchworks[cellpose]`);
   pin with `[cellpose3]` or `[cellpose4]`
+- `pycudadecon` — deconvolution step of the `dog` plugin (`patchworks[dog]`)
 - `bioio` + readers — convert CZI/LIF/ND2/OME-TIFF/… to OME-ZARR
   (`patchworks[bioio]`)
 - `imaris-ims-file-reader` — convert Imaris `.ims` (`patchworks[imaris]`)
 - `napari` — interactive viewer plugin (`patchworks[napari]`)
+- `cupy` — **install manually**, matching your CUDA version (e.g.
+  `pip install cupy-cuda12x`); not offered as an extra since it isn't one
+  generic pin. Needed for `use_gpu=True`/`dilate_gpu: true`.
 
 ---
 

docs/getting_started.md

@@ -36,12 +36,25 @@ patchworks can be installed from PyPI on all operating systems, for Python ≥ 3
     pip install "patchworks[cellpose]"
     ```
 
+=== "With deconvolution + DoG plugin"
+
+    ```bash
+    pip install "patchworks[dog]"
+    ```
+
 === "Everything"
 
     ```bash
     pip install "patchworks[all]"
     ```
 
+!!! note "cupy is always a manual install"
+    `use_gpu=True` (the `dog` plugin, `dilate_labels`) needs `cupy`, but it's
+    never pulled in automatically — unlike Cellpose, which gets GPU support
+    for free via PyTorch's self-contained CUDA wheels, `cupy` ships one wheel
+    per CUDA major version. Install the one matching your CUDA version
+    yourself, e.g. `pip install cupy-cuda12x`.
+
 ---
 
 ## The one function you need

docs/guide/custom_segmentation.md

@@ -78,10 +78,15 @@ By default the dilation itself runs on CPU (scipy), independent of whatever
 backend `fn` used — pass `use_gpu=True` to dilate via cupy instead:
 
 ```python
-fn = dilate_labels(fn, iterations=2, use_gpu=True)  # needs cupy installed
+fn = dilate_labels(fn, iterations=2, use_gpu=True)
 ```
 
-On the cluster, this is the `dilate_gpu: true` config key.
+Needs `cupy` installed **manually**, matching your CUDA version (e.g.
+`pip install cupy-cuda12x`) — it's never installed automatically by
+patchworks, unlike Cellpose's GPU support (which comes for free via
+PyTorch's self-contained CUDA wheels); cupy ships one wheel per CUDA major
+version, so there's no single generic pin that works everywhere. On the
+cluster, this is the `dilate_gpu: true` config key.
 
 ## Real example: StarDist 3-D, with model caching