PathViewer API¶
PathViewer 3.0+¶
Base URL¶
https://omero.server/pathviewer/viewer
List of query string parameters¶
Name Type Description
----------------------------------------------------------------------------------
slide Number OMERO image id to show
q_image List Comma separated list of OMERO image ids to load
q_dataset Number OMERO dataset id from which to load images
tabs String Panel and active tab visibility settings
x Number View position X
y Number View position Y
t Number Timepoint
z Number Z section
zoom Number Zoom level
rotate Number Rotation angle in degrees
flip String Image flip. Accepted values:
h - horizontal
v - vertical
hv - both horizontal and vertical
c0, c1, ..., cn String Color settings for channels 0, 1, ..., n
r String Rendering mode. Accepted values:
color
greyscale
gc Number Channel to use in greyscale mode
roi Number ROI id to select and focus on initial load
Showing single image with PathViewer¶
<base_url>/#?slide=<image_id>
Loading specific images into Slides Panel¶
<base_url>/#?slide=<image_id>&q_image=<image_id>,<image_id>,...
Loading all images from a specific OMERO dataset into Slides Panel¶
<base_url>/#?slide=<image_id>&q_dataset=<dataset_id>
Selecting active user interface components¶
URL parameter format:
tabs=<Browse_panel_option><Properties_panel_option><Browse_panel_on_off><Properties_panel_on_off>
Available options:
* S - slide tab
* V - view options tab
* D - details tab
* R - rois tab
* L - data tab (only available when label image ROIs exist)
* b - hide browse panel
* p - hide properties panel
Example 1. Setting the browse panel tab to view options tab (V), and the properties panel to ROIs tab (R), and making both panels invisible:
<base_url>/#?slide=<image_id>&tabs=VRbp
Example 2. Setting browse panel tab to slide tab (S), and the right hand side panel to ROIs tab (R), and making the properties panel invisible:
<base_url>/#?slide=<image_id>&tabs=VRp
Setting image position and orientation¶
Example 1. Rotating the image by 15 degrees and flipping it horizontally:
<base_url>/#?slide=<image_id>&rotate=15&flip=h
Example 2. Rotating the image by 15 degrees and flipping it horizontally and vertically:
<base_url>/#?slide=<image_id>&rotate=15&flip=hv
Channel color settings¶
Values for channel color settings have the following format:
rccccccf-t
^^^^^^^^ ^
| | | +- Window max as hexadecimal number
| | +--- Window min as hexadecimal number
| +------ Color as six digit hexadecimal number
+---------- Render channel: 0=off, 1=on
Example: RGB image with blue channel turned off:
<base_url>/#?slide=<image_id>&c0=1FF00000-FF&c1=100FF000-FF&c2=00000FF0-FF
Note about PathViewer 2.x compatibility¶
Releases of PathViewer 3.0.x use values for y and zoom that are not backwards compatible, so URLs created with PathViewer 2.x do not show the same image area and zoom level in PathViewer 3.0.x.
URLs in PathViewer 3.1.x restore backwards compatibility with PathViewer 2.x URLs.
PathViewer 3.2+¶
PathViewer supports a number of shape properties that are not supported by the OME schema (https://www.openmicroscopy.org/Schemas/OME/2016-06/ome.xsd).
These properties are stored in an XML annotation with namespace glencoesoftware.com/pathviewer/roi/settings. The annotation value is JSON encoded and contains the following fields:
fontColor: Color used for shape label
labelPosition: Shape label position, one of “default”, “above”, “below”, “left”, “right”
label: Raw shape label text. The text property of the shape contains this value with all variables replaced with the measurement values current as of the last save.
Example:
{
"fontColor": "rgba(0,0,255,0.8)",
"labelPosition": "above",
"label": "Area {Area} {Width:px} {Height:px}"
}
PathViewer 3.1+¶
Saved grid view format¶
Grid views are saved in YAML format with the following structure:
dataset: null|<dataset_id>
rows: <1-4>
columns: <1-4>
images:
- <image_id>
- ...
slots:
- <viewer_settings>
- ...
The list of image identifiers under images determines which images are shown in the selection drop-down list. All images used in slots should be listed here.
The viewer settings under slots include all parameters also available in the query string. Only slide is mandatory.
If there are fewer slots defined than available positions given by rows and columns, extra positions will remain empty.
If there are more slots defined than available positions given by rows and columns, paging will be enabled to navigate through all slots.
Example:
dataset: null
rows: 2
columns: 2
images:
- 156067
- 156046
- 156127
slots:
- slide: 156067
tabs: SDbp
x: 45696
y: 17173
t: 0
z: 0
zoom: 1.704
rotate: 0
c0: 1FF00000-FF
c1: 100FF000-FF
c2: 10000FF0-FF
gc: 0
- slide: 156046
tabs: SDbp
x: 34473
y: 13520
t: 0
z: 0
zoom: 1.704
rotate: 0
- slide: 156127
tabs: SDbp
x: 38304
y: 8650
t: 0
z: 0
zoom: 1.704
rotate: 0
PathViewer 3.1+¶
Hooks for custom JavaScript¶
PathViewer has a number of extension points to add custom functionality. It is recommended to load the code with the custom code via the omero.web.pathviewer.js setting.
KeepAlive¶
As long as the PathViewer browser window is open, the user session is kept active by a call every 60 seconds. Additionally custom handlers can be added that are called at the same interval:
$('viewer')
.controller('keepalive')
.registerCallback(function () {
window.console.log('custom keepalive');
});
ROI Actions¶
To add custom actions that act on ROIs, register a new button that will appear on top of the ROI list in the right-hand panel:
$('viewer')
.controller('roiManager')
.registerAction('customAction', {
icon: 'fas fa-cogs',
title: 'Custom ROI action',
enabled: function (roimanager) {
return roimanager.selected().length;
},
action: function (roimanager) {
alert('Custom action');
}
});
PathViewer 3.3+¶
Label images¶
Label image mask ROIs with attached data tables get an additional XML annotation on the ROI with namespace glencoesoftware.com/pathviewer/labelimage/filters.
The value of the annotation is a JSON string containing an array of stored query groups configured for the label image.
Each query group has the following properties:
hits is the cached hit count for this group
name
color
filters is an array of column value comparisons
query is filters formatted as a query string
manual.include and manual.exclude are optional lists of identifiers that have been added to or removed from the query results. They are not considered in the hit count stored in hits.
cached is an optional field; for groups with few hits, the query results are cached as a comma-separated string of base-36 encoded identifiers
Example:
[
{
"hits": 54,
"name": "above 90%",
"color": "rgb(255,255,0)",
"filters": [
{
"column": {
"name": "percent_probability",
"type": "long"
},
"comparison": ">=",
"value": 90
}
],
"manual": {
"include": [438,136,291,745,52,12],
"exclude": [2059,2101,2053,2538,2207,2065,2804,2172,2447]
},
"cached": "rx,ua,zu,zv,122,17v,1gz,1h0,1i2,1mp,1oh,1vj,256,281,2e0,...",
"query": "(roi==540402)&(percent_probability>=90)"
},
{
"hits": 728,
"name": "85% probability",
"color": "rgb(28,230,255)",
"filters": [
{
"column": {
"name": "percent_probability",
"type": "long"
},
"comparison": "==",
"value": 85
}
],
"query": "(roi==540402)&(percent_probability==85)",
"cached": "1u,1v,1w,1x,1y,2z,30,4y,67,7e,7f,7g,7h,7i,7j,97,98,99,..."
}
]
ROI display order¶
ROIs are rendered in a given order, so that overlapping shapes are displayed consistently. This display order is stored in an additional XML annotation on the image with namespace glencoesoftware.com/pathviewer/roidisplayorder.
The value of the annotation is a JSON string containing an object with one displayOrder property, which is a list of shape identifiers in the order the shapes should be rendered, i.e. shapes listed first are displayed behind shapes listed later.
Example:
{
displayOrder: [1003, 1001, 1002]
}
Note: due to the implementation of shape rendering in PathViewer, all read-only shapes are displayed behind all editable shapes. This may cause unintended ordering if a user can edit some, but not all shapes.
Channel groups and labels¶
Channel group information is stored in a Comment annotation on the first image channel with namespace glencoesoftware.com/pathviewer/channel/settings.
These annotations can also be read or set using the command line.
The value of the annotation is a JSON string containing an object with two properties:
descriptions is an optional object mapping channel indexes (as strings) to a string description
groups is an array of channel group objects
Channel group objects have the following properties:
name is the name of the channel group. Note that exactly one channel group must have a NUL character (represented in JSON as “\u0000”) as its name, indicating that it is the default group.
description is the optional string description of the channel group
channels is an array of channel indexes (as numbers) of the channels that are part of the channel group. Note that channels can be part of multiple channel groups, but each channel must appear in at least one group.
channelSettings is an optional object mapping channel indexes (as strings) to channel settings objects, which can override the default settings for that channel in this channel group context.
Channel settings objects have the following properties:
active is true or false
color in the standard #rrggbb format
window is an object with number start and end properties
Example:
{
"descriptions": {
"0": "Description for Channel 1",
"1": "",
"2": ""
},
"groups": [
{
"channelSettings": {
"0": {
"active": true,
"color": "#FF0000",
"window": {
"end": 182,
"start": 38
}
},
"1": {
"active": true,
"color": "#00FF00",
"window": {
"end": 255,
"start": 0
}
}
},
"channels": [
0,
1
],
"description": "A custom channel group",
"name": "Custom group"
},
{
"channelSettings": {
"0": {
"active": true,
"color": "#FF0000",
"window": {
"end": 255,
"start": 0
}
},
"1": {
"active": true,
"color": "#00FF00",
"window": {
"end": 255,
"start": 0
}
},
"2": {
"active": true,
"color": "#0000FF",
"window": {
"end": 255,
"start": 0
}
}
},
"channels": [
0,
2
],
"name": "\u0000"
}
]
}
