Skip to content

README.md

Latest commit

 

History

History
149 lines (112 loc) · 4.26 KB

README.md

File metadata and controls

149 lines (112 loc) · 4.26 KB

Annotorious Arrows Plugin

Annotorious Arrow Plugin demo video

An Annotorious plugin for drawing arrows. Arrows can be independent annotations, or they can be linked to existing shapes — either on both ends, or on one end only (start or tip). When linked, the relationships are represented in the data model.

Also available: React wrapper

Installation

npm install @annotorious/plugin-arrows

Usage

With Images (JPEG, PNG)

import { createImageAnnotator } from '@annotorious/annotorious';
import { mountImagePlugin } from '@annotorious/plugin-arrows';

const anno = createImageAnnotator('sample-image');

const arrowsPlugin = mountImagePlugin(anno, {
  // Plugin options (see below)
});

With OpenSeadragon

import { createOSDAnnotator } from '@annotorious/openseadragon';
import { mountOSDPlugin } from '@annotorious/plugin-arrows';

const viewer = OpenSeadragon({
  // OSD init options
});

const anno = createOSDAnnotator(viewer, {
  // Annotorious init options
});

const arrowsPlugin = mountOSDPlugin(anno, viewer, {
  // Plugin options (see below)
});

Usage

Once installed, the plugin integrates seamlessly with the Annotorious lifecycle. Arrow annotations trigger the same events as other annotations:

  • createAnnotation
  • updateAnnotation
  • deleteAnnotation
  • selectionChanged
  • mouseEnterAnnotation
  • mouseLeaveAnnotation

Note

clickAnnotation and viewportIntersect are currently not supported for arrows.

By default, the plugin starts enabled and in select mode:

  • You can interact with all annotations normally (regular shapes and arrows).
  • Clicking an arrow selects it, allowing the user to move it or adjust the start/tip.

To let users draw arrows, switch to draw mode:

arrowsPlugin.setMode('draw');

Users can then:

  • Click once for the start and once for the end point, or
  • Click and drag from start to end.

Plugin Options

Option Type Description
showArrows ArrowsVisibility Controls when arrows are visible

ArrowsVisibility can be one of the following:

  • ALWAYS – all arrows are visible.
  • HOVER_ONLY – arrows appear only when hovering over a connected shape annotation.
  • SELECTED_ONLY – arrows appear only when a connected annotation is selected.
  • HOVER_OR_SELECT – arrows appear when hovering over or selecting a connected annotation.

Plugin API

Method Parameters Description
setEnabled(enabled: boolean) true/false Enables or disables the plugin (arrows remain visible)
`setMode(mode: 'draw' 'select')` –
setVisibility(visibility: ArrowsVisibility) –   Changes arrow visibility.
unmount() – Cleans up and destroys the plugin instance.

Data Model

Arrow annotations differ from standard Annotorious shapes in two ways:

  • They have a motivation field with the value pointing.
  • Their target represents the arrow start and end anchors.

An arrow can be independent, with explicit start/end coordinates, or linked to existing annotations.

Example: independent (unlinked) arrow

{
  "id": "aab6d162-0156-461e-b3cd-704ee5061d89",
  "motivation": "pointing",
  "bodies": [],
  "target": {
    "created": "2025-10-20T13:16:56.486Z",
    "selector": {
      "start": { "x": 37.4, "y": 176.6 },
      "end": { "x": 120.3, "y": 80.1 }
    }
  }
}

Example: arrow linked at both ends

{
  "id": "daf0e68a-002b-44fd-9b9c-6c984c992742",
  "motivation": "pointing",
  "bodies": [],
  "target": {
    "created": "2025-10-20T13:18:26.019Z",
    "selector": {
      "start": {
        "annotationId": "617d04b3-1f49-4b65-b684-5e64d90f10be",
        "offset": { "x": -2, "y": 108.8 }
      },
      "end": {
        "annotationId": "e4309c1c-7481-4554-88a3-9ae42166ea5e",
        "offset": { "x": -13, "y": 0.1 }
      }
    }
  }
}

Linked anchors (start or end) reference other annotations by ID. The offset represents the X/Y offset from the center of the linked shape's bounding box, rather than absolute image coordinates.

License

BSD-3-Clause