annotate-board

name	annotate-board
description	Use when you want to render an annotated overlay PNG of a circuit board with bounding boxes, labels, and a legend from a components.json list.

Annotate Board

Render a visual annotation overlay on a hardware photo. Given an input image and a components.json (from identify-components or hand-edited), the skill invokes a Python script to draw colored bounding boxes by component type, numbered or named labels, and a side legend. Output is a high-quality PNG suitable for documentation or debugging.

Data storage root:

${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/hardware-id-annotation/

When to use

• You have a components.json and want a visual overview of the board layout
• You need to document or present the hardware to a team
• You want to cross-check visual IDs by seeing boxes overlaid on the original photo

Inputs to gather

• Input image — original hardware photo (JPG, PNG)
• Components JSON — path to data/<board-slug>/components.json (from identify-components)
• Output path — optional; defaults to output/<board-slug>-annotated.png
• Style options — minimal (boxes + numbers only) or detailed (boxes + names + specs)
• Label mode — number (ref-like "C1"), name (component type), or partno (part number if available)
• Color mode — type (capacitor=yellow, IC=red, etc.) or confidence (high=green, med=yellow, low=red)

Procedure

1. Validate inputs. Ensure the image file exists and components.json is valid JSON with a components array.

2. Invoke the annotation script:

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/annotate.py \
     --image <input-image> \
     --components <components.json> \
     --output <output.png> \
     --style <minimal|detailed> \
     --label-mode <number|name|partno> \
     --color-by <type|confidence>
   

   (The script uses Pillow to draw on the image; user can override all defaults via flags.)

3. Review the output. Display the PNG to the user. If boxes are misaligned or labels collide, offer to re-run with --style minimal or a different --label-mode.

4. Optional hand-tweaking. Suggest kImageAnnotator (https://github.com/ksnip/kImageAnnotator) if the user wants to add free-form arrows, text, or redactions after automatic annotation.

5. Save to disk at the user's output path or the plugin default:

   ${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/hardware-id-annotation/output/<board-slug>-annotated.png
   

Output / side effects

• Annotated PNG file written to disk
• Console output: dimensions, number of boxes drawn, legend entries, script exit status
• Image file ready for sharing, archiving, or further markup in an image editor

Safety / constraints

• Script must exist at ${CLAUDE_PLUGIN_ROOT}/scripts/annotate.py (provided by orchestrator).
• Bounding box coordinates must align with the image dimensions; validate that components.json uses consistent units (pixels or 0–1 normalized).
• Large images (e.g., 4K photos) may take several seconds; inform the user if processing is slower.
• Do not overwrite the original image unless explicitly requested.