OMERO.insight compatibility =========================== In order to mitigate compatibility issues discovered between OMERO.insight and PathViewer, PathViewer 1.1.0 introduces temporary workflows for: * :ref:`correct_colors_section` (`issue #13146 `_) by adding :term:`Correct ROI colors panel` * :ref:`roi_shape_transform_section` (`github:issue #33 `_) by disabling the ROIs with transforms produced by OMERO.insight .. _correct_colors_section: Color encoding -------------- In PathViewer 1.1.0 the :term:`Correct ROI colors panel` (example in :numref:`fig_color_panel`) was introduced to allow users to correct for a bug in OMERO.insight reported in `issue #13146 `_ and discussed on the card `213-color-in-shape-settings `_. PathViewer 1.0.x was not storing any specific information about the origin of the ROI. Starting from PathViewer 1.1.0 ROIs are being annotated what allows to classify them into two groups: 1) ROIs created by PathViewer 1.1.0 or later .. _roi_group_2: 2) ROIs created by other OMERO clients including PathViewer 1.0.x The lack of specific information about the origin of the ROIs in :ref:`group 2` has led to the following color encoding correction options: .. _color_correction_panel_options: * **Do not change colors** Apply if the color correction is not needed, e.g. if the ROI was created programmatically and the colors are correct. * **Created with Insight** Apply if the ROI was created in the OMERO.insight 5.2.x or earlier. * **Created with PathViewer** Apply if the ROI was created in PathViewer 1.0.x. The :term:`Correct ROI colors panel` is only presented to the user if one or more ROIs are classified as :ref:`group 2`. Example of the panel for multiple :ref:`group 2` ROIs is shown in :numref:`fig_color_panel_multiple_rois`. Applying color correction and saving the ROIs from PathViewer's :term:`Properties panel` annotates the ROIs as created/modified by PathViewer 1.1.0. The corrected fill and stroke colors are saved to the server and the next time the image is opened the :term:`Correct ROI colors panel` will not be shown for these ROIs. The sections :ref:`color_correction_insight_rois` and :ref:`color_correction_pathviewer_1_0_rois` illustrate the color correction workflows for the ROIs created in OMERO.insight and PathViewer 1.0.x respectively. .. _color_correction_insight_rois: Color correction for OMERO.insight ROIs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Due to a bug described in the :ref:`correct_colors_section` section the fill and the stroke colors saved by OMERO.insight (:numref:`fig_main`) are encoded incorrectly. This leads to visual differences in ROI colors between OMERO clients. .. _fig_main: .. figure:: ./_static/img/rois/roi_in_insight.png :align: center ROI created in OMERO.insight. Starting from PathViewer 1.1.0 OMERO.insight's incorrect color encoding can be corrected to match the `OME-XML schema `_. If ROIs attached to the image were not created in PathViewer 1.1.0 or later the :term:`Correct ROI colors panel` is presented to the user (:numref:`fig_color_panel`). The user can choose one of the color correction options as described in the :ref:`Color correction options` list. The panel previews the ROI colors for each option so that the correct one can be identified easier. .. _fig_color_panel: .. figure:: ./_static/img/rois/roi_insight_color_correction_panel.png :align: center :term:`Correct ROI colors panel`. Look at :ref:`Color correction options` for explanation of available options. By choosing **Created with Insight** and pressing the **Apply** button PathViewer will modify the values of the Fill and the Stoke colors to correct for OMERO.insight encoding. The colors of the ROI in PathViewer should then visually match those in OMERO.insight. The ROI is marked as edited in the ROIs tab in the :term:`Properties panel` as shown in :numref:`fig_insight_roi_in_pathviewer`. The changes to the color encoding are saved to the server only if the user confirms the changes by pressing the **Save** button in the :term:`Properties panel`. .. warning:: Once the changes are saved to the server the ROI will be rendered with different colors in OMERO.insight until the `issue #13146 `_ is resolved. However, we encourage all users to apply the changes so that the correct color encoding is saved to the server. Once the fix for OMERO.insight is in place all clients will render the ROIs the same. Further reading: :ref:`multiuser_color_correction`. .. _fig_insight_roi_in_pathviewer: .. figure:: ./_static/img/rois/roi_insight_in_pathviewer_1.1x.png :align: center OMERO.insight ROI in PathViewer 1.1.x. .. _color_correction_pathviewer_1_0_rois: Color correction for PathViewer 1.0.x ROIs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PathViewer 1.1.0 adds support for variable transparency. The **Created with PathViewer** option in the :term:`Correct ROI colors panel` (:ref:`Color correction options` list, :numref:`fig_color_panel_multiple_rois`) is used to set the correct transparency value for ROIs created with PathViewer 1.0.x. :numref:`fig_pathviewer_1_0_roi` shows ROIs in PathViewer 1.0.x with default transparency 75%. .. _fig_pathviewer_1_0_roi: .. figure:: ./_static/img/rois/roi_pathviewer_1.0x.png :align: center PathViewer 1.0.x ROIs. Due to reasons described in the :ref:`correct_colors_section` section when opening the image in PathViewer 1.1.0 the user has to pick a color correction option (:ref:`Color correction options` list) if the image contains ROIs created by PathViewer 1.0.x. The :term:`Correct ROI colors panel` previews the ROI colors for each option so that the correct one can be identified easier. .. _fig_color_panel_multiple_rois: .. figure:: ./_static/img/rois/roi_pathviewer_1.0x_color_correction_panel.png :align: center :term:`Correct ROI colors panel`. Look at :ref:`Color correction options` for available options with explanation. By choosing **Created with PathViewer** and pressing the **Apply** button PathViewer will set the correct transparency value to all ROIs. The ROIs are marked then as edited in the ROIs tab in the :term:`Properties panel` as shown in :numref:`fig_pathviewer_1_0_in_pathviewer`. The changes to the color encoding are saved to the server only if user confirms the changes by pressing the **Save** button in the :term:`Properties panel`. Further reading: :ref:`multiuser_color_correction`. .. _fig_pathviewer_1_0_in_pathviewer: .. figure:: ./_static/img/rois/roi_pathviewer_1.0x_in_pathviewer_1.1x.png :align: center PathViewer 1.0.x ROIs in PathViewer 1.1.0. .. _multiuser_color_correction: Color correction in Read and Read-Annotate groups ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For OMERO groups where members cannot edit other members' data, i.e. Read and Read-Annotate, the :term:`Correct ROI colors panel` will be also presented to the user. For ROIs owned by other group members in such situations any applied color correction will not be saved to the server. The user will be prompted about the color correction each time the image is opened until the owner of the ROI updates it using PathViewer 1.1.0 or later. .. _roi_shape_transform_section: Shape transforms ---------------- Due to current PathViewer limitations not all of the ROI shape transforms are supported. In particular the ellipse rotation implemented in OMERO.insight can not be replicated in PathViewer. Furthermore OMERO.insight describes ellipse movement through transforms which in some situations may lead to unexpected results as thoroughly discussed in `ROI: Transforms #33 `_ and `OMERO representation of transforms #97 `_ (:numref:`fig_insight_ellipse`). At present PathViewer supports translation and scaling transforms only. Transforms supported by the OME-XML schema and their current implementations are discussed in `Affine Transformations of ROI Shapes `_. .. _fig_insight_ellipse: .. figure:: ./_static/img/rois/ellipse_in_insight.png :align: center Rotatable and scalled ellipse in OMERO.insight. Starting from PathViewer 1.1.0 modification of ROIs with unsupported transforms is not allowed. Such ROIs are annotated with the Lock icon when selected and a **Warning** is present in the ROI info section of the Details tab in the :term:`Properties panel` as shown in :numref:`fig_pathviewer_ellipse`. All ROI properties are not editable. .. _fig_pathviewer_ellipse: .. figure:: ./_static/img/rois/ellipse_in_pathviewer_1.1x.png :align: center Rotatable shape (on example of ellipse) in PathViewer 1.1.0. The ROI's position is calculated with accordance to the transform, however, its shape and orientation might differ due to unsupported transform components (:numref:`fig_insight_vs_pathviewer_ellipse`). .. _fig_insight_vs_pathviewer_ellipse: .. figure:: ./_static/img/rois/ellipse_rotated_insight_vs_pathviewer_1.1.x.png :align: center The left (OMERO.insight) and right (PathViewer 1.1.0) showing the same ROI. The ROI has been translated, scaled and rotated in OMERO.insight. Support for all transforms will be added in future releases of PathViewer. The OMERO.insight transform representation issue will be resolved as a part of OMERO 5.3.x: `Affine Transformations of ROI Shapes `_. Acknowledgements ^^^^^^^^^^^^^^^^ The screeshots shown here are in whole or part based upon data generated by the TCGA Research Network: http://cancergenome.nih.gov/.