Skip to content
osdlabel

Quick Start

This guide walks you through setting up a minimal annotation interface with osdlabel.

1. Define your images

Section titled “1. Define your images”

Create an array of ImageSource objects. Each image needs a unique branded ID and a URL (DZI or standard image).

import { createImageId } from '@osdlabel/annotation';
import type { ImageSource } from '@osdlabel/viewer-api';


const images: ImageSource[] = [
  {
    id: createImageId('sample-1'),
    tileSource: 'https://openseadragon.github.io/example-images/highsmith/highsmith.dzi',
    label: 'Highsmith',
  },
  {
    id: createImageId('sample-2'),
    tileSource: 'https://openseadragon.github.io/example-images/duomo/duomo.dzi',
    label: 'Duomo',
  },
];

2. Define annotation contexts

Section titled “2. Define annotation contexts”

Contexts define which tools are available and their constraints. Each context represents a labelling task (e.g., marking a specific pathology).

import { createAnnotationContextId } from '@osdlabel/annotation-context';
import type { AnnotationContext } from '@osdlabel/annotation-context';


const contexts: AnnotationContext[] = [
  {
    id: createAnnotationContextId('default'),
    label: 'Default',
    tools: [
      { type: 'rectangle' },
      { type: 'circle' },
      { type: 'line' },
      { type: 'point' },
      { type: 'polyline' },
      { type: 'freeHandPath' },
    ],
  },
];

3. Render the Annotator

Section titled “3. Render the Annotator”

The Annotator component provides a complete annotation interface with toolbar, grid view, filmstrip, and status bar.

import { render } from 'solid-js/web';
import { Annotator } from 'osdlabel/components';
import { initFabricModule } from 'osdlabel';


initFabricModule();


function App() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <Annotator
        images={images}
        contexts={contexts}
        filmstripPosition="left"
        maxGridSize={{ columns: 4, rows: 4 }}
        showGridControls
        showFilmstrip
        showViewControls
        showFps
        onAnnotationsChange={(annotations) => {
          console.log('Annotations:', annotations.length);
        }}
      />
    </div>
  );
}


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

4. What you get

Section titled “4. What you get”

The Annotator component provides a standard layout using the following built-in components:

  • Toolbar — Tool selector that respects context constraints, showing which tools are available and their usage counts
  • Grid View — One or more image viewers in a configurable grid
  • Filmstrip — Sidebar for assigning images to grid cells
  • Status Bar — Shows the active context, tool, and annotation count
  • Grid Controls — Optional visual selector for resizing the grid (Table Selector)
  • Context Switcher — Optional dropdown for switching between different annotation tasks

All these components are also available individually for building custom layouts with AnnotatorProvider.

5. Interact with annotations

Section titled “5. Interact with annotations”

Click on a drawing tool in the toolbar (or press a keyboard shortcut like r for rectangle), then draw on the image. Annotations can be selected, moved, resized, and rotated after creation.

Use Ctrl/Cmd + drag to pan, and Ctrl/Cmd + scroll to zoom while in annotation mode.

Next steps

Section titled “Next steps”