Eight subjects,
one routine

Three tools and one indirection. The tools straighten, clean and label a folder of photographs; the indirection keeps a hand-typed key between the questions and the files, so reprocessing an image never breaks anything that points at it.

The order, and why it is fixed

Why a key and not the hash

The hash is right for the cataloguer — it dedupes identical scans and it changes loudly when a file changes. It is wrong for hand-authoring, because nobody types 0720cac7ee77 into forty records correctly. So figures.json carries a readable key onto the hashed file, and everything else references the key. It is written for you, not by you:

{
  "pof-3-8-wing-aspect-ratio-comparison": {
    "src":     "https://d31aog40626hbr.cloudfront.net/ppl/images/principles-of-flight/…png",
    "alt":     "Diagram of aerofoil section definitions",
    "caption": "A diagram from the manual showing aerofoil section definitions",
    "ref":     "3-8",
    "chapter": "3 Drag", "chapter_no": 3, "figure_no": 8,
    "kind":    "schematic-diagram",
    "role":    "plate",
    "w": 1800, "h": 1200,
    "sha": "f2bc0d96e6a8"
  }
}

Reprocess that figure and one line changes. Every question and glossary entry keeps working. The sha is kept only so a file can be traced back to its manifest record.

Where a figure earns its place

Most figures belong to the glossary, not to a question — Principles of Flight is 103 plates against 7 question figures. A picture next to prose is decoration and does nothing for recall; a picture that carries something the words cannot, or that you have to work, is worth its place. Three roles:

Plates in the glossary

An entry takes an optional figure, or an ordered series where understanding is built rather than shown, and a names list where the figure's value is its labels. Formulas belong here too, as entries in their own right with every symbol defined — the plate then carries the geometry those symbols refer to.

{ "term": "Aerofoil",
  "def": "A shape that makes much more lift than drag when air flows past it.",
  "series": ["pof-02-venturi",
             "pof-02-flat-plate",
             "pof-02-aerofoil-development",
             "pof-02-aerofoil-definitions"],
  "figureRole": "plate",
  "names": ["leading edge","trailing edge","chord line","camber"] }

What the merge writes

Two new fields on entries that gained a figure, and nothing else. Existing fields are never altered, no entry is added or removed, and the version is bumped:

{ "id": "chord-line",
  "term": "Chord line",
  "short": "…", "long": "…", "see_also": [...],
  "figures": ["pof-aerofoil-section-definitions",
              "pof-aerofoil-line-of-zero-lift"],
  "figure_captions": {
    "pof-aerofoil-section-definitions": "The side view of a wing. Look at the curve on top."
  } }

How the tray renders them

js/glossary.js fetches data/figures.json separately from the glossary and tolerates its absence, so a deployment without it still shows every definition. Plates render after the long text and before See also. Several plates on one entry are numbered as a progression; a single plate is labelled with its book reference. Images carry mix-blend-mode:multiply, which drops the white background of a lightened chart into the cream page so it sits like a knocked-out diagram rather than on a white card. Tapping an image lifts it to full size, because detail in a scanned diagram is often finer than the tray is wide.

When a photograph will not do

Where the concept is movement — relative airflow meeting the leading edge and dividing, the different path over the upper and lower surface, downwash, a thickening boundary layer — a cleaned photograph of a book page carries it poorly at any resolution. The page is a still, and the thing being taught is not. Those are worth redrawing as inline SVG with arrows, exactly as figure-dependent question diagrams already are. Send the plate to the chat and say what needs to move.

Figures in questions

{ "chapter": 17, "number": 5,
  "figure": "met-17-synoptic-1", "figureRole": "stimulus",
  "stem": "The height of the ceiling reported by Port Elizabeth is:",
  "options": [...], "answer": "c", "why": "…" }

The label drill

Where a figure's value is its labels, store two versions — the Avex original, and the same image with the labels painted out in clean.html. The drill shows the blank one and asks for the parts; the answer reveals the labelled one.

{ "key": "pof-02-aerofoil-definitions",
  "blank": "pof-02-aerofoil-definitions-blank",
  "names": ["leading edge","trailing edge","chord line","camber"] }

Naming four parts of an aerofoil from a blank drawing is genuine retrieval; looking at a labelled one is not. One extra image per diagram and no new tooling.

Figures and the audio

A deck item may carry a figure key. The renderer ignores it entirely — nothing changes about the MP3 or the cost. listen.html shows it beside that item in the transcript, so the run stays audio-only and the review afterwards has the picture attached to the fact. This is the cheapest of the three: the deck items already exist and are already tagged by section.