docs(review): embed every screenshot inline so the review happens in the file

Each shot now has its own section with the image embedded, its view, expected
content and both verdicts, plus a status table at the top that links to them.
A path alone was not a review: the owner had to open five PNGs to judge a pass.

Also recorded in AGENTS.md (a path is not a review; approval ticks both the section
and the table row), the two retail assets and tools in the arc42 building block
view and the combined architecture.md, and prettier-formatted the changed files.
This commit is contained in:
zwitschi committed 2026-11-09 09:33:23 +01:00
1 parent 2614d259aa
commit c53386fcf4
6 files changed
+99 -59

No files matched your search

+2 -2
View File
@@ -210,8 +210,8 @@ Any change that affects the game's appearance — meshes, materials, lighting, l
1. Run `Tools/render_screenshots.sh` (rebuilds `Game/GigLine/Content/Test/ReviewMap.umap` from current content, runs the game on it, captures the fixed camera list, copies the PNGs into `Screenshots/`).
2. Optional pre-check with a vision model: `Tools/judge_screenshot.py --image <shot.png> --expect "<what it should show>"` (or `--shots` to run every shot in the README) flags likely-missing content before a human looks. It reads `OPENROUTER_API_KEY` from `.env` (ignored). Small helper only — it never replaces the human verdict.
3. Update `Screenshots/README.md`: one row per screenshot with what it shows and an approval state; describe any new shots or scene changes in the same change.
3. Update `Screenshots/README.md`: the image is **embedded inline** (`![alt](demo/<shot>.png)`) with its view, expected content, verification and approval state, plus one row in the status table at the top. The point is that the review happens in the file; a path alone is not a review. Describe any new shots or scene changes in the same change.
4. The PNGs **are committed** so reviewers see exactly what the build rendered (`.gitignore` does not exclude them). Keep them in sync with this README: drop retired shots in the same change.
5. Wait for the user's approval before treating a visual change as done; record approval by ticking the table in `Screenshots/README.md`.
5. Wait for the user's approval before treating a visual change as done; record approval by ticking both the shot's section and its row in the status table in `Screenshots/README.md`.
New content that needs a different camera angle gets a new entry in the shot list in `Tools/ue_build_review_map.py`.
+10 -22
View File
@@ -1,11 +1,10 @@
# Reference analysis — retail frontage, 0.1.6
Phase 0 of the `references` pack (reference-image-match). Written before any geometry,
because the pass that produced the hero façade skipped it and cost two rebuilds.
Phase 0 of the `references` pack (reference-image-match). Written before any geometry, because the pass that produced the hero façade skipped it and cost two rebuilds.
## Source
| | |
| | |
| --- | --- |
| Image | `Art/reference/retail-neighbours/01-lee-drug-and-neighbor.jpg` (1920×953) |
| Author / licence | Gb321, own work, **CC BY-SA 4.0** — attribution required |
@@ -13,19 +12,13 @@ because the pass that produced the hero façade skipped it and cost two rebuilds
| Description | "Lee Drug and 6806 Hollywood Buildings in Hollywood" |
| Coverage | Both target buildings in one frame, mid-morning sun from the south-east |
**One photograph is the whole evidence base for 6800 and 6806–6820.** It is a street-level
oblique, not an elevation: verticals converge, the ground floor of 6806–6820 is partly behind
a parked car, and the Lee Drug shopfront is behind a bus. Everything below that the photo does
not resolve is marked *assumed* and is carried into the part report.
**One photograph is the whole evidence base for 6800 and 6806–6820.** It is a street-level oblique, not an elevation: verticals converge, the ground floor of 6806–6820 is partly behind a parked car, and the Lee Drug shopfront is behind a bus. Everything below that the photo does not resolve is marked _assumed_ and is carried into the part report.
**6822 Budget has no photograph.** It is a 6.0 m × 5.5 m single-storey sliver west of
6806–6820, and the TODO item already records that Commons has nothing usable. It stays a
blockout extrusion and the item is deferred rather than guessed.
**6822 Budget has no photograph.** It is a 6.0 m × 5.5 m single-storey sliver west of 6806–6820, and the TODO item already records that Commons has nothing usable. It stays a blockout extrusion and the item is deferred rather than guessed.
## Measured (not from the photo)
From `Geo/raw/osm-api-map-2026-11-06.osm` and the blockout, in the shared frame
(metres, X east, Y north, Z from the project datum):
From `Geo/raw/osm-api-map-2026-11-06.osm` and the blockout, in the shared frame (metres, X east, Y north, Z from the project datum):
| Building | OSM way | X | Front face Y | Height | Depth |
| --- | --- | --- | --- | --- | --- |
@@ -33,9 +26,7 @@ From `Geo/raw/osm-api-map-2026-11-06.osm` and the blockout, in the shared frame
| 6806–6820 | 424024150 | −66.08 … −33.07 | −12.52 | 12.10 m | 30.8 m |
| 6822 Budget | 424024144 | −78.54 … −72.52 | −12.92 | 5.50 m | 15.4 m |
Both target buildings are 12.10 m tall, which makes the *relative* proportions in the photo
directly usable: the parapet line, the cornice and the shopfront line can be read as fractions
of the frame height.
Both target buildings are 12.10 m tall, which makes the _relative_ proportions in the photo directly usable: the parapet line, the cornice and the shopfront line can be read as fractions of the frame height.
## 6800 Lee Drug — reading
@@ -44,9 +35,9 @@ of the frame height.
| Subject | Corner retail block at Hollywood × Highland; the street face and the corner return are both visible |
| Silhouette | Long low box, broken by a **rounded corner tower** that rises above the frontage parapet; the parapet is **stepped**, not flat |
| Storeys | Two zones, not storeys: a tall shopfront zone and a single tall display wall above it |
| Proportion (vertical) | Shopfront ≈ 0 → 0.36 H; bronze cornice ≈ 0.36 → 0.43 H; mural + lettering wall ≈ 0.43 → 0.82 H; stepped parapet ≈ 0.82 → 1.0 H (*assumed split; read off the frame, ±0.03 H*) |
| Proportion (vertical) | Shopfront ≈ 0 → 0.36 H; bronze cornice ≈ 0.36 → 0.43 H; mural + lettering wall ≈ 0.43 → 0.82 H; stepped parapet ≈ 0.82 → 1.0 H (_assumed split; read off the frame, ±0.03 H_) |
| Proportion (horizontal) | Corner tower occupies ≈ 4 m of the east end; eight mural panels at roughly 2.2 m centres along the frontage |
| Colour | Cream stucco wall `#EDE6D8`, bronze/brown cornice `#6B4A2F`, near-black mural plates `#1C1A18`, dark glazing `#20262A` (*sampled from the frame*) |
| Colour | Cream stucco wall `#EDE6D8`, bronze/brown cornice `#6B4A2F`, near-black mural plates `#1C1A18`, dark glazing `#20262A` (_sampled from the frame_) |
| Unique features | Stepped Deco parapet with 4 horizontal reveal lines; projecting bronze cornice; row of black celebrity-portrait panels; large dark "SOUVENIRS OF …" lettering on the upper wall; shopfront glazing with slim mullions |
| Mood | 1930s Deco retail, freshly painted, bright midday |
@@ -55,17 +46,14 @@ of the frame height.
| Category | Observation |
| --- | --- |
| Silhouette | Flat-fronted two-storey block; parapet steps up in fins at the west end |
| Proportion (vertical) | Shopfront ≈ 0 → 0.32 H; burgundy fascia band ≈ 0.32 → 0.38 H; window storey ≈ 0.38 → 0.62 H; blank wall + parapet ≈ 0.62 → 1.0 H (*assumed*) |
| Proportion (vertical) | Shopfront ≈ 0 → 0.32 H; burgundy fascia band ≈ 0.32 → 0.38 H; window storey ≈ 0.38 → 0.62 H; blank wall + parapet ≈ 0.62 → 1.0 H (_assumed_) |
| Horizontal | Brown pilaster strips divide the frontage into roughly 3 m bays; seven upper windows across 33 m |
| Colour | Same cream stucco; brown pilasters `#6B4A2F`; **burgundy-green** fascia `#5B3A3A`; white window frames |
| Unique features | Banded parapet with 3 reveal lines; white-framed upper windows with security bars; shopfront glazing behind a burgundy fascia |
## Camera match (for the review shot)
The photo is a street-level oblique from the **north** side looking south-east, subject filling
~80 % of the frame width. The demo review shot must reproduce that: camera at 1.7 m on the
north sidewalk, yaw toward the south frontage, 35–42° lens, both buildings in frame. A wide
block view will not compare usefully against this crop.
The photo is a street-level oblique from the **north** side looking south-east, subject filling ~80 % of the frame width. The demo review shot must reproduce that: camera at 1.7 m on the north sidewalk, yaw toward the south frontage, 35–42° lens, both buildings in frame. A wide block view will not compare usefully against this crop.
## Assumptions to carry into the model report
+4 -2
View File
@@ -47,6 +47,7 @@ Static meshes and materials in `/Game/Hollywood/Site/`:
| `SM_HeroFacade` | El Capitan Entertainment Centre detailed façade |
| `SM_ElCapitanTheatre`, `SM_Budget_6822`, `SM_Hollywood_6806`, `SM_Hollywood_6902`, `SM_Hollywood_6922`, `SM_LeeDrug_6800` | South block frontage (6 buildings) |
| `SM_Madame_Tussauds`, `SM_TCL_Chinese_Theatre` | North-side buildings (within 50 m) |
| `SM_Retail_LeeDrug`, `SM_Retail_6806` | Retail trim over 6800 and 6806–6820, modelled from their own photograph (`Tools/retail_frontage_build.py`, staged as `RetailTrim_*`). `6822 Budget` stays a bare volume: no photograph exists. |
### Art Pipeline
@@ -54,13 +55,14 @@ Python scripts in `Tools/` drive the content pipeline:
| Script group | Purpose |
| --- | --- |
| `export_*`, `hero_facade_build` | Blender headless export (FBX) |
| `ue_import_*`, `ue_hero_facade_import` | Unreal headless import + placement |
| `export_*`, `hero_facade_build`, `retail_frontage_build`, `theatre_trim_build`, `facade_kit_build` | Blender headless export (FBX); trim builders work in world coordinates |
| `ue_import_*`, `ue_hero_facade_import`, `ue_import_retail_detail` | Unreal headless import + placement |
| `ue_build_demo_map`, `ue_build_review_map` | Map assembly (lighting, meshes, player start) |
| `ue_create_input_assets` | Enhanced Input actions + mapping context |
| `render_screenshots.sh` | Screenshot capture pipeline |
| `judge_screenshot.py` | Vision-model pre-check (optional) |
| `input_emulation.py`, `input_test.py` | OS-level virtual keyboard/mouse injection for input verification |
| `Tools/_common.py` | Pure helper shared by Blender builders, importable without Blender (bay layout) |
| `Tools/tests/` | Stdlib `unittest` tests for the pure parts of the tools (`requirements-tools.txt`) |
| `Geo/tools/mapbox_buildings.py` | Second height source: Mapbox `mapbox-streets-v8` building data vs our OSM heights |
+4 -2
View File
@@ -191,6 +191,7 @@ Static meshes and materials in `/Game/Hollywood/Site/`:
| `SM_HeroFacade` | El Capitan Entertainment Centre detailed façade |
| `SM_ElCapitanTheatre`, `SM_Budget_6822`, `SM_Hollywood_6806`, `SM_Hollywood_6902`, `SM_Hollywood_6922`, `SM_LeeDrug_6800` | South block frontage (6 buildings) |
| `SM_Madame_Tussauds`, `SM_TCL_Chinese_Theatre` | North-side buildings (within 50 m) |
| `SM_Retail_LeeDrug`, `SM_Retail_6806` | Retail trim over 6800 and 6806–6820, modelled from their own photograph (`Tools/retail_frontage_build.py`, staged as `RetailTrim_*`). `6822 Budget` stays a bare volume: no photograph exists. |
### Art Pipeline
@@ -198,13 +199,14 @@ Python scripts in `Tools/` drive the content pipeline:
| Script group | Purpose |
| --- | --- |
| `export_*`, `hero_facade_build` | Blender headless export (FBX) |
| `ue_import_*`, `ue_hero_facade_import` | Unreal headless import + placement |
| `export_*`, `hero_facade_build`, `retail_frontage_build`, `theatre_trim_build`, `facade_kit_build` | Blender headless export (FBX); trim builders work in world coordinates |
| `ue_import_*`, `ue_hero_facade_import`, `ue_import_retail_detail` | Unreal headless import + placement |
| `ue_build_demo_map`, `ue_build_review_map` | Map assembly (lighting, meshes, player start) |
| `ue_create_input_assets` | Enhanced Input actions + mapping context |
| `render_screenshots.sh` | Screenshot capture pipeline |
| `judge_screenshot.py` | Vision-model pre-check (optional) |
| `input_emulation.py`, `input_test.py` | OS-level virtual keyboard/mouse injection for input verification |
| `Tools/_common.py` | Pure helper shared by Blender builders, importable without Blender (bay layout) |
| `Tools/tests/` | Stdlib `unittest` tests for the pure parts of the tools (`requirements-tools.txt`) |
| `Geo/tools/mapbox_buildings.py` | Second height source: Mapbox `mapbox-streets-v8` building data vs our OSM heights |
+78 -28
View File
@@ -12,19 +12,86 @@ Tools/render_screenshots.sh --verify
Stages the demo shot cameras, runs the game on `/Game/Hollywood/DemoMap`, copies the PNGs into `Screenshots/demo/` and then runs [`Tools/visual_loop.py`](../Tools/visual_loop.py) `--verify` to check that each shot still shows the content its expectation describes. About a minute.
## The shot list
## Status at a glance
Each shot has an **expectation** in [`Tools/visual_targets.json`](../Tools/visual_targets.json) — the content the capture must show — and a verification state produced by `--verify`: it fails if the frame is blank, the wrong size, or has no tonal range.
Every shot is embedded below, in order, so the whole review happens in this file.
| # | File | View | Expected content | Verified | Approved |
| --- | --- | --- | --- | --- | --- |
| 1 | `demo/review-demo-spawn-view.png` | north sidewalk | The whole south block: the neoclassical hero façade between its neighbours, both sidewalks and the road in the foreground | ☑ 2026-11-09 | ☑ 2026-11-09 |
| 2 | `demo/review-demo-street-level.png` | eye height, north side | Street level: the hero colonnade with the adjacent frontage buildings either side, shopfronts at pavement level | ☑ 2026-11-09 | ☑ 2026-11-09 |
| 3 | `demo/review-demo-crossing.png` | along the crosswalk | The designated mid-block crossing (s=130 m, UE X −14956): zebra bars on the asphalt, south frontage and colonnade behind | ☑ 2026-11-09 | ☑ 2026-11-09 |
| 4 | `demo/review-demo-north-buildings.png` | across the Boulevard | The two north-side buildings (TCL Chinese Theatre, Madame Tussaud's) from the south side, full height in frame | ☑ 2026-11-09 | ☑ 2026-11-09 |
| 5 | `demo/review-demo-retail-frontage.png` | north sidewalk, level horizon | The retail run beside the hero: 6800 Lee Drug's bronze cornice, mural row and parapet next to 6806–6820's burgundy fascia, pilasters and window storey | ☑ 2026-11-09 | ☐ pending |
| # | Shot | Verified | Approved |
| --- | ------------------------------------- | ------------ | ------------ |
| 1 | [Spawn view](#1-spawn-view) | ☑ 2026-11-09 | ☑ 2026-11-09 |
| 2 | [Street level](#2-street-level) | ☑ 2026-11-09 | ☑ 2026-11-09 |
| 3 | [Crossing](#3-crossing) | ☑ 2026-11-09 | ☑ 2026-11-09 |
| 4 | [North buildings](#4-north-buildings) | ☑ 2026-11-09 | ☑ 2026-11-09 |
| 5 | [Retail frontage](#5-retail-frontage) | ☑ 2026-11-09 | ☐ pending |
Approval is per shot, in the table above (owner review of the `0.1.4` set, recorded in [`Docs/reviews/0.1.4-review.md`](../Docs/reviews/0.1.4-review.md)). Add a row when a shot is added; remove the file in the same change when a shot is retired.
**Verified** is what `--verify` reports: the frame is not blank, is the right size, and has tonal range. **Approved** is the owner's verdict, recorded here. Each shot also has an **expectation** in [`Tools/visual_targets.json`](../Tools/visual_targets.json) describing the content it must show.
---
## 1. Spawn view
![Spawn view: the whole south block from the north sidewalk](demo/review-demo-spawn-view.png)
- **File:** `demo/review-demo-spawn-view.png`
- **View:** north sidewalk, 14 m back, level horizon
- **Expected content:** the whole south block — the neoclassical hero façade between its neighbouring buildings, both sidewalks and the road in the foreground
- **Verified:** ☑ 2026-11-09 · **Approved:** ☑ 2026-11-09
---
## 2. Street level
![Street level: the hero colonnade at eye height](demo/review-demo-street-level.png)
- **File:** `demo/review-demo-street-level.png`
- **View:** eye height, north side
- **Expected content:** the hero colonnade with the adjacent frontage buildings either side, shopfronts at pavement level
- **Verified:** ☑ 2026-11-09 · **Approved:** ☑ 2026-11-09
---
## 3. Crossing
![Crossing: the designated mid-block crossing with zebra bars](demo/review-demo-crossing.png)
- **File:** `demo/review-demo-crossing.png`
- **View:** from the north sidewalk along the crosswalk
- **Expected content:** the designated mid-block crossing (s=130 m, UE X −14956) — zebra bars on the asphalt, south frontage and colonnade behind
- **Verified:** ☑ 2026-11-09 · **Approved:** ☑ 2026-11-09
---
## 4. North buildings
![North buildings: TCL Chinese Theatre and Madame Tussaud's from the south](demo/review-demo-north-buildings.png)
- **File:** `demo/review-demo-north-buildings.png`
- **View:** across the Boulevard from the south side
- **Expected content:** the two north-side buildings (TCL Chinese Theatre, Madame Tussaud's), full height in frame
- **Verified:** ☑ 2026-11-09 · **Approved:** ☑ 2026-11-09
---
## 5. Retail frontage
![Retail frontage: 6800 Lee Drug and 6806–6820 from across the street](demo/review-demo-retail-frontage.png)
- **File:** `demo/review-demo-retail-frontage.png`
- **View:** north sidewalk, level horizon, 68° lens
- **Expected content:** the retail run beside the hero — 6800 Lee Drug's bronze cornice, mural row and parapet next to 6806–6820's burgundy fascia, pilasters and window storey
- **Verified:** ☑ 2026-11-09 · **Approved:** ☐ pending
Read this one against the reference photograph it was modelled from: `Art/reference/retail-neighbours/01-lee-drug-and-neighbor.jpg` (Gb321, CC BY-SA 4.0).
Known gaps in this first pass, recorded rather than hidden:
- **The parapet reads as a blank white band.** It is modelled as one 2.18 m wall with four 0.10 m reveal strips, and at review distance the strips disappear into the wash.
- **The mural row and lettering band barely read.** They are shallow plates (0.06–0.08 m) on the same plane as the wall; they need either depth or a decal before they read as the photographs' black-framed panels.
- **The corner tower is a plain cylinder with two cap rings** — the stepped Deco profile in the photograph is richer than that.
- **The camera crops the east end** of Lee Drug at 68° from the north sidewalk.
- **6822 Budget is untouched** and still a bare blockout volume: no photograph of it exists.
---
## The iteration loop (uncommitted)
@@ -41,7 +108,7 @@ Note the comparison is only meaningful when the shot and the reference frame the
## Scene conventions
- **Demo map** (`/Game/Hollywood/DemoMap`): fixed daytime — sun pitch −62 / yaw 120 (intensity 4, warm), sky light 2.6, sky atmosphere, height fog, fixed exposure.
- **Cameras**: elevation shots sit at their target height (pitch 0, so verticals stay parallel) and use a 42–55° lens to fill the frame from across the street.
- **Cameras**: elevation shots sit at their target height (pitch 0, so verticals stay parallel) and use a 42–68° lens to fill the frame from across the street.
- **Materials**: every surface carries a look-developed material from `Tools/ue_build_demo_map.py` — noise-blended base colour, masonry coursing, and a generated texture set (`Tools/generate_facade_textures.py`) sampled world-aligned. Explicit roughness and specular per surface type.
## Known cosmetic issues
@@ -50,20 +117,3 @@ Note the comparison is only meaningful when the shot and the reference frame the
- Banners sit on the column line rather than flush to the wall (they hang on the columns in the photographs, so this is acceptable).
- Between kerb and building line the walkable surface is the terrain mesh, not a modelled pavement.
- The El Capitan Theatre has no marquee or blade sign yet — the feature that makes it read as itself.
## 0.1.6 retail frontage — what to look at
Shot 5 is the review shot for this pass. Read it against
`Art/reference/retail-neighbours/01-lee-drug-and-neighbor.jpg` (Gb321, CC BY-SA 4.0).
Known gaps in this first pass, recorded rather than hidden:
- **The parapet reads as a blank white band.** It is modelled as one 2.18 m wall with four
0.10 m reveal strips, and at review distance the strips disappear into the wash.
- **The mural row and lettering band barely read.** They are shallow plates (0.06–0.08 m) on
the same plane as the wall; they need either depth or a decal before they read as the
photographs' black-framed panels.
- **The corner tower is a plain cylinder with two cap rings** — the stepped Deco profile in the
photograph is richer than that.
- **The camera crops the east end** of Lee Drug at 68° from the north sidewalk.
- **6822 Budget is untouched** and still a bare blockout volume: no photograph of it exists.
+1 -3
View File
@@ -15,9 +15,7 @@ Suggested blender skills: **references** (reference-image-match), **archviz**, *
### Patch tasks - active - session-5598ce7e-27e3-4c64-bb49-c04a4a31ee58 (branch `facade-retail-0.1.6`)
- [A] **Model 6800 Lee Drug and 6806–6820 from their own reference.** First pass 2026-11-09 on branch `facade-retail-0.1.6`: `Tools/retail_frontage_build.py` builds both façades from the one photograph (`Art/reference/retail-neighbours/`, Gb321 CC BY-SA 4.0) with the analysis in `Art/blender/retail/ref-analysis.md`;
`Tools/ue_import_retail_detail.py` imports them and the demo builder stages them as `RetailTrim_*`. The generic façade kit is now skipped on these two, so their walls carry one façade language instead of two.
**Open on this item:** the parapet reads as a blank band, the mural row and lettering band do not resolve at review distance, the corner tower is a plain cylinder, and the review camera crops the east end — all listed in `Screenshots/README.md`.
- [A] **Model 6800 Lee Drug and 6806–6820 from their own reference.** First pass 2026-11-09 on branch `facade-retail-0.1.6`: `Tools/retail_frontage_build.py` builds both façades from the one photograph (`Art/reference/retail-neighbours/`, Gb321 CC BY-SA 4.0) with the analysis in `Art/blender/retail/ref-analysis.md`; `Tools/ue_import_retail_detail.py` imports them and the demo builder stages them as `RetailTrim_*`. The generic façade kit is now skipped on these two, so their walls carry one façade language instead of two. **Open on this item:** the parapet reads as a blank band, the mural row and lettering band do not resolve at review distance, the corner tower is a plain cylinder, and the review camera crops the east end — all listed in `Screenshots/README.md`.
- [D] **Model 6822 Budget.** Deferred: no photograph exists for it (Commons has nothing usable) and the single-storey 6.0 × 5.5 m volume cannot be read from the neighbour shot. Needs photography before it can be modelled honestly; do not substitute the El Capitan Theatre's set or the 6806–6820 shot.
- [ ] Review every façade change with `Tools/render_screenshots.sh --verify` before tagging.
- [ ] Tag `v0.1.6` and write `CHANGELOG.md` entry; then remove this section.