V0.3 qp workflow

docs/qupath.rst

@@ -5,111 +5,152 @@ Description
 -----------
 
 QuPath is a cross-platform software application designed for bioimage analysis - and specifically to meet the needs of whole slide image analysis and digital pathology.
-See \ https://github.com/qupath/qupath/wiki/
+See https://github.com/qupath/qupath/wiki/
 
 We will show:
 
-- How to open an image from OMERO server in QuPath and load the ROIs from OMERO on that image
+- How to connect QuPath to OMERO.server and browse the data.
 
-- How to draw annotations and perform simple Cell detection in QuPath
+- How to open an image including ROIs from OMERO.server in QuPath.
 
-- How to export the ROIs from QuPath as OME-XML
+- How to draw an Annotation in QuPath and save it on an image in OMERO as OMERO ROI.
 
-- How to import the OME-XML to the OMERO.server and attach the QuPath ROIs to the original image in OMERO
+- How to perform simple Cell detection in QuPath.
+
+- How to save the Cell detection ROIs directly to OMERO using a script in QuPath.
+
+- How to export the Cell detection ROIs from QuPath as OME-XML.
+
+- How to import the OME-XML to the OMERO.server and attach the QuPath ROIs to the original image in OMERO.
 
 Resources
 ---------
 
 - Data: example images from
 
-  - IDR project referenced as `idr0018 <https://idr.openmicroscopy.org/search/?query=Name:idr0018>`_. Note that the data also have been imported into an OMERO.server where the possibility to write annotations exists (not the IDR server itself). See the ``Step-by-step`` section for further details.
+  - IDR project referenced as `idr0018 <https://idr.openmicroscopy.org/search/?query=Name:idr0018>`_. Note that the data also have been imported into an OMERO.server where the possibility to write ROIs/annotations exists (not the IDR server itself). See the ``Step-by-step`` section for further details.
 
+- Video showing the usage of the QuPath OMERO extension https://www.youtube.com/watch?v=IffQ18ZQ3mI
+- QuPath documentation describing the QuPath OMERO extension https://qupath.readthedocs.io/en/latest/docs/advanced/omero.html 
 
--  Plugin ``ome-omero-roitool`` **v0.2.2** for import and export of ROIs to or from OMERO using OME-XML format. The ``ome-omero-roitool-xxx.zip`` under Releases also contains the scripts for export and import of ROIs from/to QuPath in OME-XML format. For precise installation steps, see below the ``Step-by-step`` section.
+-  Plugin ``ome-omero-roitool`` **v0.2.4** for import and export of ROIs to or from OMERO using OME-XML format. The ``ome-omero-roitool-xxx.zip`` under Releases also contains the scripts for export and import of ROIs from/to QuPath in OME-XML format. For precise installation steps, see below the ``Step-by-step`` section.
 
    - https://github.com/glencoesoftware/ome-omero-roitool
 
 
 Setup
 -----
 
-Download QuPath v0.2.2 from https://qupath.github.io/.
-
+Download QuPath **v0.3.0** from https://github.com/qupath/qupath/releases/tag/v0.3.0.
+Download the **v0.3.0** OMERO extension for QuPath from https://github.com/qupath/qupath-extension-omero/releases. Install the OMERO extension as described in https://github.com/qupath/qupath-extension-omero#qupath-omero-extension.
 
 Step-by-step
 ------------
 
-#. You can go through this workflow directly using the Image with ID with ``1920105`` in the IDR. QuPath will open that image without problems and no credentials are needed. Nevertheless, as you cannot write any data directly into IDR during your analysis, you will not be able to successfully import the resulting ROIs back into the OMERO in IDR. Thus, you might consider using another OMERO.server which you can write data to and upload this or another RGB large image into it.
+.. _OpeninginQuPath:
+
+Opening images with ROIs from OMERO in QuPath
+---------------------------------------------
+
+#. You can go through this workflow directly using the Images from the IDR. Nevertheless, as you cannot write any data directly into IDR during your analysis, you will not be able to successfully import the resulting Annotations and ROIs back into the OMERO in IDR. Thus, you might consider using another OMERO.server which you can write data to and upload this or another RGB large image into it.
 
 #. In OMERO.web, identify an image in the `idr0018 <https://idr.openmicroscopy.org/search/?query=Name:idr0018>`_ project and the dataset ``Baz1a-14-100-gastrointestinal`` contained in that project.
 
 #. Select the first image and double-click on it. This will open the image in OMERO.iviewer, in a new tab of your browser.
 
 #. If on a read-write OMERO server (i.e. not IDR), you can draw and save some ROIs on that image in OMERO.iviewer to be able to open them in QuPath later below, see `OMERO.iviewer guide <https://omero-guides.readthedocs.io/en/latest/iviewer/docs/iviewer_rois.html>`_ for how to do it.
 
-#. In the OMERO.iviewer tab, select the whole URL in the address bar of your browser and copy it, for example using right-click and ``Copy``.
+#. Start your locally installed QuPath. Create a new QuPath Project by creating a new empty folder on your machine and dropping this new folder into the main QuPath window. Answer ``Yes`` when prompted.
 
-#. In QuPath, create a new Project ``File > Project > Create Project`` or open an existing one ``File > Project > Open Project``.
+#. Create a connection to your OMERO server by clicking ``Extensions > OMERO > Browse server > New server`` and paste into the dialog a valid server url including the ``http`` or ``https`` motives, for example ``https://<server>.com``. Details are described in the `Browsing an OMERO server chapter <https://qupath.readthedocs.io/en/latest/docs/advanced/omero.html#browsing-an-omero-server>`_ of the QuPath documentation.
 
-#. Once the Project is open, click the ``Add Images`` button above the left-hand pane in QuPath.
+#. Once connection to the server is established, QuPath will pop up a new dialog. In this dialog, select the correct group in OMERO in top left corner and the correct user. Expand Projects and Datasets as necessary, selecting the image with ROIs which you worked on in previous steps.
 
-#. In the following dialog, check the ``Import objects`` checkbox. This tells QuPath to import all ROIs on that image from OMERO into QuPath. Note though that masks will not be imported.
+   |image1a|
 
-#. In the same dialog, click the ``Input URL`` button.
+#. Double click on the image in the tree. In the new window, select the image again in the ``Image paths`` list, check the ``Import Objects`` checkbox and click ``Import`` in bottom-right corner.
 
-#. Paste the link to the image you copied from the OMERO.iviewer tab (see above) into the dialog.
+   |image1b|
 
-   |image0|
+#. Click on the imported image in your QuPath project to open it in QuPath. Inspect the ROIs imported from OMERO.
 
-#. Click ``OK``.
+#. To draw new ROIs or annotations in QuPath, find a region with well-defined cells and nuclei in the image, zoom in.
 
-#. If you are using a link not from IDR, but from a different OMERO.server protected by credentials, in the following dialog, enter your credentials.
+#. Draw an ``Annotation`` which denotes the region in which the cells will be detected using the ``Wand`` tool |image2|. 
 
-   |image1|
+#. Select the ``Annotations`` tab, select the class from the list to the right (e.g. ``Stroma``) and click ``Set class`` . Click ``Extensions > OMERO > Send annotations to OMERO``. A dialog will inform you how many ROIs are to be saved. Click ``OK``.
 
-#. Click ``Import``.
+#. Go to OMERO.iviewer, refresh the image and verify that the annotation was saved as an OMERO ROI (polygon).
 
-#. The image thumbnail will appear in the left-hand pane list of the QuPath Project. Click on that thumbnail to open the image in QuPath's full viewer.
+#. Note that there is some loss of metadata when going through the ``Extensions > OMERO > Send annotations to OMERO`` step 
 
-#. Set image type to ``Brightfield H&E`` in the following dialog. Click ``OK``.
+   - The Class of the ``Annotation`` in QuPath will be indicated only by a fill color of the ROI in OMERO. If you reopen the image in QuPath again from OMERO, the ROI fetched by QuPath from OMERO will have the correct name of the ``Annotation`` if you gave it one in QuPath, but both the Class as well as the ``Annotation`` color will be lost by the round trip to OMERO and back. 
+
+   - All the holes in your ``Annotation`` will be ignored (filled in), as the ``Annotation`` is translated into a polygon ROI in OMERO. The ROI in OMERO will appear as a filled-in object, as shown in the cartoon in the `Send objects back to your OMERO server chapter <https://qupath.readthedocs.io/en/latest/docs/advanced/omero.html#send-objects-back-to-your-omero-server>`_ of the QuPath documentation.
+
+   - The "derived" ROIs which were created for example by Cell detection algorithm in QuPath will be ignored when saving ``Annotations`` to OMERO. To save them either :ref:`Save detection ROIs using QuPath script<Saveroiscript>` or :ref:`ome-omero-roitool<Roitool>` workflows can be used. 
 
-#. Find your ROIs from OMERO now in QuPath on that image.
+Saving of derived ROIs from QuPath to OMERO
+-------------------------------------------
+The QuPath plugin for OMERO described above allows saving of the Annotations drawn in QuPath to OMERO, but it does not enable the saving of "derived" ROIs, such as Cell detection ROIs. To save the Cell detection ROIs either :ref:`Save detection ROIs using QuPath script<Saveroiscript>` or :ref:`ome-omero-roitool<Roitool>` workflows can be used.
 
-#. To draw new ROIs or annotations in QuPath, find a region with well-defined cells and nuclei in the image, zoom in.
 
-#. Draw an ``ROI Annotation`` which denotes the region in which the cells will be detected using the ``Wand`` tool |image2|. 
+.. _Saveroiscript:
+
+Save detection ROIs using QuPath script
+---------------------------------------
+.. warning::
+    The feature described in :ref:`Save detection ROIs using QuPath script<Saveroiscript>` was not really designed for saving large amounts of ROIs (thousands) back to OMERO. An attempt to save large amounts of ROIs might result in slow performance or other problems.    
 
-#. Note that if the ``ROI Annotation`` is encompassing a very large area, you might later get performance problems with the ``OME_XML_export.groovy`` script which exports the ``ROI Annotation`` in ome-xml format, because this script is attempting to export the ``ROI Annotation`` as a mask, see below.
+#. Connect QuPath to OMERO, open an image from OMERO in QuPath and draw an ``Annotation`` on it as described in :ref:`Opening images with ROIs from OMERO in QuPath<OpeninginQuPath>`.
 
-#. Adjust your ROI Annotation using the ``Brush`` tool |image3|.
+#. Adjust your ``Annotation`` using the ``Brush`` tool |image3|.
 
 #. Select ``Analyze > Cell detection > Cell detection``.
 
-#. You can adjust the parameters. Click ``Run``. This will draw red ROIs around cells and nuclei inside your ``ROI Annotation``.
+#. You can adjust the parameters. Click ``Run``. This will draw red ROIs around cells and nuclei inside your ``Annotation``.
 
    |image4|
 
-#. Select ``Measure > Show detection measurements``.
+#. Click on ``Hierarchy`` tab in the left-hand pane of QuPath. Expand the ``Annotation`` you have just run the ``Cell detection`` on.
+
+#. Select several detection ROIs.
+
+#. Open the scripting dialog in QuPath ``Automate > Show script editor`` and paste into it the following code::
 
-   |image5|
+      import qupath.lib.images.servers.omero.OmeroTools
+      OmeroTools.writePathObjects(getSelectedObjects(), getCurrentServer())
 
-#. Note: You can save the results locally by clicking ``Save`` in the bottom right of the ``Detection results table``. If you are using your own server, you can upload the results and link them to the Image.
+#. From the top menu, select ``Run > Run``. This saves the detection ROIs you selected in the ``Hierarchy`` tab into OMERO.
 
-#. In the following steps, we will show how to convert the ROIs your just created in QuPath into OMERO ROIs and attach them to the image in OMERO.
+#. Go to OMERO.iviewer and refresh the image. Inspect the saved detection ROIs.
 
-#. First, use the ROI OME-XML export script to export your ROIs from QuPath into OME-XML file. Find the version of ``ome-omero-roitool`` mentioned in Resources on `ome-omero-roitool releases <https://github.com/glencoesoftware/ome-omero-roitool/releases>`_ and from there download the ``ome-omero-roitool-xxx.zip``. The downloaded zip contains both the plugin and the QuPath scripts needed for this workflow.
+.. _Roitool:
+
+Save detection ROIs using ome-omero-roitool
+-------------------------------------------
+This workflow necessitates the usage of the Command Line Interface. The limitation here are the Annotation ROIs, which are transformed into masks in OMERO. Although this preserves the holes in the Annotations, if the Annotation ROIs are too large, it might result in performance problems or even running out of resources on the machine where the export of the mask from QuPath is attempted.
+
+#. Connect QuPath to OMERO, open an image from OMERO in QuPath and draw an ``Annotation`` on it as described in :ref:`Opening images with ROIs from OMERO in QuPath<OpeninginQuPath>`.
+
+#. Adjust your ``Annotation`` using the ``Brush`` tool |image3|.
+
+#. Select ``Analyze > Cell detection > Cell detection``.
+
+#. You can adjust the parameters. Click ``Run``. This will draw red ROIs around cells and nuclei inside your ``Annotation``.
+
+#. Use the ROI OME-XML export script to export your ROIs from QuPath into OME-XML file. Find the version of ``ome-omero-roitool`` mentioned in Resources on `ome-omero-roitool releases <https://github.com/glencoesoftware/ome-omero-roitool/releases>`_ and from there download the ``ome-omero-roitool-xxx.zip``. The downloaded zip contains both the plugin and the QuPath scripts needed for this workflow.
 
 #. Unzip the downloaded artifact and drag and drop the ``OME_XML_export.groovy`` into your QuPath.
 
 #. To run the script, select ``Run > Run``.
 
 #. Note: If you run a ``Cell detection`` in QuPath, the nuclei ROIs will be drawn as well as the ROIs around the cells. The ROI OME-XML export script will export both the ROIs around the cells as well as the nuclei ROIs.
 
-#. Import the OME-XML with the ROIs from QuPath into OMERO. These steps must be run on a command line. If you did not do so already, find the version of the ``ome-omero-roitool`` mentioned in Resources on `ome-omero-roitool releases <https://github.com/glencoesoftware/ome-omero-roitool/releases>`_. From there, download the ``ome-omero-roitool-xxx.zip``. Open your terminal window.
+#. Import the OME-XML with the ROIs from QuPath into OMERO. These steps must be run on a command line. 
 
-#. Unzip the downloaded file and go into the resulting folder as follows::
+#. Open your terminal window and ``cd`` into the directory containing the ``ome-omero-roitool-xxx`` folder downloaded in previous steps, then run::
 
-      unzip ome-omero-roitool-xxx.zip
       cd ome-omero-roitool-xxx
       cd bin
 
@@ -136,6 +177,12 @@ Step-by-step
 
    |image6|
 
+.. |image1a| image:: images/qupath1a.png
+   :width: 4in
+
+.. |image1b| image:: images/qupath1b.png
+   :width: 4in
+
 .. |image0| image:: images/qupath1.png
    :width: 4in
    :height: 1in