React OpenSeadragon and IIIF

Use Annotorious together with OpenSeadragon to annotate high-resolution zoomable images with React, including images served via the International Image Interoperability Framework (IIIF) standard.

import {
  Annotorious,
  OpenSeadragonAnnotator,
  OpenSeadragonViewer
} from '@annotorious/react';

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

export default function App() {
  return (
    <Annotorious>
      <OpenSeadragonAnnotator>
        <OpenSeadragonViewer options={{
          tileSources: {
            type: 'image',
            url: '/images/sample-image.jpg'
          }
        }} />
      </OpenSeadragonAnnotator>
    </Annotorious>
  );
}

Step-by-Step Guide

Import the Annotorious, OpenSeadragonViewer and OpenSeadragonAnnotator components.

import { Annotorious, OpenSeadragonAnnotator, OpenSeadragonViewer } from '@annotorious/react';

Import Annotorious base CSS styles.

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

Important: wrap your application with the <Annotatorious> root context tag - other Annotorious components depend on it. You can use Annotorious-provided hooks anywhere below the context tag.

App.tsx
MyAnnotatableViewer.tsx

export default function App() {
  return (
    <Annotorious>
      <MyAnnotatableViewer />
    </Annotorious>
  );
}

export const MyAnnotatableViewer = () => {

  // You can use Annotorious hooks here!
  const annotations = useAnnotations();

  // ...

  return (
    <OpenSeadragonAnnotator>
      <OpenSeadragonViewer options={{
        tileSources: {
          type: 'image',
          url: '/images/sample-image.jpg'
        }
      }} />
    </OpenSeadragonAnnotator>
  );
}

Styling

You can apply custom styling to annotations via the style prop. The style can be:

A DrawingStyle object.
A function that receives the ImageAnnotation and the AnnotationState as an input, and returns a DrawingStyle.

const style = (annotation: ImageAnnotation, state: AnnotationState) => ({
  fill: state.hovered ? '#ff0000' : '#ffffff',
  fillOpacity: 0.25
});

<OpenSeadragonAnnotator style={style}>
  <OpenSeadragonViewer options={OSD_OPTS} />
</OpenSeadragonAnnotator>

Filters

Using a filter, you can dynamically control the visibility of specific annotations, based on their data or external criteria. The filter is a function that receives the ImageAnnotation as an input, and returns a boolean. true makes the annotation visible, false hides it.

const showImportantFilter = (annotation: Annotation) => {
  // Show only if the annotation has an 'important' tag
  return annotation.bodies.some(b => b.purpose === 'tagging' && b.value === 'important');
};

<OpenSeadragonAnnotator filter={showImportantFilter}>
  <OpenSeadragonViewer options={OSD_OPTS} />
</OpenSeadragonAnnotator>;

Selection Behavior

When a user selects an annotation by click or tap, the default behavior is that the shape will become editable. You can change this behavior through the userSelectAction prop. The prop accepts:

a UserSelectAction object.
a function that receives an ImageAnnotation as input, and returns a UserSelectAction.

A UserSelectAction has one of the three following values.

EDIT: makes the annotation editable, allowing the users to modify its shape (default).
SELECT: clicking an annotation triggers the relevant selection event, but the annotation will not become editable.
NONE: the annotation is inert. Clicking or tapping it has no effect.

import { UserSelectAction } from '@annotorious/react';

// Make all annotations 'read-only'.
<OpenSeadragonAnnotator userSelectAction={UserSelectAction.SELECT}>
  <OpenSeadragonViewer options={OSD_OPTS} />
</OpenSeadragonAnnotator>

// Function: only allow editing on my own annotation.
const allowEditingMyOwn = (annotation: ImageAnnotation) => {
  const isMine = annotation.target.creator.id == 'me';
  return isMine ? UserSelectAction.EDIT : UserSelectAction.SELECT;
};

<OpenSeadragonAnnotator userSelectAction={allowEditingMyOwn}>
  <OpenSeadragonViewer options={OSD_OPTS} />
</OpenSeadragonAnnotator>

W3C Format Adapter

A FormatAdapter adds support for different annotation data formats, by introducing crosswalk functionality between Annotorious’ internal annotation data model and other standards.

You can supply a format adapter through the optional adapter prop. Currently, the only available adapter is for the W3C Web Annotation Data Model.

import {
  Annotorious,
  OpenSeadragonAnnotator,
  OpenSeadragonViewer,
   W3CImageFormat
} from '@annotorious/react';

<Annotorious>
  <OpenSeadragonAnnotator adapter={W3CImageFormat('example.jpg')}>
    <OpenSeadragonViewer options={OSD_OPTS} />
  </OpenSeadragonAnnotator>
</Annotorious>