# How do I manage images?

```{admonition} What will I learn?
- How to install OMERO in QuPath (and why you may want to).
- How to connect to an OMERO server.
- How to open images in OMERO.
- How to use OMERO for sharing images and annotations.
```


By default, QuPath works with images stored locally, and analysis results (e.g. annotations) are also saved locally.
This works great when you only work on one computer without collaborating with other people.

There are multiple solutions if you want to share images or analysis results:

* You can move files to a folder on a shared server that anyone has access to, so that each person can then copy the files to their own PC.
* You can move files to a folder on a shared server, and then each person can directly work with the files on the shared server (for example, by saving a QuPath project folder on the shared server).
  However, there is a risk of overriding data when multiple users work on the same file at the same time.
* You can set up an [OMERO server](https://www.openmicroscopy.org/omero/) and use the [QuPath OMERO extension](https://github.com/qupath/qupath-extension-omero).
  
This page describes how to use the latter solution, using QuPath to view images stored on an OMERO server.

## OMERO

OMERO is free software that can be installed on a server.
It allows saving, viewing, organizing, and sharing images, annotations, and regular files from a central repository.

Once an OMERO server is set up, you can:

* Upload images to the server.
  This is done using the [OMERO.insight](https://www.openmicroscopy.org/omero/downloads/) software.
* Open an image stored on the OMERO server with QuPath and perform the analysis.
  This is possible when the QuPath OMERO extension is installed.
* Once the analysis is complete, you can send the results (e.g. annotations) to the OMERO server.
  This is once again done within QuPath, by clicking on a few buttons.
* Later, another collaborator can open the same image with QuPath (without manually downloading it) and import the previous results of the analysis by just clicking on a few buttons.

Therefore, this is a quite convenient way of collaborating when working with QuPath, provided that you have an available OMERO server.
The rest of this page will be about how to use the QuPath OMERO extension.

## The QuPath OMERO extension

The QuPath OMERO extension can be downloaded with QuPath {{ qupath_version }} or later.


```{admonition} What to do
1. Click on {menuselection}`Extensions --> Manage extensions`, and installing the extension from there.
  You may need to restart QuPath once this is done.
2. Click on {menuselection}`Extensions --> OMERO --> Browse server... --> New server...`, then enter:
  * OMERO web server URL: `https://idr.openmicroscopy.org/`.
  * Check {guilabel}`Log in as a public user`.
  * Click on {guilabel}`Connect`.
3. A browser window should open. Click on {guilabel}`Public user` and select {guilabel}`Public data`.
```

```{figure} ../../images/omero/1-omero_browser.png
The OMERO browser
```

```{note}
You can connect to [https://idr.openmicroscopy.org](https://idr.openmicroscopy.org) without authenticating.
This is possible on some OMERO servers, and only allows you to view images.
Usually, you need to provide a username & password when connecting to an OMERO server.
```

You now see a list a list of folders.
Each blue folder represents a project, which contains datasets (green folders), which contain images.

```{note}
There is a {guilabel}`No access to raw pixel data` message next to a red dot.
This is because the OMERO extension has different methods to fetch pixel values:

* The default method (selected here) sends web requests to fetch pixel values, which return JPEG compressed values.
  This means that the pixel values you get in QuPath may a bit different from the ones of the original image.
  Also, only 8-bit RGB images can be read.
* Another method (ICE) doesn't have these restrictions.
  Pixel values are completely accurate, and any image can be read.
  However, this only works if you select {guilabel}`Install optional dependencies` when installing the QuPath OMERO extension through the extension manager.
  This installs around 125 MB of additional files.
  Also, this method only works when you provide a username & password when connecting to the OMERO server.
  This wasn't done when connecting to [https://idr.openmicroscopy.org](https://idr.openmicroscopy.org), which explains why this method is not available even if you have the optional dependencies installed.
```


```{admonition} What to do
1. Open the {guilabel}`idr0018-neff-histopathology/experimentA` project.
2. Open the {guilabel}`Baz1a-14-100-brain` dataset.
3. Open the {guilabel}`Bazla-14-100-brain - 2015-06-19 23.34.11.ndpi [Series 1]` image by double clicking on it.
  It should be on top of the list. 
4. Close the browser.
```

```{figure} ../../images/omero/2-omero_image.png
An image in OMERO
```


The image is stored on a remote server, and is quite big (35.5 GB uncompressed).
Still, QuPath was able to open it in a few seconds.
Also, if you zoom in on an area, the image will be first blurry and then appear sharper.
This is because pixels are fetched 'on demand', so using this extension requires a good internet connection.

The QuPath OMERO extension allows more than just opening images stored on an OMERO server.

```{admonition} What to do
1. Click on {menuselection}`Extensions --> OMERO`.
2. View the options under {guilabel}`Send to OMERO` and {guilabel}`Import from OMERO`.
```

These options allow you to send analysis results (like annotations) to the OMERO server, or to retrieve them from the server.
Note that when connecting to a server without authentication (like we did), it is generally not possible to send data to OMERO as we don't have sufficient rights.
Providing a username / password when connecting to OMERO will fix that.

The [documentation](https://qupath.readthedocs.io/en/latest/docs/advanced/omero.html) for the OMERO extension has a lot more information.