Skip to content
BranchesTags

Repository files navigation

Build Status License DOI Coverage Lines of Code

OME-Zarr for Fiji logo

Table of contents

About

A convenience layer for using OME-Zarr in Fiji/ImageJ. Open a dataset the way you would open any image: drag it in, paste a URI, use the menu, or call it from a script. Support local and remote (https/s3) stores.

If the dropped / pasted / linked target is not recognized as a OME-Zarr v0.3 - v0.5 resource, it does nothing.

Features

How to open an OME-Zarr

Drag & Drop of local OME-Zarr folders and URIs

There are several options for what Fiji can do after drag & drop / copy & paste:

Users can select the default opening behavior via Plugins -> OME-Zarr -> Settings -> Opening behavior settings

The options are:

  • Open the highest available single-resolution image in ImageJ.
  • Open a matching single-resolution image in ImageJ (initial default). Users can preset a maximum image width, and Fiji will open the highest available single-resolution image that is not larger than the preset width. This is useful for avoiding the loading and opening of excessively large images. Fiji simply chooses an appropriately sized level from the resolution pyramids (multiscales) of the dropped OME-Zarr.
  • Open as a multi-resolution source in BigDataViewer. This is useful for large OME-Zarrs. Channel names, colors, contrast limits, and the time point are automatically extracted from the OME-Zarr metadata, if available.
  • Show a dialog with all available opening options.

The list is not fixed: any Fiji plugin can register its own opener, and it then appears here and in the dialog next to the built-in ones.

Note: BigDataViewer is part of Fiji, so there's no need to install anything extra. It is an image(s) viewer especially designed for chunk-based, multiresolution data, designed around the principle of loading only pixels that are needed for the current display of the image(s). It is thus suitable for OME-Zarr datasets and easily handles even the huge ones.

Copy & Paste of OME-Zarr URIs (local folder, http, https, s3)

  • Supports local paths, http(s) URLs, and s3:// URIs
    • Public (anonymous) S3 buckets work out of the box, e.g. s3://janelia-cosem-datasets/jrc_mus-choroid-plexus-3/jrc_mus-choroid-plexus-3.zarr/recon-1/em/fibsem-uint8.
    • Private buckets use your ambient AWS credentials (environment variables, ~/.aws/credentials, instance profile, etc.); if those are absent, access falls back to anonymous.
    • The AWS region defaults to us-east-1.
  • Three entry points:
    • Paste with CTRL / CMD / SHIFT + V (requires FIJI latest)
    • Paste via menu: Plugins -> OME-Zarr -> Paste OME-Zarr URI
    • Paste via button in FIJI: fiji_paste_button.png

Open via menu (local folders)

File -> Import -> OME-Zarr... opens a folder chooser. The selected folder is checked for Zarr metadata and then opened with the same opening behavior, resolution and reader backend as drag & drop and paste. Being a single-parameter SciJava command, it is macro-recordable:

run("OME-Zarr...", "directory=/path/to/image.ome.zarr");

Only local folders can be chosen here; for http(s) and s3:// locations use copy & paste.

Open as Dataset (scripting)

Plugins -> OME-Zarr -> Open OME-Zarr as Dataset takes the location as a single line of text and hands the image back as a Dataset output, so a macro or script can keep working with it:

run("Open OME-Zarr as Dataset", "uri=/path/to/image.ome.zarr");

Unlike the File -> Import entry it accepts local paths, file: and http(s): URIs, and it always produces a Dataset instead of following the configured open behavior. The reader backend still comes from the settings. s3:// is not supported here. The command opens no dialog of its own.

FIJI links (fiji://)

A fiji:// link on a web page opens an OME-Zarr straight in a (running) Fiji, honoring the same opening behavior as drag & drop and paste. Register the scheme once via Edit -> Options -> Desktop..., then a link such as

fiji://open/url?p=https://livingobjects.ebi.ac.uk/idr/zarr/v0.5/idr0033A/BR00109990_C2.zarr/0

opens that IDR dataset. Use open/file?p= for a local path and open/source?p= to let Fiji detect the source type. s3:// targets do not work through links — paste those instead (see above).

See doc/fiji-links-demo.html for a page with clickable examples of each form.

Choosing what happens on open

Dialog options

The opening-selection dialog with six openers and the help button

The dialog shows one icon button per registered opener, plus a help button; hovering a button explains what it does. The openers shipped here are:

  • Directly open a single-resolution image in ImageJ, which best matches the preferred width in the user settings.
  • Directly open the highest-resolution image in ImageJ.
  • Directly open a multi-resolution image in BigDataViewer.
  • Open the N5 import dialog at the position of the dropped OME-Zarr. This lists resolution levels found in the OME-Zarr, allowing users to choose one and possibly even crop it and finally open it in the ImageJ window.
  • Open the N5 viewer dialog at the position of the dropped OME-Zarr. This also lists resolution levels found in the OME-Zarr, allowing users to choose one or the full pyramid and have it opened in the BigDataViewer.
  • Run a pre-defined script (e.g., a macro) while passing to it the path to the dropped OME-Zarr. This way, the user can define her own action.

The last button is not an opener: it opens a web browser pointing to this Readme file.

Multi-resolution vs. single-resolution

  • Users can drag & drop / copy & paste a top-level OME-Zarr folder, which contains a multi-resolution dataset. It will be opened as multi-resolution data.
  • Users can also drag & drop / copy & paste a subfolder of the top-level OME-Zarr folder (i.e., single-resolution data).

Reader Backend

We support two backends for reading OME-Zarrs. Users can choose between the two via the Plugins -> OME-Zarr -> Settings -> Open Behavior settings menu.

  • Zarr-java (default)
    • may be a bit quicker when opening remote resources.
    • only supports OME-Zarr v0.4 and v0.5, not v0.3.
  • N5 library
    • alternative, and the only one that reads OME-Zarr v0.3.

Scriplet support

  • Users can run a script on the OME-Zarr. The script resource can be a file and can be set in the Plugins -> OME-Zarr -> Settings -> User Script Settings menu.
  • If no script is set, the script editor opens with a default script.

What is read and displayed

Supported OME-Zarr versions

Read channel information from OME-Zarr metadata

  • The channel names, colors, and contrast limits and their active/inactive state are automatically extracted from the OME-Zarr metadata, if available. The time point is also automatically set to the time point specified in the metadata, if available.
  • Works only when a multi-resolution OME-Zarr is drag & dropped / copy & pasted and opened in BigDataViewer.

bdv_channel_information.png

Dual dataset view

  • Fiji memorizes the full context of a drag & dropped / copy & pasted OME-Zarr. That said, even if the OME-Zarr is opened as a particular resolution in ImageJ via drag & drop / copy & paste, one can still open it in BigDataViewer using all resolution pyramids (via Plugins -> OME-Zarr -> Open Current Zarr Image in BigDataViewer).
  • Or the opposite, even if the dropped / pasted OME-Zarr has right away landed in BigDataViewer, it is possible to display a particular resolution of it as Dataset in ImageJ (via Plugins > OME-Zarr > Open Resolution Level...). Images which support swithing resolutions are displayed carry (R) in their name to indicate this property.
  • To sum it up, once OME-Zarr is in Fiji, users don't have to drop / paste it again to display it differently. This is a great way to save RAM (memory) on your computer.

Known issues

  • Reading of OME-Zarrs version <= 0.2 is not supported. With the zarr-java backend, only OME-Zarr v0.4 and v0.5 are supported, not v0.3.
  • In FIJI stable, the N5 backend does not work: the N5 jars shipped there are older than this plugin needs. Updating those jars by hand is possible (see manual installation) but breaks other plugins that depend on N5, e.g. BigStitcher. Use the default zarr-java backend, which also means no OME-Zarr v0.3 on FIJI stable.
  • In FIJI stable, there is no support for s3 stores. Please use FIJI latest.
  • With FIJI stable, OME-Zarrs that use Blosc compression cannot be opened on MacOS. Please use FIJI latest, if you encounter this issue. Cf. FIJI downloads.
  • In FIJI stable, Pasting a URI via CMD / SHIFT / CTRL + V is not supported. Please use FIJI latest.
  • In FIJI stable, FIJI Links are not supported.

Example data

  • There are some OME-Zarr example datasets in the image data repository. You can download them from here to your local machine to test the drag & drop.
  • A zipped OME-Zarr archive (.ozx, 38 MB): 6001240.ozx. Open it with File -> Import -> OME-Zarr Archive (.ozx)..., or drag & drop the downloaded file. Archives are read by the zarr-java backend only.

Availability

Fiji Update Site

Enable the Fiji update site OME-Zarr in the Help -> Update -> Manage Update Sites:

update_site.png

Manual installation

Check out the repo and compile with:

mvn clean package

All jars mentioned below go into your Fiji installation's jars folder, unless noted otherwise.

The build is a multi-module reactor and produces five jars — one per module. Copy all five into that jars folder:

  • ome-zarr-imglib2/target/ome-zarr-imglib2-<version>.jar
  • ome-zarr-n5/target/ome-zarr-n5-<version>.jar
  • ome-zarr-zarrjava/target/ome-zarr-zarrjava-<version>.jar
  • ome-zarr-fiji/target/ome-zarr-fiji-<version>.jar
  • ome-zarr-fiji-ui/target/ome-zarr-fiji-ui-<version>.jar

Third-party jars

On top of those five, a number of third-party .jar files are needed. Which ones depends on the reader backend you want to use:

  • N5 backend needs the N5 library stack (n5, n5-universe, n5-zarr) plus the Fiji plugin n5-viewer_fiji.
    • Fiji-Latest ships these artifacts, so there is usually nothing to do.
    • Fiji-Stable ships older versions that have to be updated to the ones listed below. Be aware that other Fiji plugins depend on N5 as well, e.g. BigStitcher. Thus, updating the N5 jars in a Fiji-Stable installation may break them. If you can, use Fiji-Latest, or keep a separate Fiji installation for OME-Zarr work.
  • zarr-java backend (the default) needs zarr-java 0.3.0 and two of its dependencies (the Blosc codec and a Jackson module), none of which Fiji ships.

N5 backend

zarr-java backend

Delete older versions of an artifact when you add a newer one.

Note that two options of the dialog — the ones opening the N5 Importer and the N5 Viewer — are implemented using n5-ij and n5-viewer_fiji, so the N5 jars are also needed when the zarr-java backend is selected.

For developers

doc/DEVELOPERS.md covers using this project as a library rather than as a plugin:

History

About

Fiji/ImageJ plugin that brings OME-Zarr into everyday Fiji use: drag & drop, clipboard, menu and scripting, in ImageJ or BigDataViewer.

sites.imagej.net/OME-Zarr/

Topics

bigdataviewerfijiimagejimglib2ome-zarrzarr

Resources

Readme
BSD-2-Clause license
Activity
Custom properties

Stars

8 stars

Watchers

12 watching

Forks

5 forks
Report repository

Releases

Packages

Used by

Contributors

Languages