Annotation Tools

Annota provides a comprehensive set of tools for creating and editing annotations.

Overview

Tools enable users to interact with the image and create annotations. Each tool implements a specific interaction pattern:

Tool	Purpose	Interaction
PointTool	Create point markers	Single click
RectangleTool	Draw rectangles	Click and drag
PolygonTool	Draw polygons	Click vertices, double-click to finish
PushTool	Edit polygon vertices	Click and drag to push/pull vertices
ContourTool	Extract contours from masks	Click to detect contours
SplitTool	Cut annotations into pieces	Click start point, click end point

Using Tools

Basic Usage

Activate a tool using the useTool hook:

import { useTool, PointTool } from "annota";

function MyComponent({ viewer }) {
  const pointTool = new PointTool();

  useTool({
    viewer,
    handler: pointTool,
    enabled: true,
  });

  return null;
}

Tool Switching

Allow users to switch between tools:

import { useTool, PointTool, RectangleTool, PolygonTool } from "annota";
import { useState } from "react";

function ToolController({ viewer }) {
  const [activeTool, setActiveTool] = useState("point");

  const tools = {
    point: new PointTool(),
    rectangle: new RectangleTool(),
    polygon: new PolygonTool(),
  };

  useTool({
    viewer,
    handler: activeTool === "pan" ? null : tools[activeTool],
    enabled: activeTool !== "pan",
  });

  return (
    <div>
      <button onClick={() => setActiveTool("pan")}>Pan</button>
      <button onClick={() => setActiveTool("point")}>Point</button>
      <button onClick={() => setActiveTool("rectangle")}>Rectangle</button>
      <button onClick={() => setActiveTool("polygon")}>Polygon</button>
    </div>
  );
}

Point Tool

Create point annotations with a single click.

Use Cases

• Cell counting
• Nuclei detection
• Marking points of interest
• Landmarks for registration

Interaction

Single click to place a point marker at that location.

import { PointTool } from "annota";

const pointTool = new PointTool({
  style: {
    fill: "#FF0000",
    fillOpacity: 0.8,
    stroke: "#FFFFFF",
    strokeWidth: 2,
  },
});

Rectangle Tool

Draw rectangular regions by clicking and dragging.

Interaction:

1. Click to start the rectangle
2. Drag to define the size
3. Release to finish

import { RectangleTool } from "annota";

const rectangleTool = new RectangleTool({
  style: {
    fill: "#00FF00",
    fillOpacity: 0.3,
    stroke: "#00FF00",
    strokeWidth: 2,
  },
});

Polygon Tool

Draw polygons by clicking to add vertices.

Interaction:

1. Click to add vertices
2. Move mouse to preview next segment
3. Double-click or press Enter to finish
4. Press Escape to cancel

import { PolygonTool } from "annota";

const polygonTool = new PolygonTool({
  style: {
    fill: "#0000FF",
    fillOpacity: 0.3,
    stroke: "#0000FF",
    strokeWidth: 2,
  },
});

Push Tool

Edit polygon vertices by pushing and pulling.

import { PushTool } from "annota";

const pushTool = new PushTool({
  radius: 50,      // Influence radius in pixels
  strength: 1.0,   // Strength of the push effect (0-1)
  showCursor: true, // Show the cursor indicator
});

Interaction:

1. Click and drag on or near polygon edges
2. Vertices within the radius are pushed
3. Effect falls off with distance from cursor

Tip

Use the usePushToolCursor hook to display a visual indicator showing the push tool’s radius.

Split Tool

Cut annotations into multiple pieces with a line.

import { SplitTool } from "annota";

const splitTool = new SplitTool();

Workflow:

1. Select an annotation (before or during tool activation)
2. Activate the split tool
3. Click to set the start point of the split line
4. Move mouse — an orange line preview follows the cursor
5. Click to set the end point and execute the split

Note

The split tool provides visual feedback with an orange line (color: #ff6b00) showing where the split will occur.

Merge Operation

Combine multiple selected annotations into a single annotation:

import { useAnnotator } from "annota";

function MergeButton() {
  const annotator = useAnnotator();

  const handleMerge = () => {
    const merged = annotator.mergeSelected();
    if (merged) {
      console.log("Successfully merged annotations");
    }
  };

  return <button onClick={handleMerge}>Merge Selected</button>;
}

Contour Tool

Automatically detect contours from underlying image data.

import { ContourTool, loadOpenCV } from "annota";

// Load OpenCV before using ContourTool
await loadOpenCV();

const contourTool = new ContourTool({
  threshold: 128,    // Threshold for binary mask
  minArea: 100,      // Minimum contour area
  maxContours: 1000, // Maximum number of contours
});

Caution

The Contour Tool requires OpenCV.js. Install it with npm install @techstark/opencv-js.

Tool Options

All tools support these common options:

Style

const tool = new PointTool({
  style: {
    fill: "#FF0000",
    fillOpacity: 0.8,
    stroke: "#FFFFFF",
    strokeWidth: 2,
  },
});

Layer Assignment

const tool = new PointTool({
  layer: "tumor", // Annotations will be created on the 'tumor' layer
});

Custom Properties

const tool = new PointTool({
  properties: {
    type: "cell",
    confidence: 1.0,
  },
});

Best Practices

Reuse Instances

Create tool instances once, not on every render.

const [tools] = useState({
  point: new PointTool(),
  rectangle: new RectangleTool(),
});

Visual Feedback

Show which tool is active with UI highlighting.

Allow Deactivation

Always provide a way to disable tools (e.g., “Pan” mode).

Keyboard Shortcuts

Add keyboard shortcuts for common tools (P, R, G, V).

Next Steps

• Events — Respond to annotation changes
• Styling — Customize annotation appearance
• Layer System — Organize annotations