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 { useMemo } from 'react';
import {
  Annotorious,
  OpenSeadragonAnnotator,
  OpenSeadragonViewer
} from '@annotorious/react';

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

export default function App() {

  // IMPORTANT! Memo-ize your options to avoid
  // unexpected re-renders of the OSD viewer.
  const options = useMemo(() => ({
    tileSources: {
      type: 'image',
      url: '/images/sample-image.jpg'
    }
  }), []);

  return (
    <Annotorious>
      <OpenSeadragonAnnotator>
        <OpenSeadragonViewer options={options} />
      </OpenSeadragonAnnotator>
    </Annotorious>
  );
}

Step-by-Step Guide

1. Import the Annotorious, OpenSeadragonViewer and OpenSeadragonAnnotator components.

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

2. Import Annotorious base CSS styles.

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

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

4. Important: make sure to memo-ize your OpenSeadragon options to prevent unexpected re-renders of the OSD viewer component!

   App.tsx

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

   MyAnnotatableViewer.tsx

   export const MyAnnotatableViewer = () => {
   
     // You can use Annotorious hooks here!
     const annotations = useAnnotations();
   
     // ...
   
     // IMPORTANT! Memo-ize your options to avoid
     // unexpected re-renders of the OSD viewer.
     const options = useMemo(() => ({
      tileSources: {
        type: 'image',
        url: '/images/sample-image.jpg'
      }
     }), []);
   
     return (
       <OpenSeadragonAnnotator>
         <OpenSeadragonViewer options={options} />
       </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>

Read more about the Annotorious Data Format, the W3C Format and the differences here.