Annotations

What an annotation is

An annotation is a piece of hand-authored geometry that belongs to the project, not to a layer. A beat then decides which annotations are on:

{
  kind: "pin",                        // pin · callout · line · area · arrow · text · tourStop
  geometry: { type: "Point", coordinates: [28.9784, 41.0082] },
  markId: "pin-numbered",
  label: "Where it started",
  body: "Two sentences of context.",
  altText: "…",                       // read by screen readers
  style: { color: "#e81860", size: 2, dash: [2, 1.5], halo: true,
           anchor: "top", offset: [0, -8], leaderLine: true },
  anchorFeature: { datasetId, featureId, layerId },   // stick to a feature instead of a coordinate
  tourIndex: 3                                        // position in a numbered tour
}

Because they live on the project, the same pin can appear in a story chapter, on the matching slide and on a dashboard bookmark, and you author it once.

Drawing on the map

123456789

1. 1Select: the default. Click features, drag existing annotation markers.
2. 2Pan: drag the map without selecting anything. Shortcut H.
3. 3Pin: click once to place. Shortcut: pick the tool, then click the map.
4. 4Callout: a pin with a label plate and a leader line.
5. 5Line: click each vertex, double-click or Enter to finish, Esc to cancel.
6. 6Area: the same, closed into a polygon.
7. 7Fit to data: frames every dataset in the project.
8. 8Save beat: the new annotation is attached to the active beat when you save it.
9. 9Annotations: the beat's list: on / total for the project, with a toggle per annotation.

The loop:

1. Pick a tool. The cursor becomes a crosshair and the status bar shows the live coordinate.
2. Click (pin, callout) or click each vertex and double-click to finish (line, area).
3. The annotation is created, selected, and the inspector opens on it.
4. It is attached to the active beat. Other beats do not show it until you switch it on there.

Esc cancels a drawing in progress and returns to Select.

Dragging a mark from the Library

The Library rail has the map marker set. Drag one onto the map and it lands as a pin at exactly the longitude and latitude under the pointer, including on the phone preset, where the canvas is scaled.

Editing

• Move: with the Select tool, grab a point annotation's marker and drag it. The new coordinate is saved on release.
• Restyle: colour, size, dash, halo, anchor, offset and leader line in the annotation inspector.
• Relabel: label is the plate text, body the sentence under it; both are editable in place.
• Delete: select and press ⌫.

Anchoring to a feature

Instead of a fixed coordinate, an annotation can carry anchorFeature: { datasetId, featureId }. It then follows that feature, which is what you want when the underlying data refreshes and the feature moves, and the only correct answer is "the label goes wherever the vehicle is".

Numbered tours

A tour is a set of annotations with kind: "tourStop" and a tourIndex. Rendered, they are numbered reticle marks; in a story you can pair each stop with a chapter so the numbers count up as the reader scrolls. The mark set has numbered and lettered variants (pin-numbered, pin-lettered) that take the index as their badge.

Per beat

The beat inspector's Annotations section lists every annotation in the project with a switch per row, and the header shows on / total. That is the whole model: annotations are project-wide, visibility is per beat.

Two consequences worth knowing:

• Deleting an annotation removes it from every beat that referenced it.
• Duplicating a beat copies the references, so both beats show the same annotation; moving it moves it in both.

Text and arrows

• text: a label with no geometry, anchored in screen space (style.screen, fractions of the map viewport). It stays in the same corner regardless of the camera.
• arrow: a two-point line drawn with a head, for "flow goes this way".

Accessibility

Give every annotation that carries meaning an altText. The viewer exposes annotations as text alternatives alongside the map, so a reader who cannot see the pin still gets the sentence.