Basic Controls

Drawing tools

osdlabel provides six geometric annotation tools:

Tool	Shortcut	Geometry	Drawing action
Rectangle	r	Origin, width, height, rotation	Click and drag to define opposite corners
Circle	c	Center, radius	Click and drag from center outward
Line	l	Start point, end point	Click and drag between endpoints
Point	p	Single position	Single click to place
Path	d	Array of points, open/closed	Click to add vertices, Enter to finish, c to close
Free Hand Path	f	Array of sampled points	Click and drag to draw; release to commit

Drawing workflow

1. Select a drawing tool (toolbar click or keyboard shortcut)
2. The active cell switches to annotation mode — OSD navigation is disabled
3. Click/drag on the image to draw the annotation
4. The annotation is created in image-space coordinates and stored in the annotation state
5. The onAnnotationsChange callback fires with the updated annotation list

Selecting and editing

Press v (or click the select tool) to enter selection mode:

• Click an annotation to select it — shows resize handles and rotation control
• Drag a selected annotation to move it
• Drag handles to resize
• Drag rotation control (circle above the annotation) to rotate
• Escape deselects the current annotation
• Delete / Backspace deletes the selected annotation

Pan and zoom in annotation mode

While drawing or selecting, you can still navigate:

• Ctrl/Cmd + drag — Pan the image
• Ctrl/Cmd + scroll — Zoom in/out

These modifier-based gestures pass through to OpenSeaDragon while keeping Fabric in control of regular mouse events.

Polyline tool workflow

The polyline tool is multi-click (not drag-based):

1. Press d to activate the polyline tool
2. Click to place each vertex — a preview line follows the cursor
3. Press Enter to finish as an open polyline
4. Press c to close as a polygon
5. Press Escape to cancel the polyline in progress

Polylines require at least 2 points to be committed; polygons require at least 3.

Free hand path tool workflow

The free hand path tool captures a continuous stroke as you drag:

1. Press f to activate the free hand path tool
2. Click and hold, then drag to draw — vertices are sampled automatically as you move
3. Release the mouse button to commit the annotation
4. By default the stroke is closed (a filled polygon); hold Shift while drawing to produce an open polyline instead
5. Press Escape during a drag to cancel

Closed polygons require at least 3 sampled points; open polylines require at least 2. If the stroke is too short the annotation is discarded automatically.

Programmatically selecting a tool

Activate a tool through the toolbar UI or keyboard shortcuts. Tools are only available if enabled by the active annotation context.

const { actions } = useAnnotator();

// Programmatically set the active tool
actions.setActiveTool('rectangle');

// Switch to selection mode
actions.setActiveTool('select');

// Deactivate all tools (navigation mode)
actions.setActiveTool(null);