Skip to content

Commit 3390251

Browse files
authored
feat: add lightmap-uv-channel example (#116)
The second UV layer engines require for baked lighting, on a reusable market cart (ground pivot, identity transforms, Cart.* datablocks, watertight parts). Per-part UVMap/UVLight with active == UVLight and active_render == UVMap re-asserted after the pipeline - uv_layers.new() never moves the flags and the edit-mode UV ops clear both. UV0 untouched by the second unwrap (drift 0.0; the clobber trap measured 2.068), every UV1 loop inside [0,1], zero overlapping islands via an independent binned strict-SAT scan (15 hits when falsified), min island distance 0.00401 against the nominal 0.002 pack margin, island census per part. Byte-identical check output on 4.5.11 LTS and 5.1.2 (9 parts, 1114 islands). Authoring hazards pinned: iterating a held MeshUVLoopLayer.data after edit-mode UV ops segfaults 4.5.11 headless (EXCEPTION_ACCESS_VIOLATION, 5/5; survives on 5.1.2) - re-fetch layers by name; lightmap_pack silently no-ops without prior unwrap. The ROADMAP UV atlas candidate is narrowed to its remaining unbuilt slice (utilization); the UV-handle snippet note gains the segfault confirmation. The atlas board is built from live UV1 data so a change in the packed layout moves the board geometry; --falsify stacks the second-largest island onto the largest in emissive red. Signed-off-by: fOuttaMyPaint <TMhospitalitystrategies@gmail.com>
1 parent 5da8e32 commit 3390251

12 files changed

Lines changed: 1818 additions & 4 deletions

File tree

‎.cursor-plugin/plugin.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@
8080
"examples/grease-pencil-rosette",
8181
"examples/image-pixels-testcard",
8282
"examples/light-link-studio",
83+
"examples/lightmap-uv-channel",
8384
"examples/lod-decimate-chain",
8485
"examples/mesh-hygiene-audit",
8586
"examples/modular-kit-snap",

‎.github/workflows/blender-smoke.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -579,3 +579,17 @@ jobs:
579579
# origins). Exits non-zero on failure.
580580
xvfb-run -a "$BLENDER" --background \
581581
--python examples/modular-kit-snap/modular_kit_snap.py --
582+
583+
- name: Shipped example - lightmap UV channel (two-layer bake contract)
584+
run: |
585+
set -euo pipefail
586+
# Check only (no render): a 9-part market cart; asserts per-part
587+
# UVMap/UVLight layers with active == UVLight and
588+
# active_render == UVMap re-asserted after the ops (they clear
589+
# both flags), UV0 loops untouched by the UV1 unwrap (drift 0),
590+
# every UV1 loop inside [0,1], zero overlapping islands via an
591+
# independent binned SAT scan, measured min island distance >=
592+
# half the nominal pack margin, and watertight parts. Exits
593+
# non-zero on failure.
594+
xvfb-run -a "$BLENDER" --background \
595+
--python examples/lightmap-uv-channel/lightmap_uv_channel.py --

‎README.md‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
</p>
1919

2020
<p align="center">
21-
<strong>12 skills</strong> &nbsp;&bull;&nbsp; <strong>6 rules</strong> &nbsp;&bull;&nbsp; <strong>2 templates</strong> &nbsp;&bull;&nbsp; <strong>17 snippets</strong> &nbsp;&bull;&nbsp; <strong>41 examples</strong>
21+
<strong>12 skills</strong> &nbsp;&bull;&nbsp; <strong>6 rules</strong> &nbsp;&bull;&nbsp; <strong>2 templates</strong> &nbsp;&bull;&nbsp; <strong>17 snippets</strong> &nbsp;&bull;&nbsp; <strong>42 examples</strong>
2222
</p>
2323

2424
<p align="center">
@@ -800,6 +800,26 @@ measured error printed. Companion to
800800
[`prop-origin-transform`](examples/prop-origin-transform/) (pivot discipline)
801801
and [`mesh-hygiene-audit`](examples/mesh-hygiene-audit/) (topology gates).
802802

803+
</td>
804+
</tr>
805+
<tr>
806+
<td width="46%" valign="middle">
807+
<a href="examples/lightmap-uv-channel/"><img src="examples/lightmap-uv-channel/preview.webp" alt="Lightmap UV channel: a wooden market cart with a cream canvas canopy beside a dark atlas board glowing with the bed's packed lightmap islands — proof the second UV layer packs with no overlaps, channel zero untouched" /></a>
808+
</td>
809+
<td valign="middle">
810+
811+
### [lightmap-uv-channel](examples/lightmap-uv-channel/)
812+
813+
The second UV layer engines need for baked lighting, on a reusable market
814+
cart. Per-part `UVMap`/`UVLight` with **`active` vs `active_render` pinned**
815+
(the edit-mode UV ops clear both flags — re-assert or lose them), channel
816+
zero untouched by the second unwrap (drift **0.0**, the clobber probe
817+
measures **2.068**), every island inside [0,1], **0** overlapping islands
818+
by an independent SAT scan, and a measured min island distance of
819+
**0.00401** against the stated margin. Companion to
820+
[`uv-layer-grid`](examples/uv-layer-grid/) (UV authoring) and
821+
[`triangulate-tangents`](examples/triangulate-tangents/) (tangents from UVs).
822+
803823
</td>
804824
</tr>
805825
</table>

‎ROADMAP.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -106,10 +106,12 @@ Not committed; target list for the next content version. (v0.3.0 shipped the smo
106106
- ~~LOD decimate chain witness~~ **SHIPPED** as `examples/lod-decimate-chain/` — Decimate COLLAPSE evaluated through the depsgraph is non-destructive (obj.data keeps closed-form counts), evaluated tris hit `ratio × base` within 5% (measured 0.0–0.44%), silhouette bbox survives within 1e-3 (measured 7.7e-6); a stacked Decimate halves the effective ratio, an aggressive 0.02 ratio collapses the nose tip — both caught failure modes
107107
- ~~Vertex weight limit witness~~ **SHIPPED** as `examples/vertex-weight-limit/` — the 4-influence engine cap enforced via the data API (`v.groups` + `VertexGroup.remove` + renormalize); unit sums (measured 3e-8), pose preserved (4.9e-3), exact LBS from the mesh's own deform layer (2.7e-7), Root mount pinned
108108
- ~~Triangulate + tangent-space witness~~ **SHIPPED** as `examples/triangulate-tangents/` — `calc_tangents` aborts on any ngon (back cap must be an explicit fan); mikktspace matches the edge/UV-delta formula within welding tolerance on smooth fields (2.3e-6 measured); planar UVs on a cylindrical wall collapse tangents onto normals (dot 0.998); `MeshUVLoopLayer` handle dangles across `calc_tangents()` on 4.5 (471 phantom flips, silent exit 0) while the mikktspace math is byte-identical on 4.5.11 and 5.1.2
109-
- UV-handle lifetime snippet: re-fetch attribute/UV layers by name after any CustomData-reallocating call (`calc_tangents`, `VertexGroup.add`, modifier edits) — held handles dangle silently on 4.5, survive by luck on 5.1 (found authoring `triangulate-tangents`)
109+
- UV-handle lifetime snippet: re-fetch attribute/UV layers by name after any CustomData-reallocating call (`calc_tangents`, `VertexGroup.add`, modifier edits) — held handles dangle silently on 4.5, survive by luck on 5.1 (found authoring `triangulate-tangents`; **confirmed harder authoring `lightmap-uv-channel`: iterating a held `MeshUVLoopLayer.data` after edit-mode UV ops segfaults 4.5.11 headless, EXCEPTION_ACCESS_VIOLATION 5/5, survives on 5.1.2**)
110110
- ~~glTF skinned-mesh export witness: follow-up to `gltf-export-roundtrip` + `vertex-weight-limit`~~ **SHIPPED** as `examples/gltf-skin-roundtrip/` — `skins[0].joints` names every bone, JOINTS_0/WEIGHTS_0 with unit sums (3e-8), weights bit-exact, rest matrices to 2.4e-07, deformation to 4.8e-07; exporter welds duplicate loops (sorted-multiset comparisons mispair — compare by rest-key); unparented skinned meshes make the exporter bind an armature by name
111111
- ~~Degenerate-bevel weld hazard~~ **SHIPPED** as `examples/degenerate-bevel-weld/` — at `offset == min_dim/2` the bevel band collapses to exactly 12 zero-area faces (4 min-axis edges × 3 segments) with 16 coincident verts (4 × (segments+1)) and min_area down 3.2e5×; a stdlib GLB re-parse counts **32 degenerate triangles crossing the export boundary** (MEASURED regression constant) versus 0 for the safe mesh — the loops an engine merge-by-distance welds; byte-identical on 4.5.11 and 5.1.2
112112
- ~~Modular kit snap witness~~ **SHIPPED** as `examples/modular-kit-snap/` — tiling corridor segment: 16 boundary verts on `x ∈ {0, TILE}` within 1e-6 m, end rings coincident under the tile offset (nearest-key match), linked-duplicate joint deviation 0.0, shell bbox == declared tile (dev 0.0), manifold except the 16 open-end edges, 12 detail parts contained inside the tile; unsnapped probe (3 mm skew, 2 mm nudge) fails at exits 3/4 with measured errors; sorted-zip ring matching mispairs displaced verts — match by nearest key (authoring hazard, fixed); byte-identical on 4.5.11 and 5.1.2
113+
- ~~Lightmap UV channel witness~~ **SHIPPED** as `examples/lightmap-uv-channel/` — two-channel UV contract on a market cart: per-part `UVMap`/`UVLight` with `active`/`active_render` re-asserted after the ops (edit-mode UV ops clear both flags; `uv_layers.new()` never moves them), UV0 drift 0.0 (clobber trap measured 2.068), every UV1 loop in [0,1], 0 overlapping islands via independent binned strict-SAT (15 hits when falsified), min island distance 0.00401 vs nominal margin 0.002 (`MARGIN_DIV × 0.01` semantics measured live); held `MeshUVLoopLayer.data` after edit-mode UV ops segfaults 4.5.11 (5/5, EXCEPTION_ACCESS_VIOLATION), silent no-op pack without prior unwrap; byte-identical on 4.5.11 and 5.1.2 (1114 islands)
114+
- UV atlas **utilization** witness — coverage/wasted-texel closed forms for a packed lightmap atlas (the non-overlap, unit-square, margin, and active/active_render contracts shipped in `lightmap-uv-channel`; utilization is the remaining unbuilt slice of the old "UV atlas pack" candidate)
113115
- ~~GAMMA_CROSS blend-curve witness~~ **SHIPPED** as `examples/vse-gamma-cross/` — the cross blends in a gamma-0.5 space: `((1-t)·√A + t·√B)²` with `t = (frame − start)/duration`, never 1 inside the effect; mid-cross dips 0.115 below the sRGB lerp from crimson/teal (closed form (0.341, 0.349, 0.463) confirmed per frame); AgX-default sampling poisons the fit (0.146 red-channel error, `view_transform='Standard'` mandatory); deleting a consumed input orphans-and-deletes the effect — follow-up to `vse-cut-list`
114116
- Falsy `bpy_prop_collection` trap snippet: an empty collection is falsy, so `editor.strips or editor.sequences` silently falls through to the legacy accessor on an empty timeline — always branch on `hasattr`; likely generalizes across the API (found authoring `vse-cut-list`)
115117
- ~~Collision compound witness~~ **SHIPPED** as `examples/collision-hull-proxy/` — game-prop collision as a compound of convex pieces, each a `bmesh.ops.convex_hull` of a coarse `sec(π/n)`-inflated cage (containment 4.4e-08, watertight, positive signed volume, Euler 2, per-piece 255-face budget: body 70, caps 60×3, compound 250); a hull of the dense render mesh measures 380 faces — over budget — which is why pipelines hull cages; proud details cost cage rows, concave grooves are free; byte-identical on 4.5.11 and 5.1.2
@@ -126,7 +128,6 @@ Not committed; target list for the next content version. (v0.3.0 shipped the smo
126128
- Dice-pair per-face witness: material/attribute assignment driven by face normal direction, opposite-faces-sum-to-7 as an independently computed invariant, pip placement from a closed-form lattice
127129
- Bicycle-wheel radial witness: spokes via radial Array with object offset — exact angular spacing, spoke count, hub/rim concentricity, every evaluated spoke endpoint on its computed rim coordinate
128130
- ~~mesh-hygiene-audit witness~~ **SHIPPED** as `examples/mesh-hygiene-audit/` — engine-ingest topology checklist on a stepped street electrical pedestal: no ngons, no loose verts, manifold edges (exactly 2 faces), no zero-area faces (`min_area` printed), positive signed volume, Euler `V−E+F==2` (24/44/22, volume 0.989248); byte-identical on 4.5.11 and 5.1.2; dual-panel dirty vs clean still
129-
- UV atlas pack witness — lightmap/unique UV island packing with non-overlap + utilization closed forms (deferred behind hygiene/origin; overlaps `uv-layer-grid` / `triangulate-tangents` / `gltf-export-roundtrip` UV arc)
130131

131132
- ~~Gallery framing recomposition worklist~~ **DRAINED**: all four recomposition cases restaged and gated with `check_framing` — depsgraph-export (0.984x/touch→0.812x; cube+dome recentered, aim-based camera), vertex-weight-limit (touch B→0.867y; more frontal camera, lower aim, base in frame), triangulate-tangents (0.334x→0.833y; 2x-class move-in plus Key/Glint trim that also cleared a pre-existing dome blowout), text-version-stamp (0.663x→0.719x; moved in with aim on the stamp center, dead third gone). The seven marginal cases were camera-nudged in the preceding sweep; deviations documented in #108 (damped-track-aim, wave-displace); sky-texture-sun-elevation is a measurement artifact (world subject — report-only if wired). Remaining: nothing on the framing worklist — future examples inherit the gate at authoring time.
132133

947 KB
Loading
44.5 KB
Loading

‎docs/gallery/index.html‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -272,7 +272,7 @@ <h1>Examples Gallery</h1>
272272
autocomplete="off" spellcheck="false" aria-label="Search examples" />
273273
<button class="q-clear" id="qClear" type="button" aria-label="Clear search" hidden>&times;</button>
274274
</div>
275-
<span class="count" id="count" role="status" aria-live="polite">41 examples</span>
275+
<span class="count" id="count" role="status" aria-live="polite">42 examples</span>
276276
<div class="density" role="group" aria-label="Card density">
277277
<button class="density-btn" data-density="compact" type="button" aria-pressed="false">Compact</button>
278278
<button class="density-btn" data-density="detailed" type="button" aria-pressed="false">Detailed</button>
@@ -773,6 +773,17 @@ <h2><a href="modular-kit-snap/">modular-kit-snap</a></h2>
773773
<a class="card-link" href="modular-kit-snap/">View example <span aria-hidden="true">&rarr;</span></a>
774774
</div>
775775
</article>
776+
<article class="card" data-tags="uv game-pipeline render">
777+
<a class="card-media" href="lightmap-uv-channel/" aria-label="lightmap-uv-channel example detail page">
778+
<img src="assets/lightmap-uv-channel-hero.webp" alt="lightmap-uv-channel — A market cart carrying the two-channel UV contract for baked lighting: UV0 untouched, UVLight packed with no overlaps and a respected margin." loading="lazy" decoding="async" />
779+
</a>
780+
<div class="card-body">
781+
<h2><a href="lightmap-uv-channel/">lightmap-uv-channel</a></h2>
782+
<p class="teaches">A market cart carrying the two-channel UV contract for baked lighting: UV0 untouched, UVLight packed with no overlaps and a respected margin.</p>
783+
<p class="witnesses"><span class="tag">witnesses</span> Per-part UVMap/UVLight with active vs active_render pinned (ops clear both flags), UV0 drift 0.0, 1114 islands with 0 SAT overlaps, min island distance 0.00401.</p>
784+
<a class="card-link" href="lightmap-uv-channel/">View example <span aria-hidden="true">&rarr;</span></a>
785+
</div>
786+
</article>
776787
</div>
777788
<p class="noresults" id="noResults" hidden>No examples match the current filters.
778789
<button class="chip" id="resetFilters" type="button">Clear search and tags</button></p>

0 commit comments

Comments
 (0)