feat(hero): v0.1.2 — scale calibration, façade detail, export preset refactor (#28)

Merged PR #28: v0.1.2 — scale calibration, façade detail, export preset

Co-authored-by: Zwitschi <zwitschi82@gmail.com>

MEMORY.md

@@ -400,3 +400,110 @@ Scope: facts and traps that cost time to establish. Planned work lives in [TODO.
   height error; the table is the tagged height, the mesh is storey + roof.
 - Gotcha: regenerating the blockout is safe for names, but any future change to
   the import must re-verify the 6/6 frontage export and the `element.*` mapping.
+
+## 2026-11-09 — hero colonnade proportion fixed (47.6 % → 53.1 %)
+
+- The hero's colonnade (columns 2.00–7.95 + capitals 7.95–8.90) was 6.90 m of the
+  14.50 m elevation = **47.6 %**, below the photographed 50–60 %, because the
+  entablature (3.40 m) and parapet (2.20 m) used 5.60 m of the height.
+- Thinned ENTABLATURE_H 3.40 → 3.00 and PARAPET_H 2.20 → 1.80 in
+  `Tools/hero_facade_build.py`; the colonnade grows to **7.70 m = 53.1 %** while the
+  envelope, motto band and medallions keep their relationships (all positioned
+  relative to those two constants).
+- **Gotcha (cost a bad build):** `hero_facade_build.py` takes `--out` for the
+  **FBX** and `--save-blend` for the `.blend`. Passing `--out <file>.blend` writes
+  FBX bytes over the blend and Blender then reports "File format is not supported".
+  Correct invocation: `--out /tmp/gigline/hero-facade.fbx --save-blend Art/...blend
+  --report Art/...json`.
+- Rebuilt hero → re-imported (`SM_HeroFacade`, bounds 2604 × 1257 × 1450 cm) →
+  DemoMap rebuilt → screenshots re-rendered. Note `ue_hero_facade_import.py` saves
+  the map, so `chmod u+w` the `.umap` first or the import silently does not persist.
+
+## 2026-11-09 — AI detail plates from reference photos; floating windows fixed
+
+- `Tools/facade_detail_concepts.py` generates architectural detail plates from one
+  local reference photograph via OpenRouter image models (default
+  `google/gemini-2.5-flash-image`; the sibling project uses the same route in
+  `tools/generate_textures.py` — chat/completions with a text + image_url content
+  part, image returned as `message.images[].image_url.url`). Eight studies,
+  `--list` free, `--all` generates, `-vN` never overwrites, `.refgen.json` sidecar
+  per image, all output under gitignored `Art/reference/facade-details/`.
+- **Prompt gotcha:** the model refuses when the prompt describes features the
+  reference photograph does not show ("the image you sent appears to be a
+  decorative architectural detail, not an entrance with steps"). Prompts must
+  describe the *reference subject* and only restage light/people/surface.
+- **Output is real:** 1184×864 to 1344×768 PNGs, ~2 MB each.
+- **Measured defect found and fixed:** hero window panes sat at Y −1.98 while the
+  mass front is Y −0.50 and the columns reach −1.02 — i.e. glazing floating 1.44 m
+  in front of the wall and ahead of the colonnade. Now `WINDOW_Y = −0.56`
+  (6 cm proud of the wall, behind the columns). Visible as dark openings in
+  `review-hero-facade-front`.
+- Reminder: `.blend` is LFS read-only on checkout — `chmod u+w` or Blender fails
+  with "Cannot save blend file … not writable" (this bit again here).
+
+## 2026-11-09 — UE export hygiene: smoothing groups + facade collision
+
+- **All our FBX exporters used `mesh_smooth_type="OFF"`**, which is why every Unreal
+  import logged "No smoothing group information was found for this mesh". The hero
+  now exports `"FACE"` and its round parts are shaded with
+  `shade_smooth_by_angle(35°)` before export: cylinders read as round instead of
+  faceted, and the import warning is gone (6 → 0).
+- **The hero façade had no simple collision** (complex-only), so line traces and
+  capsule sweeps passed straight through it — the player could walk through the
+  wall of the demo. Caught by a new `-qaselftest` **facade occlusion probe** (40 m
+  sideways traces from the road centre at walking height).
+- **Auto-generated convex collision on a 95-part 26 m façade is unusable**: it
+  produced coarse hulls that bulged into the street and the wall probe went
+  0/35 → 2/35. Rejected in favour of `UseComplexAsSimple` via
+  `UGigLineAssetTools.set_complex_collision_as_simple` (same reason the terrain
+  uses it), saved on the asset.
+- Probe expectations must mirror the staged buildings: the facade probe now carries
+  explicit X spans per frontage (and the TCL/Tussaud's spans on the north side) so
+  a gap between buildings is not reported as a defect.
+
+## 2026-11-09 — one FBX export preset instead of six copies
+
+- The `bpy.ops.export_scene.fbx(...)` argument block was duplicated in six scripts
+  (hero, block frontage, north buildings, site, scale test, MPFB character), and
+  all six carried `mesh_smooth_type="OFF"` — hence the "No smoothing group
+  information was found" warning on every import.
+- Now `Tools/fbx_export_preset.py` holds `ue_metric_v1` and `ue_character_v1`:
+  `preset_kwargs()` (bpy-free, unit-tested) plus `export_static()` /
+  `export_character()` wrappers that import `bpy` lazily. Every caller imports it
+  and passes `selection=True/False`; the seven duplicated blocks are gone.
+- Callers in `Tools/` resolve the module with
+  `sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))`; the Blender-side
+  `Art/blender/site/export_site_fbx.py` computes the repo root
+  (`..`, `..`, `..`) and joins `Tools`. Getting that wrong silently inserts
+  `Tools/Tools` — check the import path when adding a caller.
+- Verified end to end: scale test, hero, frontage (6/6), site (7/7) and north
+  buildings all re-exported through the preset, re-imported with **0 smoothing
+  warnings**, DemoMap rebuilt and `-qaselftest` all PASS (walk, transect 0 holes,
+  wall probe 0/35, facade probe 0/9).
+- `mpfb_character_export.py` was not re-run: it needs the MPFB add-on on
+  `BLENDER_USER_SCRIPTS` ("Add-on not loaded: bl_ext.blender_org.mpfb"), which is
+  pre-existing and unrelated; the character is not in `0.1.x` gameplay.
+
+## 2026-11-09 — v0.1.2 released
+
+- Cornice finished: projecting corona over a **52-dentil course** (0.18 × 0.30 ×
+  0.22 m at 0.45 m centres, z 12.12–12.34, 0.25 m clear of the corona). Hero is now
+  3 044 tris across 148 parts, still 14.50 m. Verified: packaged `-qaselftest` all
+  PASS (transect 0 holes, wall probe 0/35, facade probe 0/9).
+- `CHANGELOG.md` gets the `0.1.2` entry (added/changed/fixed/verified/limitations),
+  the `0.1.2` section is removed from `TODO.md`, `ROADMAP.md` status updated, tag
+  `v0.1.2` cut after the merge.
+- Assumptions recorded rather than hidden: dentil spacing, base and abacus
+  dimensions are not resolvable in our reference photography.
+
+## 2026-11-09 — elevation cameras levelled (straight verticals)
+
+- archviz MUST: an elevation must not lean. `hero-facade-front` looked up ~4° from
+  4.2 m at a 7.6 m target; `demo-spawn-view` and `demo-street-level` were pitched
+  too. All three now put the camera at the target's height, so
+  `FindLookAtRotation` yields pitch 0 and roll 0 and verticals are parallel by
+  construction.
+- Do not try to *measure* verticality from the rendered PNG with a naive edge
+  scan: banners, windows and the parapet produce different edge sets at different
+  heights and the pairwise match is meaningless (it reported a 418 px "drift").
+  Verify it geometrically in the camera list instead.