OpenSeadragonAnnotator

The main entry point into the Annotorious API. An object of this type is returned when you call the createOSDAnnotator method.

import { createOSDAnnotator } from '@annotorious/openseadragon';

// ...

const anno = createOSDAnnotator(viewer);

You can provide an options object to customize the annotator behavior.

const anno = createOSDAnnotator(viewer, {
  style: { fill: #ff0000, fillOpacity: 0.4 }
});

Init Options

Property	Type	Default	Description
adapter	FormatAdapter		An optional format crosswalk adapter.
autoSave	boolean	false	When set to `true`, annotation update events trigger instantly when the user is idle. If `false`, update events only triger after the user actively de-selects the annotation after editing.
drawingEnabled	boolean	false	Enables or disables drawing functionality .
drawingMode	”click” \| “drag”		Determines how drawing is initiated. For UX purposes, the default depends on the device type. On desktop, default will be “click”. On touch devices, default will be “drag”.
userSelectAction	UserSelectActionExpression	”EDIT”	Action to perform on user selection.
style	DrawingStyleExpression	Annotation style.

Instance Fields

Field	Type	Description
viewer	OpenSeadragon.Viewer	Reference to the OpenSeadragon viewer instance.

Instance Methods

addAnnotation

anno.addAnnotation(annotation);

Add an annotation programmatically.

Argument	Type	Description
annotation	ImageAnnotation	The annotation object.

cancelSelected

anno.cancelSelected();

Programmatically cancel the current selection, if any.

canRedo

const canRedo = anno.canRedo();

Test if there are any re-doable user actions in the undo stack.

Returns: boolean

canUndo

const canUndo = anno.canUndo();

Test if there are any undoable user actions in the undo stack.

Returns: boolean

clearAnnotations

anno.clearAnnotations();

Delete all annotations from the image.

destroy

anno.destroy();

Destroy this ImageAnnotator instance, removing all annotations and the Annotorious container element.

fitBounds

anno.fitBounds(arg, opts?);

Fits the OpenSeadragon viewer to the bounds of the given annotation.

Argument	Type	Default	Description
arg	ImageAnnotation \| string	required	The annotation or annotation ID.
opts	FitboundsOptions \| string		Additional options.

FitBoundsOptions

anno.fitBounds(arg, { immediately: true, padding: 20 });

Additional options to control fitBounds behavior.

Property	Type	Default	Description
immediately	boolean	false	Whether to use animated transition or not.
padding	number \| [number, number, number, number]	0	Optional padding (pixels) when applying the fit.

fitBoundsWithConstraints

anno.fitBoundsWithConstraints(arg, opts?);

Similar to fitBounds, but using the OpenSeadragon fitBoundsWithConstraints method underneath.

Argument	Type	Default	Description
arg	ImageAnnotation \| string	required	The annotation or annotation ID.
opts	FitboundsOptions \| string		Additional options.

getAnnotationById

const annotation = anno.getAnnotationById(id);

Get the annotation with the specified ID.

Argument	Type	Description
id	string	The annotation ID.

Returns: ImageAnnotation | undefined

getAnnotations

const all = anno.getAnnotations();

Get all annotations on the image. Returns: Array<ImageAnnotation>

getSelected

const selected = anno.getSelected();

Get the currently selected annotations.

Returns: Array<ImageAnnotation>

getUser

const currentUser = anno.getUser();

Get the the user object, if any.

Returns: User

loadAnnotations

const loaded = await anno.loadAnnotations(url, replace = false)

Load annotations from a JSON file at a given URL. The method returns a promise of the fetched annotations, in case you want to perform an action after the they have loaded.

The optional replace parameter controls whether the new annotations should replace the current annotations, erasing all existing ones, or get added to them.

Argument	Type	Default	Description
url	string	required	The URL to the JSON annotation file.
replace	boolean	false	If `true`, all current annotations on the image will be cleared.

Returns: Promise<ImageAnnotation[]>

listDrawingTools

const tools = anno.listDrawingTools();

Returns a list of the available drawing tool names. By default, this method will return ['rectangle', 'polygon']. Additional tools may be available through plugins.

Returns: Array<string>

redo

anno.redo();

Programmatically redo the last undone user action.

removeAnnotation

const removedAnnotation = anno.removeAnnotation(annotationOrId);

Remove the specified annotation from the image. Returns the removed annotation.

Argument	Type	Description
annotationOrId	ImageAnnotation \| string	The annotation object or ID to remove.

Returns: ImageAnnotation | undefined

setAnnotations

anno.setAnnotations(annotations, replace = false);

Adds the given list of annotations to the image. Optionally, clearing the annotation layer first and replacing all existing annotations.

Argument	Type	Default	Description
annotations	ImageAnnotation	required	The annotation objects.
replace	boolean	false	If `true`, new annotations will replace existing ones.

setDrawingTool

anno.setDrawingTool('polygon');

Changes the current drawing tool. By default, possible values are rectangle and polygon. Additional tools may be available through plugins.

Argument	Type	Default	Description
arg	string	required	The name of the drawing tool.

setDrawingEnabled

anno.setDrawingEnabled(true);

Enables or disables the ability to create new annotation shapes.

Argument	Type	Description
arg	boolean	Whether drawing of new shapes is allowed or not.

setFilter

anno.setFilter(filter);

// Clear the filter
anno.setFilter();

Set a Filter function to control which annotations to display, and which to hide. A filter is a JavaScript function that receives the ImageAnnotation and its AnnotationState as input and returns a boolean.

Argument	Type	Descriptions
filter	Filter \| undefined	A function that returns `true` if the annotation should be displayed.

setSelected

anno.setSelected(arg, editable?);

// Clear the selection
anno.setSelected();

Programmatically set the current selection. The optional argument editable controls whether the selected annotation should become user-editable. If editable is omitted, the default value is determined by the userSelectAction set in the Init Options. Call without arguments to clear the current selection.

Argument	Type	Description
arg	string \| undefined	The ID of the annotation to select, or `undefined` to clear the selection.
editable	boolean	Optional. Uses the current `userSelectAction` by default.

setStyle

anno.setStyle(style);

// Clear the current style
anno.setStyle();

Sets the global (static or data-driven) DrawingStyle.

Argument	Type	Description
style	DrawingStyleExpression \| undefined	An object or function to define the global annotation drawing style.

setUser

anno.setUser(user);

// Clear the current user
anno.setStyle();

Sets the current user. Annotorious will use this information to insert attribution data into annotations.

Argument	Type	Description
user	User	The user object or `undefined`.

setUserSelectAction

anno.setUserSelectAction(action);

Changes the current userSelectAction, which determines what happens when the user selects an annotation interactively.

Can bea UserSelectAction, or a function that receives the annotation as input and returns a UserSelectAction. The following actions are available:

EDIT: make the annotation shape editable when selecting (default).
SELECT: just select. This will update the AnnotationState and trigger the selectionChanged event, but will not make the shape editable.
NONE: the annotation is inert, clicking has no effect.

Argument	Type	Default	Description
action	UserSelectActionExpression \| undefined	EDIT	Value or function that determines behavior when the user selects an annotation.

setVisible

anno.setVisible(visible);

Changes the visibility of the annotation layer.

Argument	Type	Description
visible	boolean	`true` to make the annotation layer visible, `false` to hide it.

undo

anno.undo();

Programmatically undo the last user action.

updateAnnotation

const previous = anno.updateAnnotation(annotation);

Updates an existing annotation, replacing the existing one with new data. The new annotation must have the same ID as the old one.

Argument	Type	Description
annotation	ImageAnnotation	The new annotation object.

Returns: ImageAnnotation - the previous version of the updated annotation.

on

anno.on(event, callback);

Adds a lifecycle event listener.

Argument	Type	Description
event	string	The event name.
callback	function	The callback function.

off

anno.off(event, callback);

Removes a lifecycle event listener.

Argument	Type	Description
event	string	The event name
callback	function	The callback function.

Events

For the list events available on the ImageAnnotator, refer to the full lifecycle event reference.