Annotorious Boolean Operations

Adds functionality to merge and subtract annotation shapes.

Important: This plugin currently only supports @annotorious/openseadragon. Support for plain (JPEG, PNG,...) images is not yet implemented. Join the discussion if you'd like to use this with @annotorious/annotorious or @annotorious/react.

Installation

npm install @annotorious/plugin-boolean-operations

Usage with OpenSeadragon

import OpenSeadragon from 'openseadragon';
import { createOSDAnnotator } from '@annotorious/openseadragon';
import { mountPlugin as mountBooleanPlugin  } from '@annotorious/plugin-boolean-operations';

import '@annotorious/openseadragon/annotorious-openseadragon.css';

/**
 * Important: the plugin requires multi-select to be enabled!
 */
const viewer = OpenSeadragon({
  /** Your viewer config **/
  multiSelect: true
});

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

// Initialize the plugin
const plugin = mountBooleanPlugin(anno);

// Merge example
document.getElementById('merge').addEventListener('click', () => {
  plugin.mergeSelected();
});

// Subtract example
document.getElementById('subtract').addEventListener('click', () => {
  plugin.subtractSelected();
});

API

| Method | Description | |--------|-------------| | canSubtractSelected() | Checks if the current selection allows subtraction (without producing an empty shape). | | mergeSelected(opts?: MergeOptions) | Merges all currently selected annotations. Accepts MergeOptions to control how annotation bodies are handled. | | subtractSelected() | Keeps the first selected annotation, clipping its geometry by subtracting all others. All other selected annotations are deleted. Selection order matters. |

MergeOptions

mergeSelected can be customized with a MergeOptions object that controls how annotation bodies are preserved in the merged shape.

You can either choose one of the built-in strategies or provide your own explicit override.

Built-in Strategies

• { strategy: 'merge_bodies' } (default). Combine bodies from all selected shapes into the merged annotation, in the order of selection.
• { strategy: 'keep_first_bodies' }. Keep only the bodies from the first selected annotation, discard all others.

Custom Merge

You can override the merge behavior by passing:

• An explicit array of AnnotationBody objects to keep.
• A function that receives the selected annotations and returns the bodies to keep.

// Keep specific bodies
plugin.mergeSelected({
  bodies: [myBody1, myBody2]
});

// Decide dynamically from the selection
plugin.mergeSelected({
  bodies: selected => selected.flatMap(a => a.bodies.filter(b => b.purpose === 'tagging'))
});