Skip to content

Update OMERO extension docs #96

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 5, 2023
Merged

Update OMERO extension docs #96

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e4ab9df
Merge pull request #95 from qupath/0.5
petebankhead Dec 1, 2023
3e36550
Update omero extension docs
petebankhead Dec 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 20 additions & 12 deletions docs/advanced/omero.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,28 @@
(omero-extension)=
# OMERO

This page describes how to use the OMERO extension in QuPath to access and interact with images hosted on OMERO servers. The installation instructions can be found [here](https://github.com/qupath/qupath-extension-omero-web).

:::{caution}
The QuPath OMERO extension has not yet been updated to work with QuPath v0.4.0.
:::
This extension makes use of the [OMERO JSON API](https://docs.openmicroscopy.org/omero/5.6.0/developers/json-api.html), which currently only allows rendered RGB 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.

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](https://github.com/qupath/qupath-extension-omero).
The extension was updated for QuPath v0.5.0 and renamed to `qupath-extension-omero-web`.

:::{warning}
This extension makes use of the [OMERO JSON API](https://docs.openmicroscopy.org/omero/5.6.0/developers/json-api.html), 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.
A new version of the QuPath OMERO extension is currently under development.
A major goal for the new extension will be to provide raw pixel access -- a preview version will be available soon for testing.
:::


## Adding OMERO images to your project

QuPath can import OMERO images to a project via their links. This can be done in three ways:

- {menuselection}`File --> Open URI...` (Shortcut {kbd}`Ctrl + Shift + O`) and enter the URL of your OMERO image.
- {menuselection}`File --> Project --> Add images` and click 'Input URL' or 'From clipboard'.
- Via the OMERO Browser (see [Browsing an OMERO server]).
- Via the OMERO Browser (see [Browsing an OMERO server](omero-browsing)).

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].
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](omero-clients).

:::{admonition} URL formats
QuPath only accepts the following OMERO URL formats:
Expand All @@ -33,12 +36,14 @@ E.g. <http://idr.openmicroscopy.org/webclient/?show=image-1920093>
:::

:::{tip}
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:
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:

- `https://<server>/webclient/?show=project-<projectId>`
- `https://<server>/webclient/?show=dataset-<datasetId>`
:::

(omero-browsing)=
## Browsing an OMERO server

You can browse OMERO servers via the {menuselection}`Extensions --> OMERO --> Browse server...` command.
Expand All @@ -54,10 +59,10 @@ How to browse an OMERO server
:::

:::{note}
The list of servers is the same one used in the OMERO web client window (see [Managing OMERO clients]).
The list of servers is the same one used in the OMERO web client window (see [Managing OMERO clients](omero-clients)).
:::

Alternatively, you can provide a new OMERO server (with which no connection was previously established) to browse by clicking on 'New server...'.
Alternatively, you can provide a new OMERO server (with which no connection was previously established) to browse by clicking on {guilabel}`New server...`.
The URL to provide should not contain any [URL query](https://en.wikipedia.org/wiki/Query_string) or unnecessary characters.

:::{figure} images/omero_browse_new_server_link.jpg
Expand All @@ -78,13 +83,15 @@ The browser will display all the projects, datasets and images filtered by OMERO
The OMERO browser (<http://idr.openmicroscopy.org>)
:::

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 add an individual image to your project by double-clicking on it.
Alternatively, select the relevant projects/datasets/images and click {guilabel}`Import OMERO project/dataset/image/selected`.

:::{Tip}
You can display more OMERO information on the selected file such as tags, key-value pairs and comments with {menuselection}`right click --> More info...`.
:::

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'.
To query a file on the OMERO server, one can also access the {guilabel}`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 {guilabel}`Import project/dataset/image/OMERO objects`.

:::{figure} images/omero_advanced_search.png
:align: center
Expand Down Expand Up @@ -128,6 +135,7 @@ You'll notice that it is indeed possible to send detection objects as well (e.g.
Additionally, the `writePathObjects(..)` method was not designed for processing too many objects. So beware not to send a huge amount of objects at once!
:::

(omero-clients)=
## Managing OMERO clients

:::{sidebar} Status refresh
Expand Down