This page describes how to use the built-in OMERO extension in QuPath to access and interact with images hosted on OMERO servers. The installation instructions for this extension can be found here.
This extension makes use of the OMERO JSON API, which currently only allows rendered images to be accessed. If you need the raw pixels for your analysis, consider downloading your files locally rather than accessing them from OMERO via QuPath.
Adding OMERO images to your project
QuPath can import OMERO images to a project via their links. This can be done in three ways:
(Shortcut Ctrl + Shift + O) and enter the URL of your OMERO image.
and click ‘Input URL’ or ‘From clipboard’.
Via the OMERO Browser (see Browsing an OMERO server).
Should the server require authentication, QuPath will prompt you to enter your credentials and will handle the permission issues. For more information about OMERO accounts in QuPath, see Managing OMERO clients.
QuPath only accepts the following OMERO URL formats:
QuPath now also accepts links to datasets and projects (screens/wells/plates are not yet implemented), in which case all the compatible images inside them will be fetched and added to the current project. The supported URL formats for projects and datasets are the following:
Browsing an OMERO server
You can browse OMERO servers via thecommand.
The menu will list all the servers that were opened in the current QuPath session, from which you can choose the one to browse.
The list of servers is the same one used in the OMERO web client window (see Managing OMERO clients).
Alternatively, you can provide a new OMERO server (with which no connection was previously established) to browse by clicking on ‘New server…’. The URL to provide should not contain any URL query or unnecessary characters.
The browser will display all the projects, datasets and images filtered by OMERO group and owner. The design is very similar to OMERO’s webclient.
You can add an individual image to your project by double-clicking on it. Alternatively, select the relevant projects/datasets/images and click ‘Import OMERO project/dataset/image/selected’.
You can display more OMERO information on the selected file such as tags, key-value pairs and comments with.
To query a file on the OMERO server, one can also access the ‘Advanced…’ feature, which will search the dataset for the input query. Again, the results can be opened by either double-clicking on them or by selecting them and clicking ‘Import project/dataset/image/OMERO objects’.
Send objects back to your OMERO server
When working on an image from a remote OMERO server, QuPath can send annotations back to the OMERO server. To do so, select the annotations on your image that you want to send back, then clickand confirm the operation.
As the object classes between OMERO and QuPath are different, some information might be ignored/lost. For instance, all QuPath objects (annotation and detection objects) will be represented as OMERO ROIs when sent back.
Two QuPath annotations
Two OMERO ROIs
You can also send objects to OMERO via scripting with the following command:
import qupath.lib.images.servers.omero.OmeroTools OmeroTools.writePathObjects(getAnnotationObjects(), getCurrentServer())
You’ll notice that it is indeed possible to send detection objects as well (e.g. with getDetectionObjects()). However, detection objects such as cells are not fully supported. Additionally, the writePathObjects(..) method was not designed for processing too many objects. So beware not to send a huge amount of objects at once!
Managing OMERO clients
QuPath allows you to manage all active OMERO clients. To display a pane with all active and non-active OMERO clients used in the current session, navigate to.
There, a window displaying the servers to which a previous connection was made, allows you to log in, log out and remove (forget) it.
If an account with authentication is currently connected to the server, its username will be written in parenthesis next to the server’s URL.
The green circle next to a server indicates whether the account is logged in to it (which will always be green if the server is public). The green circle next to the images’ URI indicates whether the image can be accessed with the current account.
In the example above, the second server (http://idr.openmicroscopy.org) has public user configured and can be reached without credentials (no username/password).
You can still attempt a login to a public server, which is sensible if you have some private data requiring authentication hosted on it.
If clicking ‘Log out’ next to the first server, the following will happen:
In the example above, the first client (MelvinGelbard) is no longer logged in to the server (https://ome-demoserver.openmicroscopy.org). QuPath can neither reach the server nor open the image listed. You can either log back in (‘Log in’) or remove the client altogether. The second server (http://idr.openmicroscopy.org) is public - therefore requires no username - and can be reached.
Different OMERO accounts can be logged in to different remote servers simultaneously (e.g. account A to server X and account B to server Y). But a remote server can only be reached with one OMERO account simultaneously.
Be aware that the ‘Manage server connections’ window displays how QuPath handles OMERO webclients. It does not directly relate to your project. E.g. deleting a project entry or switching projects will not affect the OMERO connections in any way, and vice-versa.