patchworks 3.3.0__tar.gz → 3.4.0__tar.gz

patchworks-3.4.0/.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      - main
+  # Rebuild after each release so the version shown in the header refreshes.
+  release:
+    types: [published]
+  workflow_dispatch:
+
+# Published with GitHub Pages' own deployment (repository settings > Pages >
+# Source: GitHub Actions), not by pushing a gh-pages branch.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install docs dependencies
+        run: pip install "zensical>=0.0.72" "mkdocstrings[python]>=0.24" .
+
+      - name: Build
+        run: zensical build --clean
+
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

{patchworks-3.3.0 → patchworks-3.4.0}/.github/workflows/lint.yml

@@ -47,10 +47,10 @@ jobs:
           cache: pip
 
       - name: Install docs dependencies
-        run: pip install "mkdocs-material>=9.0" "mkdocstrings[python]>=0.24" .
+        run: pip install "zensical>=0.0.72" "mkdocstrings[python]>=0.24" .
 
-      - name: mkdocs build --strict
-        run: mkdocs build --strict
+      - name: zensical build --strict
+        run: zensical build --strict
 
   mypy:
     runs-on: ubuntu-latest

patchworks-3.4.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+site/
+.pytest_cache/
+*.log
+.snakemake/
+.pixi/
+
+# graft's local graph cache — regenerable, not committed (run `graft build`).
+graft/
+
+# Your own run configs (workflow/config/local/), and what the web launcher
+# writes into the workflow folder.
+workflow/config/local/
+workflow/config/templates/
+workflow/config/launcher_*
+workflow/.streamlit_launcher_logs/
+.cache/

patchworks-3.4.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.5
+Name: patchworks
+Version: 3.4.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
+Author-email: Laurent Guerard <laurent.guerard@unibas.ch>
+License: GPL-3.0-only
+License-File: LICENSE
+Keywords: bioimage,chunked,dask,image processing,segmentation,tiling,zarr
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.11
+Requires-Dist: dask[array]>=2024.10.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: psutil
+Requires-Dist: scipy>=1.11
+Requires-Dist: zarr>=3.1.3
+Provides-Extra: all
+Requires-Dist: bioio; extra == 'all'
+Requires-Dist: bioio-bioformats; extra == 'all'
+Requires-Dist: bioio-czi; extra == 'all'
+Requires-Dist: bioio-lif; extra == 'all'
+Requires-Dist: bioio-nd2; extra == 'all'
+Requires-Dist: bioio-ome-tiff; extra == 'all'
+Requires-Dist: bioio-tifffile; extra == 'all'
+Requires-Dist: dask[diagnostics,distributed]; extra == 'all'
+Requires-Dist: imaris-ims-file-reader; extra == 'all'
+Requires-Dist: ipykernel<7; extra == 'all'
+Requires-Dist: lxml-html-clean; extra == 'all'
+Requires-Dist: napari-chunked-regionprops>=0.1.0; extra == 'all'
+Requires-Dist: napari[all]>=0.7.1; extra == 'all'
+Requires-Dist: numpy<2.5; extra == 'all'
+Requires-Dist: nvidia-ml-py; extra == 'all'
+Requires-Dist: psutil; extra == 'all'
+Requires-Dist: pyqt6<6.10; extra == 'all'
+Requires-Dist: scikit-image; extra == 'all'
+Requires-Dist: tqdm; extra == 'all'
+Provides-Extra: bioio
+Requires-Dist: bioio; extra == 'bioio'
+Requires-Dist: bioio-bioformats; extra == 'bioio'
+Requires-Dist: bioio-czi; extra == 'bioio'
+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
+Requires-Dist: cellpose<4,>=3.0; extra == 'cellpose3'
+Provides-Extra: cellpose4
+Requires-Dist: cellpose>=4; extra == 'cellpose4'
+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'
+Requires-Dist: ruff==0.15.18; extra == 'dev'
+Requires-Dist: scikit-image; extra == 'dev'
+Requires-Dist: tqdm; extra == 'dev'
+Provides-Extra: distributed
+Requires-Dist: dask[diagnostics,distributed]; extra == 'distributed'
+Provides-Extra: docs
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Requires-Dist: zensical>=0.0.72; extra == 'docs'
+Provides-Extra: dog
+Requires-Dist: pycudadecon; extra == 'dog'
+Provides-Extra: gpu
+Requires-Dist: nvidia-ml-py; extra == 'gpu'
+Provides-Extra: imaris
+Requires-Dist: imaris-ims-file-reader; extra == 'imaris'
+Provides-Extra: io
+Requires-Dist: psutil; extra == 'io'
+Requires-Dist: tqdm; extra == 'io'
+Provides-Extra: napari
+Requires-Dist: ipykernel<7; extra == 'napari'
+Requires-Dist: lxml-html-clean; extra == 'napari'
+Requires-Dist: napari-chunked-regionprops>=0.1.0; extra == 'napari'
+Requires-Dist: napari[all]>=0.7.1; extra == 'napari'
+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>=2.2; extra == 'workflow'
+Requires-Dist: snakemake>=8; extra == 'workflow'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/imcf/patchworks/main/docs/assets/logo.svg" alt="patchworks logo" width="220">
+</p>
+
+# patchworks
+
+[![PyPI](https://img.shields.io/pypi/v/patchworks.svg)](https://pypi.org/project/patchworks/)
+[![Python versions](https://img.shields.io/pypi/pyversions/patchworks.svg)](https://pypi.org/project/patchworks/)
+[![License: GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Docs](https://img.shields.io/badge/docs-imcf.one%2Fpatchworks-blue)](https://imcf.one/patchworks/)
+
+> Tiled processing of arbitrarily large images — any image, any function.
+
+```text
+┌──────┬──────┬──────┐     fn(tile) → labels      ┌──────┬──────┬──────┐
+│ tile │ tile │ tile │  ─────────────────────►    │  1   │  2   │  3   │
+├──────┼──────┼──────┤                            ├──────┼──────┼──────┤
+│ tile │ tile │ tile │                            │  4   │  5   │  6   │   globally
+├──────┼──────┼──────┤                            ├──────┼──────┼──────┤   consistent
+│ tile │ tile │ tile │                            │  7   │  8   │  9   │   labels
+└──────┴──────┴──────┘                            └──────┴──────┴──────┘
+```
+
+patchworks splits an image too large for memory into tiles, runs **any
+segmentation function** on each tile, and stitches the results into one
+consistent label image — stored with the image in a single OME-Zarr, with a
+table of every object.
+
+> [!NOTE]
+> **On how this was written.** Large parts of patchworks were vibe coded —
+> written with heavy LLM assistance rather than line by line. It is covered by
+> a test suite and has been run on real data, so it is not untested, but the
+> usual caveats apply: read the code before you trust it with anything
+> irreplaceable, and please open an issue if something looks off.
+
+## Install
+
+```bash
+pip install patchworks                 # core
+pip install "patchworks[cellpose]"     # + Cellpose
+pip install "patchworks[bioio,imaris]" # + converting CZI/LIF/ND2/TIFF/.ims to OME-Zarr
+pip install "patchworks[napari]"       # + viewing and reviewing in napari
+pip install "patchworks[all]"          # everything above and more
+```
+
+GPU options of the DoG plugin need `cupy` matching your CUDA version
+(`pip install cupy-cuda12x`). PlantSeg is on conda-forge only. See
+[Getting started](https://imcf.one/patchworks/getting_started/) for every
+extra.
+
+## Three ways to use it
+
+**Python** — any function from a tile to labels:
+
+```python
+from patchworks import tile_process
+from patchworks.plugins.cellpose import cellpose_fn
+
+tile_process("scan.zarr", cellpose_fn("cyto3", gpu=True, diameter=30))
+```
+
+The labels go into `scan.zarr/labels/labels`, as a multiscale pyramid next
+to the image.
+
+**Command line** — the same building blocks, no script:
+
+```bash
+patchworks convert scan.czi scan.zarr
+patchworks segment scan.zarr --method cellpose --model cyto3 --diameter 30 --gpu
+patchworks view scan.zarr
+```
+
+**On a cluster** — a Snakemake workflow with a pixi environment: convert,
+segment tile batches as GPU jobs, merge, relate label images (which cell
+each nucleus is in), and bundle, from one YAML config per segmentation:
+
+```bash
+cd workflow
+pixi run multi-slurm --config my_multi.yaml
+```
+
+## What you get
+
+- **One OME-Zarr** holding the image and every label image, readable by
+  napari, Fiji and any OME-Zarr tool.
+- **Object tables** — size, position, shape — and **relations** between label
+  images (the cell of each nucleus, the position of each cilium in its cell),
+  exported as spreadsheets.
+- **Review in napari**: `patchworks review scan.zarr` steps through the
+  objects most likely to be wrong; corrections flow into the tables.
+- Plugins for **Cellpose**, **PlantSeg**, a **nuclei-seeded watershed**,
+  **difference of Gaussians** (cilia, spots) and **Noise2Void** denoising —
+  or bring your own function.
+
+## Documentation
+
+**<https://imcf.one/patchworks/>** — getting started, the cluster workflow,
+guides, examples and the API reference.
+
+## License
+
+GNU General Public License v3.0 (GPL-3.0). See [LICENSE](LICENSE).

patchworks-3.4.0/README.md

@@ -0,0 +1,102 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/imcf/patchworks/main/docs/assets/logo.svg" alt="patchworks logo" width="220">
+</p>
+
+# patchworks
+
+[![PyPI](https://img.shields.io/pypi/v/patchworks.svg)](https://pypi.org/project/patchworks/)
+[![Python versions](https://img.shields.io/pypi/pyversions/patchworks.svg)](https://pypi.org/project/patchworks/)
+[![License: GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Docs](https://img.shields.io/badge/docs-imcf.one%2Fpatchworks-blue)](https://imcf.one/patchworks/)
+
+> Tiled processing of arbitrarily large images — any image, any function.
+
+```text
+┌──────┬──────┬──────┐     fn(tile) → labels      ┌──────┬──────┬──────┐
+│ tile │ tile │ tile │  ─────────────────────►    │  1   │  2   │  3   │
+├──────┼──────┼──────┤                            ├──────┼──────┼──────┤
+│ tile │ tile │ tile │                            │  4   │  5   │  6   │   globally
+├──────┼──────┼──────┤                            ├──────┼──────┼──────┤   consistent
+│ tile │ tile │ tile │                            │  7   │  8   │  9   │   labels
+└──────┴──────┴──────┘                            └──────┴──────┴──────┘
+```
+
+patchworks splits an image too large for memory into tiles, runs **any
+segmentation function** on each tile, and stitches the results into one
+consistent label image — stored with the image in a single OME-Zarr, with a
+table of every object.
+
+> [!NOTE]
+> **On how this was written.** Large parts of patchworks were vibe coded —
+> written with heavy LLM assistance rather than line by line. It is covered by
+> a test suite and has been run on real data, so it is not untested, but the
+> usual caveats apply: read the code before you trust it with anything
+> irreplaceable, and please open an issue if something looks off.
+
+## Install
+
+```bash
+pip install patchworks                 # core
+pip install "patchworks[cellpose]"     # + Cellpose
+pip install "patchworks[bioio,imaris]" # + converting CZI/LIF/ND2/TIFF/.ims to OME-Zarr
+pip install "patchworks[napari]"       # + viewing and reviewing in napari
+pip install "patchworks[all]"          # everything above and more
+```
+
+GPU options of the DoG plugin need `cupy` matching your CUDA version
+(`pip install cupy-cuda12x`). PlantSeg is on conda-forge only. See
+[Getting started](https://imcf.one/patchworks/getting_started/) for every
+extra.
+
+## Three ways to use it
+
+**Python** — any function from a tile to labels:
+
+```python
+from patchworks import tile_process
+from patchworks.plugins.cellpose import cellpose_fn
+
+tile_process("scan.zarr", cellpose_fn("cyto3", gpu=True, diameter=30))
+```
+
+The labels go into `scan.zarr/labels/labels`, as a multiscale pyramid next
+to the image.
+
+**Command line** — the same building blocks, no script:
+
+```bash
+patchworks convert scan.czi scan.zarr
+patchworks segment scan.zarr --method cellpose --model cyto3 --diameter 30 --gpu
+patchworks view scan.zarr
+```
+
+**On a cluster** — a Snakemake workflow with a pixi environment: convert,
+segment tile batches as GPU jobs, merge, relate label images (which cell
+each nucleus is in), and bundle, from one YAML config per segmentation:
+
+```bash
+cd workflow
+pixi run multi-slurm --config my_multi.yaml
+```
+
+## What you get
+
+- **One OME-Zarr** holding the image and every label image, readable by
+  napari, Fiji and any OME-Zarr tool.
+- **Object tables** — size, position, shape — and **relations** between label
+  images (the cell of each nucleus, the position of each cilium in its cell),
+  exported as spreadsheets.
+- **Review in napari**: `patchworks review scan.zarr` steps through the
+  objects most likely to be wrong; corrections flow into the tables.
+- Plugins for **Cellpose**, **PlantSeg**, a **nuclei-seeded watershed**,
+  **difference of Gaussians** (cilia, spots) and **Noise2Void** denoising —
+  or bring your own function.
+
+## Documentation
+
+**<https://imcf.one/patchworks/>** — getting started, the cluster workflow,
+guides, examples and the API reference.
+
+## License
+
+GNU General Public License v3.0 (GPL-3.0). See [LICENSE](LICENSE).

{patchworks-3.3.0 → patchworks-3.4.0}/docs/api/io.md

@@ -8,7 +8,7 @@
 tile, so it can miss signal at a tile's edge. `build_occupancy_map` +
 `tile_occupancy` are **exact**: a brick maximum exceeds the threshold exactly
 when some voxel in that brick does. Use the latter pair when the result is
-used as a skip list. See [Skipping empty tiles](../guide/skip_empty.md).
+used as a skip list. See [Skipping empty tiles](../guide/performance.md#skip-empty-tiles).
 
 ::: patchworks.estimate_empty_tiles
 

{patchworks-3.3.0 → patchworks-3.4.0}/docs/api/plugins/careamics.md

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

patchworks-3.4.0/docs/api/provenance.md

@@ -0,0 +1,28 @@
+# Provenance
+
+Every label image patchworks writes records how it was made: the
+segmentation function and its bound settings, tiling, overlap, stitching,
+level, channel, codec, the input, the library versions (including the
+segmentation tool's: Cellpose, PlantSeg, torch, ...) and a UTC timestamp.
+It sits in the label group's attrs under `"patchworks"` (for `write_to=`
+stores, on the labels array), so it travels with the data.
+
+The cluster workflow stores its whole effective config (everything but the
+email settings), plus what was only decided at run time under `resolved`
+(tiles segmented, the empty threshold, the intensity range and thresholds
+measured for the image, the size filter in voxels, the object count, and
+for Cellpose the defaults it filled in) and the [seam report](../guide/merging.md#checking-the-seams)
+ratios under `seams`.
+
+```python
+from patchworks import read_provenance
+
+rec = read_provenance("scan.zarr/labels/cilia_labels")
+rec["settings"]["custom"]                # the method's settings
+rec["settings"]["resolved"]              # tiles, empty threshold, object count
+rec["seams"]                             # seam vs interior orphan rate per axis
+```
+
+::: patchworks.read_provenance
+
+::: patchworks.provenance

patchworks-3.4.0/docs/assets/logo.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 765" width="700" height="765" role="img" aria-label="patchworks: a sewing machine">
+  <title>patchworks</title>
+  <g fill="none" stroke="#a83f7a" stroke-width="11.2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M167.8,88.3C194.0,86.7 214.4,97.5 231.7,101.6C249.1,105.7 273.2,120.3 295.7,126.1C318.2,132.0 342.5,133.1 365.2,128.1C387.9,123.1 407.1,110.3 421.7,100.3C436.3,90.2 476.3,71.8 489.7,76.0"/>
+  <path d="M144.5,84.8C138.5,85.0 123.6,86.0 117.9,87.3C112.3,88.5 106.8,90.2 101.6,92.3C96.4,94.4 91.4,96.9 86.7,99.8C82.0,102.7 77.6,106.0 73.5,109.6C69.5,113.1 65.7,117.0 62.4,121.2C59.0,125.4 56.0,129.8 53.4,134.4C50.9,139.0 48.6,143.9 46.8,148.8C44.9,153.8 43.4,159.0 42.3,164.2C41.1,169.5 40.3,174.8 39.8,180.2C39.3,185.6 39.2,191.0 39.3,196.4C39.4,201.8 39.9,207.2 40.5,212.6C41.2,218.0 42.2,223.3 43.3,228.6C44.4,234.0 45.7,239.2 47.2,244.5C48.7,249.8 50.2,255.0 51.9,260.3C53.6,265.5 55.3,270.7 57.1,275.9C58.8,281.1 60.6,286.2 62.3,291.4C64.0,296.5 65.7,301.7 67.2,306.8C68.8,311.9 70.3,317.0 71.6,322.1C72.9,327.1 74.0,332.2 74.9,337.2C75.8,342.3 77.3,357.3 77.7,362.3"/>
+  <path d="M100.5,461.9C99.3,468.7 99.1,475.8 99.9,482.8C100.6,489.9 102.3,496.9 104.8,503.4C107.4,510.0 110.8,516.1 115.2,521.5C119.6,526.8 124.8,531.2 130.9,534.5C137.1,537.8 148.1,540.0 155.9,540.5"/>
+  </g>
+  <path fill="#384144" fill-rule="evenodd" d="M34.9,763.4C33.0,761.1 32.6,751.7 34.0,743.6C38.6,717.6 58.5,702.2 87.8,702.0L95.0,702.0L95.0,698.5C95.0,686.7 103.0,682.3 140.0,673.5C148.5,671.4 165.6,667.3 178.0,664.4C203.3,658.3 204.7,658.2 210.6,661.0C225.1,668.1 228.7,687.7 217.7,699.8L215.6,702.0L302.0,701.8L388.3,701.5L392.0,689.2L395.7,677.0L390.6,677.7C387.8,678.1 376.9,678.5 366.5,678.5C307.7,678.4 231.1,652.5 197.9,621.4L195.4,619.0L109.4,618.9C8.4,618.9 11.6,619.1 5.2,612.7L0.5,608.0L0.2,594.1L-0.1,580.3L5.3,574.4L10.8,568.5L193.6,568.0C294.2,567.7 376.6,567.3 376.8,567.2C377.0,567.1 377.0,547.1 376.8,522.8C376.5,472.5 376.3,473.7 385.0,465.0C392.2,457.8 398.5,455.6 411.9,455.6L423.3,455.6L428.1,445.6C437.6,425.6 448.2,391.4 452.6,367.0C458.6,333.5 450.8,308.4 431.5,299.4C409.4,289.1 334.9,282.9 282.5,287.0C255.7,289.1 239.6,297.9 233.4,313.6C223.1,339.8 214.3,349.7 196.8,354.6L190.0,356.5L190.0,365.6L190.0,374.8L201.8,376.9C232.9,382.7 255.2,387.8 257.9,389.8C268.2,397.5 267.2,413.1 255.8,420.0L253.1,421.6L261.2,435.6C272.6,455.3 274.0,458.4 274.0,465.3C274.0,484.5 251.2,498.7 236.4,488.8C229.0,483.8 224.5,476.9 203.6,438.7L199.8,431.9L193.2,432.6C189.5,432.9 186.3,433.4 186.1,433.6C185.8,433.9 185.4,445.6 185.2,459.8C184.8,485.1 184.7,485.6 182.2,490.3C179.9,494.5 171.1,504.0 168.4,505.1C167.8,505.3 166.7,513.5 165.9,523.9L164.4,542.3L160.6,545.7C155.5,550.4 152.8,549.2 155.4,543.2C156.2,541.4 155.9,540.5 153.7,538.2C152.2,536.6 151.0,534.7 151.0,533.8C151.0,532.9 150.5,532.0 149.8,531.8C149.1,531.5 148.3,526.7 147.7,519.1L146.7,506.8L138.1,498.5L129.5,490.2L129.2,459.3L128.9,428.4L122.8,425.7C115.4,422.5 116.1,422.0 107.9,435.6C89.6,465.9 85.6,470.9 77.3,474.0C70.6,476.5 69.4,476.5 62.4,473.9C51.8,469.9 42.8,458.7 42.7,449.1C42.7,443.7 44.7,439.4 60.4,412.1L70.9,393.7L66.2,390.2C53.4,380.6 50.3,374.7 53.0,364.8C55.0,357.8 64.7,349.7 68.8,351.6C69.8,352.0 70.7,352.4 71.0,352.5C71.3,352.6 72.7,353.2 74.1,353.7C77.3,355.1 83.2,355.6 84.7,354.7C85.3,354.3 90.7,354.9 96.7,356.0C117.7,360.0 123.0,361.1 124.5,361.6C125.5,362.0 126.0,361.6 126.0,360.2C126.0,359.1 126.2,357.5 126.6,356.7C127.0,355.7 125.5,354.8 120.8,353.5C104.2,348.9 94.1,337.7 90.8,320.5C89.1,311.1 89.0,155.9 90.8,146.2C94.2,127.5 107.0,114.8 124.7,112.5C127.3,112.2 131.0,111.7 132.8,111.4L136.2,110.9L136.0,102.2C136.0,97.4 136.2,90.4 136.6,86.6C137.0,82.2 136.8,78.4 136.0,76.1C131.5,62.5 145.0,52.7 163.9,56.0C174.9,57.8 177.5,60.5 177.2,69.6C176.9,81.7 177.0,93.2 177.6,103.1L178.1,112.7L185.4,113.3C197.4,114.2 199.3,115.6 226.5,144.1C245.2,163.6 271.7,168.9 317.5,162.1C325.8,160.9 337.4,159.3 343.5,158.5C349.6,157.6 365.3,154.9 378.5,152.5C391.7,150.0 410.6,146.7 420.5,145.1C430.4,143.4 445.7,140.8 454.5,139.1C524.3,126.1 543.0,125.3 571.8,133.6C595.5,140.5 617.1,159.0 630.9,184.2L635.2,192.0L644.6,192.0L654.0,192.0L654.0,176.5C654.0,158.9 654.3,157.9 661.2,151.4C673.3,139.7 690.8,142.5 698.6,157.2C700.7,161.2 700.7,318.8 698.6,322.8C690.6,338.1 671.5,339.9 658.5,326.4L654.2,322.0L653.5,308.5L652.8,295.0L648.4,295.0L644.1,295.0L643.8,323.2C643.6,338.8 643.6,374.7 643.8,403.1L644.1,454.7L650.8,455.4C667.4,457.1 675.0,464.0 675.0,477.4C675.0,489.6 666.4,496.7 649.2,498.5C643.9,499.1 642.9,499.5 642.5,501.3C642.2,502.5 641.3,506.8 640.5,510.9C634.5,540.1 615.3,574.4 591.0,599.4C583.0,607.6 570.1,619.2 567.3,620.5C566.9,620.7 579.6,654.3 589.0,678.1L598.4,701.7L612.5,702.3C633.0,703.3 643.3,707.1 652.8,717.4C662.9,728.4 669.8,754.6 664.6,762.5L663.0,765.0L349.6,765.0C66.9,765.0 36.1,764.8 34.9,763.4ZM498.1,623.5C522.7,615.1 524.2,582.5 500.5,571.0C481.9,562.0 457.7,582.6 463.4,602.4C468.1,618.6 484.1,628.3 498.1,623.5ZM551.4,269.0C581.5,253.8 570.2,205.7 536.5,205.5C507.0,205.4 493.0,245.0 515.6,264.9C524.3,272.6 540.5,274.4 551.4,269.0ZM475.3,120.3C463.8,118.0 466.4,96.8 477.9,98.5C483.9,99.4 567.3,99.5 572.5,98.5C582.5,96.8 587.4,110.6 579.4,118.1L576.8,120.5L527.2,120.6C499.9,120.7 476.5,120.6 475.3,120.3ZM474.2,19.9C469.9,18.2 467.7,14.3 468.2,9.0C469.2,-0.7 464.8,0.0 525.0,0.0L577.7,0.0L579.8,2.3C584.6,7.4 584.4,13.7 579.2,18.3C577.1,20.2 478.8,21.6 474.2,19.9Z"/>
+  <path fill="#19b4ab" fill-rule="evenodd" d="M351.0,645.3C336.7,644.4 323.2,642.4 313.0,640.0C289.5,634.2 252.9,620.6 254.4,618.2C254.7,617.7 281.6,617.0 314.2,616.7C386.1,616.0 385.2,616.1 395.9,604.4C408.1,591.1 409.0,586.2 409.6,536.5L410.1,497.5L509.8,497.2C569.2,497.1 609.8,497.4 610.3,497.9C611.4,499.0 607.7,510.6 601.3,526.5C592.4,548.5 584.7,559.9 567.1,577.4C553.7,590.6 552.6,591.2 551.5,585.7C549.6,577.2 538.1,559.0 529.7,551.4C504.1,528.0 463.3,531.6 442.6,559.1C435.9,568.0 431.1,578.7 423.1,602.6C414.6,628.0 409.4,642.0 408.1,643.3C406.3,645.1 367.4,646.5 351.0,645.3ZM496.5,456.3C477.3,456.1 461.2,455.6 460.8,455.2C460.3,454.7 462.0,448.8 464.6,441.9C486.0,383.7 491.7,337.3 481.0,308.8C472.0,284.8 448.3,267.2 416.0,260.6C381.1,253.5 285.0,251.6 257.3,257.4C232.0,262.8 215.6,277.6 200.6,308.5L193.3,323.7L183.4,324.3C164.7,325.6 133.3,325.1 129.5,323.6C122.0,320.4 122.5,326.5 122.5,232.5C122.5,166.7 122.8,148.0 123.8,146.2C125.1,144.0 125.1,144.0 152.9,144.0L180.8,144.0L185.7,147.8C188.3,149.9 195.5,157.0 201.5,163.4C220.8,184.1 234.4,191.8 260.5,196.6C274.9,199.2 306.2,198.1 328.5,194.0C337.9,192.3 368.2,187.1 396.0,182.4C423.8,177.7 455.8,171.9 467.3,169.4C478.7,167.0 495.3,163.8 504.3,162.4C560.3,153.5 593.7,169.3 608.1,211.5L610.5,218.5L610.5,337.5L610.5,456.5L571.0,456.5C549.3,456.5 515.8,456.4 496.5,456.3ZM546.2,290.9C603.5,279.2 601.7,196.9 543.9,187.9C509.5,182.6 478.5,214.4 485.4,248.0C491.5,277.6 518.5,296.6 546.2,290.9Z"/>
+  <g fill="#a83f7a"><rect x="481" y="20" width="86" height="80" rx="5"/><circle cx="536.1" cy="238.6" r="33.0"/><circle cx="489.8" cy="596.3" r="28.2"/></g>
+</svg>

patchworks-3.4.0/docs/examples/cellpose_2d.md

@@ -0,0 +1,27 @@
+# Cellpose 2-D
+
+Segment every z-slice independently: each tile is one plane `(1, y, x)`.
+
+```bash
+pip install "patchworks[cellpose,gpu]"
+```
+
+```python
+from functools import partial
+from patchworks import auto_tile_shape_cellpose, tile_process
+from patchworks.plugins.cellpose import cellpose_fn
+
+tile_process(
+    "image.zarr",
+    cellpose_fn("cyto3", gpu=True, diameter=30),
+    channel=0,
+    tile_shape=partial(auto_tile_shape_cellpose, diameter=30, use_gpu=True),  # fits the VRAM
+    overlap=20,        # about one cell diameter
+    skip_empty=True,
+)
+```
+
+Cellpose arguments not listed in `cellpose_fn`'s signature (`flow_threshold`,
+`cellprob_threshold`, ...) are passed through. A cyto stain with a nuclear
+channel: on the cluster, set `nuclei_channel:`
+([Options worth knowing](../guide/snakemake.md#options-worth-knowing)).

patchworks-3.4.0/docs/examples/cellpose_3d.md

@@ -0,0 +1,32 @@
+# Cellpose 3-D
+
+`do_3D=True` segments the xy, xz and yz planes and combines them, so each
+tile holds a block of z as well. It is slower than 2-D: skip empty tiles.
+
+```python
+from functools import partial
+from patchworks import auto_tile_shape_cellpose, tile_process
+from patchworks.plugins.cellpose import cellpose_fn
+from patchworks.plugins.ome_zarr import read_pixel_size
+
+fn = cellpose_fn(
+    "cyto3",
+    gpu=True,
+    do_3D=True,
+    diameter=20,
+    voxel_size=read_pixel_size("image.zarr"),  # anisotropy = z / lateral
+)
+
+tile_process(
+    "image.zarr",
+    fn,
+    channel=0,
+    tile_shape=partial(auto_tile_shape_cellpose, do_3D=True, use_gpu=True, diameter=20),
+    overlap=[4, 20, 20],
+    skip_empty=True,
+)
+```
+
+Without `voxel_size` (or `anisotropy=`), Cellpose assumes isotropic voxels
+and fragments objects along z. The cluster workflow passes the calibration
+by itself ([Configure](../guide/snakemake.md#2-configure)).

patchworks-3.4.0/docs/examples/dog.md

@@ -0,0 +1,83 @@
+# Difference of Gaussians (spots, cilia, fibres)
+
+For small structures Cellpose is not made for: blur at two sigmas, subtract,
+threshold, label. CPU by default, GPU with `use_gpu=True` (needs `cupy`);
+optionally deconvolve each tile first with
+[pycudadecon](https://github.com/tlambert03/pycudadecon)
+(`pip install "patchworks[dog]"`, CUDA only).
+
+> Cilia DoG + deconvolution approach courtesy of
+> [angelo-angonezi](https://github.com/angelo-angonezi).
+
+```python
+from patchworks import tile_process
+from patchworks.plugins.dog import dog_label_fn
+
+from patchworks import intensity_range
+
+rng = intensity_range("image.zarr", 1, percentiles=(1, 99.9))[0]
+fn = dog_label_fn(low_sigma=1.0, high_sigma=3.0, threshold=0.05, intensity_range=rng)
+tile_process("image.zarr", fn, channel=1, tile_shape=(16, 1024, 1024), overlap=[4, 8, 8])
+```
+
+## Parameters
+
+- `low_sigma`: about the object's radius; `high_sigma`: a few times larger
+  (the background to subtract).
+- `threshold` applies to the DoG image, as a fraction of the channel's
+  intensity range (1st to 99.9th percentile), measured once for the whole
+  image: the same on every tile, and on 8- or 16-bit data. Too low, and
+  background texture joins into a few huge objects (a warning says so).
+  With the API, pass the range: `intensity_range=patchworks.intensity_range(
+  "image.zarr", 1, percentiles=(1, 99.9))[0]`; without it the threshold is
+  in raw counts.
+- `connectivity=3` (3-D) joins voxels touching at an edge or corner, so an
+  oblique cilium is one object rather than a row of fragments. With the API,
+  pass the same value to `merge_tile_labels`; the workflow does it for you.
+- `dilate_labels(fn, iterations=2)` grows thin labels
+  ([Growing labels](../guide/custom_segmentation.md#growing-labels)).
+
+## Deconvolution first
+
+```python
+from patchworks.plugins.ome_zarr import read_pixel_size
+
+fn = dog_label_fn(
+    low_sigma=1.0, high_sigma=3.0, threshold=0.05,
+    decon_kwargs=dict(psf=psf, wavelength=525, na=1.4, nimm=1.515),
+    voxel_size=read_pixel_size("image.zarr"),   # fills dxdata/dzdata/dxpsf/dzpsf
+)
+```
+
+Anything set in `decon_kwargs` wins, such as `dxpsf`/`dzpsf` for a PSF sampled
+differently from the data. A wrong voxel size does not fail, it gives a
+subtly wrong image, so let it come from the image. Make `overlap` cover the
+PSF as well as `high_sigma`.
+
+## On the cluster
+
+`workflow/config/config_cilia.yaml` is a complete example:
+
+```yaml
+channel: 2
+overlap: [8, 30, 30]
+method: "custom"
+label_name: "cilia_labels"
+custom:
+  module: "patchworks.plugins.dog"
+  kwargs:
+    low_sigma: 1.0
+    high_sigma: 3.0
+    threshold: 0.05          # of the channel's intensity range
+    connectivity: 3          # keep oblique cilia whole
+    decon_kwargs:            # optional; voxel sizes come from the image
+      psf: "/path/to/psf.tif"
+      wavelength: 525
+      na: 1.4
+      nimm: 1.515
+max_volume: 10               # µm³: drop texture that joined up
+```
+
+Deconvolution needs a GPU in the segment jobs. List it in a multi config
+next to the cells to get each cilium's cell
+([Tables and relations](../guide/tables.md#relating-two-label-images)).

{patchworks-3.3.0 → patchworks-3.4.0}/docs/examples/dog.py

@@ -4,14 +4,18 @@ Blur twice at different sigmas, subtract, threshold, label the connected
 components. CPU (scipy) by default.
 """
 
-from patchworks import tile_process
+from patchworks import intensity_range, tile_process
 from patchworks.plugins.dog import dog_label_fn
 
 IMAGE = "image.zarr"
 OUTPUT = "labels_dog.zarr"
 CHANNEL = 1
 
-fn = dog_label_fn(low_sigma=1.0, high_sigma=3.0, threshold=0.02)
+# The threshold is a fraction of the channel's range, measured once.
+rng = intensity_range(IMAGE, CHANNEL, percentiles=(1, 99.9))[0]
+fn = dog_label_fn(
+    low_sigma=1.0, high_sigma=3.0, threshold=0.05, intensity_range=rng
+)
 
 tile_process(
     IMAGE,

{patchworks-3.3.0 → patchworks-3.4.0}/docs/examples/standalone_merge.md

@@ -25,7 +25,6 @@ labeled = image.map_blocks(
     meta=np.empty((0,) * image.ndim, dtype="int32"),
 )
 
-# Merge: boundary scan → connected components → relabel
 merged = merge_tile_labels(labeled, write_to="labels.zarr", progress=True)
 ```
 
@@ -55,18 +54,3 @@ from patchworks import merge_tile_labels
 # labeled was computed with da.overlap.overlap(depth=20)
 merged = merge_tile_labels(labeled, write_to="labels.zarr", overlap=20)
 ```
-
-## Integration with other frameworks
-
-patchworks's merge step is framework-agnostic. Any pipeline that produces a
-dask array of integer labels (one value per voxel, distinct per tile) can
-use `merge_tile_labels`:
-
-```python
-# zarr → your pipeline → per-tile labels
-labeled = your_pipeline(da.from_zarr("image.zarr"))  # dask.array.Array
-
-from patchworks import merge_tile_labels
-
-merged = merge_tile_labels(labeled, write_to="final.zarr")
-```