Skip to content

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

PropertyTypeDefaultDescription
adapterFormatAdapterAn optional format crosswalk adapter.
autoSavebooleanfalseWhen 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.
drawingEnabledbooleanfalseEnables 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”.
userSelectActionUserSelectActionExpression”EDIT”Action to perform on user selection.
styleDrawingStyleExpressionAnnotation style.

Instance Fields

FieldTypeDescription
viewerOpenSeadragon.ViewerReference to the OpenSeadragon viewer instance.

Instance Methods

addAnnotation

anno.addAnnotation(annotation);

Add an annotation programmatically.

ArgumentTypeDescription
annotationImageAnnotationThe 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.

ArgumentTypeDefaultDescription
argImageAnnotation | stringrequiredThe annotation or annotation ID.
optsFitboundsOptions | stringAdditional options.

FitBoundsOptions

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

Additional options to control fitBounds behavior.

PropertyTypeDefaultDescription
immediatelybooleanfalseWhether to use animated transition or not.
paddingnumber | [number, number, number, number]0Optional padding (pixels) when applying the fit.

fitBoundsWithConstraints

anno.fitBoundsWithConstraints(arg, opts?);

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

ArgumentTypeDefaultDescription
argImageAnnotation | stringrequiredThe annotation or annotation ID.
optsFitboundsOptions | stringAdditional options.

getAnnotationById

const annotation = anno.getAnnotationById(id);

Get the annotation with the specified ID.

ArgumentTypeDescription
idstringThe 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.

ArgumentTypeDefaultDescription
urlstringrequiredThe URL to the JSON annotation file.
replacebooleanfalseIf 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.

ArgumentTypeDescription
annotationOrIdImageAnnotation | stringThe 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.

ArgumentTypeDefaultDescription
annotationsImageAnnotationrequiredThe annotation objects.
replacebooleanfalseIf 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.

ArgumentTypeDefaultDescription
argstringrequiredThe name of the drawing tool.

setDrawingEnabled

anno.setDrawingEnabled(true);

Enables or disables the ability to create new annotation shapes.

ArgumentTypeDescription
argbooleanWhether 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.

ArgumentTypeDescriptions
filterFilter | undefinedA 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.

ArgumentTypeDescription
argstring | undefinedThe ID of the annotation to select, or undefined to clear the selection.
editablebooleanOptional. Uses the current userSelectAction by default.

setStyle

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

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

ArgumentTypeDescription
styleDrawingStyleExpression | undefinedAn 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.

ArgumentTypeDescription
userUserThe 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.
ArgumentTypeDefaultDescription
actionUserSelectActionExpression | undefinedEDITValue or function that determines behavior when the user selects an annotation.

setVisible

anno.setVisible(visible);

Changes the visibility of the annotation layer.

ArgumentTypeDescription
visiblebooleantrue 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.

ArgumentTypeDescription
annotationImageAnnotationThe new annotation object.

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

on

anno.on(event, callback);

Adds a lifecycle event listener.

ArgumentTypeDescription
eventstringThe event name.
callbackfunctionThe callback function.

off

anno.off(event, callback);

Removes a lifecycle event listener.

ArgumentTypeDescription
eventstringThe event name
callbackfunctionThe callback function.

Events

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