patchworks 2.6.12__tar.gz → 2.8.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchworks
-Version: 2.6.12
+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
@@ -57,6 +57,7 @@ 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: psutil; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'

{patchworks-2.6.12 → patchworks-2.8.0}/docs/api/plugins/ome_zarr.md

@@ -25,6 +25,10 @@ resolution, matching anisotropic microscopy stacks.
 
 ::: patchworks.plugins.ome_zarr.register_labels
 
+## reshard_level
+
+::: patchworks.plugins.ome_zarr.reshard_level
+
 ## read_pixel_size
 
 ::: patchworks.plugins.ome_zarr.read_pixel_size
@@ -37,6 +41,14 @@ matches the store, and reads both.
 
 ::: patchworks.plugins.ome_zarr.ngff_version
 
+Every writer takes an `ngff_version=` keyword: `"auto"` (default) follows the
+installed zarr — 0.5 on v3, 0.4 on v2 — and `"0.4"` pins the older, zarr-v2
+layout. Writing into an existing store always follows *that store's* format,
+so a label pyramid added later can never disagree with the image it sits in.
+NGFF 0.6 is released but not written: RFC-5 replaces `axes` with
+`coordinateSystems` and requires `input`/`output` on every coordinate
+transformation, and no reader supports it yet.
+
 ::: patchworks.plugins.ome_zarr.read_ngff_attr
 
 ::: patchworks.plugins.ome_zarr.write_ngff_attrs

{patchworks-2.6.12 → 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.6.12 → patchworks-2.8.0}/docs/guide/snakemake.md

@@ -50,7 +50,9 @@ work_dir: "/scratch/results"   # everything is written here
 # conversion (input → pyramidal OME-ZARR)
 reuse_pyramid: true            # .ims: copy its own pyramid (fast)
 convert_chunks: null           # null → bounded auto chunks; or [c,z,y,x]
-shard: false                   # true → pack chunks into shards (fewer files)
+shard: false                   # true → pack chunks into shards (fewer files);
+                               # covers the image and the label pyramids
+ngff_version: "auto"           # OME-ZARR version: "auto" (0.5), or "0.4"
 
 # tiling
 channel: 0                     # channel to segment, 0-based (null = keep all)
@@ -83,21 +85,241 @@ cellpose:
 pyramid_levels: 5
 pyramid_downscale: 2
 sequential_labels: true        # renumber labels to a contiguous 1..N
+shard_labels: false            # true → also reshard label level 0 after the
+                               # merge (one extra pass; see tip below)
 ```
 
 !!! tip "Growing labels after segmentation"
     `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)
     for how it works and the equivalent direct-API call.
 
+!!! tip "What `shard: true` covers, and `shard_labels` for label level 0"
+    Without sharding, one chunk is one file, and a fine-chunked level 0 can
+    run to ~950k of them — painful on a shared filesystem at write time and
+    on every read after. `shard: true` packs chunks into far fewer files
+    without changing the chunking or the memory profile.
+
+    `shard: true` applies to **the converted image (all levels)** and to
+    **the label pyramid levels (1..N)**. It cannot apply to **label level
+    0** *while that level is being written*: a shard has to be written whole
+    by a single writer, while level 0 is filled one chunk at a time by
+    concurrent `segment` jobs (or by the merge's own worker pool). Two
+    writers doing a read-modify-write on the same shard file silently lose
+    each other's chunks.
+
+    Once the merge has finished, though, nothing is writing it anymore, so a
+    single-threaded pass *can* rewrite it sharded. That is `shard_labels`:
+
+    ```yaml
+    shard: true
+    shard_labels: true       # or an explicit shape, e.g. [16, 512, 512]
+    ```
+
+    `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. 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
+    is 7,616 files per label group, well under the 200,000 at which the
+    conversion starts warning. On scicore that is fine; on a filesystem with
+    a tighter inode or per-directory budget it may not be.
+
+!!! tip "Which OME-ZARR version gets written (`ngff_version`)"
+    OME-ZARR is versioned, and the version decides the **zarr format** as
+    well as the metadata layout — the two are not separate choices. NGFF 0.4
+    is specified over zarr v2 and puts `multiscales`, `labels` and
+    `image-label` at the top level of the store's attributes; 0.5 is the
+    zarr-v3 revision and nests them under an `ome` key.
+
+    `ngff_version: "auto"` (the default) follows the installed zarr, which on
+    any current environment means **0.5**. Pin `"0.4"` only when a downstream
+    tool still cannot read 0.5:
+
+    ```yaml
+    ngff_version: "0.4"
+    shard: false           # required: zarr v2 has no sharding codec
+    ```
+
+    That is a real trade-off, not a formality — 0.4 means a zarr-v2 store, and
+    sharding is a zarr-v3 feature, so `shard`/`shard_labels` stop doing
+    anything. The workflow refuses the combination rather than silently
+    ignoring it. The store's own root file changes too (`.zgroup` instead of
+    `zarr.json`), which the rules account for.
+
+    Writing into an **existing** store always follows that store's format,
+    whatever this key says: the label pyramid is written by `merge`, long
+    after `convert` made the image, and a store with v2 arrays and v3
+    metadata is one no reader can open.
+
+    **What about 0.6?** It was released on 14 September 2026 and patchworks
+    does not write it. It is not a version bump but a different metadata
+    document: RFC-5 replaces a multiscale's `axes` with `coordinateSystems`
+    and requires an `input`/`output` pair on every coordinate transformation.
+    Nothing reads it yet either — ome-zarr-py, and so napari, still default
+    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
@@ -258,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
@@ -362,6 +619,7 @@ input: "/data/scan.ims"
 work_dir: "/scratch/results"
 tile_shape: [16, 1024, 1024]
 shard: false                   # true → far fewer files, same chunks
+ngff_version: "auto"           # convert reads it, so it belongs here
 tiles_per_job: 4
 ```
 
@@ -447,11 +705,21 @@ snakemake --workflow-profile profile/slurm --configfile config/common.yaml confi
 ```
 
 !!! warning "Conversion settings belong in the shared file"
-    `convert` runs **once**, from the first config only. A `shard`, `input` or
-    `pyramid_levels` set on the second config is therefore never read, and
-    nothing logs that it was dropped. `run_multi` refuses to start when those
-    keys disagree across configs and tells you which one — but if you drive
-    the configs by hand, keep them in `common.yaml`.
+    `convert` runs **once**, from the first config only. A `shard`, `input`,
+    `convert_chunks`, `sequence_pattern` or `reuse_pyramid` set on the second
+    config is therefore never read, and nothing logs that it was dropped.
+    `run_multi` refuses to start when those keys disagree across configs and
+    tells you which one — but if you drive the configs by hand, keep them in
+    `common.yaml`.
+
+    `ngff_version` is in that list: it decides the store's zarr format, so a
+    second config disagreeing about it would describe a store that is not the
+    one on disk.
+
+    `merge` runs once **per config**, so the keys it reads —
+    `pyramid_levels`, `pyramid_downscale`, `sequential_labels`,
+    `min_volume`/`max_volume` and `shard_labels` — may legitimately differ
+    between them, and are only in `common.yaml` for convenience.
 
     Splitting the configs is optional: a self-contained config still works,
     and `common:` can simply be left out of `multi.yaml`.
@@ -560,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.6.12 → patchworks-2.8.0}/pyproject.toml

@@ -96,7 +96,16 @@ napari = [
 # openpyxl -> scripts/run_multi.py writes label_relations() output as an
 # Excel workbook (per-object + per-container sheets), not a plain CSV.
 workflow = ["snakemake>=8", "snakemake-executor-plugin-slurm", "openpyxl"]
-dev = ["pytest", "pytest-cov", "scikit-image", "psutil", "tqdm"]
+# jsonschema validates what we write against the vendored official
+# OME-NGFF schemas (tests/ngff_schemas/); without it that one test skips.
+dev = [
+    "pytest",
+    "pytest-cov",
+    "scikit-image",
+    "psutil",
+    "tqdm",
+    "jsonschema>=4.18",
+]
 docs = ["mkdocs-material>=9.0", "mkdocstrings[python]>=0.24"]
 all = [
     "patchworks[io,gpu,bioio,imaris,napari]",

{patchworks-2.6.12 → patchworks-2.8.0}/src/patchworks/_chunks.py

@@ -449,6 +449,18 @@ def auto_tile_shape_cellpose(
     (1, 2048, 2048)
     """
     n_workers = n_workers or cpu_allocation()
+    # Cellpose resizes the tile before the net runs -- by `rescale`
+    # (= 30 / diameter) on every axis, and by `anisotropy` on z as well -- so
+    # the array it actually holds is bigger than the one it was handed, and a
+    # budget computed from the unresized tile under-counts by that factor. A
+    # diameter half the model's 30 px means a 2x upsample per axis: 8x the
+    # voxels, enough to turn a comfortable tile into an OOM.
+    #
+    # Both only ever *shrink* the tile. A predicted downsample (diameter > 30)
+    # would license a bigger one, but these are a safety margin against a
+    # rough memory model, not a measurement to spend headroom on.
+    rescale = max(1.0, 30.0 / diameter) if diameter else 1.0
+    z_resize = max(1.0, anisotropy or 1.0)
     # A tile holds n_channels planes per voxel (e.g. Cellpose's
     # cyto+nuclei pair), so the per-voxel cost -- and every budget
     # derived from it below -- scales with them.
@@ -475,7 +487,8 @@ def auto_tile_shape_cellpose(
     min_tile = int(4 * diameter) if diameter is not None else 1
 
     if n_spatial == 2 or not do_3D:
-        max_pixels_2d = max(1, max_raw_bytes // itemsize)
+        # Two axes resized, so the cost per configured pixel is rescale**2.
+        max_pixels_2d = max(1, int(max_raw_bytes // (itemsize * rescale**2)))
         tile_side = max(min_tile, int(max_pixels_2d**0.5))
         if n_spatial == 2:
             y, x = shape[-2], shape[-1]
@@ -485,9 +498,10 @@ def auto_tile_shape_cellpose(
             chunk_spatial = [1, min(y, tile_side), min(x, tile_side)]
     else:
         z, y, x = shape[-3], shape[-2], shape[-1]
-        # Cellpose resizes z by `anisotropy` before the net runs, so the tile
-        # it actually holds is that much deeper than the one handed to it.
-        effective_z = z * max(1.0, anisotropy or 1.0)
+        # All three axes are resized: z by anisotropy * rescale, y/x by
+        # rescale each -- so one configured voxel costs
+        # anisotropy * rescale**3 of them.
+        effective_z = z * z_resize * rescale**3
         max_pixels_per_slice = max(
             1, int((max_raw_bytes // 3) // (effective_z * itemsize))
         )

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

@@ -18,32 +18,128 @@ _ZARR_V3 = int(zarr.__version__.split(".")[0]) >= 3
 _ZARR_V3 = int(zarr.__version__.split(".")[0]) >= 3
 
 
-def zarr_compressor_kwargs() -> dict:
+def zarr_compressor_kwargs(zarr_format: int = 3) -> dict:
     """Keyword arguments pinning the compression codec for a new array.
 
     zstd is already zarr v3's default, but relying on a library default means
     the stores patchworks writes change silently if that default ever moves.
     Labels in particular are highly compressible, so this is worth stating.
 
+    The codec *object* depends on the format of the array being written, not
+    on the installed zarr: zarr-python 3 can write a zarr-v2 array (which is
+    what NGFF 0.4 needs), and a v2 array rejects ``zarr.codecs.ZstdCodec`` --
+    it wants the numcodecs one.
+
+    Parameters
+    ----------
+    zarr_format : int, optional
+        Format of the array about to be created, 2 or 3 (default 3).
+
     Returns
     -------
     dict
-        ``compressors=``/``compressor=`` as the installed zarr expects, or
+        ``compressors=``/``compressor=`` as that combination expects, or
         empty if the codec cannot be built (then the default applies).
     """
     try:
-        if _ZARR_V3:
+        if _ZARR_V3 and zarr_format != 2:
             from zarr.codecs import ZstdCodec
 
             return {"compressors": (ZstdCodec(level=1),)}
         import numcodecs
 
-        return {"compressor": numcodecs.Zstd(level=1)}
+        codec = numcodecs.Zstd(level=1)
+        return {"compressors": (codec,)} if _ZARR_V3 else {"compressor": codec}
     except Exception:  # pragma: no cover - depends on the installed zarr
         logger.debug("could not pin a compressor; using zarr's default")
         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,
@@ -75,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")
@@ -93,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