An annotation framework for React and Svelte
npm install annota
A high-performance React annotation framework for large-scale images, built on OpenSeadragon and PixiJS.
Annota is designed for applications that need to handle thousands of annotations on large, zoomable images. While it excels at whole slide imaging and digital pathology workflows, it's versatile enough for any domain requiring image annotation at scale.
- ⚡ High Performance - Hardware-accelerated PixiJS rendering with viewport culling for smooth 60 FPS with 10,000+ annotations
- 🎨 Rich Annotation Tools - Points, rectangles, polygons, contour detection, and vertex editing
- 🔌 Event-Driven Architecture - Comprehensive event system for the annotation lifecycle
- 📦 Multi-Layer Organization - Independent visibility, opacity, and locking controls
- 💾 Flexible Data Loading - Built-in loaders for H5, JSON, and PGM formats
- ⚛️ React First - Modern hooks API with TypeScript support
``bash
npm install annotaModern package managers (npm 7+, pnpm) automatically install peer dependencies
Quick Start
`tsx
import { AnnotaProvider, AnnotaViewer, Annotator } from 'annota';
import { useState } from 'react';
import 'annota/dist/index.css';function App() {
const [viewer, setViewer] = useState(null);
return (
options={{
tileSources: '/path/to/image.dzi',
prefixUrl: 'https://cdn.jsdelivr.net/npm/openseadragon@4/build/openseadragon/images/',
}}
onViewerReady={setViewer}
/>
);
}
`For more examples including tools, event handling, and layer management, see the documentation.
Performance
Annota is optimized for large-scale annotation workflows:
- Viewport Culling - Only renders visible annotations
- Level of Detail - Adaptive rendering based on zoom level
- Smart Caching - Graphics re-rendered only when necessary
- R-tree Indexing - Fast spatial queries in O(log n) time
- Hardware Acceleration - WebGL rendering for 60 FPS performance
Benchmark: Smooth interaction with 10,000+ annotations at 60 FPS.
Core APIs
$3
`typescript
useAnnotator() // Access annotator instance
useAnnotations() // Get all annotations
useSelection() // Access selected annotations
useTool(options) // Activate annotation tool
useLayerManager() // Control layers
`$3
- PointTool - Create point markers
- RectangleTool - Draw rectangular regions
- PolygonTool - Freeform polygons with vertex editing
- ContourTool - Automated contour detection
- PushTool - Interactive vertex manipulation
$3
-
loadH5Masks - Load polygon masks from HDF5
- loadH5Coordinates - Load point coordinates from HDF5
- loadJSON - Load annotations from JSON
- loadPGM - Load mask data from PGM imagesUse Cases
- Digital Pathology & whole slide imaging
- Medical imaging analysis
- AI/ML training dataset creation
- Geospatial & satellite imagery
- High-resolution document analysis
- Quality control & defect tracking
Browser Support
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
Requires WebGL support for hardware-accelerated rendering.
Documentation
- Documentation - https://annota.dev
- API - Complete API Docs
- Examples - Interactive Examples
Contributing
See CONTRIBUTING.md for development setup, code style, and PR guidelines.
For publishing releases, see PUBLISHING.md.
$3
When developing the library and testing changes in the documentation site locally:
`bash
In the docs directory
cd docs
pnpm link ../
`This creates a direct symlink from your local library source to the docs project. Any changes you make to the library will be available in the docs after rebuilding the library with
pnpm build or pnpm dev.To switch back to the npm version:
`bash
cd docs
pnpm install --force
`Note: The docs project uses the npm version (
^0.7.9`) in production deployments. The symlink setup is only for local development.MIT
Built with OpenSeadragon, PixiJS, RBush, and React.