OMERO.insight compatibility¶

In order to mitigate compatibility issues discovered between OMERO.insight and PathViewer, PathViewer 1.1.0 introduces temporary workflows for:

Color encoding (issue #13146) by adding Correct ROI colors panel

Shape transforms (github:issue #33) by disabling the ROIs with transforms produced by OMERO.insight

Color encoding¶

In PathViewer 1.1.0 the Correct ROI colors panel (example in Fig. 2) 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:

ROIs created by PathViewer 1.1.0 or later

ROIs created by other OMERO clients including PathViewer 1.0.x

The lack of specific information about the origin of the ROIs in group 2 has led to the following color encoding correction 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 Correct ROI colors panel is only presented to the user if one or more ROIs are classified as group 2. Example of the panel for multiple group 2 ROIs is shown in Fig. 5.

Applying color correction and saving the ROIs from PathViewer’s 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 Correct ROI colors panel will not be shown for these ROIs.

The sections Color correction for OMERO.insight ROIs and Color correction for PathViewer 1.0.x ROIs illustrate the color correction workflows for the ROIs created in OMERO.insight and PathViewer 1.0.x respectively.

Color correction for OMERO.insight ROIs¶

Due to a bug described in the Color encoding section the fill and the stroke colors saved by OMERO.insight (Fig. 1) are encoded incorrectly. This leads to visual differences in ROI colors between OMERO clients.

_images/roi_in_insight.png — Fig. 1 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 Correct ROI colors panel is presented to the user (Fig. 2). The user can choose one of the color correction options as described in the Color correction options list. The panel previews the ROI colors for each option so that the correct one can be identified easier.

_images/roi_insight_color_correction_panel.png — Fig. 2 Correct ROI colors panel. Look at 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 Properties panel as shown in Fig. 3. 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 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: Color correction in Read and Read-Annotate groups.

_images/roi_insight_in_pathviewer_1.1x.png — Fig. 3 OMERO.insight ROI in PathViewer 1.1.x.¶

Color correction for PathViewer 1.0.x ROIs¶

PathViewer 1.1.0 adds support for variable transparency. The Created with PathViewer option in the Correct ROI colors panel (Color correction options list, Fig. 5) is used to set the correct transparency value for ROIs created with PathViewer 1.0.x. Fig. 4 shows ROIs in PathViewer 1.0.x with default transparency 75%.

_images/roi_pathviewer_1.0x.png — Fig. 4 PathViewer 1.0.x ROIs.¶

Due to reasons described in the Color encoding section when opening the image in PathViewer 1.1.0 the user has to pick a color correction option (Color correction options list) if the image contains ROIs created by PathViewer 1.0.x. The Correct ROI colors panel previews the ROI colors for each option so that the correct one can be identified easier.

_images/roi_pathviewer_1.0x_color_correction_panel.png — Fig. 5 Correct ROI colors panel. Look at 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 Properties panel as shown in Fig. 6. The changes to the color encoding are saved to the server only if user confirms the changes by pressing the Save button in the Properties panel.

Further reading: Color correction in Read and Read-Annotate groups.

_images/roi_pathviewer_1.0x_in_pathviewer_1.1x.png — Fig. 6 PathViewer 1.0.x ROIs in PathViewer 1.1.0.¶

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

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 (Fig. 7). 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.

_images/ellipse_in_insight.png — Fig. 7 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 Properties panel as shown in Fig. 8. All ROI properties are not editable.

_images/ellipse_in_pathviewer_1.1x.png — Fig. 8 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 (Fig. 9).

_images/ellipse_rotated_insight_vs_pathviewer_1.1.x.png — Fig. 9 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/.