PathViewer API ============== .. _api: PathViewer 3.0+ ----------------- Base URL ^^^^^^^^ :: https://omero.server/pathviewer/viewer .. _query_string_parameters: 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: /#?slide= Loading specific images into Slides Panel ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: /#?slide=&q_image=,,... Loading all images from a specific OMERO dataset into Slides Panel ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: /#?slide=&q_dataset= Selecting active user interface components ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ URL parameter format: :: tabs= 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: :: /#?slide=&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: :: /#?slide=&tabs=VRp Setting image position and orientation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Example 1. Rotating the image by 15 degrees and flipping it horizontally: :: /#?slide=&rotate=15&flip=h Example 2. Rotating the image by 15 degrees and flipping it horizontally and vertically: :: /#?slide=&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: :: /#?slide=&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| rows: <1-4> columns: <1-4> images: - - ... slots: - - ... 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 :ref:`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" } ] }