Merge pull request #97 from qupath/0.5

Sync to v0.5

Author: petebankhead

docs/advanced/omero.md

@@ -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:
@@ -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.
@@ -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
@@ -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
@@ -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