OpenSeadragon and IIIF

This guide explains how to use Annotorious together with OpenSeadragon to annotate high-resolution zoomable images, including images served via International Image Interoperability Framework (IIIF) standard.

Quick Start

Here’s a basic example to get you started. The code below creates an OpenSeadragon viewer, initializes Annotorious on the viewer, attaches an event listener, and loads annotations from a file.

import OpenSeadragon from 'openseadragon';
import { createOSDAnnotator } from '@annotorious/openseadragon';

// Import essential CSS styles
import '@annotorious/openseadragon/annotorious-openseadragon.css';

// Initialize OpenSeadragon viewer
const viewer = OpenSeadragon({
  element: document.getElementById('my-openseadragon-container'),
  tileSources: {
    type: 'image',
    url: '/images/sample-image.jpg'
  }
});

// Initialize annotator
const anno = createOSDAnnotator(viewer);

// Attach listeners to handle annotation events
anno.on('createAnnotation', function(annotation) {
  console.log('created', annotation);
});

// Load annotations from a JSON file
anno.loadAnnotations('./annotations.json');

Step-by-Step Guide

In your JavaScript file, import OpenSeadragon from the openseadragon package, and createOSDAnnotator from the Annotorious OpenSeadragon plugin package.
```
import OpenSeadragon from 'openseadragon';
import { createOSDAnnotator } from '@annotorious/openseadragon';
```

Important: import the Annotorious CSS stylesheet.

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

Create an OpenSeadragon viewer instance in an existing DIV element. Full documentation is on the OpenSeadragon project website.

const viewer = OpenSeadragon({
  element: document.getElementById('my-openseadragon-container'),
  tileSources: {
    type: 'image',
    url: '/images/sample-image.jpg'
  }
};

Create an annotator instance on the viewer.

const anno = createOSDAnnotator(viewer);

Optional: you can pass options to customize the annotator.

const anno = createOSDAnnotator(viewer, {
  drawingEnabled: true,
  style: {
   fill: '#ff0000',
   fillOpacity: 0.25
  }
});

Handle events. Read more about lifecycle events.

anno.on('createAnnotation', (annotation) => {
  console.log('Annotation created:', annotation);
});

anno.on('updateAnnotation', (annotation, previous) => {
  console.log('Annotation updated:', annotation);
});

anno.on('deleteAnnotation', (annotation) => {
  console.log('Annotation deleted:', annotation);
});

Load existing annotations. Read more about the data model on the next page. Note that annotation coordinates are relative to the base resolution of the image.
```
anno.loadAnnotations('./annotations.json');
```

IIIF Example

You can use Annotorious and OpenSeadragon to annotate IIIF images.

const viewer = OpenSeadragon({
  element: document.getElementById('my-openseadragon-container'),
  tileSources: {
    '@context': 'http://iiif.io/api/image/2/context.json',
    '@id': 'https://libimages1.princeton.edu/loris/pudl0001%2F4609321%2Fs42%2F00000001.jp2',
    height: 7200,
    width: 5233,
    profile: [ 'http://iiif.io/api/image/2/level2.json' ],
    protocol": 'http://iiif.io/api/image',
    tiles: [{
      scaleFactors: [ 1, 2, 4, 8, 16, 32 ],
      width: 1024
    }
  }
});

Alternatively, you can provide the link to the IIIF image info.json URL.

const viewer = OpenSeadragon({
  element: document.getElementById('my-openseadragon-container'),
  tileSources: https://iiif.princeton.edu/loris/pudl0001%2F4609321%2Fs42%2F00000001.jp2/info.json
});

For more information, see OpenSeadragon IIIF documentation.

Script Import

If you are not using a build system, you can include Annotorious via CDN. The createOSDAnnotator function is available under the global AnnotoriousOSD object.

<html>
  <head>
    <script src="https://cdn.jsdelivr.net/npm/openseadragon@latest/build/openseadragon/openseadragon.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/@annotorious/openseadragon@latest/dist/annotorious-openseadragon.js"></script>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@annotorious/openseadragon@latest/dist/annotorious-openseadragon.css">
  </head>
  <body>
    <div
    <script>
      window.onload = function() {
        var viewer = OpenSeadragon({
          element: document.getElementById('my-openseadragon-container'),
          tileSources: {
            type: 'image',
            url: '/images/sample-image.jpg'
          }
        };

        var anno = AnnotoriousOSD.createOSDAnnotator(viewer);
      }
    </script>
  </body>
</html>