https://github.com/qupath/qupath-extension-omero

QuPath extension to work with images through OMERO's APIs
https://github.com/qupath/qupath-extension-omero

Last synced: 3 months ago
JSON representation

QuPath extension to work with images through OMERO's APIs

• Host: GitHub
• URL: https://github.com/qupath/qupath-extension-omero
• Owner: qupath
• License: apache-2.0
• Created: 2024-02-07T13:37:41.000Z (12 months ago)
• Default Branch: main
• Last Pushed: 2024-09-12T08:46:11.000Z (5 months ago)
• Last Synced: 2024-09-13T17:16:53.779Z (4 months ago)
• Language: Java
• Size: 1.06 MB
• Stars: 3
• Watchers: 3
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# QuPath OMERO extension

Welcome to the OMERO extension for [QuPath](http://qupath.github.io)!

This adds support for accessing images hosted on an [OMERO](https://www.openmicroscopy.org/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](#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](https://github.com/qupath/qupath-extension-omero/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](https://www.openmicroscopy.org/omero/downloads/), 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](https://github.com/glencoesoftware/omero-ms-pixel-buffer)):

  * 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

```bash

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

```bash

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.