patchworks 0.6.0__tar.gz → 0.8.0__tar.gz

{patchworks-0.6.0 → patchworks-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchworks
-Version: 0.6.0
+Version: 0.8.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

{patchworks-0.6.0 → patchworks-0.8.0}/docs/guide/ome_zarr_napari.md

@@ -50,6 +50,17 @@ to_ome_zarr("scan.czi", "scan.zarr", n_levels=5)   # via bioio
 to_ome_zarr("scan.ims", "scan.zarr")               # Imaris, native HDF5
 ```
 
+!!! note "Imaris pyramids: rebuild (default) or reuse"
+    `.ims` files carry their own resolution pyramid. By default `to_ome_zarr`
+    reads only the **full-resolution** level and **builds a fresh NGFF pyramid**
+    (XY-only, nearest-neighbour, calibrated) for consistency. Pass
+    `reuse_pyramid=True` to instead **copy the Imaris levels** as-is — faster,
+    no recompute, keeping each level's native scale:
+
+    ```python
+    to_ome_zarr("scan.ims", "scan.zarr", reuse_pyramid=True)
+    ```
+
 ### Pixel calibration
 
 The physical voxel size is read from the input — bioio's `physical_pixel_sizes`,
@@ -96,13 +107,17 @@ write_labels("scan.zarr", my_labels, name="nuclei")
 layer in one call. OME-ZARR pyramids are handed to napari as a lazy multi-scale
 list, so even huge stores open instantly and only on-screen data is fetched.
 
+Because `tile_process` writes labels **into** the store by default, you usually
+need no `labels=` argument at all — `view_in_napari` auto-loads every label
+image found under `scan.zarr/labels/`:
+
 ```python
 from patchworks.plugins.napari import view_in_napari
 
-# one store holding both image and labels/<name>:
-view_in_napari("scan.zarr", labels="scan.zarr/labels/labels")
+# auto-loads scan.zarr/labels/* as Labels layers:
+view_in_napari("scan.zarr")
 
-# or a separate plain label store written with write_to=:
+# or point at a separate plain label store written with write_to=:
 view_in_napari("scan.zarr", labels="labels.zarr")
 ```
 
@@ -120,7 +135,7 @@ from patchworks.plugins.napari import view_in_napari
 tile_process("scan.zarr", fn, progress=True)
 
 # 2. inspect image + labels together, straight from the one store
-view_in_napari("scan.zarr", labels="scan.zarr/labels/labels")
+view_in_napari("scan.zarr")  # labels auto-loaded from scan.zarr/labels/
 ```
 
 Plugging in a different segmentation method is just swapping `fn` — any

{patchworks-0.6.0 → patchworks-0.8.0}/docs/guide/performance.md

@@ -17,6 +17,22 @@ merge step are sized to the host automatically:
 The RAM figure is read live via `psutil`; without it, a conservative default is
 used instead of guessing high.
 
+## Live progress dashboard (GPU runs)
+
+A single-GPU run still gets a **Dask dashboard**: patchworks spins up a tiny
+1-worker / 1-thread in-process cluster, which keeps GPU evaluations serial (no
+VRAM contention) while exposing the dashboard so you can watch tiles stream
+through. The URL is logged at the start of staging:
+
+```text
+INFO:patchworks._core:Dask dashboard for this run: http://127.0.0.1:8787/status
+```
+
+This needs `distributed` (and `bokeh` for the UI) installed; if they are
+missing, patchworks logs a warning and falls back to the threaded scheduler
+(no dashboard, same result). A cluster you start yourself
+(`make_local_cluster`) is used as-is instead.
+
 ## Overriding the worker count
 
 ```python

{patchworks-0.6.0 → patchworks-0.8.0}/src/patchworks/_core.py

@@ -332,7 +332,31 @@ def tile_process(
     import dask as _dask
 
     _tile_nbytes = int(np.prod(labeled.chunksize)) * labeled.dtype.itemsize
-    if _active is None:
+    _temp_cluster = None
+    _temp_client = None
+    if _active is None and use_gpu:
+        # Single-GPU runs still get a live Dask dashboard: a 1-worker /
+        # 1-thread in-process cluster keeps GPU evals serial (no VRAM
+        # contention) while exposing the dashboard for progress.
+        try:
+            from dask.distributed import Client, LocalCluster
+
+            _temp_cluster = LocalCluster(
+                n_workers=1, threads_per_worker=1, processes=False
+            )
+            _temp_client = Client(_temp_cluster)
+            logger.info(
+                "Dask dashboard for this run: %s",
+                _temp_client.dashboard_link,
+            )
+        except Exception as exc:  # no distributed/bokeh → threaded fallback
+            logger.warning(
+                "Could not start a dashboard cluster (%s); "
+                "falling back to the threaded scheduler.",
+                exc,
+            )
+
+    if _distributed_client() is None:
         _workers = (
             max_workers
             if max_workers is not None
@@ -363,6 +387,9 @@ def tile_process(
     logger.info("Staging tiles to %s …", stage_path)
     with _sched_ctx:
         _stage_to_zarr(labeled, stage_path, "staged", progress)
+    if _temp_client is not None:
+        _temp_client.close()
+        _temp_cluster.close()
     labeled = da.from_zarr(stage_path, component="staged")
 
     # NB: no post-staging skip-count pass here — counting skipped tiles by

{patchworks-0.6.0 → patchworks-0.8.0}/src/patchworks/plugins/napari.py

@@ -14,13 +14,12 @@ napari is an optional, GUI-heavy dependency. Install it with
 Usage
 -----
 >>> from patchworks import tile_process
->>> from patchworks.plugins.ome_zarr import to_ome_zarr
 >>> from patchworks.plugins.napari import view_in_napari
 >>>
->>> tile_process("scan.zarr", fn, write_to="labels.zarr")
->>> to_ome_zarr("scan.zarr", "scan_pyramid.zarr")        # optional, for speed
->>>
->>> view_in_napari("scan_pyramid.zarr", labels="labels.zarr")
+>>> # labels are written into scan.zarr/labels/ by default …
+>>> tile_process("scan.zarr", fn)
+>>> # … so the viewer finds and overlays them with no labels= argument:
+>>> view_in_napari("scan.zarr")
 """
 
 from __future__ import annotations
@@ -86,6 +85,15 @@ def _resolve_image(
     return source
 
 
+def _inner_label_names(store: Union[str, Path]) -> list[str]:
+    """Names registered under an OME-ZARR's NGFF ``labels/`` group, if any."""
+    try:
+        grp = zarr.open_group(f"{store}/labels", mode="r")
+    except Exception:
+        return []
+    return list(grp.attrs.get("labels", []))
+
+
 def _resolve_labels(
     source: Union[da.Array, str, Path], component: str
 ) -> Union[da.Array, list[da.Array]]:
@@ -123,7 +131,10 @@ def view_in_napari(
     labels : da.Array, str, Path or None
         Label array to overlay. A plain ``.zarr`` store written by
         ``tile_process`` is read from its ``labels_component``; an OME-ZARR
-        pyramid is shown multi-scale; ``None`` shows the image only.
+        pyramid is shown multi-scale. ``None`` (default) **auto-loads** every
+        label image stored inside the OME-ZARR under ``labels/<name>/`` — the
+        place ``tile_process`` writes them by default — each as its own Labels
+        layer. (Falls back to image-only if there are none.)
     channel : int or None, optional
         Channel to display from the image (``None`` keeps all channels).
     labels_component : str, optional
@@ -145,7 +156,7 @@ def view_in_napari(
 
     Examples
     --------
-    >>> view_in_napari("scan.zarr", labels="labels.zarr")  # doctest: +SKIP
+    >>> view_in_napari("scan.zarr")  # auto-loads scan.zarr/labels/*  # doctest: +SKIP
     """
     napari = _require_napari()
 
@@ -161,6 +172,15 @@ def view_in_napari(
     if labels is not None:
         lab = _resolve_labels(labels, labels_component)
         viewer.add_labels(lab, name=labels_name)
+    elif _is_zarr(image):
+        # No labels given → auto-overlay every label image stored inside the
+        # OME-ZARR under labels/<name>/ (the default place tile_process writes
+        # them), each as its own multi-scale Labels layer.
+        for name in _inner_label_names(image):
+            levels = _multiscale_levels(f"{image}/labels/{name}", None)
+            lab = [lvl.astype("int32") for lvl in levels]
+            viewer.add_labels(lab if len(lab) > 1 else lab[0], name=name)
+            logger.info("auto-loaded labels/%s from %s", name, image)
 
     if show:
         napari.run()

{patchworks-0.6.0 → patchworks-0.8.0}/src/patchworks/plugins/ome_zarr.py

@@ -255,8 +255,8 @@ def _open_bioio(path: str, scene: int) -> tuple[da.Array, str, PixelSize]:
     return arr, axes, pixel_size
 
 
-def _open_imaris(path: str) -> tuple[da.Array, str, PixelSize]:
-    """Open an Imaris ``.ims`` file lazily → ``(array, axes, pixel_size)``."""
+def _open_imaris(path: str, level: int = 0) -> tuple[da.Array, str, PixelSize]:
+    """Open an Imaris ``.ims`` *level* lazily → ``(array, axes, pixel_size)``."""
     try:
         from imaris_ims_file_reader.ims import ims
     except ImportError as exc:
@@ -265,8 +265,8 @@ def _open_imaris(path: str) -> tuple[da.Array, str, PixelSize]:
             "Install it with:\n    pip install 'patchworks[imaris]'"
         ) from exc
 
-    # Full-resolution level; the object is array-like and h5py-backed (lazy).
-    reader = ims(path, ResolutionLevelLock=0)
+    # The object is array-like and h5py-backed (lazy).
+    reader = ims(path, ResolutionLevelLock=level)
     order = _DEFAULT_ORDER[len(_DEFAULT_ORDER) - reader.ndim :]
     arr = da.from_array(reader, chunks=_default_chunks(reader.shape, order))
 
@@ -293,6 +293,46 @@ def _open_imaris(path: str) -> tuple[da.Array, str, PixelSize]:
     return arr, axes, pixel_size
 
 
+def _write_imaris_pyramid(
+    path: str,
+    out: str,
+    *,
+    chunks: Union[tuple[int, ...], None],
+    overwrite: bool,
+) -> str:
+    """Copy an Imaris file's own resolution levels into an OME-ZARR.
+
+    Each Imaris ``ResolutionLevel`` is written as a pyramid level with its own
+    physical scale, so no downsampling is recomputed. Lazy (h5py-backed) reads
+    stream straight to disk.
+    """
+    from imaris_ims_file_reader.ims import ims
+
+    base = ims(path, ResolutionLevelLock=0)
+    n_levels = int(getattr(base, "ResolutionLevels", 1) or 1)
+
+    zarr.open_group(out, mode="w" if overwrite else "w-")
+    datasets: list[dict] = []
+    axes = ""
+    calibrated = False
+    for level in range(n_levels):
+        arr, axes, ps = _open_imaris(path, level=level)
+        scale = _base_scale(axes, ps)
+        calibrated = calibrated or bool(ps)
+        da.to_zarr(
+            arr.rechunk(chunks or _default_chunks(arr.shape, axes)),
+            out,
+            component=str(level),
+            overwrite=True,
+        )
+        datasets.append(_dataset(str(level), scale))
+        logger.info("imaris level %d copied: shape=%s", level, arr.shape)
+    _write_multiscales(
+        out, axes, datasets, Path(out).stem, calibrated=calibrated
+    )
+    return out
+
+
 def _to_dask(
     source: Union[da.Array, np.ndarray, str, Path],
     axes: Union[str, None],
@@ -327,6 +367,7 @@ def to_ome_zarr(
     n_levels: int = 5,
     downscale: int = 2,
     chunks: Union[tuple[int, ...], None] = None,
+    reuse_pyramid: bool = False,
     overwrite: bool = False,
 ) -> str:
     """Write *source* as a pyramidal, calibrated OME-ZARR store.
@@ -359,6 +400,12 @@ def to_ome_zarr(
         Per-level X/Y downsampling factor (default 2).
     chunks : tuple of int, optional
         Chunk shape for the written levels. ``None`` → a bounded default.
+    reuse_pyramid : bool, optional
+        *Imaris ``.ims`` only.* Copy the file's **own** resolution levels
+        instead of rebuilding the pyramid (faster, no recompute), keeping each
+        level's native scale. Ignored for other inputs; falls back to a
+        rebuild if the Imaris levels can't be read. Default ``False`` (rebuild,
+        for a consistent XY-only, nearest-neighbour NGFF pyramid).
     overwrite : bool, optional
         Overwrite an existing store at *out_path*.
 
@@ -378,6 +425,22 @@ def to_ome_zarr(
     if n_levels < 1:
         raise ValueError("n_levels must be >= 1")
 
+    # Reuse an Imaris file's own resolution pyramid instead of rebuilding it.
+    if (
+        reuse_pyramid
+        and isinstance(source, (str, Path))
+        and str(source).lower().endswith(".ims")
+    ):
+        try:
+            return _write_imaris_pyramid(
+                str(source), str(out_path), chunks=chunks, overwrite=overwrite
+            )
+        except Exception as exc:
+            logger.warning(
+                "reuse_pyramid failed (%s); rebuilding the pyramid instead.",
+                exc,
+            )
+
     arr, axes, detected = _to_dask(source, axes, scene)
     if len(axes) != arr.ndim:
         raise ValueError(

{patchworks-0.6.0 → patchworks-0.8.0}/tests/test_napari.py

@@ -39,3 +39,32 @@ def test_require_napari_message(monkeypatch):
             nplugin._require_napari()
     else:
         assert nplugin._require_napari() is napari
+
+
+def test_inner_label_discovery(tmp_path):
+    """Labels written into a store are discoverable for auto-overlay."""
+    import numpy as np
+
+    from patchworks.plugins.ome_zarr import to_ome_zarr, write_labels
+
+    store = to_ome_zarr(
+        np.zeros((8, 8, 8), "uint16"), tmp_path / "scan.zarr", n_levels=2
+    )
+    write_labels(store, np.ones((8, 8, 8), "int32"), name="cells", n_levels=2)
+
+    assert nplugin._inner_label_names(store) == ["cells"]
+    levels = nplugin._multiscale_levels(f"{store}/labels/cells", None)
+    assert len(levels) == 2
+    assert levels[1].shape == (8, 4, 4)  # Z preserved, XY downsampled
+
+
+def test_inner_label_discovery_none(tmp_path):
+    """A store without labels yields an empty list (image-only view)."""
+    import numpy as np
+
+    from patchworks.plugins.ome_zarr import to_ome_zarr
+
+    store = to_ome_zarr(
+        np.zeros((8, 8, 8), "uint16"), tmp_path / "img.zarr", n_levels=1
+    )
+    assert nplugin._inner_label_names(store) == []

{patchworks-0.6.0 → patchworks-0.8.0}/tests/test_ome_zarr.py

@@ -128,3 +128,14 @@ def test_write_labels_into_store(tmp_path):
     assert load_ome_zarr(group, channel=None, level=1).shape == (8, 4, 4)
     lg = zarr.open_group(group, mode="r")
     assert lg.attrs["image-label"]["version"]
+
+
+def test_reuse_pyramid_ignored_for_arrays(tmp_path):
+    """reuse_pyramid only affects .ims inputs; arrays still rebuild."""
+    out = to_ome_zarr(
+        np.zeros((8, 8, 8), "uint16"),
+        tmp_path / "arr.zarr",
+        n_levels=2,
+        reuse_pyramid=True,
+    )
+    assert load_ome_zarr(out, channel=None, level=1).shape == (8, 4, 4)