ImageAnnotator
The main entry point into the Annotorious API. An object of this
type is returned when you call the createImageAnnotator
method.
You can provide an options object to customize the annotator behavior.
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 | true | Enables or disables drawing functionality. |
drawingMode | ”click” | “drag" | "drag” | Determines how drawing is initiated. |
userSelectAction | UserSelectActionExpression | ”EDIT” | Action to perform on user selection. |
style | DrawingStyleExpression | Annotation style. |
Instance Fields
Field | Type | Description |
---|---|---|
element | HTMLDivElement | A container element that Annotorious generates around the image. |
Instance Methods
addAnnotation
Add an annotation programmatically.
Argument | Type | Description |
---|---|---|
annotation | ImageAnnotation | The annotation object. |
cancelSelected
Programmatically cancel the current selection, if any.
canRedo
Test if there are any re-doable user actions in the undo stack.
Returns: boolean
canUndo
Test if there are any undoable user actions in the undo stack.
Returns: boolean
clearAnnotations
Delete all annotations from the image.
destroy
Destroy this ImageAnnotator instance, removing all annotations and the Annotorious container element.
getAnnotationById
Get the annotation with the specified ID.
Argument | Type | Description |
---|---|---|
id | string | The annotation ID. |
Returns: ImageAnnotation | undefined
getAnnotations
Get all annotations on the image. Returns: Array<ImageAnnotation>
getSelected
Get the currently selected annotations.
Returns: Array<ImageAnnotation>
getUser
Get the the user object, if any.
Returns: User
loadAnnotations
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
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
Programmatically redo the last undone user action.
removeAnnotation
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
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
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
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
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
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
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
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
Changes the current userSelectAction
, which determines what happens when the user selects an annotation interactively.
Can be a 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
Changes the visibility of the annotation layer.
Argument | Type | Description |
---|---|---|
visible | boolean | true to make the annotation layer visible, false to hide it. |
undo
Programmatically undo the last user action.
updateAnnotation
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
Adds a lifecycle event listener.
Argument | Type | Description |
---|---|---|
event | string | The event name. |
callback | function | The callback function. |
off
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.