# Rendering — how pictures of a sculpture get made

**There are two kinds of image in this project, and confusing them is the one
unforgivable mistake.** Everything below exists to keep them apart.

## Kind 1 — ACCURATE drawings (buildable)

Drawn **from the design sheet by code**, so the picture cannot disagree with the
design. Every dimension in the image traces to a line in `docs/<design>.md`.

- Tool: `scripts/slow_bloom_elevation.py` (Pillow). Elevation, drawn to scale.
- The gather step **parses the design sheet** and fails loudly if a dimension is
  missing or a table changes shape. Never hand-type a dimension into a drawing.
- Output: `output/<design>-elevation.png`
- The Slow Bloom drawing set is **three sheets, one script each** (never one script
  serving several designs):

  | Sheet | Script | Output |
  |---|---|---|
  | side elevation | `scripts/slow_bloom_elevation.py` | `output/slow-bloom-elevation.png` |
  | plan view — the swept envelope and the five bloom positions | `scripts/slow_bloom_plan.py` | `output/slow-bloom-plan.png` |
  | one bloom at large scale — the two offset lobes on the vertical axle | `scripts/slow_bloom_bloom_detail.py` | `output/slow-bloom-bloom-detail.png` |
- **These are the drawings a fabricator can work from.** They still say "not an
  engineering drawing" on their face, because no structural check has been done.

    /home/mike/.venvs/pdf/bin/python scripts/slow_bloom_elevation.py --json   # what it read
    /home/mike/.venvs/pdf/bin/python scripts/slow_bloom_elevation.py          # render

## Kind 2 — IMPRESSIONS (sellable, not accurate)

Generated by an image model. They are beautiful and they **will get the geometry
wrong** — the first Slow Bloom impression came back with two arms, six bowls and
unsplit petals.

- Tool: the `image_generate` tool (`image_gen`, provider `nous`, `krea-2-medium-turbo`)
- Use for: mood, hero shots, marketing, "what it could feel like in a garden"
- **Never** use for: a buyer asking what they are getting, or a fabricator asking
  what to build.

### What the model actually does wrong — measured, 2026-11-08 (NDY-5)

Producing the four Slow Bloom stills took **23 generations; 19 were wrong.** The
failures are not random, so plan for them:

- **It cannot hold a count.** Twelve of the twenty-three came back with six, seven
  or eight blooms instead of five. **Negations make it worse** — writing "no sixth
  bloom" or "do not add a second arm" names the thing, and the model draws it.
  Describe only what should be there, positively and concretely.
- **"Cut in half" is understood; a whole bowl is the default.** Solid bowls came
  back six times even when the prompt said the dish was sawn down its middle. A
  comparison the model can act on — "a shallow dish sawn down the middle, its two
  halves drawn apart on a spindle" — beats a description of the parts.
- **A view from below is read as things hanging.** Twice, blooms were drawn
  *under* the arm. Say explicitly that they stand up **above** it.
- **`complexity` is a trap.** Turning composition density down (-80/-90) to stop
  it inventing extra blooms does that — and also collapses the picture into flat
  vector-art. Keep `complexity` near neutral and fight the count in the prompt.
- **Roughly one usable picture in six** for a piece with an unusual count. Budget
  for it, and keep the rejects: `output/renders/rejected/`, with the failure in
  the file name. The record of what was wrong is part of the deliverable.
- **`vision_analyze` is not a counting instrument.** The same picture read as six
  blooms in one pass and seven in a crop of the same picture. Accept only on a
  reading that matches the design exactly, reject on any reading that does not, and
  re-check each keeper on its own at full resolution before shipping it.
- `scripts/impression_contact_sheet.py` tiles candidates into one labelled sheet
  (panel 1..N) so a single look covers several. The vision model is rate-limited;
  one call per candidate stalls the job.

## The rule

**Every image states which kind it is.**

- Accurate drawings: the code that drew them is named on the image, and the
  design sheet it read is named on the image.
- Impressions: the file name says `impression` and the caption says it was
  generated, not drawn. **A caption that only lives on a page does not travel with
  the file** — so the stills carry their caption burned onto the picture itself
  (`scripts/impression_caption.py`, band appended below the photograph, original
  kept in `output/renders/uncaptioned/`). Every caption must state a direction:
  one that cannot is not finished.

If a picture is going to a customer or a fabricator and you cannot say which kind
it is, do not send it.

## Motion

The sculpture moves — three ways (yaw, lean, spin). Motion has **two** treatments,
and they are the same two kinds as the pictures above:

- **The motion study — ACCURATE, drawn by code.** `scripts/slow_bloom_motion_study.py`
  parses the design sheet and draws both `output/slow-bloom-motion-directions.png`
  (the three motions, with a curved arrow on the axis each turns about and the
  direction of each stated in words) and
  `output/renders/slow-bloom-motion-directions.mp4` (one motion at a time, all three
  legible and in the right direction, the three labels in every frame's footer).
  Both audit their own layout **every frame**: nothing may land off the page, and no
  two text boxes may print on each other (see *"elements on top of each other"*, below).
  **This is the file a fabricator may work from.**
- **The impression of the movement — generated.** `video_gen` (provider `nous`),
  named `<design>-motion-impression.mp4`. Always an impression; say so.

**A generated video cannot state a direction, and that is not a prompt problem.**
The 8-second Slow Bloom impression was checked frame by frame (t = 0.2 … 7.8 s): the
arm was **level in every frame**, so the lean was never legible; the yaw read only as
a change in foreshortening; the blooms read as whole dishes in the wide frames; and no
per-bloom rate or sense could be claimed at all. A text-to-video model animates a
*picture* of the piece, not the *mechanism*. So the direction of each motion is drawn
by code, and the generated clip stays mood — which is why the accurate one carries the
name *motion study* and the generated one carries *impression* in its file name.

**Sped-up motion must say so.** An 8-second clip cannot show a 15–60 s turn or a 3–6 s
lean period at true speed. Say on the face of the clip and the sheet that it is sped
up, and print the real numbers beside it. And **never invent a number to fill a
label**: the sheet fixes the spin RANGE (5–30 rpm) and the rule that no two blooms run
alike, but no rate for any individual bloom — so the clip shows *relative* rates,
labelled as relative, and points at the commissioning log that will hold the real ones.

**The `video_gen` toolset is not enabled for the `cli` platform** in
`~/.hermes/config.yaml` (it is listed in `known_builtin_toolsets.cli` but not in
`platform_toolsets.cli`, and a toolset change only lands on a new session). With
`image_gen` on and `video_gen` off, the stills can be made in-session but the
video cannot. Workaround used on 2026-11-08: hand the job to a **child Hermes
process** that has the toolset for that invocation —

    hermes chat -Q --ignore-rules -t video_gen,file,terminal -q "<ask it to call video_generate once and copy the result to output/renders/>"

The configured `video_gen.provider: nous` resolves to the FAL plugin's managed
gateway, so no key is needed. Verify the result by pulling frames with `ffmpeg`
and looking at them; check duration and dimensions with `ffprobe`.

## Directions of movement — required on every image

Slow Bloom has **three motions and nothing else**, and every drawing and every
impression caption must say which way each one goes. A fabricator who cannot tell
which way a part moves cannot build the mechanism.

| Motion | About what | Which way | Speed |
|---|---|---|---|
| **Yaw** — the whole arm swings to face the wind | the mast's vertical axis | the blooms' wind pressure pushes the arm until it sits **downwind of the mast** | a full turn in roughly 15–60 s in a 5 mph breeze |
| **Lean** — the arm tips into the gust and eases back | the arm's own horizontal pivot axis, across the arm | **into** the gust, then back to rest — both directions | 3–8° of travel, taken against four urethane pads |
| **Spin** — each bloom turns on its own axle | that bloom's own **vertical** axle | same way relative to the arm, for all five | 5–30 rpm, every bloom different |

Rules for annotating:

- Draw **curved arrows** on the axis each motion turns about, not floating arrows
  in space. The reader must see *what* turns and *around what*.
- Show **both directions** of lean, because it returns. Show the **swept arc** for
  yaw, because the arm travels through it.
- **The counterweight moves the opposite way to the blooms** on any lean. Say so —
  it is the reason the arm is balanced and it is not obvious.
- Spin direction: because the arm yaws to face the wind, all five blooms should see
  flow from the same relative direction and turn the same way relative to the arm.
  **Record this as an observation to be confirmed, not as settled fact** — say that
  it is unverified rather than asserting it.
- State plainly that **nothing is powered**, no motion has a reverse, and nothing
  hangs. Those three negatives are the design.

## Ask about PRESENCE, not just cleanliness

**Asking an image check "is anything clipped or overlapping?" cannot find an element
that was never drawn at all.** The first elevation silently lost its title, its
entire notes block, and the line saying it was *not* an engineering drawing — all
four were being drawn outside the canvas, and nothing visible looked broken.

So:

- Ask instead: **"Is X present, and where?"** — one question per element that must
  be there. The disclaimer is the one that must never go missing.
- **Make the renderer audit itself.** Track a bounding box for every element and
  fail the render if any lands outside the page. It is cheap, mechanical, and it
  catches what eyes skip.
- **Off-the-page is not the only failure: check for elements on top of each other.**
  The first audit only caught elements that fell off the canvas — so a bloom-detail
  sheet passed with two labels drawn straight over its dimension lines and its
  centreline. Keep every text box, compare them pairwise, and fail the render when
  two intersect (with an explicit exclusion list for deliberately nested labels, such
  as a value inside a table cell). Both checks belong in every drawing script.
- **Ask the code "was it drawn at all?"** `Sheet.require("TITLE", "DISCLAIMER", …)`
  fails the render when a named element was never emitted — the one failure a box
  audit cannot see, because an element that does not exist has no box.
- **A size table's columns are laid out from the measured font advance width**, and
  the render fails if a field's widest possible text can reach the next field. Fixed
  pixel offsets drift the moment a clip width or a unit changes.
- **A region-of-ink check on the finished PNG is a fast second opinion**: crop each
  band and confirm it is not blank. `scripts/drawing_ink_check.py`: named bands in,
  ink fraction and a BLANK verdict out, exit 1 if any band is empty.
- **Count the elements, and count them twice if the count matters.** On a generated
  image the bloom count is the thing most likely to be wrong, and a single glance is
  not a count: a first pass read six blooms where a zoomed, left-to-right count found
  five. **Crop and count individually before contradicting or confirming anything.**

### The heading printed through its own paragraph — and the model said it looked fine

2026-11-08 (NDY-6). The elevation drew each motion heading (`1  YAW`, …) with a
**centred** vertical text anchor while the paragraph under it was centred 28 px lower.
A centred anchor puts the *whole block's* middle on `y`, so a 17 px heading at `cy-8`
lands inside a 90 px paragraph centred at `cy+20`: the heading printed straight through
the paragraph's first line. Measured with PIL's own ink rows — the title's rows 143–159
and the body's 136–225 share the same x-range — not by eye.

**`vision_analyze` reported "the heading is on its own line, clearly separated" twice**,
and read the mangled paragraph back coherently. That is worse than failing: it is
confident and wrong. The other two sheets had always used a top-left anchor, which is
why only one sheet was broken — and why a *spot* check on one sheet proves nothing
about its siblings.

So: **anchor a stacked text block by its top, not its centre**, and let the overlap
gate (above) decide whether two labels collide. Do not ask a model whether text
overlaps; ask the boxes.

### The clip's title printed through its own attribution line

2026-11-08 (NDY-7 follow-up). The motion-study clip's header put the attribution line at
a **typed-in** `x = 330` while the title runs to `x = 456`, so in **every frame of the
clip** the title's last two words had letters printed through them — 1778 px² of overlap,
the same failure as the heading above, in a script that had the off-page gate but not the
text gate.

**The gate belongs in every script that draws text.** The three drawing sheets got it in
NDY-6; the motion study was written later without it, and that is exactly where the
collision landed. It is now in both renders of the motion study, proved to fire: with the
old position restored the clip refuses to encode.

This time the model and the boxes agreed — `vision_analyze` named the overlap in three
separate sampled frames and PIL's own boxes measured 1778 px² — but the boxes decide, so
**place a label at the previous element's measured edge, never at a typed-in x.**

## Sizes of the pieces — every drawing, not just the outline

An outline gives the envelope; it does not tell anyone what to cut. Every drawing
must state the size of **each piece**, taken from the sources, never from memory.

- The **schedule comes from the BOM by mark**, quoting the BOM's own words. Where
  the BOM states no dimension for a piece, print what it *does* say and flag the
  gap. **Never invent a dimension to make the table look complete.**
- **Every A–E mark goes in the schedule, on every drawing** — the elevation, the
  plan and the bloom detail each carry all of them, so any sheet can be picked up
  and cut from. Marks F (fasteners, finish, sealants) are in the BOM and are not
  repeated. The mark list is **read from the BOM**, not typed into the script, so
  a new BOM line cannot be forgotten.
- **The gap is a column, not a footnote.** `DIM?` reads `yes` where the BOM's own
  words state a dimension and `GAP` where they do not; a red line under the table
  names the gap marks and quotes the line. `yes`/`GAP` — not `in`, which reads as
  the unit.
- **Quote the source text; do not re-type a number.** Extraction regexes mangle
  fractions — a pattern that handles `13-1/4` but not `3/4` silently dropped the
  base plate's size, and the table still looked plausible.
- **Callout text is looked up from the BOM by mark**, not typed in. A hand-typed
  dimension on the same sheet as parsed ones is a lie waiting to drift.

## One contradiction the sheets flag, and do not resolve

The bloom-detail sheet carries a **FLAG** on its face, because the design sheet says two
things that cannot both be true of a bowl cut on its diameter: section 2.4 and step 7 of
the build plan push each half **1-1/2 in off the axis**, and section 2.4 also states
**about 1-1/4 in of clear space between the cut edges**. Two halves offset 1-1/2 in each
side leave 3 in between them (a 16-1/4 in rotor over the lobes); a 1-1/4 in gap means
5/8 in each side and a 14-1/2 in rotor — which is the width the structural brief uses for
this rotor's wind area.

The drawings plot the **1-1/2 in mounting offset**, because that is the dimension the
halves are bolted to, and print the conflict on the sheet face and in its notes. **A
drawing task does not edit the design sheet**, so `docs/slow-bloom.md` is left as it
stands: it is a flag for whoever settles the geometry, not a change of design.

## Verification — do not skip this

**A zero exit code proves nothing about a picture.** Render, then LOOK at it with
`vision_analyze` and ask specifically about:

- text clipped at an edge, or overlapping text
- the element counts (how many blooms? one arm or two?)
- anything running off the canvas

The renderer printed "success" the first time while drawing a guard failure over
the whole task, and the AI generator returned a confident picture of the wrong
sculpture. Trust the looking, not the exit code.

## Where things go

```
docs/<design>.md                  the design sheet — the only source of dimensions
docs/slow-bloom-bom.json          the priced bill of materials — the source of piece sizes
scripts/<design>_elevation.py     the drawing code for that design
output/<design>-elevation.png     the accurate elevation
scripts/slow_bloom_plan.py        the plan view (envelope, bloom positions) — one script per design
output/slow-bloom-plan.png
scripts/slow_bloom_bloom_detail.py  one bloom, large scale (the two-lobe rotor)
output/slow-bloom-bloom-detail.png
scripts/drawing_ink_check.py      region-of-ink check on any finished PNG (bands in, verdict out)
output/renders/                   impression stills, named <design>-impression-NN.png
scripts/slow_bloom_motion_study.py  the accurate motion study: still sheet + clip
output/slow-bloom-motion-directions.png   the three motions, with the direction of each in words
output/renders/slow-bloom-motion-directions.mp4   the accurate motion study, animated
output/renders/                   videos, named <design>-motion-<what>.mp4: <design>-motion-directions.mp4
                                  is DRAWN (accurate); <design>-motion-impression.mp4 is GENERATED
scripts/impression_caption.py     burn the kind + the motion onto an impression, below the picture
output/renders/uncaptioned/       the uncaptioned originals of the impressions
```

**A new sculpture needs its own drawing script.** Do not bolt a second design into
`slow_bloom_elevation.py` — copy it, change the sheet it reads, and keep one script
per design so a change to one cannot silently change the other.
