Getting Started with the OpenSeadragon Plugin

The Annotorious OpenSeadragon plugin is an extension to the OpenSeadragon viewer for zoomable high-resolution images. Click or tap the annotation to edit. Hold the SHIFT key while clicking and dragging the mouse to create a new annotation.

Download the latest release and include script and stylesheet file in your web page. Make sure to include the script after the OpenSeadragon script.

Important! Annotorious version 2.7.x strictly requires OpenSeadragon 3.0 or higher. For compatibility with OpenSeadragon v2.4 and below, please use Annotorious 2.6.x.

<!-- CSS stylesheet -->
<link rel="stylesheet" href="annotorious.min.css">

<!-- JS -->
<script src="openseadragon/openseadragon.3.0.0.min.js"></script>
<script src="openseadragon-annotorious.min.js"></script>

Alternatively, grab the files from CDN.

<!-- CSS stylesheet -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@recogito/annotorious-openseadragon@2.7.14/dist/annotorious.min.css">

<!-- JS -->
<script src="https://cdn.jsdelivr.net/npm/@recogito/annotorious-openseadragon@2.7.14/dist/openseadragon-annotorious.min.js"></script>

Important! You must include the stylesheet in the <head> of your page. If you include it anywhere in your <body>, Annotorious will not work when switching OpenSeadragon to fullscreen mode.

Create the viewer and initialize the Annotorious plugin.

<script>
  window.onload = function() {
    var viewer = OpenSeadragon({
      id: "openseadragon1",
      tileSources: {
        type: "image",
        url: "1280px-Hallstatt.jpg"
      }
    });

    // Initialize the Annotorious plugin
    var anno = OpenSeadragon.Annotorious(viewer);

    // Load annotations in W3C WebAnnotation format
    anno.loadAnnotations('annotations.w3c.json');
  }
</script>

The plugin takes a config object as optional second argument. See the API Reference for details.

var anno = OpenSeadragon.Annotorious(viewer, config);

Using NPM

If you use npm, npm install @recogito/annotorious-openseadragon and then

import OpenSeadragon from 'openseadragon';
import * as Annotorious from '@recogito/annotorious-openseadragon';

import '@recogito/annotorious-openseadragon/dist/annotorious.min.css';

const viewer = OpenSeadragon({
  id: "openseadragon",
  tileSources: {
    type: "image",
    url: "1280px-Hallstatt.jpg"
  }
 });

const config = {}; // Optional plugin config options

Annotorious(viewer, config);

A Note on Fullscreen Mode

If you experience the problem that annotations don’t appear in OpenSeadragon fullscreen mode: please make sure that you include the Annotorious stylesheet file (annotorious.min.css) in the <head> of your document!

Reason: when switching to fullscreen mode, OpenSeadragon temporarily removes all content from the page body, and replaces it with the viewer element. If you include the Annotorious stylesheet somewhere inside the body, it will get removed from the page in fullscreen mode, causing annotations to disappear. ALWAYS add the Annotorious stylesheet in the document <head>!