References: pipeline, gates, prompting, matrices, effort tiers, naming, failure modes

This commit is contained in:
2026-10-14 11:39:57 +00:00
parent 7a18cb4157
commit d876bd7261
7 changed files with 672 additions and 0 deletions
+88
View File
@@ -0,0 +1,88 @@
# Render effort tiers
**Status: newly adopted (October 2026) and on trial.** The scheme below was agreed for the next major town batch and
is being evaluated there. Everything in it is a proposal with reasons, not a law. Use it, measure it, and adjust the
numbers to your own table, budget and renderer.
## The one test
**Tier = the probability that the place comes into focus at the table.**
Not its size, not its importance in the world, not how pretty it would be. A third-rate pub that the storyline sends
the party to is tier 1. A master weaponsmith in a town the party only passes through is tier 3. The categories below
are examples of where places usually land, never rules.
| Tier | Meaning | Typically | Render deliverables | Budget (one hosted edit model, 2026 prices) |
|---|---|---|---|---|
| **1** | Guaranteed to come into focus | town overviews and approaches; the party's base, inn or hall; the storyline's buildings; the guild's tavern | block model + aerial and approach plates; the full time x weather matrix; every room the party will stand in; scene beats; named staff as reusable anchor characters | ~100-200 renders, ~$10-20 |
| **2** | Likely | adventuring shops (gold, gems, weapons, armor, alchemist, healer); civic and sacred landmarks (temple, moot hall, gates, market, docks) | exterior A/B day + night + one snow; one counter interior; the proprietor as a scene character; goods at the wealth tier; a price list | ~20-40 renders, ~$2-4 |
| **3** | Possible | third-rate pubs, mundane townsfolk shops | one exterior day, one interior, a keeper from the pool | ~5-10 renders, under $1 |
| **4** | Unlikely / background | everything else on the map | a name, a tagline, one line of text, maybe a sign emblem | no renders |
Special-case venues may warrant their own budget regardless of tier; decide that per campaign.
## Deliverables per tier, spelled out
### Tier 1
- **Geometry:** block model of the site in its town context; template plates for every camera (approach, aerial,
entrance, interior rooms).
- **Exterior matrix:** Day / Sunset / Night x Dry / Rain / Snow (light) for the A and B cameras (18 frames), plus
whatever storm and deep-snow cells your calendar needs (references/matrices.md).
- **Interiors:** every room the party will stand in, as an empty master (people-free, so it stays reusable as a plate).
- **Population x time matrix (venues with people):** 4 x 3, Morning / Afternoon / Evening / Late Night x Quiet /
Moderate / Packed, from one "reveal from the door" camera (12 frames). A 4 x 4 with an **Empty** column only for
storyline hubs where an empty room is itself a scene (16 frames).
- **Scenes:** the beats the story needs, on the canon rooms with the canon faces.
- **Named staff** as reusable characters with locked faces.
### Tier 2
- Exterior A and B: Day Dry, Night Dry, one Snow (light).
- One counter interior, empty master.
- The proprietor as a scene character (a face that recurs, not a full anchor pack).
- Goods rendered at the wealth tier; a price list in text.
- **Population matrix 2 x 3:** Day / Sunset x Quiet / Moderate / Packed (6 frames), for any venue with a counter or
benches.
### Tier 3
- One exterior, Day Dry. One interior. A keeper drawn from the generic pool.
- **Population matrix 1 x 2:** its peak hour x Quiet / Packed (2 frames).
### Tier 4
- Text only: name, tagline, one line. A sign emblem if it is cheap. No renders.
## Model-cost tiering (which agent does what)
Image QA is the real token cost, not the renders. So the agent that executes a tier is sized to the tier:
| Tier | Planning | Execution | Review |
|---|---|---|---|
| 1 | the most capable model writes the brief and reads the report | a mid-sized model runs the lane | a short review by the capable model |
| 2 | brief from a template | mid-sized model | none beyond the lane's own gates |
| 3 | template | a small model | none |
| 4 | — | a local or text-only model (it never has to see an image) | none |
**Canon guard for lanes run by smaller models:** every brief says "anything not in this brief is marked PROPOSED".
A lane invents less when it knows invention is allowed but must be labeled. (The "no glass anywhere" rule that
haunted one campaign for a week was a lane's invention; see references/prompting.md on glass.)
## Rules
- **Play promotes, never demote.** A place the players actually enter moves up a tier for the next session. Nothing
rendered is ever deleted; superseded files are moved aside.
- **Per-tier ceiling.** A lane may not exceed its tier's budget without the GM's say-so. Cap retakes and the number of
images reviewed, not just renders.
- **Attention is the scarcest resource,** then tokens, then wattage. Tier budgets cap tokens and renders, but never by
pushing review load onto the human: spend more on self-gating so fewer, better frames reach them.
- **Canon-direct delivery.** Work that passes its own gates goes straight into the campaign's canon folder with a
one-line note. A human review entry is reserved for: the face of a story-critical character; a human gate before
something permanent (a model fine-tune, a bake); something the GM asked to see. Reviewed means done: review remarks
are records, not new work orders.
- **Renderer policy is unchanged by tier.** Cut spend by volume (fewer takes, re-roll caps, tighter candidate sets),
never by switching to a weaker renderer for the cheap tiers. A weaker renderer costs more in retakes and review.
## What to evaluate after the trial
- Did the smaller-model lanes invent canon? How often?
- Retake rate per tier compared with capable-model lanes.
- Actual tokens and renders per tier against the budget.
- Did the tiering match what the table actually visited? (That is the only question that matters.)
+80
View File
@@ -0,0 +1,80 @@
# Failure modes and the fix that worked
Quick index. Each line: the symptom, the measured cause, the fix. Longer versions live in prompting.md, gates.md and
matrices.md.
## Geometry
| symptom | cause | fix |
|---|---|---|
| overview invents halls, towers, a church | at town scale each house is a few px; the plate barely constrains the renderer | invented-structure gate; closer camera; name the absent big things in the town block |
| wide view zoomed in 4-10 % | the renderer frames for legibility | FRAMING LOCK with band positions in % of frame |
| small town moved up toward the mountains behind a wide foreground | same | the explicit FOREGROUND sentence ("the town is SMALL and sits LOW, houses from 71 % to 96 %") |
| facade cropped by the plate restored to full height, with the tower | the renderer steps back to show the building | "every edge cuts the scene where image 1's edges cut it; the set-back story and tower are hidden from here" (0/3 -> 4/4) |
| castle redrawn as a palace at 3 km | prior for "castle" | landmark region correlation (0.16 vs 0.4-0.7) + "the castle stays small, not enlarged into a palace; no new towers, spires or domes" |
| mountain shrunk to fit its summit in frame | the plate's wall runs out the top edge | SKY_FIT column gate + "rises out of the top edge, no sky above them there" |
| snow on a low flank through a telephoto | prior for "alpine" | one edit-with-itself replacing white patches with rock; gate on snow-colored px below the snow line |
| verticals tilted 1-2.6 degrees, frame shrunk | a pitched-up plate | render level with a vertical lens shift |
| a feature on the wrong face | named in a shared feature list while occluded from this camera | per-camera visibility list; disown occluded features positively |
| a river or castle appears in a view facing away from it | the prompt's global landmark text | "there is NO river, NO lake, NO castle; they are behind the camera" |
| eleven gables where the map has four houses | touching quads in the massing | 4-7 px gaps, stepped fronts |
| ruins in the plate | footprint slivers | open with a 2 m disc, drop pieces under 40 m2 |
| a stone post with a ball finial by the road | a mannequin cut by the frame edge | proxies 10 m or more from the camera, off the edge |
| battlements across a roof | convex split of an L-wing with merlons on the internal seam | fix the edge list; check the untextured plate |
| a quay or wall runs to the frame edge | the model never said where it ends | model the far side as a different surface |
| a false lake beside the town | river class from a blurred floor level | take the river from the terrain's own water mask |
| the road in a trench | the road layer cut below grade | a broad shelf on a 1 m layer |
| a gate hidden in its own wall's shadow | the hour chosen for the plate | move the sun (16:00 instead of 16:30) and name the hour in the prompt |
## People
| symptom | cause | fix |
|---|---|---|
| aerial figures 2.4-5 m tall | nobody set their size; the renderer sizes for legibility | proxies in the plate; the figure-bracket gate; shrink-in-place for legacy sets |
| near walkers +25-28 % | eye-level camera with no horizon relation | the EYELINE clause (eyes on the horizon line) |
| giants at a gate | no nearest-object relation | SIZES BY THE NEAREST OBJECT (adults reach half the palisade, a third of the posts) |
| a 1 m character at 1.4 m | a stated size is ignored | a contact relation the renderer has to draw (a hand flat on his hood, arm straight down) |
| extra lantern-carriers at night | the noun "lantern" | HEADCOUNT lock, lanterns carried by the same people |
| ghosts on quays and stair posts | "steam vents" | drop the steam clause |
| guests on the shut terrace | "2-3 guests on the balcony"; the noun beats the negation | state where everyone is as a positive fact; repeat the untrodden snow |
| a busy room with backs to the lens | packed density fills the foreground | NEAR-FOREGROUND and LOWER-RIGHT locks |
| a referenced man drawn twice | face reference + "lying" | exact headcount; "appears exactly ONCE ... the corner is EMPTY" |
| an outfit sheet's cowl on the wrong woman | a sheet attached without its wearer's face | describe the garment in prose; "she has NO brow ornament" |
| modern waistcoats, derbies, riveted aprons | "prosperous" + a plain garment noun | the period cut as construction facts; forbid the modern modes by name; a women's clause with no trousers |
| hip flips on side gear | "on the viewer's right" | "on HER own right hip" + "the back view is the same person turned round" (0 flips) |
| bloomers under a shift | the men's trouser clause reused on a woman | a women's clause: "hangs straight from the belt; lower legs bare" |
| a V sign | "two fingers raised" | drop the gesture; "no hand sign" |
| field sheds become people in deep snow | "tiny dark upright marks = townspeople" | a lock naming the sheds; eye-check open fields at 2x |
## Surfaces and weather
| symptom | cause | fix |
|---|---|---|
| snow cell fails the gate 18/18 | a snow cap raises every surface ~4 px | thin fall "no deeper than a finger" for the calm cell; wall-band gate for storms |
| storm cells show a dusting | the thin-fall clause reused | storm prompt names snow in the air, loads, cornices, drifts; legibility clause outranks the storm |
| night heavy blizzard reads as a dark soft frame | wording cannot push a clear plate to a whiteout; contrast metrics misrank | veil-before-edit (deterministic veil from the depth plate), then "IMAGE 1 ALREADY SHOWS THE STORM AT FULL STRENGTH; keep visibility as low or lower"; silhouette gate |
| summer edit of a winter keeper adds ponds, drains channels, adds bridges | snowy low ground and snow-banked water look alike | pixel or guide lock; or build summer keepers from a summer plate; review water at 1-2x |
| a bright sunset glow in the east | the sky in frame is east; the sun is behind the camera | "THE SKY IN THIS PICTURE IS THE EASTERN SKY ... NO glow" |
| a sun disc in frame | the prompt named the sun without its position | "the sun is behind the camera; no sun disc" |
| a smoke plume from a building with no hearth | "chimney smoke rises" | a no-smoke clause for that building |
| the bar counter survives the "shut" state | "no counter" | "under the roof there is NOTHING: no counter, no shelves, no casks" |
| seven map-true houses look like seven barns | footprint + tier say nothing about function | the character pass (one emblem sign, the trade visible) |
| false glass "defects" | a blanket no-glass rule | glass by wealth tier |
| pseudo-script on books, signs, ledgers | anything flat invites writing | "every book is CLOSED"; signs are emblems only; corner and sign sweep |
| arch-shaped doors | "filling the recess" | "a rectangular door under the tympanum, which stays stone" |
| a sky sliver above a facade | the prompt named the sky | "no sky in view" |
| a window in an internal partition | the prompt read it as exterior | "that wall has no window" |
| a people-free view with people | nothing said so | the explicit people-free clause |
| a cleared wilderness trail in deep snow | prompt alone cannot bury a walled path | pre-bury the route pixels in IMAGE 1; class D gate |
| a hut becomes a horse and sledge | "sledge-packed" | name the hut in a lock; eye-check at 4x |
## Process
| symptom | cause | fix |
|---|---|---|
| a lane's conclusion lost in the hand-off | completion messages truncate | write REPORT.md first; hand back the path; anything load-bearing in the first line |
| the same brief dispatched twice, rendered twice | no check for a live sibling | check the lane folder for a fresh REPORT first; re-verify, never re-render |
| a gate that rewards the wrong frame | it measures persistence, not correctness | name the absence in the prompt; crop the background by eye; do not let the gate pick |
| a number right, the story wrong | the lane's interpretation unchecked | verify the lane's interpretation, not just its numbers; run a known-bad control |
| spend out of control | volume: 54-cell matrices x takes x re-rolls | a Cost line per run; cut by volume, never by renderer |
| the GM's attention spent on review folders | every gated set went to review | canon-direct delivery; review only story-critical faces and permanent bakes |
+112
View File
@@ -0,0 +1,112 @@
# Gates: what each one measures, what it catches, what it is blind to
Every gate here was built because a specific failure slipped through the one before it. Run them in this order and
report which gate each pick passed. **Verify your verifier first:** score the plate against itself (must be ~perfect)
and against the plate shifted 3 px and scaled 1.01 (must fail) before you trust a threshold. `scripts/smoke_test.py`
does exactly that on a synthetic town.
## 0. Plate gate (before any renderer call)
Overlay the map's checkable facts on the plate seen through the same camera. For a square: elongation, the closing
range, the saw-tooth of gables, the ways in, the tracks, open ground clear of buildings. **Any miss found here costs one
re-run of massing. Found after re-surfacing it costs everything downstream, because the renderer photographs the
plate's mistakes as faithfully as its truths.** Also eyeball the untextured plate for: merged house blocks (split
them), footprint slivers (they become ruins), a mannequin cut by the frame edge near the camera (it becomes a stone
post), and built features that run off the frame with no end (the renderer extends them forever; model where a quay
or wall STOPS).
## 1. Geometry drift (frame vs plate), `gate.py`
| metric | what | measured bands |
|---|---|---|
| `grad_corr` | Pearson correlation of gradient magnitude at 896x504 | textured facade at 20 m: 0.5-0.7; town from 3 km: 0.4-0.55; smooth landscape: 0.15-0.3 (low by nature, judge layout by eye) |
| `edge_rec` | share of plate edges that have a frame edge within 4 px | reported |
| `ecc_cc`, `scale`, `rot_deg`, `tx_px`, `ty_px` | affine ECC frame -> plate | a faithful take: scale 0.995-1.01, shift under ~10 px; a reframed take: scale 0.92-0.98 or 1.04-1.10 |
| `landmark_grad_corr` | `grad_corr` inside the landmark solids' mask | castle at 3 km kept: 0.4-0.7; redrawn as a palace: 0.16 |
Calibrate per view. The plate vs itself scores 1.0 / scale 1.0; +3 px and x1.01 must fail on every instrument.
**Blind to:** water becoming land (a surface change, not a shift), an invented building in a low-texture far band,
a feature relocated to a face the camera cannot see, extra people. Those need the gates below and the eye.
## 2. Skyline and invented structures (wide views), `gate.py`
The sky/ground boundary per column, fitted plate -> frame by scale + shift (`sky_s`, `sky_tx`, `sky_ty`, `sky_res`
in px). Then `invented_structures`: runs of columns where the frame's skyline rises more than `--bump` px (default 18)
above the plate's, outside the dilated landmark columns. **This is the gate for the one failure the block method still
has: in a city-wide frame each house is a few pixels, the plate barely constrains the renderer, and it "improves" the
skyline with halls, towers and churches.** Reject any frame with a run; prefer a closer camera or stronger plate
conditioning over more retakes.
Related measured failures on mountains: the renderer shrinks a massif to fit its summit in frame when the plate's wall
runs out of the top edge (gate per column: sky in the frame where the plate has none, under 10 % of columns), and it
paints snow on a low flank through a telephoto lens (fix: one edit-with-itself "replace every white patch with rock,
scree, grass; change nothing else"). Color classifiers are haze-confounded beyond ~6 km.
## 3. Figure scale brackets, `gate.py`
Every proxy person the plate can see (from `<V>_people.json`, visibility from the oid buffer) is drawn on the frame as
a bracket: foot line, true-height head line, and a +-25 % band (orange). Registered to the frame through the ECC warp
when the warp is credible (ecc_cc >= 0.55, scale within 8 %). **Pass = the dressed figure stands on its bracket with
its head inside the band.** `qc/<id>_figzoom.jpg` crops the 16 largest.
What the numbers looked like: street-level figures with proxies and the eye-line clause land at +5-13 % (heads on the
horizon line); without the clause the nearest walkers came out +25-28 %; without proxies at all, aerial figures were
2.4 m at the far edge and 4-5 m at the near edge. Indoors with a face reference attached, close figures bias +8-22 %
even with proxies. At ~20 px (aerial) scale holds but figures are not 1:1 with the proxies (a few move or drop).
**Blind to:** people the renderer ADDED that no proxy owns (a wide view added six tiny travelers at true size for where
they stood; disclosed, not rejected). Count heads against the proxy count by eye.
## 4. Corner and edge sweep, `gate.py`
Four corners and the top/bottom bands of every frame, contrast-boosted (CLAHE + unsharp), on one sheet per position.
Looking for: text, runes, numbers, watermarks, logos, captions, borders, a sun disc in frame. Read the sheet at 1:1.
## 5. Sign and emblem lock across angles (eye check)
Every sign is an emblem only, never lettering (a renderer "writes" pseudo-script on anything flat). Crop each sign at
4x from every camera and compare: same emblem, same board, same position on the building. A coin plaque with ring
marks in one take and clean in another: pick the clean one and say so.
## 6. Occlusion check (eye, per camera)
For every named feature in the frame ask: which face is it on, and can this camera see that face? A balcony that is
really on the far side but appears on the near face passed every element-by-element check and was still impossible.
The fix is upstream: prompts per camera from a visibility list, with occluded features disowned as a positive
instruction ("the balcony is on the far side and is NOT visible from here").
## 7. Storm intensity and snow depth, matrix cells
- **Storm cells:** a snow-loaded roof hides the texture and lifts the eaves, so the full-frame gate fails by design.
Ladder: full frame -> building band (ground to ridge) -> **wall band** (the same thresholds measured only on the
walls, roofs masked out). Report which rung passed. Controls: keeper vs itself 0.0; a thin-snow take passes; a real
whole-frame shift fails on every rung.
- **Night whiteout:** brightness-normalized contrast metrics score a dark, soft frame as "heavy" when the eye does not.
The instrument is a **silhouette gate** on the building band against the already-gated plate (sigma-2 flake
smoothing), with the side-by-side sheet as the decisive check. A visible veil of lit, snow-filled air is the
requirement, not low contrast.
- **Deep snow (medium/heavy):** gate structure ABOVE the snow line (walls higher than depth + lee drift, eaves,
ridges, parapets) and exempt the buried ground band. Measure depth and walkways against the site's Snow (light) cell
of the same camera and light, not against the sunny plate (sun and shadow bias the snow line by 0.3-0.5 m). Count
NEW dark lines only for walkways; the shared line network scores the same in every cell. Walkways on class C/D
routes are a FAIL (references/matrices.md). At overview scale (1-2 px/m) depth reads but walkways and drifts do not;
expect them only at street scale. Small field sheds turn into oversized people under a "tiny dark upright marks =
townspeople" clause; eye-check open fields at 2x.
- **Seasonal edit of a winter keeper moves water:** snowy low ground becomes a pond, frozen channels drain into grass.
The geometry gate is blind to it. Review the water at 1-2x against the plate's water class outlined on the frame, or
build summer keepers from a summer plate.
## 8. Same-tier recognizability (contact sheet)
Thumbnail every batch of exteriors on one wealth rung before calling it done. Seven map-true houses on one rung came
out as seven identical timber barns; each passed its gate. Fix: a **character pass**, a one-change edit per pick that
adds the house's tell at the frontage (one emblem sign, its trade visible: casks and trestles, boots on a rail, a
smelter stack and slag heap, herb-drying racks), gated with ECC against its own source frame plus the corner sweep.
## Reviewer sub-agents
Automatic gates catch shifts, zooms and scale. Independent reviewer passes, one per view, sweeping 1:1 quadrants,
catch what they cannot: extra people, see-through ghosts, lost window columns, sky slivers, arch-shaped doors, a river
that appeared in a view facing away from it. They take 15-50 minutes each. Brief them with the bracket rule and the
density rule relationally (tight numeric ranges over-flag), and have them produce a fix list with boxes.
+113
View File
@@ -0,0 +1,113 @@
# Matrices: time x weather, population x time, snow levels, seasons
A matrix is what lets the GM show the place as it really is at the hour and in the weather the party walks in.
Every cell is an **edit of an accepted keeper of the same camera**, never a fresh re-surface, so geometry carries.
## The exterior 9-square
`Day | Sunset | Night` x `Dry | Rain | Snow (light)` = 9 cells, rendered for the A and B cameras (18 frames) when
feasible. The fixed set keeps every establishment comparable; ad-hoc condition sets ("golden hour", "deep winter")
break that. Label lock: Dry = no rain, wet or snow effects; Rain = wet sheen, no snow; Snow = snow load, no rain.
Build order per camera:
1. Day Dry = the accepted re-surface pick (the keeper).
2. Day Rain and Day Snow (light) = weather edits of the keeper.
3. Sunset and Night of each weather = **relights of that weather's Day pick** (a light-only edit). Relights hold
geometry (ECC scale within 0.15 %, shift under 2 px against the Day pick) and carry the snow over; fresh edits do
not. No approved Night keeper? Make Night Dry as a light-only relight of Day Dry with the dusk wording.
4. Storm cells, if your calendar has them: Blizzard, Heavy Blizzard, Ice Fog. A heavy storm that drifts under a relight
should be **intensified** from the gate-passing same-time Blizzard pick, not relit from Day.
## Snow has three levels
| level | depth | must show | file token |
|---|---|---|---|
| Snow (light) | a thin lying fall, "no deeper than a finger" | shapes and heights unchanged (it keeps the geometry gate honest) | `Snow` / `Snow (light)` |
| Snow (medium) | at least knee-deep, ~0.5 m | visible wind drifts on the lee side of walls | `Snow (medium)` |
| Snow (heavy) | 1-1.5 m | drifts and **hand-shoveled walkways** with banks along the major streets and to each door | `Snow (heavy)` |
Display fallback chain when a place lacks a level: heavy -> medium -> light. Roof loads match the depth. One prevailing
wind per site across every camera and cell. The thin-fall clause is for the calm Snow (light) cell ONLY: storm cells
want roofs loaded, and they use the wall-band gate instead of a thinner storm.
### Route clearance classes (medium and heavy only)
| class | routes | treatment |
|---|---|---|
| **A kept** | main streets, market, gate and bridge approaches, the main work road | hand-shoveled walkways with banks (heavy) or trampled, sledge-packed snow (medium). **Never "plowed"**: there are no plows in the setting; packed snow stays on the surface |
| **B trodden** | side lanes, yards | one narrow foot-trodden path to each door, nothing wider |
| **C unkept** | roads between settlements and to outlying farms | NOT cleared: at most a ski or sledge track, snow poles or cairns mark the line, can drift shut. This is the isolation |
| **D untouched** | wilderness trails | pristine, no tracks at all; markers buried or just showing |
Deep snow has to feel like winter isolation. A cleared trail kills the menace of a dangerous path and flattens the
geography. Store the class per route in the site's data; the prompt states it per route; a walkway on C/D fails the
cell. The prompt alone cannot bury a walled path: pre-bury it in IMAGE 1 (inpaint the route pixels from the texture
beside them) before the edit. Table consequence worth telling the GM: horses founder in medium and deeper; travel off
class-A routes is by ski, snowshoe or sledge.
## Foliage follows the season, no new axis
Read the season off the existing cells: a terrace bar open in Dry and furnished in Rain implies summer (deciduous
trees in full leaf); shut in Snow implies winter (bare). Put "whether the deciduous trees are in leaf or bare, and the
color of the grass" in the edit's CHANGE ONLY list, keep "DO NOT add or remove a tree", and say the leaves fill the
tree's own crown outline "and no bigger". Conifers unchanged. Leafing out cost no gate passes. If a matrix carries no
season information, default to summer and file it as an open question.
## Population by weather (exteriors)
- **Dry:** people out at plausible density, in period clothing.
- **Rain and snow:** considerably fewer but never empty: a hurried figure, someone under the eaves, a lit window.
- **Night:** fewer people, lit windows; lanterns carried by the SAME people (the noun "lantern" spawns a new person,
so use a headcount lock).
- **Storms:** a hooded pair with a lantern against the warm, populated interior glowing behind the windows. That
contrast is the look.
- Judge density relationally against the same hour's Dry cell; the GM's words define it, not exact counts.
- **Which people a cell keeps is decided BEFORE the edit** by which proxies the plate carries (the renderer removes
people cleanly but cannot be told which to keep). Never keep a proxy mostly hidden behind another without its
occluder; it comes back as a bust or a ghost.
## Population x time-of-day matrix (venues with people in them)
For every pub, tavern, inn, dining hall, taproom, and any shop with a counter, sized by tier
(references/effort-tiers.md):
| tier | hours x densities | frames per camera |
|---|---|---|
| 1 | Morning, Afternoon, Evening, Late Night x Quiet, Moderate, Packed; add Empty only for storyline hubs | 12 (16) |
| 2 | Day, Sunset x Quiet, Moderate, Packed | 6 |
| 3 | its peak hour x Quiet, Packed | 2 |
| 4 | none | 0 |
Camera: one "reveal from the door" view of the room. Recipe: IMAGE 1 = the canon empty master as "the set, same
tripod at another sitting; ADD ONLY PEOPLE"; name the tables by frame position and put every party on one; give each
density a number (~5 / ~15 / ~35 / ~70 for a big hall) but brief reviewers relationally. Locks that held:
**NEAR-FOREGROUND** (the bottom third shows only the empty near end of the foreground table; the crowd begins halfway
down it; nobody cut off by the bottom edge) fixes guests sitting with their backs to the lens; **LOWER-RIGHT** (the
empty floor before the edge post) stops the packed crowd piling against the frame edge. About 1 take in 6 comes back
reframed; a **structure-band gate** (the thresholds measured on the top ~44 % of the frame, rafters and windows, which
people never touch) catches it. **Zoom-check the master's props before the population wave:** people inherit the
master's defects, and fixing the master (one region composited from a clean sibling) is cheaper than fixing 12 cells.
A winter version of the population matrix is a later problem; build the summer one first.
## Matrix traps measured in use
- **Landmark creep:** a view facing AWAY from the river or the castle grew them back in 3 of 8 cells; the gate is blind
to distant low-texture tiles. Lock by naming the absence: "the view looks WEST, away from the river: there is NO
river, NO lake, NO water of any kind, NO castle; they are behind the camera." 5/5 after.
- **Furniture persistence in a "shut" state:** the bar counter survived in every take because the prompt only said
it was gone. Say what stands there instead: "under the roof there is NOTHING: no counter, no shelves, no casks; only
the bare snowy deck and the balustrade beyond." A take that keeps the counter can pass the geometry gate precisely
because it kept it; do not let the gate pick.
- **Guests on the shut terrace:** "2-3 guests on the balcony" in a winter cell put them on the terrace above it. The
noun beats the negation. State WHERE everyone is as a positive fact (on the street, the quay, the balcony "one full
story below the terrace") and repeat the terrace's untrodden snow.
- **"Steam vents along the river front"** become pale ghost figures. A recurring see-through figure is usually the
steam clause.
- **"Several people"** came back as 15-27. Use a HEADCOUNT lock ("no more than about N out of doors").
- **Dry cells carry the most defects** (fused pairs, ghosts, half-bodies on newel posts). Budget re-rolls or a local
fix for them.
- **Local fix** when a take passes every gate but carries one small defect: inpaint a guide, run edit-with-itself on
the guide (4 variants), register and color-match each locally, composite through your own feathered radial mask so
every pixel outside it stays byte-identical, re-gate, eye-check at 4-6x. One or two of four come back clean. Always
disclose fixed cells.
+47
View File
@@ -0,0 +1,47 @@
# Naming conventions
Names are differentiator-first so a folder sorts into its matrix and a display tool can key on the tokens.
## Canon frames (table-facing)
```
<Time> <Weather> <Letter> Exterior <Place> [<View name>].jpg
<Time> <Weather> <Letter> Interior <Place> <Room>.jpg
```
- Time: `Day` | `Sunset` | `Night` (add `Morning` only where a view's day light is a morning by decision).
- Weather: `Dry` | `Rain` | `Snow (light)` | `Snow (medium)` | `Snow (heavy)` | `Blizzard` | `Heavy Blizzard` |
`Ice Fog`. Files already named plain `Snow` are Snow (light) and are not renamed.
- Letter: the camera, `A`, `B`, `C` ... stable for the life of the place. **Letters can change at promotion** if a
review set used working letters; record the mapping in the place's truth file.
- Examples: `Day Dry A Exterior Library Approach.jpg`, `Night Snow (heavy) B Exterior Stonehaven Lodge.jpg`,
`Evening Packed A Interior Grimfrost Taproom.jpg` (population cells use `<Hour> <Density>` in the Time/Weather slots).
## Working files (lane folders)
```
plates/<V>_mass.png _depth.npy _oid.png _cls.png _cam.json _people.json _landmarks.json
out_<tag>/<V>_<pass>_t<k>.png pass = day | sunset | night | Day-Rain | Sunset-SnowLight | Morning-Packed ...
out_<tag>/qc/gate_out_<tag>.json, <id>_geo.jpg, <id>_figs.jpg, <id>_figzoom.jpg, CORNERS-<tag>-<pos>.jpg
jobs_<tag>.json + jobs_<tag>_PROMPTS.md
picks.json {"V": {"day": "<id>", "sunset": "<id>"}}
REPORT.md the lane's deliverable; the hand-off is its path
```
View keys `<V>` are `<Letter>_<slug>`: `A_first_view`, `C_gate_approach`, `R02_hall_from_door`.
## Place folders (canon)
```
<Place>/
<place>-truth.md what is canon (map-derived), what is PROPOSED, the camera letters and their meaning
Exterior/ the matrix frames
Rooms/<Room>/ empty masters, population cells, scenes
.sources/<DATE>-<lane>/ plates, picks, gate JSON, the prompts used, the REPORT (so a ruling is one edit + re-render)
```
## The report
Every run writes `REPORT.md` first and hands back its path. Sections, in order: Problem (one paragraph); Why (two
levels); What was built (every number a named constant and where it lives); Picks with their gate numbers; Failures
found and fixed; PROPOSED items (each with "if you rule otherwise, change X and re-render Y"); Open questions; Not done
and limits; **Cost** (`scripts/cost.py`: calls accepted and rejected, dollars, API minutes, local GPU minutes); How to
re-render after a ruling (the exact command chain).
+126
View File
@@ -0,0 +1,126 @@
# The pipeline in detail
The problem this solves: a renderer given a prompt plus the map as a reference puts the right *things* in the frame
and still invents the town: a square drawn as a broad plaza when the map draws it long and narrow, a river on the
wrong side, a metropolis with a cathedral for a town of twenty thousand. **Why 1:** a reference image moves the layout
but the proportions come from the model's idea of "a town square", and words cannot carry an aspect ratio. **Why 2:**
"camera from the south" asks the model to invent a 3D scene from a 2D plan, and every renderer fills that gap with
its prior. So geometry has to arrive as pixels, from the target camera. Splitting geometry (a block model, ray-marched)
from surface (a re-surfacing edit) removes the trade-off, and a correction becomes one edit to the model plus a
re-render of every camera. Across angles, every frame shows the same building by construction.
## 0. Inputs (write all of them down before step 1)
1. **The map bitmap** at native export resolution, and its **scale** in meters per pixel, calibrated on something of
known size (a canon building, a bridge span, a template-matched patch of a sheet whose scale you already know).
Two sheets of one town at different scales: template-match five footprint patches between them (NCC 0.92-0.96 in
practice) and resample one to the other, so one segmentation recipe applies to both.
2. **Never re-export the map to fix a fit.** Map tools rarely reproduce the exact position and zoom, and a re-export
that differs ever so slightly moves every pin and breaks every model registered on the sheet. Move a pin to a
better-fitting building that already exists, or paste a small patch bitmap onto the existing sheet and pixel-diff
the result so the change stays inside the patch box.
3. **The subject's extent** in map px. For a square, street or yard the extent is the open ground, never the open
ground plus its frontages.
4. **Ridge directions** of the buildings that matter, read from a drawn ridge highlight at 12x, else from the shingle
course direction at 10x, never from proportion or shading.
5. **The checkable facts** the frame must show (five or six: elongation, a closing range, a saw-tooth of gables, the
ways in, the tracks, open ground clear of buildings). The plate gate scores these.
6. **Target cameras.** Pick the camera that *presents* the defining feature: a saw-tooth of gable ends reads from
across the square, not along it. Find streets from an occupancy top-down of the heightfield, never by eye on the map
(a first approach camera landed inside a house row).
7. **What is canon and what you are about to PROPOSE.** Terrain is almost never on a map; walls and gates may not be
drawn; heights are never drawn. Everything not on the map is a proposal and lives as a named constant.
## 1. Segment (`segment_map.py`)
Roof, tree and water masks. Trees are the cauliflower glyphs (dense short dark strokes in compact blobs); roofs are
darker than the parchment and not a tree, with the cast-shadow halo stripped by a 1 px erosion; water is the teal.
**Eyeball the check image.** Known misses: two "trees" on a square that were building-edge detail; a big tree glyph at
a gable read as roof; a sheet whose tree glyphs cannot be separated from roofs within ~50 m of the subject (replace
that patch with houses fitted to the roof mask minus hand-placed tree glyphs).
## 2. Mass (`massing.py`)
Footprints straightened (polygon approximation at 1 px), slivers opened away with a 2 m disc, pieces under 40 m2
dropped (slivers become ruins when re-surfaced), merged blocks split into 8-15 m houses with a 1-cell gap (separate
houses must be separate in pixels or the renderer re-slices them into an 11-gable "caterpillar"), a gable over each
fitted rectangle (fill > 0.70, ridge on the long axis) else a capped hip from the distance transform, trees as lumpy
domes, roof components over water as bridge decks. **Heights are proposed by wealth zone** (the map gives footprints,
not heights). Landmarks you model by hand are cut out of the auto-massing. If a frozen earlier tool has a known
offset bug in its roof heights, fix it in your copy, not by prompt.
A landmark with canon dimensions goes into `scene.json` as analytic solids: prisms traced from the map, boxes, cones,
gables. Watch for a convex split of an L-shaped wing that puts battlements on the internal seam ("a wall across the
roof"); check the untextured plate for it.
## 3. Terrain and roads (optional, all PROPOSED)
A plateau = the town's drawn extent closed and grown by a margin; a valley floor along the river; walls rising with
distance from the floor (a glacial trough profile: gentle toe, faces steepening to ~30 degrees); ridged noise. Roads
benched in afterwards, at a grade cap (10 %), on a 1 m layer that cuts a broad shelf (no trench). Model where a built
feature ENDS: if a quay, wall or paving just stops, give the far side its own visibly different geometry, or the renderer
continues the built feature to the frame edge. When shaping terrain to match a painting's skyline, scale the massif
about the painter's eye, never shape terrain by sight lines. The renderer draws its own switchbacks, so gate roads
tolerantly.
## 4. Proxies (`scene.json` people, carts, horses)
True-scale mannequins (1.60-1.80 m, varied), carts, pack horses, placed where the story needs them. They are the scale
anchors: the renderer dresses each where it stands, so the proxies BECOME the population and the headcount per cell is
how many proxies that cell's plate carries. Keep proxies 10 m or more from an eye-level camera and off the frame edge (a
mannequin cut by the edge becomes a stone post with a ball finial, 4/4). Never a proxy mostly hidden behind another
without its occluder.
## 5. Plates (`render_plate.py`)
One pinhole camera per view with an optional vertical lens shift (render level and shift, never pitch up: a pitched-up
plate tilted the verticals 1-2.6 degrees in every take). A 2048x1152 plate takes 1-15 minutes on 32 cores; run views
in parallel. The plate carries a window/door rhythm on the walls (the renderer builds real shuttered houses from it)
and sun shadows from the hour you will name in the prompt. Outputs: the plate, depth, a solid-id buffer, a class map,
the camera, the projected people table, the projected landmarks.
**Plate gate before any renderer call** (references/gates.md section 0).
## 6. Re-surface (`build_jobs.py`, `render_batch.py`)
IMAGE 1 = the plate; IMAGE 2.. = material and light references from a *different* camera (a register of the town's
materials, a canon landmark photo), each with a stated purpose and an "ignore its camera and composition" clause. The
prompt blocks are in references/prompting.md. Three to four takes per view, for choice not control (the model has no
seed and no strength dial; wording barely moves geometry). Concurrency 4-8 in flight was smooth; 16-20 with several
4 MB references hit upload timeouts. Measured cost per call: about $0.06 with one reference and $0.09 with four, at
2048x1152 high quality on the hosted model used.
Day frames are fresh re-surfaces. **Sunset, night and morning are relights** (light-only edits) of the picked day
frame, which hold geometry to within 0.15 % scale and 2 px.
## 7. Gate (`gate.py`, `qc_sheet.py`)
references/gates.md. In one line: drift and ECC against the plate; landmark-region correlation; skyline fit and the
invented-structure check on wide views; figure brackets; the corner sweep; then the eye on the contact sheet for what
instruments cannot see (occlusion, water, extra people, signs).
## 8. Matrices (`matrix_jobs.py`)
references/matrices.md: the time x weather 9-square per camera, snow levels and route clearance, and the population x
time matrix for every venue with people in it, sized by tier.
## 9. Interiors
The same method indoors: a convex-solid room model (box, oriented box, gable prism, walls with openings, mannequins),
a plate per camera with a color key (orange = fire, pale warm = sunlit opening, pale blue = sky opening, black = dark
doorway), IMAGE 1 = "the set, not a style reference; same tripod". 51/51 held exits, hearth wall, counter and stair.
The only failure class: windows invented in an internal partition the prompt could read as an exterior wall. Multiple
angles of one room agree by construction, and the same model takes proxies for scenes. The empty master is the keeper
that every population cell and scene descends from.
## 10. Deliver
Picks and alternates, the QC sheets, a README for the GM (what to show when, the PROPOSED items with "if you rule
otherwise", the open questions, the known flaws), the REPORT with its Cost line. Verify delivery by fetching back
and hashing. Promote gated work straight to canon; a human review entry is the expensive unit (references/effort-tiers.md).
## How to re-render after a ruling
Edit the named constant (in `scene.json`, the zones, the terrain, the camera) -> re-render the affected plates ->
re-run the day jobs for those views -> gate -> relight from the new picks -> re-run the matrix cells that descend from
them. Because every downstream frame descends from a plate, a ruling is one edit and a known chain, never a redraw.
+106
View File
@@ -0,0 +1,106 @@
# Prompting a re-surfacing model
The method only works because the prompt does one job: **tell the renderer that IMAGE 1 is the truth and that its
job is surface.** Everything else in the prompt protects that premise from the renderer's priors. The blocks in
`examples/prompts.example.json` are the wording that measurably held; this file explains what each one is for and
the failures that produced it.
## Principles
1. **Geometry arrives as pixels, never as words.** Words cannot carry an aspect ratio, a distance or a height. The
plate carries them. A prompt that argues with the plate loses; a prompt that argues with the renderer's prior wins
only sometimes. Fix geometry in the model and re-render; never by wording.
2. **The renderer photographs the plate's mistakes as faithfully as its truths.** There is no wording that makes it
correct a wrong block. Gate the plate first.
3. **Per camera, from a visibility list.** Enumerate what THIS camera sees. State what it does NOT see as a positive
instruction ("the balcony is on the far side and is not visible from here; do not show a balcony"). A feature named
in a prompt will be rendered somewhere; if its true position is occluded, the renderer relocates it. One shared
feature list reused across angles is exactly what causes this (9/9 wrong with a shared list, 0/8 with per-camera
lists).
4. **Name absence; describe what is there instead.** "No counter" keeps the counter. "Under the roof there is
nothing: only the bare deck and the balustrade beyond" removes it.
5. **A noun is a vote for the noun.** "No more than a few lanterns" spawns lantern-carriers. "Steam vents" spawn
ghosts. "Sledge-packed" turns a hut into a horse and sledge (15 of 17 takes). To get less of something say less about
it; to get none, say nothing, or say what fills the space instead.
6. **State construction facts, not adjectives.** "Prosperous" plus "apron" gives modern artisan workwear. "The cut is
T-shaped, pulled on over the head with no opening down the front; soft turn-shoes with no laces and no heels; no
waistcoat, no lapels, no buttons" gave 13/13 period outfits.
7. **Material references come from a DIFFERENT camera than the plate.** A same-camera materials board pulled the
composition toward the board's framing (0/3), while the same board was harmless on cameras it did not resemble.
8. **Every constraint you add gets its own QC.** If you wrote "no sun disc", check for a sun disc.
## The blocks
| block | job | what it fixed |
|---|---|---|
| `resurface` | the premise: IMAGE 1 is the ground truth for position, size and shape; add surface only; keep the camera | the whole method |
| `people` | the mannequins ARE the people; dress each where it stands at its size; add nobody; carts and animals likewise; then the period cut as construction facts | proxies become the population; figure scale holds at street level |
| `eyeline` | the camera is at a standing adult's eye height, so every standing adult's EYES are ON THE HORIZON LINE | near walkers went from +25-28 % to +5-13 % |
| `nomodern` | the list of modern objects by name, plus NO TEXT of any kind | lamp posts, wire, glazing, lettering, watermarks |
| `setting` | climate, season and ground cover as facts, tied to what the plate shows ("woods exactly where image 1 shows its darker patches") | season drift, snow on summer slopes |
| `town` | what the town is, materials by wealth quarter, each landmark's shape in two clauses, and **the list of large things the renderer likes to invent for a town of this kind, negated** ("no city wall, no cathedral, no spires, no domes, no brick") | invented cathedrals, walls, metropolis skylines |
| per-view `intro` | what the camera is, where it stands, what fills the frame, and what each attached image is FOR ("IMAGE 2 is another part of this same town: use it ONLY for materials and light; ignore its buildings, camera and composition") | reference bleed |
| per-view `keep` | KEEP EXACTLY: the skylines, the road's bends, the river's line, each landmark by position, every traveler at its size | the renderer's "improvements" |
| per-view `frame` | **FRAMING LOCK** with measured band positions in % of the frame, plus **SIZES BY THE NEAREST OBJECT** (the palisade is 3 m, so adults reach a little above half of it; the posts are 5.6 m, so the watchmen reach a third) | zooms of 4-10 % on wide views (0/4 -> pass); giants at a gate (r3 clean after two rounds of oversized figures); a cropped facade restored to full height (0/3 -> 4/4) |
| `lights.*` | the hour, where the sun is relative to the CAMERA ("behind the camera and a little to the right"), "shadows fall away from the camera exactly as image 1 shows them", no sun disc | a sun disc drawn in a frame that faces away from the sun |
| `relights.sunset` | light only; and when the camera faces AWAY from the sunset, say so: "THE SKY IN THIS PICTURE IS THE EASTERN SKY ... a dusky-pink Earth's-shadow band, NO glow" | a bright orange sunset painted in the east, 5 views out of 5, two rounds running |
### Framing-lock numbers
Measure them on the plate: the row (in % of frame height) where the far ground meets the sky, where the town band
starts and ends, where a landmark's ridge sits; the columns where the road enters the bottom edge. The lock quotes
them. For wide foreground plates (a small town low in the frame behind an empty field) add the explicit "the town is
SMALL in this view and sits LOW in the frame (houses from about 71 % to 96 % of the frame height). Do not move the
town up toward the mountains and do not enlarge it." Giving a bounding box alone did not help; the sentence did.
### Scale by relation, not by number
The renderer ignores a stated size but obeys a physical relation it has to draw. A 1 m character prompted as "about one
meter tall" rendered at 1.4-1.5 m; with "her hand rests flat on top of his hood, her arm hanging straight down" he
rendered at 1.0-1.1 m. The same lever works for gateposts, carts and counters: "the cart's wheels come up to a man's
chest", "the counter reaches their hips".
## Wealth tier as visual vocabulary
Wealth buys **space, permanence and uniformity**, in that order, and only at the far end **ornament with no function**.
The poor share walls; the rich own the ground they do not build on. Cheap is patched in several materials; expensive is
one material carried across the whole structure. Below the wealthy rung, status markers read as a lie (a carved gate on
a patched roof). At the top, prefer functionless carved detail over expensive-looking surfaces: a plain carved stone
beast beside a door says more than gilding, because carving cannot be faked.
Put the tier into the prompt as facts about the subject: its ground surface (mud and ruts / beaten earth / gravel /
flags), its boundary (none / salvaged boards / coursed wall with a formal gate), its spacing (touching / a gap / land
held empty on purpose), its roof (patchwork / one material, repairs matched / slate, ridge true). Never assert a tier
against the map: a building the map draws hemmed in stays hemmed in; the tier shows in roof, surface and boundary.
The strongest single interior tell is the counter material: rough wood -> scrubbed -> polished dark hardwood -> marble.
**Glass follows the wealth tier; it is never banned outright.** Low and modest venues: wood, horn, pewter, ceramic,
horn or oiled-skin windows, at most a few prized pieces. Comfortable: glass lamp chimneys, some bottles, leaded panes.
Wealthy: clear glassware and glazed windows are normal. Only electric light is banned. A blanket "no glass" was a
lane's over-generalization of one district's local rule and produced false defects for a week.
**Same-rung houses come out interchangeable** (a block model carries footprint and roofline; the tier fixes materials;
neither says what the house does). Add each house's tell in the brief: one emblem sign (never lettering) and its trade
visible at the frontage.
## Things that failed and the wording that fixed them
- A pitched-up plate: the renderer tilted the verticals 1-2.6 degrees and shrank the frame. Fix in the model: render
the plate level with a vertical lens shift.
- A door "filling the recess" built arch-shaped doors. "A rectangular door under the tympanum, which stays stone."
- A facade that fills the frame grew a ~90 px sky sliver because the prompt named the sky. "No sky in view."
- Open books grow pseudo-script even under the full no-text clause. "Every book is CLOSED, even though IMAGE 1 shows
open books; loose sheets face down."
- "Two fingers raised" came out as a modern V sign, 4/4. Drop the gesture; say "no hand sign".
- "The roof hatches are thrown open" took the roof off the room. "The room is whole and roofed; only two small
square hatches, each about an arm-span across."
- A people-free door view came back with people on the stair. An explicit people-free clause, 6/6 clean.
- Window columns, partitions and end gables grow windows the plate does not have. Per view: "that wall has no
window", "no other openings". Check partitions a prompt might read as an exterior wall.
- A plume of smoke from a building with no hearth under an "Ice Fog, chimney smoke rises" cell. Add a no-smoke clause
for that building.
- Flags with crosses on an old plate read as modern national flags. "Plain single-color streamers, even though IMAGE 1
shows crosses."
- Output-stage safety refusals on scenes with a dying patient ran ~14 %; softening the wording lowers but does not
remove it. Budget extra takes; after an outright refusal the lane stops and reports it rather than switching
renderers on its own.