osdlabel

Web-based image annotation library with rich drawing controls, customizable annotation contexts, and built-in serialization.

Powered by OpenSeaDragon for deep zoom tiled image support and Fabric.js v7 for interactive canvas rendering, with official UI bindings for SolidJS and React. Draw rectangles, circles, lines, points, and freehand paths on gigapixel images with smooth pan and zoom.

Features

• Deep Zoom support — annotate gigapixel images served as DZI tiles, or plain image files
• Multi-image grid — view and annotate up to 16 images simultaneously in a configurable grid layout
• Annotation tools — rectangle, circle, line, point, polyline/polygon, and freehand path drawing
• Vertex editing — long-press a polygon or polyline to move, insert, and delete individual vertices
• Geometry conversion — convert a selected circle to its bounding rectangle
• Context system — define multiple annotation contexts with per-tool constraints (max count, count scope)
• Decorations & measurements — derived text labels, calibrated area/length/perimeter measurements, and connector lines via composable DecorationProvider functions, recomputed at render time (never serialized)
• View controls — per-cell rotate, flip, and tonal adjustment (exposure, contrast, invert) with overlay annotations following in lockstep
• Drag-driven controls — a customControl overlay mode that routes raw pointer input to your own handler, used by the built-in two-axis exposure/contrast gesture
• Serialization — export and import annotations as JSON with a versioned document format
• Keyboard shortcuts — fully configurable hotkeys for tools, grid navigation, and drawing actions
• Framework-agnostic core — annotation model, serialization, and constraint logic have zero UI framework dependencies
• SolidJS and React — first-class bindings for both frameworks with identical APIs
• Tree-shakeable — ESM sub-path exports let you import only what you need

Installation

SolidJS

npm install @osdlabel/solid

@osdlabel/solid on npm

React

npm install @osdlabel/react

@osdlabel/react on npm

Quick Start

SolidJS

import { render } from 'solid-js/web';
import { Annotator, createImageId, createAnnotationContextId } from '@osdlabel/solid';
import type { ImageSource, AnnotationContext } from '@osdlabel/solid';

const images: ImageSource[] = [
  {
    id: createImageId('slide-1'),
    tileSource: 'https://example.com/slides/slide-1.dzi',
    label: 'Slide 1',
  },
];

const contexts: AnnotationContext[] = [
  {
    id: createAnnotationContextId('review'),
    label: 'Review',
    tools: [
      { type: 'rectangle', maxCount: 5, countScope: 'per-image' },
      { type: 'circle' },
      { type: 'point' },
    ],
  },
];

function App() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <Annotator
        images={images}
        contexts={contexts}
        showFilmstrip={true}
        showGridControls={true}
        showContextSwitcher={true}
        onAnnotationsChange={(annotations) => console.log(annotations)}
      />
    </div>
  );
}

render(() => <App />, document.getElementById('app')!);

React

import { createRoot } from 'react-dom/client';
import { Annotator, createImageId, createAnnotationContextId } from '@osdlabel/react';
import type { ImageSource, AnnotationContext } from '@osdlabel/react';

// images and contexts defined the same way as above

function App() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <Annotator
        images={images}
        contexts={contexts}
        showFilmstrip={true}
        showGridControls={true}
        showContextSwitcher={true}
        onAnnotationsChange={(annotations) => console.log(annotations)}
      />
    </div>
  );
}

createRoot(document.getElementById('app')!).render(<App />);

The viewer registers the Fabric id custom property automatically when it mounts, so there is no setup call to remember. initFabricModule() is still exported and idempotent for advanced setups that build Fabric objects before any viewer exists.

Composable API

For more control, use the individual components and provider directly:

// SolidJS — the same names are exported from '@osdlabel/react'
import {
  AnnotatorProvider,
  useAnnotator,
  Toolbar,
  StatusBar,
  GridView,
  Filmstrip,
  GridControls,
  ContextSwitcher,
  ViewControls,
  serialize,
  deserialize,
} from '@osdlabel/solid';

Wrap your UI in <AnnotatorProvider>, call useAnnotator() for access to state and actions, then compose Toolbar, GridView, Filmstrip, StatusBar, GridControls, ContextSwitcher, and ViewControls however you like.

Direct Package Imports

Import everything from the single umbrella package you already depend on (@osdlabel/solid, @osdlabel/react, or osdlabel). Types such as ImageId, AnnotationId, and ImageSource physically live in lower-level subpackages, so importing them from those paths only resolves when the subpackage is a direct dependency of your app. The umbrella re-exports them all.

Reach for the granular packages only when building a custom UI layer, and add them as explicit dependencies:

import type { Annotation, Geometry } from '@osdlabel/annotation';
import type { ImageSource } from '@osdlabel/viewer-api';
import type { AnnotationContext } from '@osdlabel/annotation-context';
import { serialize, deserialize, applyAnnotationAction } from 'osdlabel';

This is the beginning of the README. Read the rest at the original. Read the full README ↗