Image Annotations

Image annotations

Add precise visual callouts to screenshots, diagrams, and demo frames by drawing rounded rectangles, leader lines, and short labels with consistent colors, padding, and typography.

When to invoke

• "Highlight this area in a screenshot for my PR."
• "Annotate the before and after images."
• "Add labels and arrows to this architecture diagram."
• "Create annotated frames for a GIF demo."
• "Mark what changed in this UI image."

Prerequisites and context

Install Pillow only if the project environment does not already provide it:

pip install Pillow -q

Check Image.open(path).size before placing annotations. HiDPI screenshots are larger than they appear; 150% display scaling means coordinates may be 1.5 times CSS pixel dimensions.

Annotation style rules

Font and sizing

Never resize screenshots with PIL just to fit Markdown; resizing creates artifacts and makes annotation coordinates harder to verify.

Reference implementation

from PIL import Image, ImageDraw, ImageFont

font = ImageFont.truetype('C:/Windows/Fonts/Inkfree.ttf', 36)  # or ImageFont.load_default()
color = '#FF9F1C'
stroke = 5
pad = 18

img = Image.open('screenshot.png')
draw = ImageDraw.Draw(img)

# Inspect before placing callouts: img.size
# Rounded rect with padding
draw.rounded_rectangle(
    [x1 - pad, y1 - pad, x2 + pad, y2 + pad],
    radius=14, outline=color, width=stroke
)

# Leader line, same thickness as rect
cy = (y1 + y2) // 2
draw.line([x2 + pad, cy, x2 + pad + 40, cy - 30], fill=color, width=stroke)

# Label: same-color stroke, no white glow
_draw_label_at = (x2 + pad + 45, cy - 60)
draw.text(
    _draw_label_at, 'label text',
    fill=color, font=font, stroke_width=1, stroke_fill=color
)

img.save('annotated.png')

Placement guidelines

1. Use consistent thickness for rectangles, lines, and visual text weight; 5px is a good default.
2. Place labels close to the target with short leader lines.
3. Allow labels to overlap content only when the same-color stroke keeps them legible.
4. Use debug=True or an equivalent preview mode for the first annotation on a new image.
5. Show the result locally before uploading to a PR or embedding in a document.
6. Keep 2-6 annotations per image; more callouts usually need a numbered legend or multiple images.

Limits

• Ink Free is Windows-only; other platforms need ImageFont.load_default() or a provided font.
• PIL text rendering is basic; it does not support rich text or Markdown.
• Animated GIF annotations require frame-by-frame processing and can be slow for long recordings.
• Algorithmic placement works best with 2-6 annotations; split crowded images instead of overloading one frame.

Progressive disclosure and bundled resources

• references/annotation-script-and-media.md: read before implementing scripted annotations, image diffs, GIF overlays, or reusable media workflows.

Annotation terminology

This skill uses PIL/Pillow. workflows for color-coded callouts. Treat red as bad/removed, avoid circles/ellipses, avoid eye-catching red, keep stroke_fill=<same color as fill>, and preserve line width consistency. Read the code-heavy bundled reference for scripted media workflows.

Output template

## Image annotation result

**Status:** complete | blocked | failed
**Input:** `<path/to/source-image>`
**Output:** `<path/to/annotated-image>`
**Image size:** `<width>x<height>`

| Callout | Color | Coordinates | Label | Purpose |
| --- | --- | --- | --- | --- |
| 1 | `#FF9F1C` | `[x1, y1, x2, y2]` | `<label>` | <what reviewers should notice> |

### Validation
- Source image size checked: pass | fail
- Annotated output opened or previewed locally: pass | fail
- Markdown display sizing recommended: pass | fail

Quality gate

• Image.open(path).size was checked before coordinate placement.
• Red #E63946 is used only for bad or removed things.
• Neutral highlights use #FF9F1C or a justified project color.
• Rounded rectangles have 18px padding and consistent 5px visual weight unless image scale requires adjustment.
• Labels are short, close to the target, and do not use white stroke.
• The annotated image was previewed locally before delivery or upload.
• GIF work reads references/annotation-script-and-media.md before frame-by-frame implementation.