Instead of transferring large amounts of image data, this post discusses how to set up a centralized Omero server for remote access by QuPath, to enable real-time whole slide image reviewing and annotating!

Introduction

Scientists and researchers in the fields of biomedical imaging generate vast amounts of image data using microscopy techniques. Managing, analyzing, and sharing this data can be a daunting task, especially when dealing with large and complex datasets. This is where the OMERO server comes in.

OMERO is an open-source software platform that provides a centralized solution for managing, visualizing, and remotely sharing scientific images and data. This means that data can be stored in a single location and accessed remotely via a web browser by collaborators eliminating the need for large data transfers. Though OMERO is a promising tool for visualizing your data, the annotation modules are not as mature as QuPath, an application many folks are already especially comfortable and skilled with. Qupath is an open-source software platform used for digital pathology image analysis and visualization. Unfortunately, QuPath requires having local access to the data, necessitating the large file transfers that OMERO was designed to avoid

To address this limitation, researchers can now have QuPath connect to an OMERO server. This integration allows researchers to analyze their microscopy data using a range of advanced image analysis tools locally, without needing to download the large image data to their local machine. Using QuPath+OMERO, researchers can view, annotate, and analyze large medical images by streaming only the pixels that need to be visible in a specific viewport, instead of the entire image. This approach is made possible thanks to the fast internet speeds available in many labs today.

In this blog post, we will explore the features and benefits of the OMERO server, including its installation, integration with Qupath, and how it can help scientists to better manage, analyze, and share their data.

Prerequisites

OMERO is compatible with Linux, macOS, and Windows operating systems. Here are some general recommendations for the machine specifications:

1. Processor: OMERO can be resource-intensive, particularly when working with large datasets. Therefore, a multi-core processor, such as an Intel i7 or AMD Ryzen, is recommended.
2. RAM: The amount of RAM required depends on the size of your datasets. However, as a general rule, a minimum of 8GB of RAM is recommended, with 16GB or more being ideal.
3. Storage: OMERO requires storage space for storing metadata and image data. The amount of storage space required will depend on the size of your datasets but as a general rule, a minimum of 200MB of storage space is required, plus additional space for each dataset. This means that if you have a large number of datasets or particularly large datasets, you may need to invest in additional storage to ensure that OMERO can handle your data effectively.

Unfortunately, the OMERO team withdrew support for OMERO.server on Windows starting with the 5.3.0 release. This means OMERO.web hosting will not be possible on Windows. Those users should instead use WSL2. However, it is possible to install OMERO on MacOS, please check the following link for more reference.

https://omero.readthedocs.io/en/v5.6.7/sysadmins/unix/server-installation.html

Now, let’s take a look at the installation process!

A. Set up OMERO on your server.

We assume that Docker is already installed on your system, if not, please follow the directions here: https://docs.docker.com/engine/install/

Then we need to start a postgres database:

docker run -d --name omero-postgres -e POSTGRES_PASSWORD=postgres postgres

It is highly suggested to change the default POSTGRES_PASSWORD ‘postgres’.

We now run the OMERO server docker image using the following command line:

docker run -d --name omero-server --link omero-postgres:db \
-e CONFIG_omero_db_user=postgres \
-e CONFIG_omero_db_pass=postgres \
-e CONFIG_omero_db_name=postgres \
-e ROOTPASS=<password for root> \
-p 4063:4063 -p 4064:4064 \
-v <host-src:container-dest> \
openmicroscopy/omero-server

The CONFIG_omero_db_pass password must be the same as POSTGRES_PASSWORD above.

The OMERO root password (ROOTPASS) should be selected at this point as well and a strong password: https://en.wikipedia.org/wiki/Password_strength

When running OMERO with Docker, it is recommended to use the ‘-v’ option to bind a volume. This allows you to specify the location of the images on the host machine and mount them to a destination within the Docker container, without the need to duplicate the data.

For example, the command ‘-v /data/wsi_host:/data/wsi_container’ would bind the volume located at ‘/data/wsi_host’ on the host machine to ‘/data/wsi_container’ within the Docker container.

We can now run the OMERO web docker image:

docker run -d --name omero-web \
-e OMEROHOST=<server> \
-p 4080:4080 -p 4081:4081 \
openmicroscopy/omero-web-standalone

OMEROHOST must match the OMERO server address, if you don’t know the server address, please use this command line to check the server information.

hostname -I

OR

ip addr show

Execute the OMERO server in docker using the following command line.

docker exec -it omero-server bash

Some configurations must be done inside the OMERO docker server container.

export PATH=/opt/omero/server/venv3/bin:$PATH
export OMERODIR=/opt/omero/server/OMERO.server
omero --sudo root -u <username> login
DID=$(omero obj new Dataset name=<choose_a_name>)

After omero –sudo root -u <username> login, type enter and then the OMERO root password (ROOTPASS above) if you login as root (-u root). <choose_a_name>: a name for the dataset must be chosen.

The next step is to limit the duplication of the data to limit the storage requirements by linking the data to existing files within the server over the mounted drive.

This must be done inside the OMERO docker server as well. Go to the directory where the images are and type:

SAVEIFS=$IFS
IFS=$(echo -en "\n\b")
for f in `ls -1`
do
omero import -d $DID --transfer=ln_s "`pwd`/$f"
done

Next to ls -1, you can add a command to select only the images if there are other files in the directory. For example: ls -1 *.ndpi to select only the .ndpi files. This step can take a few hours if there are many images. Finally, we can open a browser and go to: http://<server>:4080/ where the server is the server where the installation has been done.

We can log in with the user root and the password you set up before (ROOTPASS above).

After logging into the OMERO web server. You can check if all the data are correctly set up.

Everything is working well!

B. Using QuPath with OMERO

If you’re looking to integrate QuPath with the OMERO server, the first step is to install the OMERO extension for QuPath.

The installation process for the OMERO extension is relatively straightforward. First, you’ll need to download the extension file from the QuPath GitHub repository:

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

Once you’ve downloaded the file, you can drag it into the QuPath window to initiate the installation process.

Then copy the address used by the OMERO web client, it should be http://<server>:{portname}/

Open QuPath and create a project (File -> Project -> Create project). Choose a new folder. In the menu bar, go to Extensions -> OMERO -> Browse server -> New server.

Paste the address of the server. Enter your login password for OMERO when asked.

A new window in now open, click on the folder (the arrow on its left) where your images are located.

Wait, the loading can take some time. Select the images you want to import and click Import. The images should now be available in the Project tab.

After importing the images to QuPath, you can annotate the areas/objects of interest as you usually do in QuPath, after annotating the entire image, you can set the annotations’ class, and save them.

After processing all the images, you can use Paquo to process all the annotations following this blog post:

Using Paquo to directly interact with QuPath project files for usage in digital pathology machine learning

And then you will only need to transfer the QuPath folder to others (pathologists/scientists) instead of transferring all the images which will be very time-consuming.

C. Adding new users and change password

reference:

https://omero-guides.readthedocs.io/en/latest/introduction/docs/group-user-management.html

When you wish to involve multiple users in your project, you may need to administrate groups and users. The easiest way is to administrate using the web interface.

• Go to the OMERO web in browser, and login as root.

• Click ‘Add new User’, and in that page, you can add user’s information including password, group information and privileges.

Conclusion

In conclusion, setting up OMERO and connecting it to QuPath can be a powerful tool for managing and analyzing your microscopy data.

While the process may seem intimidating at first, following the steps outlined in this post can help you get started with ease!

If you encounter any issues during the set-up or have questions, please don’t hesitate to reach out to me via email at [fxf109@case.edu]. I’m happy to help and answer any questions you may have!