Skip to content

Open zipped OME-Zarr images - #171

Merged
prete merged 1 commit into
mainfrom
claude/zipped-ome-zarr-images
Nov 18, 2026
Merged

prete merged 1 commit into
mainfrom
claude/zipped-ome-zarr-images

Conversation

@prete

@prete prete commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Problem

Zip detection (detectZarrZip) accepted only SpatialData. Any other zipped Zarr store threw "Only SpatialData stores are read from a zip", and the OME-Zarr loader could read only folders and Icechunk repositories. A zipped OME-Zarr image could not be opened at all. One example is the BioImage Archive's synthetic 24-plex series in S-BIAD3559:
https://ftp.ebi.ac.uk/biostudies/fire/S-BIAD/559/S-BIAD3559/Files/generated/packed_parallel_1gb_10k/image.ome.zarr.zip

Change

  • detectZarrZip returns an image dataset (imageKind: 'ome-zarr') when the zip's root attributes hold multiscales (v0.4), ome.multiscales (v0.5), or bioformats2raw.layout. SpatialData is still checked first. Other zips still throw, now with "neither SpatialData nor an OME-Zarr image". The predicate (isOmeZarrImageRootAttributes) is shared with Icechunk detection, which now also takes a bioformats2raw root as an image.
  • openImageStore in omeZarrLoader.ts opens a .zip URL with the existing openZippedZarrStore, then applies consolidated metadata when the store has it. Because the zip's directory lists every file, a missing key costs no request. openOmeZarrMultiscaleGroup uses the same path.
  • openImagePyramid sends .zip URLs to the OME-Zarr loader rather than the TIFF one. A manifest image ending in .zip gets imageKind: 'ome-zarr', and naming a zchunkstore alongside it is rejected, as for other OME-Zarr images.
  • Docs: user guide, architecture detection table, image modality page, manifest known limitations.

Testing

  • omeZarrLoader.test.ts: opens an image from a macOS-style zip (store in a folder, every entry deflated, a __MACOSX/ resource fork) and reads a channel tile's pixels.
  • datasetFactory.test.ts: a zipped OME-Zarr with a labels/ group detects as an image (not as SpatialData), a bioformats2raw zip as an image, and an AnnData zip is still rejected.
  • src/zarr, datasetFactory, datasetManifest, morphologyImage and imageOnlyDataset tests (211) pass, plus typecheck, lint and Prettier.
  • In the app (dev server, headless Chromium) with the S-BIAD3559 1gb_10k zip (846 MB, 5,412 entries, 24 channels, 4096², 5 levels):
    • It opened as "Image · 24 channels" with the channel names from the image's metadata and no page errors.
    • The first view took 26 requests and 2.3 MB.
    • Zoomed to level 0 with DAPI and PanCK on, it took 62 requests and 9.8 MB, and nuclei and membrane rings drew correctly.
    • The overview matches the deposit's preview.png.

Not covered

The deposit's objects/cells.enriched.geoparquet cell outlines can't be shown over the image. That needs a way to pair an image with an outlines file. The label stores named in its metadata.json were not deposited.

Zip detection read SpatialData only and threw for any other store, so a
zipped OME-Zarr image, such as the BioImage Archive's S-BIAD3559
image.ome.zarr.zip, could not be opened. A zip whose root holds
multiscales (v0.4 or v0.5) or a bioformats2raw layout now opens as an
image, read from the zip by byte range with the existing zip store; a
.zip image URL in a manifest goes to the OME-Zarr loader. Zips holding
anything else still get an error. Icechunk detection also takes a
bioformats2raw root as an image.
@prete
prete merged commit 709fa11 into main Nov 18, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant