Skip to content

BioImageTools/ome-zarr-fiji-java

BranchesTags

Repository files navigation

Build Status License DOI Coverage Lines of Code

About

This repo is currently primarily a Fiji Drag & Drop / Copy & Paste handler for OME-Zarrs.

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

Features

Drag & Drop of local OME-Zarr folders and Copy & Paste of OME-Zarr URIs (local folder, http, https)

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

Users can select the default drag & drop / copy & paste 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.

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:

  • Supports local paths and http(s) URLs (s3 is planned)
  • 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

Dialog options

dialog.png

Top row:

  • 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.
  • Directly open a single-resolution image in ImageJ, which best matches the preferred width in the user settings.
  • 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.

Bottom row:

  • 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.
  • Directly Open multi-resolution image in BigDataViewer.
  • Open a web browser pointing to this Readme file.

Supported OME-Zarr versions

  • OME-Zarr v0.5 (Zarr v3)
  • OME-Zarr v0.4 (Zarr v2)
  • Supports 2D (xy), 3D (xyc, xyt, xyz), 4D (xyct, xyzc, xyzt) and 5D (xyzct) images.

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. (not yet supported)
  • 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.

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.
  • Drag & dropping / copy & pasting a subfolder of the top-level OME-Zarr folder (i.e. single-resolution data) is currently not supported.

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

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.

  • N5 library (default)
  • Zarr-java (alternative, may be a bit quicker when opening remote resources).

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.

Known issues

  • Reading of OME-Zarrs version <= 0.3 is not supported.
  • 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.

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.

Availability

Fiji Update Site

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

update_site.png

Manual installation

Check out the repo and compile with:

mvn clean package

and place the resulting .jar file into your Fiji.app/jars folder.

You also need to copy the following .jar files to your Fiji.app/jars folder (and delete the older versions, if they are present):

Beyond that, you need to copy this extra .jar files to your Fiji.app/jars folder:

History

Outlook

This is a brief outline of what @xulman would like to have in Fiji so that the usual Fiji pipelines (meaning the standard ImageJ macros, Jython scripts, and even GUI-operated plugins) could work with Zarrs and benefit from their chunk-based nature. It is greatly inspired by his previous work on DataStore, which is essentially a suite of Fiji plugins to manage (create, modify and delete full datasets, read and write images or even their chunks) a http-servered N5 datasets.

So, we basically need a suite of Fiji (in fact scijava) plugins that (are “headless” and) all of them would take a URI to some NGFF data plus specific parameters depending on a particular function/purpose of a plugin. Examples are a query plugin, that tells how many time points are available at a given URI, or how many channels are available, or a plugin that can read a full image at a given time point and a given channel from URI etc. Using these, it is easy to construct e.g. a for-loop over all time points to process an image (at variable time point and fixed particular channel) one after another. To optimize the work with a particular URI, a scijava service (we could call it NgffService) should work in conjunction with these plugins. Note that a scijava service is a singleton object that lives uninterruptedly within Fiji; it is opened and closed automatically with Fiji. That way, the commands/plugins are “routed” through the NgffService, which could implement caching (with time-limited memory) so that e.q. repetitive queries will need not to inspect/talk to the URI-pointed place (e.g. folder, or remote resource); only the first query will be “expensive” in this way. At the heart should be a public Java API — interfaces. Currently, the first implementation is planned using the n5 library. The NgffService should wrap around these interfaces.

The plugins would basically outsource their work to the NgffService, and they could look roughly like this:

@Plugin(type = Command.class, menuPath = "Plugins>OME-Zarr>Read Image")
public class OmeZarrReadImage implements Command {
	@Parameter
	NgffService ngff;

	@Parameter
	String URI;

	/* More params specifying which image to read in particular */

	@Parameter(type = ItemIO.OUTPUT)
	Dataset ds;

	@Override
	public void run() {
		Img<?> img = ngff.read(URI, /* params */);
		//create 'ds' around the obtained 'img'
		//plus the usual 'try-catch', you know ;-)
	}
}

Such plugins are directly available via Fiji menus, are (or can be made) macro recordable, accessible in the standard ImageJ macros and Jython scripts; the NgffService can be also directly accessible in the Jython scripts. In fact, these are cheap “side-effects” of the great scijava universe.

The first version is expected to be delivered in 2025.

About

A drag-and-drop gateway of OME-Zarrs into Fiji.

Resources

Readme

License

BSD-2-Clause license
Activity
Custom properties

Stars

3 stars

Watchers

13 watching

Forks

1 fork
Report repository

Releases 4

ome-zarr-fiji-0.4.0 Latest
May 18, 2026
+ 3 releases

Packages

 
 
 

Contributors

Languages