Bioformats zarr loader using wrong paths for current bioformats2raw output

[xinaesthete]

Describe the bug
I have a test image processed with bioformats2raw and served locally. When I try to load this URL in Avivator, it posts errors to the console about not finding METADATA.ome.xml and ultimately doesn't show any output.

It seems like loadBioformatsZarr is just looking in the wrong places... if I change this in the version I'm running locally

export async function loadBioformatsZarr(
  source: string | (File & { path: string })[],
  options: Partial<ZarrOptions> = {}
) {
  const METADATA = 'OME/METADATA.ome.xml';
  const ZARR_DIR = '';

then it works as expected with my test data. I can provide more details of the versions of bioformats2raw used etc if that helps.

[xinaesthete]

@keller-mark clearly it's not that Zarr images in viv aren't being used anywhere - and presumably this change would break things in other circumstances - but in my testing with bioformats2raw output (which according to the documentation is what this is to be used with), I didn't get any useful results without. I'll look in more detail at vitessce spatial data examples where zarr images are used etc.

There should probably be an entry in source-info.js using OME-NGFF and we might also identify if test coverage can be improved here.

I'll open a PR for this shortly.

Best,
Peter

[xinaesthete]

Come to think of it, maybe loadOmeZarr as opposed to loadBioformatsZarr is what's being used elsewhere?

[xinaesthete]

I tried loading one of the Zarr images used in one of the vitessce demos (http://localhost:3000/?dataset=codeluppi-2018&theme=dark) in current production version of Avivator, and it isn't working:

https://avivator.gehlenborglab.org/?image_url=https://vitessce-data.storage.googleapis.com/0.0.31/master_release/linnarsson/linnarsson.images.zarr/

I'll try with my modification.

[xinaesthete]

This image does work in current Avivator

https://avivator.gehlenborglab.org/?image_url=https://storage.googleapis.com/vitessce-demo-data/spatialdata-august-2025/visium_hd_3.0.0.spatialdata.zarr/images/Visium_HD_Mouse_Small_Intestine_full_image

[keller-mark]

Bioformats-Zarr predates OME-Zarr. I am almost certain you want the latter.

[xinaesthete]

Right - but what we want is that when we put a URL like https://vitessce-data.storage.googleapis.com/0.0.31/master_release/linnarsson/linnarsson.images.zarr/ into Avivator and it decides automatically what to do, it does the right thing.

[keller-mark]

That linnarsson example image is super old though. It is not an OME-Zarr/OME-NGFF image. No one should be generating images in that format anymore.

[keller-mark]

You may be running into this separate issue vitessce/vitessce#2199

[xinaesthete]

The original issue here is that generating something with bioformats2raw, serving it, and then pointing Avivator at that image, doesn't work.

[keller-mark]

Then yes, I believe you are running into the issue described in vitessce/vitessce#2199

https://ngff.openmicroscopy.org/0.4/index.html#bf2raw

[xinaesthete]

ok, that does indeed seem related.

Bioformats-Zarr predates OME-Zarr. I am almost certain you want the latter.

The call to loadBioformatsZarr is made by createLoader in sites/avivator/src/utils.js - in Avivator, only if that throws an error does it fall back to loadOmeZarr. When I tried changing that code-path to use loadOmeZarr, it also didn't work (for reasons that may be related to the issue you linked).

That linnarsson example image is super old though. It is not an OME-Zarr/OME-NGFF image. No one should be generating images in that format anymore.

ok, interesting - also important to make sure old data doesn't break, so maybe useful as a test-case to have samples such as that... although having said that, that linnarson sample still works in Vitessce and maybe never worked in Avivator - so maybe it's not particularly important here.

The Visium intestine image correctly displays in Avivator with or without my change, as it always fails to find that METADATA.xml and falls back to loadOmeZarr which interprets it correctly.

New output from current bioformats2raw doesn't appear to work. The loadBioformatsZarr documentation says that it

Opens root directory generated via bioformats2raw --file_type=zarr

In fact, that --file_type=zarr isn't recognised by the current version.

As of now, I haven't seen any samples that regress as a result of changing the loadBioformatsZarr implementation, but they may well exist. Am I to take it that loadOmeZarr should ultimately be able to properly interpret current bioformats2raw outputs - at which point maybe loadBioformatsZarr becomes irrelevant?

[keller-mark]

Am I to take it that loadOmeZarr should ultimately be able to properly interpret current bioformats2raw outputs - at which point maybe loadBioformatsZarr becomes irrelevant?

Correct

In fact, that --file_type=zarr isn't recognised by the current version.

Right, this is why no one should be generating images in this format. We should deprecate the Bioformats-Zarr stuff, as there (at least to my knowledge) are no tools that will output them, and the terminology is confusing.