patchworks 2.7.0__tar.gz → 2.8.0__tar.gz

{patchworks-2.7.0 → patchworks-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchworks
-Version: 2.7.0
+Version: 2.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-2.7.0 → patchworks-2.8.0}/docs/guide/custom_segmentation.md

@@ -81,8 +81,11 @@ backend `fn` used — pass `use_gpu=True` to dilate via cupy instead:
 fn = dilate_labels(fn, iterations=2, use_gpu=True)
 ```
 
-Needs `cupy` installed **manually**, matching your CUDA version (e.g.
-`pip install cupy-cuda12x`) — it's never installed automatically by
+Needs `cupy`, matching your CUDA version. Under the Snakemake workflow, use
+the environment that already carries it — `pixi install -e cuda12` (or
+`-e cuda13`), then `pixi run -e cuda12 <task>`; outside it, install the
+matching wheel yourself (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

{patchworks-2.7.0 → patchworks-2.8.0}/docs/guide/snakemake.md

@@ -93,10 +93,21 @@ shard_labels: false            # true → also reshard label level 0 after the
     `dilate: N` grows every label by `N` pixels once segmentation finishes,
     regardless of `method`. `0` (default) disables it. Runs on CPU (scipy)
     by default; set `dilate_gpu: true` to dilate via cupy instead — that
-    needs `cupy` installed in the segment job's environment (matching your
-    CUDA version, e.g. `pip install cupy-cuda12x`) and a GPU allocated for
+    needs `cupy` in the segment job's environment and a GPU allocated for
     that job (`set-resources: segment:` in `profile/slurm/config.yaml`,
-    same as for a GPU `method`). It's independent of whatever `method`
+    same as for a GPU `method`). cupy ships one wheel per CUDA major
+    version, so pick the environment that matches yours rather than editing
+    `pixi.toml`:
+
+    ```bash
+    nvidia-smi                       # read the CUDA version off a GPU node
+    pixi install -e cuda12           # or -e cuda13
+    pixi run -e cuda12 multi-slurm   # every task works in these too
+    ```
+
+    A pixi environment includes the default feature as well, so `-e cuda12`
+    is "everything the default has, plus cupy". `cellpose4-cuda12` and
+    `cellpose4-cuda13` combine it with the pinned Cellpose. It's independent of whatever `method`
     itself runs on — you can dilate on GPU even with `method: "threshold"`
     (CPU), or on CPU even with `method: "cellpose"` (GPU). See [Growing
     labels afterwards](custom_segmentation.md#growing-labels-afterwards-dilation)
@@ -127,10 +138,29 @@ shard_labels: false            # true → also reshard label level 0 after the
     `true` reuses whatever spec `shard` carries; a list overrides it.
     `shard: false` does not veto it — an unsharded image with sharded labels
     is a valid combination. It is opt-in because it costs one extra full
-    read+write of level 0, and because it is the level with the most chunks
-    it is also the one worth paying for. The array's attributes (including
-    the merge's own completion marker) are carried across, so a later rerun
-    still sees the merge as done.
+    read+write of level 0. The array's attributes (including the merge's own
+    completion marker) are carried across, so a later rerun still sees the
+    merge as done.
+
+    **Set both keys**, but expect level 0 to dominate. `shard: true` sends
+    the pyramid down the dask path, where each level is rechunked to the
+    `(16, 1024, 1024)` cap — so levels 1..N shrink fourfold each, the way
+    you would expect. Level 0 does not: its chunks come from `tile_shape`,
+    it is the full-resolution level, and it is the one `shard` cannot reach.
+
+    Measured on a real `(126, 45961, 42072)` label group whose tiles are 32%
+    occupied (empty chunks are never written):
+
+    | level | files, `shard` only | with `shard_labels` too |
+    |---|---|---|
+    | 0 | ~10,656 | ~666 |
+    | 1–4 | ~462 | ~462 |
+    | **total** | **~11,100** | **~1,130** |
+
+    So level 0 is ~96% of a label group here, and `shard` alone barely moves
+    the file count. The two keys are not interchangeable and neither is
+    redundant — `shard` handles the pyramid, `shard_labels` handles the level
+    that actually holds the files.
 
     Check whether the file count is actually a problem for your data first —
     a `(126, 34000, 28500)` image at the `(16, 1024, 1024)` label chunk cap
@@ -173,6 +203,123 @@ shard_labels: false            # true → also reshard label level 0 after the
     to 0.5. Setting `ngff_version: "0.6"` is rejected with that explanation
     rather than writing a store you could not open.
 
+!!! tip "Repacking a store that was written unsharded (`pixi run reshard`)"
+    Sharding normally has to be chosen before a store is written, because
+    concurrent writers cannot share a shard file. Once the store is finished
+    nothing is writing it, so a single pass can repack it in place — same
+    data, same chunking, same metadata, far fewer files, no re-conversion and
+    no re-segmentation:
+
+    ```bash
+    pixi run reshard --store /path/to/image.zarr --dry-run     # report only
+    pixi run reshard --store /path/to/image.zarr --labels-only
+    ```
+
+    It skips anything already sharded, so re-running it is a no-op, and it
+    carries each array's attributes across — including the merge's own
+    completion marker, without which a later re-run would merge already-merged
+    ids together.
+
+    Submit it rather than running it on a login node: it reads and writes
+    every level. Mind the QOS ceiling (see the warning in section 5b) —
+    `sbatch --qos=1day --time=12:00:00 --cpus-per-task=8 --mem=64G`.
+
+!!! tip "Exporting a store as a single file (`.zip` or `.iso`)"
+    A zarr store is tens of thousands of small files, which copies slowly
+    everywhere and badly to Windows. Two ways to make it one file:
+
+    ```bash
+    pixi run zip --store /path/to/image.zarr        # needs nothing extra
+    pixi run iso --store /path/to/image.zarr        # needs an ISO builder
+    ```
+
+    **`.zip` is the one that always works.** It needs nothing beyond Python,
+    and zarr reads a store straight out of it *without unpacking*:
+
+    ```python
+    import zarr
+    store = zarr.storage.ZipStore("image.zarr.zip", mode="r")
+    group = zarr.open_group(store, path="image.zarr", mode="r")
+    ```
+
+    Windows Explorer opens it natively, and unzipping gives the store back
+    byte for byte. patchworks reads a bundle wherever it takes a store path,
+    so the viewer works on one directly — same layers, same calibration,
+    same auto-loaded label groups:
+
+    ```bash
+    pixi run -e viewer napari /path/to/image.zarr.zip
+    ``` It is written `ZIP_STORED` — the chunks are already
+    zstd-compressed, so deflating them again would cost a full pass to save
+    almost nothing — and entry by entry, so memory stays flat.
+
+    **Automatically, at the end of a run.** Add a `bundle:` block to the
+    multi config and `pixi run multi-slurm` packs the store itself, once
+    every segmentation *and* relation has succeeded:
+
+    ```yaml
+    # config/multi.yaml
+    bundle:
+      format: "zip"    # or "iso"; omit the block for no bundle
+      qos: "1day"      # `time` must stay under this QOS's MaxWall
+    ```
+
+    Or `--bundle zip` for a one-off. Under `--profile` it is submitted as
+    its own job, for the same reason the occupancy and relate steps are. A
+    failed relation skips it deliberately: a bundle of a half-finished run
+    would look complete while missing workbooks. If the packing itself
+    fails, nothing is lost — the store is complete on disk and
+    `pixi run zip` retries just that step.
+
+    **`.iso` mounts as a read-only drive**, which `.zip` does not, so the
+    store can be opened in place by anything that takes a path. The cost is
+    that it needs `xorriso`, `genisoimage` or `mkisofs` on the system, and
+    none of them is on conda-forge, so on a cluster without one this option
+    is simply unavailable.
+
+!!! tip "Details of the `.iso` format"
+    A zarr store is tens of thousands of small files, which copies slowly
+    everywhere and badly to Windows. `pixi run iso` packs a finished store
+    into one image that mounts read-only with a double-click:
+
+    ```bash
+    pixi run iso --store /path/to/image.zarr --dry-run   # report, write nothing
+    pixi run iso --store /path/to/image.zarr
+    ```
+
+    Mount it: **Windows** right-click → Mount; **macOS** double-click or
+    `hdiutil attach`; **Linux** `sudo mount -o loop <iso> /mnt/point`. The
+    store inside opens with napari/patchworks unchanged — same bytes, just
+    packaged.
+
+    **Submit it rather than running it on a login node**: packing a store
+    reads every file and writes the whole image, and a shared login node
+    kills a process that large with no message — the run just returns to the
+    prompt partway through, leaving no usable `.iso`. Same QOS ceiling as
+    everything else:
+
+    ```bash
+    sbatch --qos=1day --time=12:00:00 --cpus-per-task=4 --mem=8G \
+      --wrap "cd $PWD && pixi run iso --store /path/to/image.zarr"
+    ```
+
+    It needs **`xorriso`, `genisoimage` or `mkisofs`** from the system —
+    whichever is present. None of them is on conda-forge (it carries no
+    ISO-building C tool), so this is deliberately *not* a pixi dependency:
+    declaring one makes `pixi install` unsolvable and takes every
+    environment down with it. Check with
+    `which xorriso genisoimage mkisofs`, and try `module avail` before
+    asking an admin.
+
+    Do not substitute a pure-Python ISO builder such as `pycdlib`: those
+    assemble the whole image in RAM and die partway through a store with
+    tens of thousands of files. The C tools stream straight to the output
+    file, so the file count costs no memory at all. The
+    image is ISO-9660 level 3 with Rock Ridge *and* Joliet and deep-directory
+    relocation disabled, because a zarr v3 chunk path nests deeper than
+    ISO-9660's 8 levels — without that, Windows sees a tree flattened into
+    `RR_MOVED` that still looks like it copied correctly.
+
 !!! tip "Dropping objects by size with `min_volume`/`max_volume`"
     `min_volume: N` drops any object smaller than `N` µm³; `max_volume: N`
     drops any object larger than `N` µm³ (e.g. several objects merged into
@@ -333,6 +480,41 @@ set-resources:
     runtime: 240
 ```
 
+!!! warning "`runtime` is capped by the QOS, and sbatch rejects — it does not truncate"
+    Every `runtime:` above is bounded by the QOS the job lands in. Ask for
+    more and **`sbatch` refuses the job**, so it never starts:
+
+    ```
+    sbatch: error: QOSMaxWallDurationPerJobLimit
+    sbatch: error: Batch job submission failed: Job violates accounting/QOS policy
+    ```
+
+    The giveaway is an **empty log file**: the rule's `logs/<rule>.log` is
+    created by Snakemake but nothing ever writes to it, because the script
+    never ran. The reason appears only in the submission error, not in the
+    log.
+
+    Raising `runtime` past the cap therefore does not work on its own — you
+    have to request a QOS that allows it, per rule:
+
+    ```yaml
+    set-resources:
+      merge:
+        qos: "1day"      # a QOS your account may use on that partition
+        runtime: 720
+    ```
+
+    List what you may ask for, and each one's ceiling:
+
+    ```bash
+    sacctmgr show assoc user=$USER format=partition,qos%40
+    sacctmgr show qos format=name,maxwall
+    ```
+
+    On scicore the default QOS allows 6h, which is why the shipped profile
+    keeps every CPU rule at or below `runtime: 360` and gives the long
+    `segment` rule an explicit `qos:`.
+
 Then launch (from a login node — Snakemake submits and watches the jobs):
 
 ```bash
@@ -646,9 +828,30 @@ abort the others; you get a per-config status and a non-zero exit.
     caps the wall time below `--relate-time` — `srun` fails immediately with
     `QOSMaxWallDurationPerJobLimit` when that happens; `sacctmgr -p show
     assoc user=$USER` and `sacctmgr -p show qos` list what's available and
-    each one's `MaxWall`. Under plain `multi` (no `--profile`), relations
+    each one's `MaxWall`.
+
+    The same settings can live in the multi config as a `relate:` block, so
+    the shipped `pixi run multi-slurm` task keeps working without extra
+    flags:
+
+    ```yaml
+    # config/multi.yaml
+    relate:
+      qos: "1day"
+      time: 720        # minutes, per pair; must stay under that QOS's MaxWall
+    ```
+
+    A `--relate-*` flag overrides the block for that one key; anything the
+    block does not set keeps its default. An unknown key there is an error
+    rather than silently ignored, since a typo would otherwise run with the
+    default you meant to replace. Under plain `multi` (no `--profile`), relations
     still run locally, in-process, one after another, as before.
 
+    Each pair logs its shape, chunk count and object count before it starts,
+    then a progress line roughly once a minute (`label_relations: 412/3,600
+    (11%) after 7m, ~55m left`), so a long relation is distinguishable from a
+    hung one in `logs/relate/<a>_to_<b>.log`.
+
     Because every pair gets its own job, one running long no longer starves
     the others out of a shared time budget, and a pair that gets killed no
     longer takes an already-finished sibling's workbook down with it.

{patchworks-2.7.0 → patchworks-2.8.0}/src/patchworks/_io.py

@@ -55,6 +55,91 @@ def zarr_compressor_kwargs(zarr_format: int = 3) -> dict:
         return {}
 
 
+def open_zarr_source(
+    store_path: Union[str, Path],
+) -> tuple[Union[str, "zarr.storage.StoreLike"], str]:
+    """Resolve a store path, transparently opening a ``.zip`` bundle.
+
+    A store packed by ``pixi run zip`` is one file holding
+    ``<name>.zarr/...``. zarr reads it in place through a ``ZipStore``, so
+    nothing has to be unpacked first -- but a plain path string does not,
+    and every reader here takes a path. This returns what zarr and dask
+    should actually be handed, plus the prefix to prepend to a component.
+
+    Parameters
+    ----------
+    store_path : str or Path
+        A ``.zarr`` directory, or a ``.zip`` bundle containing one.
+
+    Returns
+    -------
+    tuple
+        ``(source, prefix)``. For a directory, the path and ``""``. For a
+        bundle, an open read-only ``ZipStore`` and the store's name inside
+        it, so a component is addressed as ``f"{prefix}/{component}"``.
+
+    Raises
+    ------
+    ValueError
+        If a ``.zip`` does not hold exactly one top-level store.
+    """
+    text = str(store_path)
+    if ".zip" not in text:
+        return text, ""
+
+    import zipfile
+
+    # The bundle may be addressed with a group path after it, e.g.
+    # "scan.zarr.zip/labels/cells" -- callers build those by string-joining.
+    head, _, tail = text.partition(".zip")
+    archive_path = head + ".zip"
+    with zipfile.ZipFile(archive_path) as archive:
+        tops = {
+            name.split("/", 1)[0] for name in archive.namelist() if "/" in name
+        }
+    if len(tops) != 1:
+        raise ValueError(
+            f"{archive_path} must contain exactly one top-level store; found "
+            f"{sorted(tops) or 'nothing'}. Bundles written by "
+            "`pixi run zip` always do."
+        )
+    prefix = tops.pop()
+    inner = tail.strip("/")
+    if inner:
+        prefix = f"{prefix}/{inner}"
+    return zarr.storage.ZipStore(archive_path, mode="r"), prefix
+
+
+def open_group_any(path: Union[str, Path], mode: str = "r"):
+    """``zarr.open_group`` that also accepts a path *inside* a .zip bundle.
+
+    Callers build group paths by string-joining (``f"{store}/labels"``),
+    which a bundle breaks: the archive is a file, not a directory. Split on
+    the ``.zip`` instead, so ``bundle.zip/labels/cells`` resolves to the
+    right group inside it.
+    """
+    source, prefix = open_zarr_source(path)
+    return zarr.open_group(source, path=prefix, mode=mode)
+
+
+def from_zarr_any(path: Union[str, Path], component: str | None = None):
+    """``dask.array.from_zarr`` that also accepts a .zip bundle."""
+    import dask.array as _da
+
+    source, prefix = open_zarr_source(path)
+    inner = _component(prefix, component) if component else prefix
+    return (
+        _da.from_zarr(source, component=inner)
+        if inner
+        else _da.from_zarr(source)
+    )
+
+
+def _component(prefix: str, name: str) -> str:
+    """Join a bundle prefix and a component, tolerating an empty prefix."""
+    return f"{prefix}/{name}" if prefix else name
+
+
 def load_ome_zarr(
     store_path: Union[str, Path],
     channel: int | None = 0,
@@ -86,7 +171,8 @@ def load_ome_zarr(
     >>> arr.shape
     (128, 2048, 2048)
     """
-    root = zarr.open_group(str(store_path), mode="r")
+    source, prefix = open_zarr_source(store_path)
+    root = zarr.open_group(source, path=prefix, mode="r")
     # OME-ZARR 0.5 nests under "ome" key; older stores use "multiscales" directly
     _attrs = dict(root.attrs)
     _ms = _attrs.get("multiscales") or _attrs.get("ome", {}).get("multiscales")
@@ -104,7 +190,9 @@ def load_ome_zarr(
         if zarr_ndim > len(chunks):
             zarr_chunks = (1,) * (zarr_ndim - len(chunks)) + tuple(chunks)
 
-    arr = da.from_zarr(str(store_path), component=path, chunks=zarr_chunks)
+    arr = da.from_zarr(
+        source, component=_component(prefix, path), chunks=zarr_chunks
+    )
     if channel is not None:
         arr = _select_channel(arr, channel, _ms[0], store_path)
     return arr

{patchworks-2.7.0 → patchworks-2.8.0}/src/patchworks/_relations.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 import logging
-from concurrent.futures import ThreadPoolExecutor
+import time as _time
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 from typing import Union
 
@@ -11,6 +12,8 @@ import dask.array as da
 import numpy as np
 
 from ._chunks import cpu_allocation
+from ._progress import PROGRESS_INTERVAL_S as _PROGRESS_INTERVAL_S
+from ._progress import log_progress
 
 logger = logging.getLogger(__name__)
 
@@ -97,14 +100,35 @@ def label_relations(
     total = int(np.prod(n_blocks))
     nw = n_workers if n_workers is not None else min(4, cpu_allocation())
 
+    logger.info(
+        "label_relations: scanning %d chunk(s) of %s with %d worker(s)",
+        total,
+        "x".join(str(n) for n in a.shape),
+        nw,
+    )
+
     def _one(flat_idx: int) -> np.ndarray:
         idx = np.unravel_index(flat_idx, n_blocks)
         return _chunk_pairs(
             np.asarray(a.blocks[idx]), np.asarray(b.blocks[idx])
         )
 
+    # as_completed, not ex.map: map returns an iterator that yields in
+    # submission order, so one slow early chunk withholds every later result
+    # and the log stays silent however many have actually finished. This step
+    # runs for hours in a batch job where the only question the log has to
+    # answer is "working, or hung?".
+    started = _time.monotonic()
+    last = started
+    parts = []
     with ThreadPoolExecutor(max_workers=nw) as ex:
-        parts = list(ex.map(_one, range(total)))
+        futures = {ex.submit(_one, i): i for i in range(total)}
+        for done, future in enumerate(as_completed(futures), start=1):
+            parts.append(future.result())
+            now = _time.monotonic()
+            if now - last >= _PROGRESS_INTERVAL_S or done == total:
+                log_progress("label_relations", done, total, started)
+                last = now
 
     rows = [p for p in parts if p.size]
     if not rows:

{patchworks-2.7.0 → patchworks-2.8.0}/src/patchworks/plugins/napari.py

@@ -29,9 +29,8 @@ from pathlib import Path
 from typing import Any, Union
 
 import dask.array as da
-import zarr
 
-from .._io import load_ome_zarr
+from .._io import from_zarr_any, load_ome_zarr, open_group_any
 from .ome_zarr import read_ngff_attr
 
 logger = logging.getLogger(__name__)
@@ -84,7 +83,7 @@ def _has_multiscales(path: Union[str, Path]) -> bool:
     bool
         True if the group has a ``multiscales`` attribute.
     """
-    root = zarr.open_group(str(path), mode="r")
+    root = open_group_any(path)
     return read_ngff_attr(root.attrs, "multiscales") is not None
 
 
@@ -105,7 +104,7 @@ def _multiscale_levels(
     list of da.Array
         One lazy array per resolution level.
     """
-    root = zarr.open_group(str(path), mode="r")
+    root = open_group_any(path)
     datasets = read_ngff_attr(root.attrs, "multiscales")[0]["datasets"]
     return [
         load_ome_zarr(path, channel=channel, level=i)
@@ -204,7 +203,7 @@ def _label_hint(path: Union[str, Path]) -> dict[str, Any]:
         ``metadata=``/merge into a bigger dict either way.
     """
     try:
-        attrs = zarr.open_group(str(path), mode="r").attrs
+        attrs = open_group_any(path).attrs
     except Exception:
         return {}
     if "n_objects" not in attrs:
@@ -229,7 +228,7 @@ def _inner_label_names(store: Union[str, Path]) -> list[str]:
         Registered label-image names (empty if there are none).
     """
     try:
-        grp = zarr.open_group(f"{store}/labels", mode="r")
+        grp = open_group_any(f"{store}/labels")
     except Exception:
         return []
     return list(read_ngff_attr(grp.attrs, "labels", []) or [])
@@ -256,9 +255,9 @@ def _resolve_labels(
         if _has_multiscales(source):
             levels = _multiscale_levels(source, None)
             return [lvl.astype("int32") for lvl in levels]
-        arr = da.from_zarr(str(source), component=component)
+        arr = from_zarr_any(source, component=component)
     elif isinstance(source, (str, Path)):
-        arr = da.from_zarr(str(source))
+        arr = from_zarr_any(source)
     else:
         arr = da.asarray(source)
     return arr.astype("int32")

{patchworks-2.7.0 → patchworks-2.8.0}/src/patchworks/plugins/ome_zarr.py

@@ -58,16 +58,17 @@ from itertools import product as _iproduct
 from pathlib import Path
 from typing import Union
 
+import dask
 import dask.array as da
 import numpy as np
 import zarr
 
-from .._chunks import cpu_allocation
+from .._chunks import cpu_allocation, safe_worker_count
 from .._progress import (
     PROGRESS_INTERVAL_S as _PROGRESS_INTERVAL_S,
 )
 from .._progress import dask_progress, log_progress
-from .._io import load_ome_zarr, zarr_compressor_kwargs
+from .._io import load_ome_zarr, open_group_any, zarr_compressor_kwargs
 
 logger = logging.getLogger(__name__)
 
@@ -774,7 +775,26 @@ def _to_zarr_level(
         shards=sh,
         dtype=arr.dtype,
     )
-    with ctx:
+    # Rechunking to the shard size is the one place this module hands work to
+    # dask's scheduler, and dask defaults to one thread per *machine* core --
+    # on a 128-core node that is 128 tasks each holding a whole shard
+    # (~512 MB by default), inside whatever cgroup the job was granted. Bound
+    # it here rather than in each caller, so a direct API call is as safe as
+    # the workflow's.
+    shard_nbytes = int(np.prod(sh)) * arr.dtype.itemsize
+    n_workers = max(
+        1,
+        min(
+            cpu_allocation(),
+            safe_worker_count(shard_nbytes, fn_overhead=3),
+        ),
+    )
+    logger.debug(
+        "resharding with %d worker(s) for %.0f MB shards",
+        n_workers,
+        shard_nbytes / 1024**2,
+    )
+    with ctx, dask.config.set(scheduler="threads", num_workers=n_workers):
         arr.rechunk(sh).store(z, lock=True, compute=True)
 
 
@@ -1124,7 +1144,9 @@ def _read_zarr_calibration(store: Union[str, Path], axes: str) -> PixelSize:
         the store has no multiscales metadata).
     """
     try:
-        root = zarr.open_group(str(store), mode="r")
+        # open_group_any, not zarr.open_group: the store may be a .zip
+        # bundle, possibly with a group path after it.
+        root = open_group_any(store)
         ms = read_ngff_attr(root.attrs, "multiscales")[0]
         ax = [a["name"] for a in ms["axes"]]
         scale = ms["datasets"][0]["coordinateTransformations"][0]["scale"]

{patchworks-2.7.0 → patchworks-2.8.0}/tests/test_napari.py

@@ -104,3 +104,78 @@ def test_label_hint_empty_without_n_objects(tmp_path):
 def test_label_hint_missing_store_returns_empty():
     """A path that doesn't exist (or isn't a label group) just yields {}."""
     assert nplugin._label_hint("/no/such/store.zarr") == {}
+
+
+def test_a_zip_bundle_opens_exactly_like_the_directory(tmp_path):
+    """`pixi run napari` must work on a bundle, not only on a directory.
+
+    Every reader here builds group paths by string-joining
+    (f"{store}/labels/{name}"), which a bundle breaks: the archive is a
+    file. Without this, packing a store made it unviewable.
+    """
+    import zipfile
+    from pathlib import Path
+
+    import zarr
+
+    from patchworks.plugins import napari as napari_plugin
+    from patchworks.plugins.ome_zarr import (
+        read_pixel_size,
+        register_labels,
+        to_ome_zarr,
+    )
+
+    image = np.arange(4 * 64 * 64, dtype="uint16").reshape(4, 64, 64)
+    store = to_ome_zarr(
+        image,
+        tmp_path / "image.zarr",
+        axes="zyx",
+        n_levels=3,
+        chunks=(2, 32, 32),
+        pixel_size={"z": 0.24, "y": 0.108, "x": 0.108},
+        progress=False,
+    )
+    labels = np.zeros((4, 64, 64), dtype="uint32")
+    labels[1:3, 10:30, 10:30] = 7
+    group = zarr.open_group(f"{store}/labels/cilia", mode="a")
+    base = group.create_array(
+        "0", shape=labels.shape, chunks=(2, 32, 32), dtype="uint32"
+    )
+    base[:] = labels
+    register_labels(store, "cilia", n_levels=3, progress=False, n_objects=1)
+
+    bundle = tmp_path / "image.zarr.zip"
+    with zipfile.ZipFile(bundle, "w", zipfile.ZIP_STORED) as archive:
+        for item in sorted(Path(store).rglob("*")):
+            if item.is_file():
+                archive.write(item, item.relative_to(Path(store).parent))
+
+    for source in (str(store), str(bundle)):
+        label_group = f"{source}/labels/cilia"
+        assert napari_plugin._inner_label_names(source) == ["cilia"], source
+        assert napari_plugin._has_multiscales(source), source
+        assert [
+            tuple(level.shape)
+            for level in napari_plugin._multiscale_levels(source, None)
+        ] == [(4, 64, 64), (4, 32, 32), (4, 16, 16)], source
+        assert [
+            tuple(level.shape)
+            for level in napari_plugin._multiscale_levels(label_group, None)
+        ] == [(4, 64, 64), (4, 32, 32), (4, 16, 16)], source
+        assert napari_plugin._label_hint(label_group)["n_objects"] == 1
+        assert napari_plugin._pyramid_calibration(label_group, 3) == (
+            [0.24, 0.108, 0.108],
+            ["micrometer"] * 3,
+        ), source
+        assert read_pixel_size(source) == {
+            "z": 0.24,
+            "y": 0.108,
+            "x": 0.108,
+        }, source
+
+    # And the pixel data itself round-trips.
+    from patchworks import load_ome_zarr
+
+    assert np.array_equal(
+        np.asarray(load_ome_zarr(str(bundle), channel=None, level=0)), image
+    )