void} // Optional: Pointer position callback\n onZoomChange={(zoom, viewport, externalInvoke) => void} // Optional: Zoom change callback\n gridEnabled={boolean} // Optional: Show grid (default: true)\n gridScale={number} // Optional: Grid zoom threshold (default: 6)\n gridLine={{ stroke?: string; strokeWidth: number }} // Optional: Grid style (default: white, 0.05)\n disableZoom={boolean} // Optional: Disable zoom (default: false)\n blobColors={Array<{r, g, b}>} // Optional: Colors for blob detection\n boundingBoxes={RectConfig[]} // Optional: Additional overlay boxes\n/>\n```\n\n### ImageCacheProvider\n\nManages tile caching for downloaded raster layers. **Required** when using downloaded raster layers with tiling.\n\n```tsx\n\n {/* Your LayersProvider and AnnotationCanvas */}\n\n```\n\n---\n\n### ToolProvider\n\nProvides drawing tool context.\n\n```tsx\nimport { Tool, BrushShape, useTool } from 'annotation-canvas';\n\nfunction Toolbar() {\n const {\n selectedTool, // Currently selected tool\n setSelectedTool, // Change tool\n drawColor, // Stroke/draw color (RGBA)\n setDrawColor, // Change stroke color\n fillColor, // Fill color for vector shapes (RGBA or undefined)\n setFillColor, // Change fill color\n toolSize, // Brush/tool size in pixels\n setToolSize, // Change tool size\n brushShape, // BrushShape.Circle or BrushShape.Square\n setBrushShape // Change brush shape\n } = useTool();\n\n return (\n \n \n \n \n\n {/* Set color */}\n \n\n {/* Set tool size */}\n setToolSize(parseInt(e.target.value))}\n />\n
\n );\n}\n```\n\n**Available Tools:**\n\nGeneral:\n- `Tool.Move` - Pan canvas\n- `Tool.ZoomIn` / `Tool.ZoomOut` - Zoom controls\n\nRaster:\n- `Tool.Brush` - Paint with brush\n- `Tool.Eraser` - Erase drawn content\n- `Tool.Floodfill` - Flood fill areas\n- `Tool.Clear` - Clear rectangular regions\n\nVector:\n- `Tool.Rectangle` - Draw rectangles\n- `Tool.Circle` - Draw circles\n- `Tool.Line` - Draw lines\n- `Tool.Polygon` - Draw polygons\n- `Tool.Drag` - Drag/move vector elements\n- `Tool.Edit` - Edit vector element points (polygons)\n- `Tool.Remove` - Remove vector elements\n- `Tool.ChangeFill` - Toggle fill on/off for vector elements\n\n### Layer Types and Structures\n\n```typescript\nenum LayerType {\n downloadedRaster, // Tiled images from server\n downloadedVector, // SVG shapes from server\n createdRaster, // Drawing canvas\n createdVector, // User-drawn shapes\n animated // Dynamic canvas layers\n}\n\n// Layer structure (all types share these base properties)\ninterface Layer {\n id: string | number; // Unique identifier\n type: LayerType; // Layer type\n visible: boolean; // Show/hide layer\n opacity: number; // 0.0 to 1.0\n data: LayerData; // Type-specific data\n}\n\n// Downloaded Raster Layer data\ninterface DownloadedRasterLayerData {\n getImage?: GetImage; // Optional: Function to fetch tile data\n coloring?: number[][]; // Optional: Color mapping (256x3 for heatmap, 1x3 for solid)\n threshold?: { // Optional: Threshold for grayscale\n min: number; // Min threshold (0-255)\n max: number; // Max threshold (0-255)\n };\n hatching?: { // Optional: Hatching pattern overlay\n blankWidth: number; // Width of transparent stripes\n maskWidth: number; // Width of visible stripes\n };\n}\n\n// Downloaded Vector Layer data (SVG string)\ntype DownloadedVectorLayerData = string;\n\n// Created Raster Layer data (initialized as null, canvas created internally)\ntype CreatedRasterLayerData = null;\n\n// Created Vector Layer data\ninterface CreatedVectorLayerData {\n elements: (CreatedVectorLayerLine | CreatedVectorLayerRectangle | CreatedVectorLayerCircle)[];\n layer?: Konva.Layer; // Internal reference (auto-managed)\n}\n```\n\n### useLayers Hook\n\nProvides access to layer state and operations:\n\n```tsx\nimport { useLayers } from 'annotation-canvas';\n\nfunction LayerControls() {\n const {\n // Layer state\n rasterWidth, // Canvas width\n rasterHeight, // Canvas height\n layers, // Array of all layers\n setLayers, // Update layers array\n selectedLayer, // Index of selected layer\n setSelectedLayer, // Change selected layer\n selectedLayerType, // Type of selected layer\n tiling, // Tiling configuration (if set)\n\n // Layer operations\n createLayer, // (layer: Layer) => void\n setLayerByIndex, // (index, updater) => void\n setLayerById, // (layer) => void\n removeLayer, // (index) => Promise\n removeLayerById, // (id) => void\n rasterizeLayer, // (index) => void - Convert vector to raster\n\n // History\n historyPush, // Internal use - adds history record\n undo, // Undo last action\n undoAvailable, // Can undo?\n redo, // Redo last undone action\n redoAvailable, // Can redo?\n } = useLayers();\n\n return (\n <>\n \n \n \n \n );\n}\n```\n\n### Memory Leak Testing\n\nThe library includes tools for long-term memory monitoring (validated over 40+ hours of continuous operation):\n\n```bash\n# 1. Start dev server and set memory test mode in browser console:\nlocalStorage.setItem('memoryLeakTest', 'true')\n\n# 2. Get browser process ID and run:\n./measureMemory.sh \n\n# 3. View results at http://localhost:8000\n```\n\nSee [memoryFrontend/](./memoryFrontend/) for the visualization tool.\n\n## Advanced Features\n\n### Pixel-Perfect Raster Drawing\n\nThe library implements custom **Bresenham line and circle algorithms** to achieve antialiasing-free pixel-perfect drawing. This is critical for machine learning annotations where exact pixel values matter - browser native canvas applies antialiasing that can corrupt training data.\n\n### Heatmap & Blob Detection\n\n- **Heatmap visualization**: Apply color mapping to grayscale images (e.g., neural network outputs)\n- **Blob detection**: Automatically detect and label colored regions using OpenCV.js\n- **Threshold & Hatching**: Additional visualization options for raster layers\n\n**See the [demo application](./src/App.tsx) for complete examples** of these features.\n\n## License\n\nMIT © Martin Schneider\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## Links\n\n- [GitHub Repository](https://github.com/xReav3r/annotation-canvas)\n- [npm Package](https://www.npmjs.com/package/annotation-canvas)\n- [Issue Tracker](https://github.com/xReav3r/annotation-canvas/issues)\n","readmeFilename":"README.MD"}