API Reference: OpenSeadragon Plugin

The OpenSeadragon Plugin is an extension to the OpenSeadragon zoomable image viewer. If you are looking for the standard version of Annotorious, which works with normal images embedded in websites, see here instead.

Initialization

When included via <script> tag:

var anno = OpenSeadragon.Annotorious(viewer, config);

With npm:

import OpenSeadragon from 'openseadragon';
import * as Annotorious from '@recogito/annotorious-openseadragon';
import '@recogito/annotorious-openseadragon/dist/annotorious.min.css';

const viewer = OpenSeadragon({
  id: "openseadragon",
  tileSources: {
    type: "image",
    url: "1280px-Hallstatt.jpg"
  }
 });

const config = {}; // Optional plugin config options

Annotorious(viewer, config);

The config object is optional, and supports following properties:

Property Type Default Description
allowEmpty Boolean false Annotations created without bodies are normally discarded. Set to true to allow empty annotations.
disableEditor Boolean false Disable the editor if you only need drawing functionality, but not the popup.
disableSelect Boolean false Disables selection functionality. Clicking will no longer open the editor. (The clickAnnotation event still fires.)
drawOnSingleClick Boolean false If true users can start drawing with a single click also, not just with click-and-drag
formatters Array | Function - A formatter function or list of functions providing custom style rules.
fragmentUnit String ‘pixel’ Store rectangle coordinates in pixel units (default) or percent units.
gigapixelMode Boolean false Enables slower, but more accurate shape rendering on images with extrememly high resolution. Note that gigapixelMode current doesn’t support rotate or flipped OSD views.
handleRadius Number 6 Radius of the shape resize handles.
hotkey Object - Re-assigns the key that activates drawing mode (Shift by default). Allowed values are, either, a keycode (e.g. ‘Shift’, ‘Alt’, ‘Control’), or an object with a key and an optional inverted property. If inverted is set to true, Annotorious is permanently in drawing mode. Image navigation is only possible when the hotkey is pressed.
locale String - Two-character ISO language code or auto to use the browser setting.
messages Object - Custom UI labels. Requires a message dictionary object.
readOnly Boolean false Display annotations in read-only mode.
widgets Array - A list of editor widget definitions (see this guide for details).

Instance Fields

disableEditor

console.log(anno.disableEditor); // true or fals
anno.disableEditor = !anno.disableEditor; // toggles state

Change the operation mode between normal (drawing tools & editor popup) and headless. In headless mode, only drawing tools and lifecycle events are active. The editor will not open.

disableSelect

console.log(anno.disableSelect); // true or false
anno.disableSelect = !anno.disableSelect;

Disables selection functionality. Clicking an annotation will no longer open the editor, or fire the selectAnnotation event. The clickAnnotation event will still fire!

Setting disableSelect to true will not clear the current selection, if any.

formatters

anno.formatters = [ ...anno.formatters, MyFormatter ];

The formatter functions on this Annotorious instance.

readOnly

console.log(anno.readOnly); // true or fals
anno.readOnly = !anno.readOnly; // toggles state

Change display mode between normal (annotations are editable) and read-only.

widgets

Dynamically changes the current set of editor widgets.

anno.widgets = [...anno.widgets, MyCustomWidget ];

Change display mode between normal (annotations are editable) and read-only.

Instance Methods

.addAnnotation

anno.addAnnotation(annotation);

Adds an annotation programmatically. The format is the W3C WebAnnotation model.

Argument Type Value
annotation Object the annotation in W3C WebAnnotation format

.addDrawingTool

anno.addDrawingTool(plugin);

Register a drawing tool plugin.

.cancelSelected

anno.cancelSelected();

Programmatically cancel the current selection, if any.

Note: programmatic cancel will not trigger the cancelSelected event!

.clearAnnotations

anno.clearAnnotations();

Delete all annotations from the image.

.clearAuthInfo

anno.clearAuthInfo();

Clears the user auth information. Annotorious will no longer insert creator data when a new annotation is created or updated. (See setAuthInfo for more information about creator data.)

.destroy

anno.destroy();

Destroys this instance of Annotorious, removing the annotation layer on the image.

.fitBounds

anno.fitBounds(arg [, immediately]);

Makes the OpenSeadragon viewport pan and zoom to the bounds of the specified annotation.

Argument Type Value
arg String, Object the annotation or the annotation ID
immediately Boolean if true pans and zooms without animation

.fitBoundsWithConstraints

anno.fitBoundsWithConstraints(arg [, immediately]);

Makes the OpenSeadragon viewport pan and zoom to the bounds of the specified annotation, while enforcing the constraints (minZoom, maxZoom and visibilityRatio).

Argument Type Value
arg String, Object the annotation or the annotation ID
immediately Boolean if true pans and zooms without animation

.getAnnotationById

const annotation = getAnnotationById(id);

Returns the annotation with the specified ID.

Argument Type Value
id String the annotation ID

.getAnnotations

anno.getAnnotations();

Returns all annotations according to the current rendered state, in W3C Web Annotation format.

.getAnnotationsIntersecting

anno.getAnnotationsIntersecting(arg);

Returns the annotations whose bounding boxes intersect with the bounding box of the specified annotation.

Argument Type Value
arg String, Object the annotation or the annotation ID

.getImageSnippetById

const { snippet, transform } = anno.getImageSnippetById(annotationId);

Returns an object containing:

Warning: this method is currently for experimental use only. It will only return a valid snippet if the given annotation is currently visible in the OpenSeadragon viewport.

Field Type Value
snippet Canvas the image under the given annotations’ bounds as a CANVAS element
transform Function coordinate conversion function

.getSelected

const selected = anno.getSelected();

Returns the currently selected annotation.

.getSelectedImageSnippet

const { snippet, transform } = anno.getSelectedImageSnippet();

Returns an object containing:

Field Type Value
snippet Canvas the image under the current selection bounds as a Canvas element
transform Function coordinate conversion function

.listDrawingTools

const toolNames = anno.listDrawingTools();

Returns a list of the available drawing tools, including those from registered drawing tool plugins.

.loadAnnotations

anno.loadAnnotations(url);

Loads annotations from a JSON URL. The method returns a promise, in case you want to perform an action after the annotations have loaded.

anno.loadAnnotations(url).then(function(annotations) {
  // Do something
});
Argument Type Value
url String the URL to HTTP GET the annotations from

.off

anno.off(event [, callback]);

Unsubscribe from an event. If no callback is provided, all event handlers for this event will be unsubscribed.

Argument Type Value
event String the name of the event
callback Function the function used when binding to the event

.on

anno.on(event, callback);

Subscribe to an event. (See Events for the list.)

Argument Type Value
event String the name of the event
callback Function the function to call when the event is emitted

.once

anno.once(event, callback);

Subscribe to an event only once. (See Events for the list.)

Argument Type Value
event String the name of the event
callback Function the function to call when the event is emitted

.panTo

anno.panTo(arg [, immediately]);

Pans the OpenSeadragon viewport to the specified annotation.

Argument Type Value
arg String, Object the annotation or the annotation ID
immediately Boolean if true pans without animation

.removeAnnotation

anno.removeAnnotation(arg);

Removes an annotation programmatically. Note: programmatic remove will not trigger the deleteAnnotation event!

Argument Type Value
arg String, Object the annotation in W3C WebAnnotation format or the annotation ID

.removeDrawingTool

anno.removeDrawingTool(id);

Removes the drawing tool with the specified tool ID.

Argument Type Value
id String the drawing tool ID

.saveSelected

anno.saveSelected();

Saves the current selection. This is essentially a programmatic way to hit the Ok button on the editor.

.selectAnnotation

anno.selectAnnotation(arg);

Selects an annotation programmatically, highlighting its shape, and opening the editor popup. Note: programmatic select will not trigger the selectAnnotation event!

Argument Type Value
arg String, Object the annotation or the annotation ID

.setAnnotations

anno.setAnnotations(annotations);

Renders the list of annotations to the image, removing any previously existing annotations.

Argument Type Value
annotations Array array of annotations in W3C WebAnnotation format

.setAuthInfo

var anno = Annotorious.init({ image: 'my-image' });

anno.setAuthInfo({
  id: 'http://recogito.example.com/rainer',
  displayName: 'rainer'
});

Specifies user authentication information. Annotorious will use this information when annotations are created or updated, and display it in the editor popup.

Editor popup example

Set this data right after initializing Annotorious, and in case the user login status in your host application changes. The argument to .setAuthInfo is an object with the following properties:

Property Type Value
id String REQUIRED the user ID, which should be a URI
displayName String REQUIRED the user name, for display in the UI

Annotorious will insert this data into every new annotation body that gets created:

{ 
  type: "Annotation",
  
  // ...  

  body:[{
    type: "TextualBody",
    value:"My comment",
    purpose: "commenting",
    created: "2020-05-18T09:39:47.582Z",
    creator: {
      id: "http://recogito.example.com/rainer",
      name: "rainer"
    }
  }]
}

.setDrawingEnabled

anno.setDrawingEnabled(enabled);

Switches the OpenSeadragon viewer from its normal zoom & pan behavior to “drawing mode”. That means the user no longer needs to hold SHIFT in order to start drawing. Instead, drawing starts immediately when clicking and holding the mouse button.

After the annotation is created or canceled, OpenSeadragon automatically switches back to normal zoom & pan behavior.

.setDrawingEnabled has no effect while readOnly mode is active.

Argument Type Value
enabled Boolean if true OpenSeadragon switches from navigation to drawing mode

.setDrawingTool

anno.setDrawingTool(toolName);

Switches between the different available drawing tools. Per default, Annotorious provides a standard rectangle tool (rect) and a standard polygon drawing tool (polygon).

More tools may be available through plugins. Use .listDrawingTool to get the list of registered tools.

Argument Type Value
toolName String E.g. rect or polygon

.setServerTime

Set a “server time” timestamp. When using authInfo, this method helps to synchronize the created timestamp that Annotorious inserts into the annotation with your server environment, avoiding problems when the clock isn’t properly set in the user’s browser.

After setting server time, the Annotorious will adjust the created timestamps by the difference between server time the user’s local clock.

.setVisible

anno.setVisible(visible);

Shows or hides the annotation layer.

Argument Type Value
visible Boolean if true show the annotation layer, otherwise hide it

.updateSelected

anno.updateSelected(annotation[, saveImmediately]);

Replace the currently selected annotation with the one given as argument to .updateSelected. Optionally: save the annotation immediately, triggering a createAnnotation or updateAnnotation event.

Important: this method returns a Promise. The update will not be effective immediately. Make sure you wait until the Promise completes before saving the annotation.

Use this method for applications that (with disableEditor set to true).

var anno = Annotorious.init({
  image: 'my-image'
  disableEditor: true
});

anno.on('createSelection', async function(selection) {
  selection.body = [{
    type: 'TextualBody',
    purpose: 'tagging',
    value: 'MyTag'
  }];

  // Make sure to wait before saving!
  await anno.updateSelected(selection);
  anno.saveSelected();

  // Or: anno.updateSelected(selection, true);
});

Events

cancelSelected

anno.on('cancelSelected', function(selection) {
  // 
});

Fired when the user has canceled a selection, by hitting Cancel in the editor, or by clicking or tapping outside the selected annotation shape.

Argument Type Value
selection Object the canceled selection in W3C WebAnnotation format

changeSelectionTarget

anno.on('changeSelectionTarget', function(target) {
  // 
});

Fired when the shape of a newly created selection, or of a selected annotation is moved or resized.

Argument Type Value
target Object the W3C WebAnnotation target

clickAnnotation

anno.on('clickAnnotation', function(annotation, element) {
  // 
});

Fired every time the user clicks an annotation (regardless of whether it is already selected or not).

Argument Type Value
annotation Object the clicked annotation
element Element the clicked annotation SVG shape element

createAnnotation

anno.on('createAnnotation', function(annotation, overrideId) {
  // 
});

Fired when a new annotation is created from a user selection.

Argument Type Value
annotation Object the annotation in W3C WebAnnotation format
overrideId Function a callback function for assigning a custom annotation ID

When an annotation is created, Annotorious automatically assigns it a globally unique ID. It is possible to override this ID with your own (e.g. server-generated) ID via the overrideId callback function.

r.on('createAnnotation', async (annotation, overrideId) => {
  // POST to the server and receive a new ID
  const newId = await server.createAnnotation(annotation);

  // Inject that ID into RecogitoJS
  overrideId(newId);
});

createSelection

anno.on('createSelection', function(selection) {
  // 
});

Fired when a new selection shape is drawn on the image.

Argument Type Value
selection Object the selection object in W3C WebAnnotation format

deleteAnnotation

anno.on('deleteAnnotation', function(annotation) {
  // 
});

Fired when an existing annotation was deleted.

Argument Type Value
annotation Object the deleted annotation

mouseEnterAnnotation

anno.on('mouseEnterAnnotation', function(annotation, element) {
  // 
});

Fired when the mouse moves into an existing annotation.

Argument Type Value
annotation Object the annotation
element Object the annotation shape SVG element

mouseLeaveAnnotation

anno.on('mouseLeaveAnnotation', function(annotation, element) {
  // 
});

Fired when the mouse moves out of an existing annotation.

Argument Type Value
annotation Object the annotation
element Object the annotation shape SVG element

selectAnnotation

anno.on('selectAnnotation', function(annotation, element) {
  // 
});

Fired when the user selects an annotation. Note that this event will not fire when the selection is made programmatically through the selectAnnotation(arg) API method.

Argument Type Value
annotation Object the annotation in W3C WebAnnotation format
element Element the annotation SVG shape element

startSelection

anno.on('startSelection', function(point) {
  console.log(point.x, point.y)
});

Fired when the user starts drawing a new shape.

Argument Type Value
point Object the x/y coordinates of the start point (image pixel coordinates)

updateAnnotation

anno.on('updateAnnotation', function(annotation, previous) {
  // 
});

Fired when an existing annotation was updated.

Argument Type Value
annotation Object the updated annotation
previous Object the annotation state before the update

Formatters

Per default, Annotorious renders annotations as SVG group elements with an a9s-annotation CSS class. A formatter function allows you to dynamically add additional attributes and elements to the SVG annotation shape.

A formatter is a JavaScript function takes a single argument - the annotation - and must return a string, a DOM element or an object.

Element Caveats

When using DOM elements, keep in mind that you should specify at least the x,y positions and the width and height attributes.
The x and y positions are calculated from the upper left when using the box tool. If using SVG elements then make sure to use the appropriate fill/stroke attributes.

String Example

/** 
 * This simple formatter will add an extra 'long' CSS class to 
 * long comments
 */
var formatter = function(annotation) {

  var longComments = annotation.bodies.filter(function(body) {
    var isComment = body.type === 'TextualBody' && 
      (body.purpose === 'commenting' || body.purpose === 'replying');

    var isLong = body.value.length > 100;

    return isComment && isLong;
  });

  if (longComments.length > 0) {
    // This annotation contains long comments - add CSS class
    return 'long';
  }
}

var anno = Annotorious.init({
  image: document.getElementyById('my-image'),
  locale: 'auto',
  formatter: formatter
});

You can then apply a visual style to long comments in your own CSS stylesheet.

.a9s-annotation.long {
  stroke-width:4;
  stroke:red;
}

Object Example

/**
 * This formatter will add usernames from the annotation as a data
 * attribute and apply an inline style (red outline) where multiple 
 * users have annotated
 */
var formatter = function(annotation) {

  var contributors = [];

  annotation.bodies.forEach(function(body) {
    if (body.creator)
      contributors.push(body.creator.id);
  });

  if (contributors.length > 1) {
    return {
      'data-users': contributors.join(', '),
      'style': 'stroke-width:2; stroke: red'
    }
  }
}

var anno = Annotorious.init({
  image: document.getElementyById('my-image'),
  locale: 'auto',
  formatter: formatter
});