# Image overlays

An educator can mark regions on an image — the lead lines on a knee film, the
level of a narrowing, the border of a lesion — and a learner sees them only when
they ask. This is the contract for how those marks are stored and drawn.

## Why vectors and not a second picture

The obvious implementation is a second PNG with the marks burnt in, shown
instead of the original. It fails four ways: it cannot be turned off (which is
the whole point — the learner should look first and check second), it cannot be
corrected without redrawing, it doubles the storage for every marked image, and
it is correct at exactly one size. Vectors have none of those problems and draw
as crisply on a phone as on a monitor.

## The shape of the data

`media_assets.overlay`, JSON, null when nothing is marked:

```json
{
  "shapes": [
    {
      "kind": "path",
      "points": [[0.31, 0.52], [0.34, 0.51], [0.38, 0.53]],
      "color": "#5eead4",
      "width": 0.006,
      "label": "Dense metaphyseal bands"
    },
    { "kind": "rect", "x": 0.12, "y": 0.4, "w": 0.2, "h": 0.15, "color": "#5eead4" },
    { "kind": "ellipse", "cx": 0.5, "cy": 0.5, "rx": 0.1, "ry": 0.08, "color": "#f0a53d" },
    { "kind": "arrow", "points": [[0.2, 0.2], [0.4, 0.35]], "color": "#5eead4" }
  ]
}
```

**Every coordinate is normalised to 0–1** against the image's own width and
height — never pixels. That is what makes one drawing correct in a 256px
thumbnail, in the viewer, and on a projector. `width` is normalised too, against
the image width, so a stroke stays the same relative weight.

Four kinds, and no more without a reason: `path` (freehand or polyline, the one
that traces an anatomical edge), `rect`, `ellipse`, `arrow` (a `path` of exactly
two points, drawn with a head). `label` is optional on any shape and is what a
screen reader is given.

## Drawing it

An SVG with `viewBox="0 0 1 1"` and `preserveAspectRatio="none"`, absolutely
positioned over the image at the same size. Because the viewBox is the unit
square, the stored numbers are the SVG's own coordinates and no conversion is
needed at any size.

## Rules

- **Off by default.** The learner sees the image, and turns the overlay on.
  Marks shown before the learner has looked answer the question for them.
- **The original is never modified.** Nothing here writes to the image file.
- **An overlay is not a caption.** What the marks *mean* belongs in the
  description; the overlay says where.