Skip to content

Commit 46b55d9

Browse files
committed
docs: codify the framing band in VISUAL-STYLE and CLAUDE gates
Layer 1 framing now carries its numbers where every run reads them: the 0.70-0.90 fill band in at least one axis, the 2 percent minimum edge margin, the hero-fill versus all-elements-margin distinction, and the instruction to measure with examples/gallery_framing.py rather than eyeball. CLAUDE.md's quality gates gain the matching framing-gate bullet so the standard example prompt inherits the rule by reference, plus one line naming the cross-example import shim. A read-only survey of every shipped hero with the helper found 13 examples outside the band (worklist for a future pass, not fixed here). Signed-off-by: fOuttaMyPaint <TMhospitalitystrategies@gmail.com>
1 parent 0dec7da commit 46b55d9

2 files changed

Lines changed: 16 additions & 2 deletions

File tree

‎CLAUDE.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,9 @@ wire all of: gallery.json entry, `.cursor-plugin/plugin.json` examples array (CI
9494
a `blender-smoke.yml` step, a README gallery row, hero webp (1280×720) in
9595
`docs/gallery/assets/` + preview webp (1200×675), then run `python scripts/build_gallery.py`.
9696
Renders must conform to the gallery look spec at `docs/VISUAL-STYLE.md`.
97+
Render paths gate framing through the shared helper `examples/gallery_framing.py` —
98+
imported via a `__file__`-relative `sys.path` shim, the repo's only
99+
cross-example import mechanism (see its docstring).
97100

98101
## Blender Runtime Discovery
99102

@@ -118,6 +121,7 @@ Stage with **explicit paths only** — never `git add -A` or `git add .`. Cursor
118121
## Quality Gates for Example Runs
119122

120123
- `docs/VISUAL-STYLE.md` is the **binding** render standard; deviations are defects.
124+
- **Framing gate:** Layer 1 framing is measured, not eyeballed — the example's `--output` render path calls the shared helper `examples/gallery_framing.py` (`check_framing`, exit 10 on violation) before writing the still: hero fill 0.70–0.90 of frame in at least one axis, every element that matters clearing all four edges by ≥ 0.02. The check-only path never invokes it, so smoke runtimes are unaffected.
121125
- **Contact-sheet gate:** composite the candidate hero beside the pinned calibration set — currently `armature-bend`, `damped-track-aim`, `bmesh-gear` — commit the composite under `docs/gallery/contact-sheets/`, link it in the PR body, and report per-criterion verdicts (stage darkness, wedge warmth, subject fill, saturation, thumbnail legibility) including mean luminance versus the calibration images. A claim without the committed composite is not acceptable evidence. **This list is the canonical home of the pinned set** — update it here when a new example outclasses a member; `docs/new-example-prompt.md` points here rather than naming members. The longer "calibration references" list in `docs/VISUAL-STYLE.md` is a style reference, not this contact-sheet set.
122126
- **Falsification:** every check must be proven to fail once — break the contract, observe the non-zero exit, restore — with the probe and the measured error reported in the PR body. An assertion that cannot fail witnesses nothing.
123127
- **After gallery regeneration** (`python scripts/build_gallery.py`), read the **generated HTML** character by character — the `<img alt>` text and witnesses callouts in `docs/gallery/index.html` and `docs/gallery/<name>/index.html` — not just `examples/gallery.json`. Precedent: the `teaches.split(".")[0]` bug truncated 14/21 card alts at dotted API paths like `bmesh.ops` while the source JSON looked fine (fixed in PR #68).

‎docs/VISUAL-STYLE.md‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,18 @@ the default stage.
4949

5050
## Framing and camera
5151

52-
- The subject fills roughly 70–90 % of the frame in at least one axis.
53-
Nothing that matters may touch or cross the frame edge.
52+
- The subject fills 70–90 % of the frame in at least one axis, measured —
53+
never eyeballed. Nothing that matters may touch or cross the frame edge.
54+
- Measure with the shared helper `examples/gallery_framing.py`, called on the
55+
render path only (import shim and full contract in its docstring):
56+
`gallery_framing.check_framing(sc, cam, hero=..., elements=..., stage=...)`
57+
prints the numbers and exits 10 on violation. **Fill** is measured on the
58+
hero subject only and must land in the 0.70–0.90 band in at least one axis,
59+
neither axis above 0.90. **Margin** is measured on the union of every
60+
element that matters — hero, placards, labels, comparison props, overlay
61+
markers — and must clear all four edges by ≥ 2 % of the frame dimension.
62+
Default strategy is the silhouette alpha matte; projection is the cheap
63+
bbox alternative for boxy subjects (tradeoff in the helper's docstring).
5464
- Camera: a chosen angle, not the default — typically a 45–55 mm lens,
5565
slightly above subject height, aimed with a `TRACK_TO` constraint at an
5666
empty on the subject. Flat subjects present toward the camera (lean or

0 commit comments

Comments
 (0)