Class: AnnotationToolkit

OSDPaperjsAnnotation.AnnotationToolkit(openSeadragonViewer, optsopt)

A class for creating and managing annotation tools on an OpenSeadragon viewer.

Constructor

new AnnotationToolkit(openSeadragonViewer, optsopt)

Create a new AnnotationToolkit instance.
Parameters:
Name Type Attributes Description
openSeadragonViewer OpenSeadragon.Viewer The OpenSeadragon viewer object.
opts object <optional>
Properties
Name Type Attributes Default Description
addUI object | boolean <optional>
 Deprecated. If set, annotation UI is created via addAnnotationUI. Prefer toolbar/layerUI/layout for new code.
toolbar object | boolean <optional>
 If set, toolbar is created at construction (same as getToolbar after). Value: true or { tools?: string[] }.
layerUI object | boolean <optional>
 If set, layer UI is created at construction (same as getLayerUI after). Value: true or { addFileButton?: boolean }.
layout object | boolean <optional>
 If set, AnnotationLayout (grid + optional toggle) is created at construction (same as addAnnotationLayout after). Value: true or { addButton?, initialOpen?, buttonTogglesToolbar?, buttonTogglesLayerUI? }.
overlay object <optional>
 a PaperOverlay object to use
destroyOnViewerClose object <optional>
 whether to destroy the toolkit and its overlay when the viewer closes
cacheAnnotations object <optional>
 whether to keep annotations in memory for images which aren't currently open
strictGeometry boolean <optional>
 false when true, `convertPaperItemToAnnotation` throws if `toGeoJSONGeometry()` has coordinates whose array nesting does not match RFC 7946 for the declared `geometry.type` (e.g. Polygon vs MultiPolygon). When false (default), the same mismatch only logs a console warning. Does not replace a full GeoJSON schema validator.
strictPaperItemContract boolean <optional>
 false when true, `convertPaperItemToAnnotation` throws if `paperItem` violates `AnnotationItem.constructor.paperItemShapeContract` (e.g. MultiPolygon requires `paper.CompoundPath`). When false (default), a violation only logs a console warning.
Source:

Extends

  • OpenSeadragon.EventSource

Members

annotationUI

Get the default style for the annotation items.
Source:

defaultStyle

Get the default style for the annotation items.
Source:

paperScope

Get the paperScope associated with this toolkit
Source:

Methods

_emitIntegrationEvent(name, payload, ctxopt)

Emit an integration hook event to the configured targets. This is the single entrypoint for toolkit-owned "public hook" events so we can keep payloads consistent and optionally avoid extra calls.
Parameters:
Name Type Attributes Description
name string event name (kebab-case)
payload Object event payload (will be shallow-cloned and enriched)
ctx Object <optional>
Properties
Name Type Attributes Description
tool OSDPaperjsAnnotation.ToolBase <optional>
 tool instance associated with the event
Source:

addAnnotationLayout(optsopt) → {AnnotationLayout|null}

Build the annotation layout (grid, resize, toggle button) using AnnotationLayout. Uses getToolbar() and getLayerUI() (lazy-creating with default opts if needed). Mutually exclusive with addAnnotationUI.
Parameters:
Name Type Attributes Description
opts Object <optional>
 addButton, buttonTogglesToolbar, buttonTogglesLayerUI, initialOpen (all optional).
Source:
Returns:
The layout, or null if addAnnotationUI already exists.
Type
AnnotationLayout | null

addAnnotationUI(optsopt) → {AnnotationUI}

Add an annotation UI to the toolkit.
Parameters:
Name Type Attributes Default Description
opts object <optional>
 {} The options for the annotation UI.
Source:
Returns:
The annotation UI object.
Type
AnnotationUI

addEmptyFeatureCollectionGroup() → {paper.Group}

Add a new, empty FeatureCollection with default label and parent
Source:
Returns:
The paper group object representing the feature collection.
Type
paper.Group

addFeatureCollections(featureCollections, replaceCurrent, parentImageopt)

Add feature collections to the toolkit from GeoJSON objects.
Parameters:
Name Type Attributes Description
featureCollections Array.<object> The array of GeoJSON objects representing feature collections.
replaceCurrent boolean Whether to replace the current feature collections or not.
parentImage OpenSeadragon.TiledImage | OpenSeadragon.Viewport | false <optional>
 which image to add the feature collections to
Source:

addTools(toolNamesopt)

Add a set of tools without the full UI (toolbar). Use when addUI is false. Creates a toolset (tool layer + tool instances) so getTool(name) and activation work.
Parameters:
Name Type Attributes Description
toolNames Array.<string> <optional>
 Array of tool names (e.g. ['default', 'ruler']). Default tool is always included.
Source:

clearCache()

Empty any cached annotations
Source:

close()

Close the toolkit and remove its feature collections.
Source:

destroy()

Destroy the toolkit and its components.
Source:

getFeatureCollectionGroups(parentLayeropt) → {Array.<paper.Group>}

Get the feature collection groups that the toolkit is managing.
Parameters:
Name Type Attributes Description
parentLayer paper.Layer <optional>
 The layer to find feature collections within. If not specified, finds across all layers.
Source:
Returns:
The array of paper groups representing feature collections.
Type
Array.<paper.Group>

getFeatures() → {Array.<paper.Item>}

Get the features in the toolkit.
Source:
Returns:
The array of paper item objects representing features.
Type
Array.<paper.Item>

getLayerUI(optsopt) → {LayerUI|null}

Get the toolkit's layer UI, creating it on first call with the given opts. Use .element to get the root DOM node (official API; do not look up by CSS class or id).
Parameters:
Name Type Attributes Description
opts Object <optional>
 Used only when creating: opts.addFileButton - optional boolean.
Source:
Returns:
The layer UI instance, or null if addAnnotationUI exists but did not create a layer UI.
Type
LayerUI | null

getLayerUIElement(optsopt) → {HTMLElement|null}

Get the root DOM element for the layer UI (official API). Returns null if no layer UI exists.
Parameters:
Name Type Attributes Description
opts Object <optional>
 Passed to getLayerUI(opts) when lazy-creating.
Source:
Returns:
Type
HTMLElement | null

getTool(name) → {OSDPaperjsAnnotation.ToolBase|null}

Get a tool instance by name (e.g. 'ruler', 'default'). Works with full UI or headless addTools().
Parameters:
Name Type Description
name string Tool name.
Source:
Returns:
Type
OSDPaperjsAnnotation.ToolBase | null

getToolbar(optsopt) → {AnnotationToolbar|null}

Get the toolkit's toolbar, creating it on first call with the given opts. Use .element to get the root DOM node (official API; do not look up by CSS class or id).
Parameters:
Name Type Attributes Description
opts Object <optional>
 Used only when creating: opts.tools - optional array of tool names.
Source:
Returns:
The toolbar instance, or null if addAnnotationUI exists but did not create a toolbar.
Type
AnnotationToolbar | null

getToolbarElement(optsopt) → {HTMLElement|null}

Get the root DOM element for the toolbar (official API). Returns null if no toolbar exists.
Parameters:
Name Type Attributes Description
opts Object <optional>
 Passed to getToolbar(opts) when lazy-creating.
Source:
Returns:
Type
HTMLElement | null

loadGeoJSON(geoJSON, replaceCurrent, parentImageopt, pixelCoordinatesopt)

Load feature collections from GeoJSON objects and add them to the project.
Parameters:
Name Type Attributes Description
geoJSON Array.<object> The array of GeoJSON objects representing feature collections.
replaceCurrent boolean Whether to replace the current feature collections or not.
parentImage OpenSeadragon.TiledImage | OpenSeadragon.Viewport | false <optional>
 Which image (or viewport) to add the object to
pixelCoordinates boolean <optional>
Source:

makePlaceholderItem(style)

Make a placeholder annotation item
Parameters:
Name Type Description
style Object options (e.g strokeColor) to pass to the paper item
Source:

off(name, fn) → {this}

Unsubscribe from Paper.js project events. Equivalent to: `tk.paperScope.project.off(name, fn)`.
Parameters:
Name Type Description
name string
fn function
Source:
Returns:
Type
this

on(name, fn) → {this}

Subscribe to Paper.js project events without reaching into paperScope internals. Equivalent to: `tk.paperScope.project.on(name, fn)`.
Parameters:
Name Type Description
name string
fn function
Source:
Returns:
Type
this

registerWithConfigurationWidget(configurationWidget)

Opt in to a ConfigurationWidget by adding an "Annotations" custom section (generic addSection only). The toolkit owns the section DOM (toolbar visibility toggles for the pencil and save/load buttons when present). Requires `addAnnotationUI()` first. Idempotent when called again with the same widget. Unregisters automatically on `destroy()`.
Parameters:
Name Type Description
configurationWidget OSDPaperjsAnnotation.ConfigurationWidget
Source:

setGlobalVisibility(showopt)

Set the global visibility of the toolkit.
Parameters:
Name Type Attributes Default Description
show boolean <optional>
 false Whether to show or hide the toolkit.
Source:

toGeoJSON(optionsopt) → {Array.<Object>}

Convert the feature collections in the toolkit to GeoJSON objects.
Parameters:
Name Type Attributes Description
options Object <optional>
Properties
Name Type Attributes Description
layer Layer <optional>
 The specific layer to use
Source:
Returns:
The array of GeoJSON objects representing feature collections.
Type
Array.<Object>

toGeoJSONString(replaceropt, spaceopt) → {string}

Convert the feature collections in the project to a JSON string.
Parameters:
Name Type Attributes Description
replacer function <optional>
 The replacer function for JSON.stringify().
space number | string <optional>
 The space argument for JSON.stringify().
Source:
Returns:
The JSON string representing the feature collections.
Type
string

(static) registerFeature(item)

Register an item as a GeoJSONFeature that the toolkit should track
Parameters:
Name Type Description
item paper.Item The item to track as a geoJSONFeature
Source:

(static) registerFeatureCollection(group)

Register a group as a GeoJSONFeatureCollection that the toolkit should track
Parameters:
Name Type Description
group paper.Group The group to track as a geoJSONFeatureCollection
Source: