imagej / imagej-omero

Server- and client-side communication between ImageJ and OMERO

ImageJ-OMERO Presentation Slides

Overview

This project provides interoperability between ImageJ and the OMERO server.

ImageJ-OMERO is one of two official integration mechanisms combining the two tools. The other project is OMERO.imagej.

The two mechanisms work differently and have different features:

• ImageJ-OMERO is built on ImageJ2. It is maintained by the ImageJ team. You can install it using one of the OMERO-x.y update sites, replacing x.y with your version of the OMERO server. The paradigm is to download complete 5-D images from OMERO as ImageJ2 datasets, with blocks of pixels loaded on demand via the ImgLib2 cached cell image mechanism. It also supports transferring ROIs to/from OMERO as imglib2-roi objects, and results tables to/from OMERO as scijava-table objects.

• OMERO.imagej is built on ImageJ 1.x. It is maintained by the OMERO team. It must be installed manually; it does not have an ImageJ update site. The plugin is a thin wrapper of the OMERO.insight client, enabling you to connect to OMERO via the OMERO.insight GUI, browse your database as usual, and send images to ImageJ on demand. It also supports transferring ROIs to/from OMERO. The ImageJ ROIs are converted into OMERO ROIs when uploaded to OMERO. The supported workflow is to do your analysis in ImageJ as usual, then upload results tables as attachments on the OMERO side.

A third way to integrate OMERO with ImageJ, if you are comfortable writing scripts, is via PyImageJ, as described in the OMERO documentation.

Which approach works best for you will depend on your requirements. For help, please post on the Image.sc Forum using the imagej and omero tags.

ImageJ commands for working with OMERO

There are ImageJ commands for accessing images from a remote OMERO server, as well as uploading image data from ImageJ to OMERO as a new image.

Installation

To try it out, enable the appropriate update site:

• OMERO-5.5-5.6 If your OMERO server version is >= 5.5
• OMERO-5.4 If your OMERO server is version 5.4.x.
• OMERO-5.2 If your OMERO server is version 5.2.x.
• OMERO-5.1 If your OMERO server is version 5.1.x.
• OMERO-5.0 If your OMERO server is version 5.0.x.

You will then have the following new menu items:

• File > Import > OMERO...
• File > Export > OMERO...

OMERO Setup

If you do not already have access to a local OMERO server, the quickest method to get one up and running is to use the Docker example. This will create a server + web client.

Demonstration Video

Calling ImageJ commands as OMERO scripts

You can execute ImageJ modules (commands, scripts, etc.) on the server side as OMERO scripts.

Currently images, tables, and ROIs are supported. However, only ROIs can be updated on the server. Images and tables must be uploaded as new objects.

Additionally, it is possible to dictate where in OMERO outputs get stored by using special parameter properties.

• attachToOMERODatasetIDs - This is used for output images to specify which OMERO Datasets they should be associated with. The OMERO Dataset must be specified by ID, and each output image can be associated with multiple OMERO Datasets.
• attachToImages - This is used to dictate to which input images output ROIs/tables should be attached. These images must be inputs to the script, and should be referenced by their name (not ID).

If you wish to give it a test drive, the steps are:

Prerequisites

• OMERO 5
• Python 2.7 or later

Installation

Download the ImageJ-OMERO installer, and run it:

sh install-imagej <path/to/omero>

The installer will:

• Download and install ImageJ into OMERO's lib/ImageJ.app folder, with the Fiji and OMERO-5.x update sites enabled.
• Install OMERO script wrappers for all available ImageJ commands into OMERO's lib/scripts/imagej folder.

Using an existing ImageJ installation

If you already have ImageJ installed on the OMERO server machine, you can use that, rather than installing a new copy of ImageJ:

1. Enable the OMERO-5.x update site.

   <path-to-imagej>/<imagej-launcher> --update add-update-site OMERO-5.x http://sites.imagej.net/OMERO-5.x
   <path-to-imagej>/<imagej-launcher> --update update-force-pristine

   Where x is your OMERO version, <path-to-imagej> is a path to your ImageJ directory (i.e. ImageJ.app or Fiji.app), and <imagej-launcher> is the launcher for your operating system (i.e. ImageJ-linux64)

2. Run gen-scripts in ImageJ's lib directory.

Take it for a spin

• Fire up OMERO:

  omero admin start

• List available scripts:

  omero script list

• List parameters of "System Information" command:

  omero script params $(omero script list | grep 'System_Info' | sed 's/|.*//')

• Execute the "System Information" command:

  omero script launch $(omero script list | grep 'System_Info' | sed 's/|.*//')

• Repeat with any other desired commands. Also try from OMERO.web and OMERO.insight!

Uninstalling

If you wish to remove ImageJ support from OMERO:

OMERO_PREFIX="/path/to/omero"
rm -rf "$OMERO_PREFIX/lib/scripts/imagej" "$OMERO_PREFIX/lib/ImageJ.app"

Demonstration Videos

Under the hood: a SCIFIO format for OMERO data

This component provides a SCIFIO Format implementation which offers transparent read and write access to image pixels on an OMERO server.

With this format implementation, SCIFIO's ImgOpener class can be used to "open" (i.e., download on demand) an ImgLib2 ImgPlus directly from an OMERO server. The ImgPlus will be backed by a SCIFIOCellImg, which is backed by an OMEROFormat.Reader, which is backed by an omero.client connection.

The ImgPlus can then be wrapped as an ImageJ2 Dataset, enabling ImageJ2 commands to operate upon it directly.

When changes are made to the local ImgPlus's pixels, those changes happen in memory, to the Img's "cells"; i.e., paged blocks. As new cells are requested which push memory consumption beyond desired limits, old dirty cells are cached out to disk. These cached cells, when present, are used in preference to data from the original source. In this way, it is possible to iterate over a massive remote dataset and apply image processing filters, with all changes recorded to the disk cache, as long as there is sufficient disk space.

Finally, once processing is complete, SCIFIO's ImgSaver class can be used to "save" (i.e., upload) the ImgPlus back to OMERO as a new pixels object.