PMA.UI Documentation by Pathomation

Viewport

Viewport

Creates a new viewer

Constructor

new Viewport(options, readyCallbackopt, failCallbackopt)

Source:
Tutorials:
  • Tutorial: 01-viewer-minimal
  • Tutorial: 02-viewer-full
  • Tutorial: 05-annotations
  • Tutorial: 07-3rd-party-annotations
Parameters:
Name Type Attributes Description
options Object Initialization properties
Properties
Name Type Attributes Default Description
caller string Downstream application identifier
element string | HTMLElement The element that hosts the viewer. It can be either a valid CSS selector or an HTMLElement instance
image string The path or UID of the image to load
serverUrls Array An array of one or more PMA.core URLs to attempt to connect to. The viewer will loop through all the provided URLs until an accessible one is found.
username string <optional>
 The PMA.core username to use to authenticate, in order to obtain a sessionID. If a username and password pair is provided, then a sessionID is not required.
password string <optional>
 The PMA.core password to use to authenticate, in order to obtain a sessionID. If a username and password pair is provided, then a sessionID is not required.
sessionID string <optional>
 The PMA.core sessionID to use to interact with PMA.core. If a sessionID is provided, then a username and password pair is not required.
keyboardPanFactor Number <optional>
 0.5 A factor to calculate pan delta when pressing a keyboard arrow. The actual pan in pixels is calculated as keyboardPanFactor * viewportWidth.
theme Themes <optional>
 "default" The theme to use
overview boolean | Object <optional>
 true Whether or not to display an overview map
Properties
Name Type Attributes Description
collapsed boolean <optional>
 Whether or not to start the overview in collapsed state
tracking boolean <optional>
 Whether or not to start viewport movement tracking
dimensions boolean | Object <optional>
 true Whether or not to display the dimensions selector for images that have more than one channel, z-stack or timeframe
Properties
Name Type Attributes Description
collapsed boolean <optional>
 Whether or not to start the dimensions selector in collapsed state
flip Viewport~flipOptions <optional>
 Image flip options
barcode boolean | Object <optional>
 false Whether or not to display the image's barcode if it exists
Properties
Name Type Attributes Description
collapsed boolean <optional>
 Whether or not to start the barcode in collapsed state
rotation Number <optional>
 Rotation in steps of 90 degrees
loadingBar boolean | Object <optional>
 true Whether or not to display a loading bar while the image is loading
position Viewport~position <optional>
 The initial position of the viewport within the image
snapshot boolean <optional>
 false Whether or not to display a button that generates a snapshot image
rotationControl boolean <optional>
 true Whether or not to display rotation controls
Properties
Name Type Attributes Description
collapsed boolean <optional>
 Whether or not to start rotation controls in collapsed state
fullscreenControl boolean <optional>
 true Whether or not to add a full screen toggle button
annotations Viewport~annotationOptions <optional>
 Annotation options
referenceImage Viewport~referenceImage <optional>
 Reference image options that will load if no server url, server credentials and image path are provided
digitalZoomLevels Number <optional>
 0 The number of digital zoom levels to add
scaleLine boolean <optional>
 true Whether or not to display a scale line when resolution information is available
colorAdjustments boolean <optional>
 false Whether or not to add a control that allows color adjustments
annotationsLayers boolean | Object <optional>
 true Whether or not to show server side annotation layers
Properties
Name Type Attributes Default Description
collapsed boolean <optional>
 false Whether or not to show the annotation layers control collapsed
loadLayers boolean <optional>
 false Whether or not to show all the annotation layers control on slide load
magnifier Object | boolean <optional>
 false Whether or not to show the magnifier control
Properties
Name Type Attributes Description
collapsed Object | boolean <optional>
 Whether or not to show the magnifier control in collapsed state
grid Object <optional>
 Options for measurement grid
Properties
Name Type Attributes Description
size Array.<number> <optional>
 Grid cell width and height in micrometers
filename string | Viewport~filenameCallback <optional>
 A string to display as the file name or a callback function. If no value is supplied, no file name is displayed.
attributions boolean | Viewport~attributionOptions <optional>
 Whether or not to display Pathomation attribution in the viewer
customButtons Array.<Viewport~customButton> <optional>
 An array of one or more custom buttons to add to the viewer
fov Viewport~fov <optional>
 A specified field of view to load
zoomSlider boolean <optional>
 Whether or not to show the zoomSlider control
readyCallback function <optional>
 Called when the slide has finished loading
failCallback function <optional>
 Called when loading the slide failed

Members

barcodeControl :AssociatedImage

Source:
The barcode control
Type:

colorAdjustmentsControl :ColorAdjustment

Source:
The color adjustment control
Type:

dimensionsControl :DimensionSelector

Source:
The dimension selector control
Type:

layerSwitcher :LayerSwitch

Source:
The server side annotation layers control
Type:

map

Source:
The underlying OpenLayers map

measureDraw :Draw

Source:
The measure draw interaction
Type:
  • Draw

mouseWheelInteraction :PmaMouseWheelZoom

Source:
The mouse wheel interaction
Type:
  • PmaMouseWheelZoom

overviewControl :Overview

Source:
The overview control
Type:

rotationControl :RotationControl

Source:
The rotation control
Type:

Methods

addTileTransformer(transformer)

Source:
Adding tile transformer to the list of transformers
Parameters:
Name Type Description
transformer PMA.UI.View.tileTransformer function that gets pixels as an input parameter and returns nothing, it should adjust pixels values directly in array from parameters

calculateArea(geom) → {number}

Source:
Calculates the area of an OpenLayers geometry
Parameters:
Name Type Description
geom ol.geom The geometry to calculate the area of
Returns:
The area in squared microns or zero if resolution information is not available
Type
number

calculateLength(geom) → {number}

Source:
Calculates the length of an OpenLayers geometry
Parameters:
Name Type Description
geom ol.geom The geometry to calculate the length of
Returns:
The length in microns or zero if resolution information is not available
Type
number

fitToExtent(extent, constrainResolution)

Source:
Fits the view to supplied extent
Parameters:
Name Type Description
extent ol.geom.SimpleGeometry | Array.<number> An array of numbers representing an extent: `[minx, miny, maxx, maxy]` or a simple geometry
constrainResolution bool Whether to fit at any resolution even outside the allowed range

focusToAnnotation(annotationId)

Source:
Pans and zooms the viewer appropriately to focus around an annotation
Parameters:
Name Type Description
annotationId number The id of the annotation to which the viewport should focus

formatArea(area) → {number}

Source:
Formats the area of an OpenLayers geometry
Parameters:
Name Type Description
area number The area of the geometry to format
Returns:
The string with the formatted area and unit
Type
number

getActiveChannels() → {Array}

Source:
Gets an array that contains the indices of the currently active channels
Returns:
Type
Array

getActiveLayer() → {number}

Source:
Gets the index of the active layer (z-stack)
Returns:
Type
number

getActiveServerUrl() → {string}

Source:
Gets the URL of the PMA.core server currently connected to
Returns:
Type
string

getActiveTimeFrame() → {number}

Source:
Gets the index of the active time frame
Returns:
Type
number

getAnnotationFormattedLabel(featureopt) → {String}

Source:
Returns the text of an annotation. This method is not meant to be used by PMA.UI consumers.
Parameters:
Name Type Attributes Description
feature ol.Feature <optional>
 The ol.Feature associated with the annotation
Returns:
The annotation text
Type
String

getAnnotationLabelsVisible()

Source:
Gets a value indicating whether or not the text of the annotations is rendered in the viewer

getAnnotationLayersVisibility() → {Array.<Object>|string|boolean}

Source:
Gets the visibility of the third party annotation layers
Returns:
  • options - An array of options
    Type
    Array.<Object>
  • options.name - The name of the layer to change the visibility
    Type
    string
  • options.visible - Whether to show or hide the specified layer
    Type
    boolean

getAnnotations() → {Array}

Source:
Returns all the annotations
Returns:
An array of ol.Feature instances
Type
Array

getAnnotationsLayersNames()

Source:
Returns the supported annotation layer names for the loaded slide

getAnnotationStyle(styleopt, featureopt) → {function}

Source:
Returns a style that contatins the text of an annotation. This method is not meant to be used by PMA.UI consumers.
Parameters:
Name Type Attributes Description
style ol.style.Style <optional>
 The ol.style.Style associated with the annotation
feature ol.Feature <optional>
 The ol.Feature associated with the annotation
Returns:
The annotation style function
Type
function

getAnnotationTextStyle(featureopt) → {ol.style.Text}

Source:
Returns the text style to be used to render the text part (labels) of annotations. This method is not meant to be used by PMA.UI consumers.
Parameters:
Name Type Attributes Description
feature ol.Feature <optional>
 The ol.Feature associated with the annotation
Returns:
A text style instance
Type
ol.style.Text

getBrightness() → {number}

Source:
Gets the current brightness value of the viewer
Returns:
Type
number

getColorBalance()

Source:
Gets the color balance values
Returns:
An array containing the color balance values for [red, green, blue]

getContrast() → {number}

Source:
Gets the current contrast value of the viewer
Returns:
Type
number

getControlsConfiguration() → {Array.<Viewport~ControlConfiguration>}

Source:
Gets the current configuration of the controls of the viewport
Returns:
configuration - The control configuration object
Type
Array.<Viewport~ControlConfiguration>

getCurrentExtent(unrotate) → {Array.<number>}

Source:
Gets the currently visible extent
Parameters:
Name Type Description
unrotate bool Whether to unrotate the extend back to axis aligned
Returns:
An array of numbers representing an extent: `[minx, miny, maxx, maxy]`
Type
Array.<number>

getCurrentObjective() → {string}

Source:
Returns the current objective magnification
Returns:
- A string representing the current objective magnification ie. "1X", "2X" etc
Type
string

getFlip() → {Viewport~flipOptions}

Source:
Gets the image flip options
Returns:
Type
Viewport~flipOptions

getGamma() → {number}

Source:
Gets the current gamma value of the viewer
Returns:
Type
number

getMaxObjective() → {string}

Source:
Returns the max objective magnification
Returns:
- A string representing the max objective magnification ie. "1X", "2X" etc
Type
string

getMouseWheelZoomMode() → {MouseWheelZoomMode}

Source:
Gets the wheel zoom mode to one of "Normal", "Objectives". The normal mode zooms through all the available resolution, while the "Objectives" mode zoom only on the round objective resolutions 1X,2X,5X,10X, 20X, 40X, 80X, 160X
Returns:
mode
Type
MouseWheelZoomMode

getPosition() → {Viewport~position}

Source:
Gets the current viewport position
Returns:
position
Type
Viewport~position

getSessionID() → {string}

Source:
Gets the currently used sessionID
Returns:
Type
string

getSnapshot(formatopt, extraParamsopt) → {Promise.<Blob>}

Source:
Generates an image with a snapshot of the current viewport and saves it if format is "png" or "jpg"
Parameters:
Name Type Attributes Default Description
format string <optional>
 png The snapshot image format, one of "png", "jpg", "blob"
extraParams Object <optional>
 Extra parameters to draw the snapshot
Properties
Name Type Attributes Default Description
title string <optional>
 A title to draw on top middle of the snapshot
scalebar boolean <optional>
 true Whether to draw a scalebar of the slide
scalebarLocation boolean <optional>
 "TopLeft" When the scalebar will be positioned, one of "TopLeft","TopRight", "BottomLeft", "BottomRight"
scalebarFont boolean <optional>
 "24px serif" A valid css font property to draw e.g. "24px serif"
barcode boolean <optional>
 false Whether to draw the barcode of the slide
overview boolean <optional>
 false Whether to draw an overview of the slide
dpi number <optional>
 null Set the dpi of the output image
filename string <optional>
 snapshot The filename of the image
action string <optional>
 "download" Action that will take place after snapshot created, one of "download","open-tab"
Returns:
A promise to the blob object
Type
Promise.<Blob>

getSnapshotParameters() → {PMA.UI.Components~snapshotParameters}

Source:
Generates the parameters required for generating a snapshot url using getSnapshotUrl
Returns:
Type
PMA.UI.Components~snapshotParameters

getSnapshotUrl(download, objectiveResolutionopt, formatopt, drawScaleBaropt, dpiopt, filenameopt, featureopt, scaleopt) → {PMA.UI.View~SnapshotResult}

Source:
Generates a URL where a snapshot of the current viewport is rendered
Parameters:
Name Type Attributes Default Description
download boolean True to prompt the user to save the snapshot instead of viewing it within the browser
objectiveResolution PMA.UI.View.ObjectiveResolutions <optional>
 The desired objective resolution. If not passed the viewport scale will be used
format string <optional>
 jpg The snapshot image format
drawScaleBar boolean <optional>
 false Whether or not to draw a scalebar
dpi number <optional>
 null Dots per inch to set to the image
filename string <optional>
 snapshot The filename of the image
feature ol.Feature <optional>
 null Clip the snapshot to the bounding box of this annotation
scale number <optional>
 null A factor to scale the image by. Default is the current viewport scale
Returns:
- An object containing the url, width and height of the final image
Type
PMA.UI.View~SnapshotResult

getTileTransformers() → {Array.<PMA.UI.View.tileTransformer>}

Source:
Gets the current list of tile transformers
Returns:
Type
Array.<PMA.UI.View.tileTransformer>

getViewportCoordinates() → {Array.<Array.<number>>}

Source:
Generates a rectangle for the current view
Returns:
An array of the x, y coordinates of the 4 corners of viewing rectangle
Type
Array.<Array.<number>>

hideGrid()

Source:
Hides the measurement grid if visible or does nothing

initializeFeatures(annotations, projection)

Source:
Converts an array of pma.core annotations to open layers features
Parameters:
Name Type Description
annotations Array.<Viewport~annotation> An annotation array as returned by pma.core
projection Object The projection used for diplay

listen(eventName, callback)

Source:
Attaches an event listener to the viewer
Parameters:
Name Type Description
eventName PMA.UI.View.Events The name of the event to listen to
callback function The function to call when the event occurs

login(username, password)

Source:
Authenticates and forces the viewer to redraw
Parameters:
Name Type Description
username string
password string

redraw()

Source:
Forces the viewer to refresh

reloadAnnotations(readyCallbackopt, fingerprintopt)

Source:
Reloads annotations from the server
Parameters:
Name Type Attributes Description
readyCallback function <optional>
 Called when the annotations have finished loading
fingerprint string <optional>
 If exists, will reload annotations by fingerprint

setActiveChannels(channels)

Source:
Sets the active channels
Parameters:
Name Type Description
channels Array An array that contains the indices of the channels to display
Fires:
  • PMA.UI.View.Events#event:DimensionsChanged

setActiveLayer(layer)

Source:
Sets the active layer (z-stack)
Parameters:
Name Type Description
layer number The index of the layer to activate
Fires:
  • PMA.UI.View.Events#event:DimensionsChanged

setActiveTimeFrame(timeframe)

Source:
Sets the active time frame
Parameters:
Name Type Description
timeframe number The index of the time frame to activate
Fires:
  • PMA.UI.View.Events#event:DimensionsChanged

setAnnotationLayersVisibility(options)

Source:
Sets the visibility of the third party annotation layers
Parameters:
Name Type Description
options Array.<Object> An array of options
Properties
Name Type Attributes Description
name string The name of the layer to change the visibility
visible boolean Whether to show or hide the specified layer
opacity number <optional>
 A number between 0 and 1 that sets the opacity of the layer

setBrightness(brightness)

Source:
Sets the brightness of the viewer
Parameters:
Name Type Description
brightness number

setBrightnessContrastGamma(brightness, contrast, gamma)

Source:
Sets the brightness and contrast of the viewer
Parameters:
Name Type Description
brightness number
contrast number
gamma number

setChannelRenderingOptions(options)

Source:
Sets the rendering options for a channel
Parameters:
Name Type Description
options object An object that determines the channel and the options to be set
Properties
Name Type Description
index number An object that determines the channel and the options to be set
clipping Array.<Number> A pair of values [0..100] to clip and scale pixel values
gamma Number A value of tha gamma correction factor for this channel

setColorBalance(red, green, blue)

Source:
Sets the color balance for each rgb channel
Parameters:
Name Type Description
red number A value between 0 and 2 indicating the red channel balance
green number A value between 0 and 2 indicating the green channel balance
blue number A value between 0 and 2 indicating the blue channel balance

setContrast(contrast)

Source:
Sets the contrast of the viewer
Parameters:
Name Type Description
contrast number

setControlsConfiguration(configuration)

Source:
Sets a new configuration for the controls of the viewport
Parameters:
Name Type Description
configuration Array.<Viewport~ControlConfiguration> The control configuration object

setFlip(horizontally, vertically)

Source:
Sets the image flip options
Parameters:
Name Type Description
horizontally bool Whether or not to flip the image horizontally
vertically bool Whether or not to flip the image vertically

setGamma(gamma)

Source:
Sets the gamma of the viewer
Parameters:
Name Type Description
gamma number

setMouseWheelZoomMode(mode)

Source:
Sets the wheel zoom mode to one of "Normal", "Objectives". The normal mode zooms through all the available resolutions, while the "Objectives" mode zooms only to the rounded objective resolutions 1X, 2X, 5X, 10X, 20X, 40X, 80X and 160X
Parameters:
Name Type Description
mode MouseWheelZoomMode

setPosition(position)

Source:
sets the current viewport position
Parameters:
Name Type Description
position Viewport~position

setSessionID(sessionID)

Source:
Overrides the current sessionID and forces the viewer to redraw
Parameters:
Name Type Description
sessionID string

setTileTransformers(transformers)

Source:
Setting list of tile transformers
Parameters:
Name Type Description
transformers Array.<PMA.UI.View.tileTransformer> list of transformer function that gets pixels as an input parameter and returns nothing, it should adjust pixels values directly in array from parameters

showAnnotation(id, show)

Source:
Toggles the visibility of an annotation
Parameters:
Name Type Description
id number The id of the annotation to hide or show
show boolean True to show the annotation, otherwise hide it

showAnnotations(show)

Source:
Toggles the visibility of the annotations layer in total
Parameters:
Name Type Description
show boolean True to show the annotations, otherwise hide them

showAnnotationsByFingerprint(show)

Source:
Toggles the visibility of annotations loaded by fingerprint and loads them if not already loaded
Parameters:
Name Type Description
show boolean True to show the annotation, otherwise hide it

showAnnotationsLabels(visible, showMeasurementsopt)

Source:
Toggles the text of the annotations visibility
Parameters:
Name Type Attributes Description
visible boolean True to show the annotation labels, otherwise hide them
showMeasurements boolean <optional>
 True to show the annotation measurements, otherwise hide them

showGrid(size)

Source:
Shows a measurement grid
Parameters:
Name Type Description
size Array.<number> The size of the grid cells in micrometers

startMeasuring(type)

Source:
Start the realtime measuring tool
Parameters:
Name Type Description
type "area" | "line" Whether to start measuring length or area

stopMeasuring()

Source:
Stops and clears all realtime measurements

unlisten(eventName, callback) → {bool}

Source:
Detaches an event listener from the viewer
Parameters:
Name Type Description
eventName PMA.UI.View.Events The name of the event to remove the callback from
callback function The function to remove from the event listener list
Returns:
Whether or not the callback was actually found and removed
Type
bool

updateSize()

Source:
Forces the viewer to recalculate the viewport size

zoomToObjective(objective)

Source:
Zooms the view to a specific objective
Parameters:
Name Type Description
objective string 1:1, 1X, 2X, 5X, 10X etc.

Type Definitions

annotation

Source:
Properties:
Name Type Attributes Description
AnnotationID Number The annotation id
LayerID Number The layer id
Geometry string The annotation geometry in wkt format
Notes string <optional>
 Optional notes for the annotation
Classification string <optional>
 Optional classification string (Necrosis, tumor etc)
Color string <optional>
 Optional color
CreatedBy string <optional>
 Optional created by string
UpdateInfo string <optional>
 Optional update info
Updatedby string <optional>
 Optional updated by info
FillColor string <optional>
 Optional fill color
Dimensions Number <optional>
 Optional dimensionality of the annotation
Context string <optional>
 Optional context value of the annotation
An annotation as returned by pma.core

annotationOptions

Source:
Properties:
Name Type Attributes Default Description
visible boolean <optional>
 true Whether or not to display the loaded annotations
labels boolean <optional>
 false Whether or not to render the text label of each annotation in the viewer
imageBaseUrl boolean <optional>
 "" The base URL from which to load images
imageScale number <optional>
 NaN Scale factor for images
alwaysDisplayInMicrons boolean <optional>
 false Whether or not to automatically select the appropriate units for annotations (μm(^2) or mm(^2)) depending on the value
showMeasurements boolean <optional>
 true Whether to show the length and area of an annotation
loadAnnotationsByFingerprint boolean <optional>
 false Whether to load annotations based on image's fingerprint
currentUserOnly boolean <optional>
 false Whether to load annotations for the current user only or for everyone
contexts Array.<string> <optional>
 [] Optional context filters
filter Viewport~annotationsFilterCallback <optional>
 A function that takes a PMA.core annotation and returns true if the annotation should be loaded, otherwise false
Annotation display options
Type:
  • Object

annotationsFilterCallback(annotation) → {bool}

Source:
Function that takes a PMA.core annotation and returns true if the annotation should be loaded, otherwise false
Parameters:
Name Type Description
annotation Object The annotation object to filter
Returns:
Type
bool

attributionOptions

Source:
Properties:
Name Type Attributes Default Description
html string The HTML contents to add inside the attribution container element
className string <optional>
 "ol-attr" The CSS class to assign to the attribution container element
Attribution display options
Type:
  • Object

ControlConfiguration

Source:
Properties:
Name Type Description
control Controls The control to configure
visible boolean The visibility of the control
collapsed boolean Whether the control is collapsed or not
An object for configuring the visible and collapse state of a control

customButton

Source:
Properties:
Name Type Attributes Default Description
title string The title of the button
content string The inner html of the button
class string The class of the button
location ButtonLocations <optional>
 ButtonLocations.S The location in the viewport of the custom button
callback function The callback to call when the button is clicked with this referring to the viewer
A custom button to be added to the viewer
Type:
  • Object

filenameCallback(options) → {string}

Source:
Function that returns a file name to display in the viewer
Parameters:
Name Type Description
options Object
Properties
Name Type Description
serverUrl string The URL of the current PMA.core server
fileName string The full path of the currently loaded image
Returns:
Type
string

flipOptions

Source:
Properties:
Name Type Attributes Default Description
horizontally boolean <optional>
 false Whether or not to flip the image horizontally
vertically boolean <optional>
 false Whether or not to flip the image vertically
Image flip options
Type:
  • Object

fov

Source:
Properties:
Name Type Attributes Default Description
extent Array The extent of the viewport [minx, miny, maxx, maxy]
rotation number The rotation of the viewport
constrainResolution bool <optional>
 Whether to contain the resolution to allowed values when fitting to extent
channels Array <optional>
 The selected channels
layer number <optional>
 0 The selected layer
timeframe number <optional>
 0 The selected timeframe
Viewport Field of view
Type:
  • Object

position

Source:
Properties:
Name Type Attributes Default Description
center Array The x and y coordinates of the center point
zoom number The zoom level. Can be omitted if resolution is specified
resolution number <optional>
 Can be omitted if zoom is specified
rotation number <optional>
 0
Viewport position
Type:
  • Object

referenceImage

Source:
Properties:
Name Type Attributes Default Description
src string "pathomation.png" Source of reference image to load
width Number 383 Width of reference image
height Number 183 Height of reference image
backgroundColor string <optional>
 "#ffffff" Background color of viewport in css format
Annotation display options
Type:
  • Object

SnapshotCoordinates

Source:
Properties:
Name Type Description
x Integer The x coordinate
y Integer The y coordinate
w Integer The width
h Integer The height
scale Number The scale of the current view in radians
rotation Number The rotation of the current view in radians
flip Viewport~flipOptions Whether the image is flipped
An object for configuring the visible and collapse state of a control