Annotate Screenshot

Annotate Screenshot

Mark up a raster this plugin did not render: a dashboard capture, a chart someone sent you, a screenshot under review. Pillow does the drawing. Nothing else is needed.

pip install Pillow -q

Not for artifacts you can regenerate. If you own the generator, put the callout in the source and re-render, because a vector figure beats any raster markup. See figure-generator.

Rule 1: fix the resolution before you draw, never after

The annotation layer is resolution independent. The image underneath is not. Draw at the output size and the text is crisp however poor the source; draw small and enlarge afterwards and the text is resampled into mush that no filter recovers.

Upscaling makes an image smoother, never sharper. Say so in the caption rather than letting a soft chart read as a crisp one.

Read what you have before deciding, because a HiDPI capture is already larger than it looks on screen and usually needs no upscale:

im = Image.open(path)
print(im.size, im.info.get("dpi"))   # DPI metadata is a hint, not proof of capture scale

Judge usable resolution from pixel dimensions and the intended display size. Compare against a known UI dimension when capture scale matters; DPI metadata is often absent, copied, or unrelated to the source device's pixel ratio.

Rule 2: supersample the shapes, draw the text once

Pillow does not anti-alias ellipse, line, or arc. Scaling up alone gives bigger jagged edges. Draw shapes oversized on a transparent layer and reduce with LANCZOS.

Text is the exception. FreeType anti-aliases truetype glyphs natively, so text drawn once at final size is sharper and cheaper than supersampled text.

This also removes a constraint worth knowing about. Advice to prefer rounded rectangles over circles exists because aliased curves pixelate. Supersampled circles do not, so shape choice becomes a design decision again rather than a workaround.

Rule 3: measure the coordinates, do not place them by eye

Eyeballed callouts land near the right feature and miss some of them. When the marks carry an argument, detect the features: flood fill connected components of the marker color, filter by size and squareness, take the centroids.

Calibrate against something the image already states. If a labeled value computes back from your pixel mapping to the number printed on the chart, the coordinate system is verified and every figure in the caption is defensible.

For an unfamiliar image, overlay a coordinate grid first. Scaled previews lie about pixel positions, and the error grows with distance from the origin.

Rule 4: render, then look at it

Annotation defects are invisible in code and obvious in the picture. Open the output every time, per render-verify:

• Does a badge cover the thing it points at?
• Did an emphasis line obscure the feature being criticized?
• Is the notes strip tall enough, or is the last line clipped?
• Do the marks sit on the features, or one position off?

Guard what code can check, so the eye only has to catch the rest:

assert content_bottom <= canvas.height, f"notes clipped: {content_bottom} of {canvas.height}"

Conventions

Put the long-form reasoning in a notes strip below the image with numbered badges, rather than crowding sentences onto the figure.

Reference implementation

from PIL import Image, ImageDraw, ImageFont

S, SS = 3, 4                    # S: output scale. SS: extra supersampling for shapes
ORANGE, RED = (255, 159, 28), (230, 57, 70)

src = Image.open("chart.png").convert("RGB")
W, H = src.size[0] * S, src.size[1] * S
canvas = Image.new("RGB", (W, H), "white")
canvas.paste(src.resize((W, H), Image.LANCZOS), (0, 0))

# Source-pixel coordinates: target center and label anchor.
x, y = src.width * 0.50, src.height * 0.45
lx, ly = x + 30, y - 30

shapes = Image.new("RGBA", (W * SS, H * SS), (0, 0, 0, 0))
sd = ImageDraw.Draw(shapes)
k = lambda v: int(round(v * S * SS))          # source coords to supersampled coords

sd.ellipse([k(x) - k(11), k(y) - k(11), k(x) + k(11), k(y) + k(11)],
           outline=ORANGE + (255,), width=k(3))
sd.line([k(x), k(y), k(lx), k(ly)], fill=ORANGE + (255,), width=k(2))

shapes = shapes.resize((W, H), Image.LANCZOS)
canvas = Image.alpha_composite(canvas.convert("RGBA"), shapes).convert("RGB")

d = ImageDraw.Draw(canvas)                    # text goes on after compositing
try:
  font = ImageFont.truetype("C:/Windows/Fonts/Inkfree.ttf", 12 * S)
except OSError:
  try:
    font = ImageFont.truetype("DejaVuSans.ttf", 12 * S)
  except OSError:
    font = ImageFont.load_default()
d.text((lx * S, ly * S), "1", fill=ORANGE, font=font, stroke_width=1, stroke_fill=ORANGE)

canvas.save("annotated.png", dpi=(96 * S, 96 * S))

Beyond this skill

Automatic non-overlapping label placement and pixel-diff cluster detection are harder problems with a documented solution in the image-annotations companion plugin. Reach for it when a single image needs many labels placed without collisions, or when the change you are marking is too subtle to see by eye. It is optional; nothing here depends on it.

Anti-patterns

Attribution

The color, font, shape, and spacing conventions are adapted from the image-annotations skill in github/awesome-copilot (MIT), distributed through the Alex ACT Plugin Mall. The resolution pipeline, supersampling approach, measured placement, and verification loop are this plugin's own, developed on 2026-08-18 while annotating a low-resolution dashboard capture.

Falsifiability

This skill is decorative if by 2026-11-18:

• Annotation jobs are done without it and the output is fine at source resolution
• Every source turns out to be HiDPI already, so the resolution table never decides anything
• Supersampling produces no visible difference in a side-by-side at 3x
• The conventions drift from the upstream companion without anyone noticing, which would mean the attribution above has become a fossil rather than a live reference