QuPath OMERO extension

Welcome to the OMERO extension for QuPath!

This adds support for accessing images hosted on an OMERO server through OMERO's web (and other) API.

Important!

By default, this extension uses the OMERO web API to read images, which has several limitations. See the Reading images section.

The extension is intended for QuPath v0.6 and later. It is not compatible with earlier QuPath versions.

Installing

To install the OMERO extension, download the latest qupath-extension-omero-[version].jar file from releases and drag it onto the main QuPath window.

If you haven't installed any extensions before, you'll be prompted to select a QuPath user directory. The extension will then be copied to a location inside that directory.

You might then need to restart QuPath (but not your computer).

Reading images

The extension uses several APIs to read images:

• The OMERO web API:
  • This method is enabled by default and is available on every OMERO server.
  • It is fast but only 8-bit RGB images can be read, and they are JPEG-compressed. This effectively means it is most useful for viewing and annotating RGB images (including whole slide images), but is not suitable for quantitative analysis where JPEG compression artifacts would be problematic.
• The OMERO Ice API:
  • This method can read every image and access raw pixel values.
  • However, you have to install the OMERO Java dependencies to enable it: from the OMERO download page, under "OMERO Java", download the .zip file, unzip it and copy the libs folder in your extension directory.
  • Note that it is not possible to use the Ice API when accessing an OMERO server with a guest account, you have to be authenticated.
  • If you can't open any image with the Ice API, it may be because the OMERO.server instance is on a different server than the OMERO.web instance. You can define a different address and port to the OMERO.server in the settings of the extension.
• The OMERO Pixel Data Microservice (available here):
  • This method can read every image and access raw pixel values.
  • If this microservice is installed on your OMERO server, the extension will automatically detect it. If that's not the case, check that the port indicated in the settings of the extension corresponds to the port used by the microservice on the OMERO server (by default 8082).

These APIs are only about retrieving pixel values. Everything else (for example image metadata) is retrieved using calls to the OMERO web server. Therefore, the URI displayed in the "Image" tab of QuPath might not reflect the API used to retrieve pixel values. You can see which pixel API is used by looking at the "Image type" entry.

Scripting

Script examples are located in the sample-scripts folder. They show how the extension can be used from scripts (with or without the graphical user interface).

Building

You can build the extension using OpenJDK 21 or later with

gradlew clean build

The output will be under build/libs. You can drag the jar file on top of QuPath to install the extension.

Running tests

You can run the tests with

gradlew test

Some of the tests require having Docker installed and running.

By default, a new local OMERO server will be created each time this command is run. As it takes a few minutes, you can instead create a local OMERO server by running the qupath-extension-omero/src/test/resources/server.sh script and setting the OmeroServer.IS_LOCAL_OMERO_SERVER_RUNNING variable to true (qupath-extension-omero/src/test/java/qupath/ext/omero/OmeroServer file). That way, unit tests will use the existing OMERO server instead of creating a new one.