Skip to content

Commit 137045a

Browse files
TMHSDigitalclaude
andcommitted
fix: wave-displace presentation, the wave as a tile on the studio floor
Render path only: a skirted copy of the checked grid stands on the floor instead of bleeding off three frame edges. Contract and exit codes unchanged on 4.5.11, 5.1.2 and 5.2.1. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
1 parent 99c988e commit 137045a

8 files changed

Lines changed: 169 additions & 50 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -361,7 +361,7 @@ then re-reads its own render and fails unless the pixels prove the flat-vs-check
361361
</tr>
362362
<tr>
363363
<td width="46%" valign="middle">
364-
<a href="examples/wave-displace/"><img src="examples/wave-displace/preview.webp" alt="Wave displace: a glossy sapphire-blue surface displaced into smooth standing-wave dunes against a black backdrop" /></a>
364+
<a href="examples/wave-displace/"><img src="examples/wave-displace/preview.webp" alt="Wave displace: a sapphire-blue tile whose top is displaced into smooth standing-wave dunes, standing on a dark studio floor" /></a>
365365
</td>
366366
<td valign="middle">
367367

-2.09 KB
Loading
-336 Bytes
Loading

‎docs/gallery/wave-displace/index.html‎

Lines changed: 81 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,13 @@
1616
<meta property="og:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/wave-displace-hero.webp" />
1717
<meta property="og:image:width" content="1280" />
1818
<meta property="og:image:height" content="720" />
19-
<meta property="og:image:alt" content="A blue grid surface displaced into rolling sine-wave hills." />
19+
<meta property="og:image:alt" content="A blue tile whose top is a grid displaced into rolling sine-wave hills, standing on a dark studio floor." />
2020
<meta property="og:site_name" content="Blender Developer Tools" />
2121
<meta name="twitter:card" content="summary_large_image" />
2222
<meta name="twitter:title" content="wave-displace — Examples — Blender Developer Tools" />
2323
<meta name="twitter:description" content="Bulk vertex IO at real scale — 9,409 vertices displaced into a standing wave with one foreach_get and one foreach_set, no per-vertex access." />
2424
<meta name="twitter:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/wave-displace-hero.webp" />
25-
<meta name="twitter:image:alt" content="A blue grid surface displaced into rolling sine-wave hills." />
25+
<meta name="twitter:image:alt" content="A blue tile whose top is a grid displaced into rolling sine-wave hills, standing on a dark studio floor." />
2626
<style>
2727
/* fonts are deployed by the landing build (docs/fonts/) */
2828
@font-face { font-family: 'Barlow Condensed'; font-weight: 600; font-display: swap;
@@ -268,8 +268,8 @@ <h1>wave-displace</h1>
268268
<p>Bulk vertex IO at real scale — 9,409 vertices displaced into a standing wave with one foreach_get and one foreach_set, no per-vertex access.</p>
269269
</header>
270270
<main id="main">
271-
<button class="detail-hero" id="heroZoom" type="button" aria-label="View full size: A blue grid surface displaced into rolling sine-wave hills.">
272-
<img src="../assets/wave-displace-hero.webp" alt="A blue grid surface displaced into rolling sine-wave hills." width="1280" height="720" />
271+
<button class="detail-hero" id="heroZoom" type="button" aria-label="View full size: A blue tile whose top is a grid displaced into rolling sine-wave hills, standing on a dark studio floor.">
272+
<img src="../assets/wave-displace-hero.webp" alt="A blue tile whose top is a grid displaced into rolling sine-wave hills, standing on a dark studio floor." width="1280" height="720" />
273273
</button>
274274
<p class="zoom-hint">Rendered headless by the example itself — click to zoom.</p>
275275
<div class="callout"><span class="tag">witnesses</span> The bulk path is correct, not just fast: the Z span matches the wave amplitude and every vertex matches the closed-form wave, so a stride bug in the flat buffer cannot hide.</div>
@@ -280,8 +280,9 @@ <h1>wave-displace</h1>
280280
<section class="detail-section md">
281281
<p>A runnable example that displaces a 96×96 grid (9,409 vertices) into a standing wave using <strong>one <code>foreach_get</code> and one <code>foreach_set</code></strong> — the bulk-IO pattern from <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/rules/use-foreach-set-for-bulk-data.mdc"><code>use-foreach-set-for-bulk-data</code></a> and the <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/skills/mesh-editing-and-bmesh/SKILL.md"><code>mesh-editing-and-bmesh</code></a> skill — instead of 9,409 individual <code>mesh.vertices[i].co</code> accesses.</p>
282282
<p><strong>What it witnesses:</strong> the bulk path is not just faster, it is <em>correct</em> — the check asserts the flat grid gained the expected Z span (the write actually landed) and that <strong>every</strong> vertex matches the closed-form wave, so a stride or interleave bug in the flat buffer cannot hide behind a lucky probe.</p>
283-
<h2>Framing deviation</h2>
284-
<p>Edge-to-edge field — the displaced sheet fills the frame and crops at the left, right, and bottom edges so the wave reads as a surface, not an object on a stage (measured fill 1.000x/0.817y with edge touch on three sides). If wired to <code>examples/gallery_framing.py</code>, call it with <code>deviation=&quot;edge-to-edge wave field; the fill is the point&quot;</code>.</p>
283+
<h2>Staging</h2>
284+
<p>The still used to be an edge-to-edge field: the sheet cropped at the left, right and bottom edges on a black void, so nothing showed where the surface ended or what it stood on. <code>gallery_framing</code> has no <code>deviation=</code> flag any more, so that framing could not be gated at all.</p>
285+
<p>The render path now stages a <strong>copy</strong> of the checked grid. Its boundary is extruded straight down to a flat base 0.30 m below the deepest trough, so the wave is the top face of a cast tile standing on the studio floor, framed whole. The checked <code>Wave</code> object is left exactly as asserted and hidden from the render. The copy is render-only and never enters <code>check()</code>. Measured framing on 5.2.1: fill 0.753 x / 0.761 y, every margin ≥ 0.117.</p>
285286
<h2>Run</h2>
286287
<pre><code># Cheap correctness check (no render) — the CI check:
287288
blender --background --python wave_displace.py --
@@ -391,31 +392,87 @@ <h2>Source</h2>
391392
bsdf.inputs[<span class="s">&quot;Roughness&quot;</span>].default_value = <span class="n">0.18</span>
392393
obj.data.materials.append(mat)
393394

395+
<span class="c"># render-only staging: the displaced grid is the contract and stays as</span>
396+
<span class="c"># checked. A copy of it gets a skirt, its boundary extruded straight</span>
397+
<span class="c"># down to a flat base, so the wave reads as the top of a cast tile</span>
398+
<span class="c"># standing on the studio floor instead of a sheet bleeding off the frame.</span>
399+
base = <span class="n">0.30</span> <span class="c"># base sits this far below the deepest trough</span>
400+
tile_me = obj.data.copy()
401+
bm = bmesh.new()
402+
<span class="k">try</span>:
403+
bm.from_mesh(tile_me)
404+
rim = [e <span class="k">for</span> e <span class="k">in</span> bm.edges <span class="k">if</span> e.is_boundary]
405+
ret = bmesh.ops.extrude_edge_only(bm, edges=rim)
406+
skirt = [g <span class="k">for</span> g <span class="k">in</span> ret[<span class="s">&quot;geom&quot;</span>] <span class="k">if</span> isinstance(g, bmesh.types.BMFace)]
407+
<span class="k">for</span> g <span class="k">in</span> ret[<span class="s">&quot;geom&quot;</span>]:
408+
<span class="k">if</span> isinstance(g, bmesh.types.BMVert):
409+
g.co.z = -AMP - base
410+
bottom = [g <span class="k">for</span> g <span class="k">in</span> ret[<span class="s">&quot;geom&quot;</span>] <span class="k">if</span> isinstance(g, bmesh.types.BMEdge) <span class="k">and</span> g.is_boundary]
411+
bmesh.ops.holes_fill(bm, edges=bottom, sides=<span class="n">0</span>)
412+
bmesh.ops.recalc_face_normals(bm, faces=bm.faces)
413+
<span class="k">for</span> f <span class="k">in</span> skirt:
414+
f.smooth = <span class="k">False</span>
415+
bm.to_mesh(tile_me)
416+
<span class="k">finally</span>:
417+
bm.free()
418+
tile = bpy.data.objects.new(<span class="s">&quot;WaveTile&quot;</span>, tile_me)
419+
tile.location.z = AMP + base
420+
scene.collection.objects.link(tile)
421+
obj.hide_render = <span class="k">True</span>
422+
423+
floor_me = bpy.data.meshes.new(<span class="s">&quot;Floor&quot;</span>)
424+
bm = bmesh.new()
425+
<span class="k">try</span>:
426+
bmesh.ops.create_grid(bm, x_segments=<span class="n">1</span>, y_segments=<span class="n">1</span>, size=<span class="n">60.0</span>)
427+
bm.to_mesh(floor_me)
428+
<span class="k">finally</span>:
429+
bm.free()
430+
fmat = bpy.data.materials.new(<span class="s">&quot;Studio&quot;</span>)
431+
fmat.use_nodes = <span class="k">True</span>
432+
fb = fmat.node_tree.nodes[<span class="s">&quot;Principled BSDF&quot;</span>]
433+
fb.inputs[<span class="s">&quot;Base Color&quot;</span>].default_value = (<span class="n">0.03</span>, <span class="n">0.032</span>, <span class="n">0.037</span>, <span class="n">1.0</span>)
434+
fb.inputs[<span class="s">&quot;Roughness&quot;</span>].default_value = <span class="n">0.7</span>
435+
floor_me.materials.append(fmat)
436+
floor = bpy.data.objects.new(<span class="s">&quot;Floor&quot;</span>, floor_me)
437+
scene.collection.objects.link(floor)
438+
wall = bpy.data.objects.new(<span class="s">&quot;Wall&quot;</span>, floor_me.copy())
439+
wall.location = (<span class="n">0.0</span>, <span class="n">14.0</span>, <span class="n">0.0</span>)
440+
wall.rotation_euler = (math.radians(<span class="n">90</span>), <span class="n">0.0</span>, <span class="n">0.0</span>)
441+
scene.collection.objects.link(wall)
442+
394443
world = bpy.data.worlds.new(<span class="s">&quot;World&quot;</span>)
395444
world.use_nodes = <span class="k">True</span>
396-
world.node_tree.nodes[<span class="s">&quot;Background&quot;</span>].inputs[<span class="s">&quot;Color&quot;</span>].default_value = (<span class="n">0.008</span>, <span class="n">0.009</span>, <span class="n">0.012</span>, <span class="n">1.0</span>)
445+
world.node_tree.nodes[<span class="s">&quot;Background&quot;</span>].inputs[<span class="s">&quot;Color&quot;</span>].default_value = (<span class="n">0.02</span>, <span class="n">0.021</span>, <span class="n">0.025</span>, <span class="n">1.0</span>)
397446
scene.world = world
398447

399-
<span class="c"># grazing cool key picks out the crests; warm rim from behind</span>
400-
key = bpy.data.lights.new(<span class="s">&quot;Key&quot;</span>, <span class="s">&#x27;AREA&#x27;</span>); key.energy = <span class="n">2000.0</span>; key.size = <span class="n">6.0</span>
401-
key.color = (<span class="n">0.9</span>, <span class="n">0.95</span>, <span class="n">1.0</span>)
402-
key_ob = bpy.data.objects.new(<span class="s">&quot;Key&quot;</span>, key)
403-
key_ob.location = (-<span class="n">6.5</span>, -<span class="n">5.0</span>, <span class="n">3.2</span>)
404-
key_ob.rotation_euler = (math.radians(<span class="n">65</span>), <span class="n">0.0</span>, math.radians(-<span class="n">50</span>))
405-
scene.collection.objects.link(key_ob)
406-
rim = bpy.data.lights.new(<span class="s">&quot;Rim&quot;</span>, <span class="s">&#x27;AREA&#x27;</span>); rim.energy = <span class="n">1300.0</span>; rim.size = <span class="n">4.0</span>
407-
rim.color = (<span class="n">1.0</span>, <span class="n">0.68</span>, <span class="n">0.38</span>)
408-
rim_ob = bpy.data.objects.new(<span class="s">&quot;Rim&quot;</span>, rim)
409-
rim_ob.location = (<span class="n">4.5</span>, <span class="n">6.5</span>, <span class="n">2.6</span>)
410-
rim_ob.rotation_euler = (math.radians(-<span class="n">68</span>), <span class="n">0.0</span>, math.radians(<span class="n">148</span>))
411-
scene.collection.objects.link(rim_ob)
412-
448+
<span class="k">def</span> light(name, loc, energy, size, col, rot):
449+
ld = bpy.data.lights.new(name, <span class="s">&#x27;AREA&#x27;</span>)
450+
ld.energy = energy; ld.size = size; ld.color = col
451+
ob = bpy.data.objects.new(name, ld)
452+
ob.location = loc
453+
ob.rotation_euler = tuple(math.radians(a) <span class="k">for</span> a <span class="k">in</span> rot)
454+
scene.collection.objects.link(ob)
455+
456+
<span class="c"># grazing cool key picks out the crests; warm rim from behind; a warm</span>
457+
<span class="c"># wedge rakes the back wall like the rest of the gallery stages</span>
458+
light(<span class="s">&quot;Key&quot;</span>, (-<span class="n">8.0</span>, -<span class="n">7.0</span>, <span class="n">6.5</span>), <span class="n">2400.0</span>, <span class="n">7.0</span>, (<span class="n">0.9</span>, <span class="n">0.95</span>, <span class="n">1.0</span>), (<span class="n">55</span>, <span class="n">0</span>, -<span class="n">48</span>))
459+
light(<span class="s">&quot;Fill&quot;</span>, (<span class="n">9.0</span>, -<span class="n">6.0</span>, <span class="n">3.0</span>), <span class="n">120.0</span>, <span class="n">10.0</span>, (<span class="n">0.78</span>, <span class="n">0.86</span>, <span class="n">1.0</span>), (<span class="n">70</span>, <span class="n">0</span>, <span class="n">55</span>))
460+
light(<span class="s">&quot;Rim&quot;</span>, (<span class="n">5.0</span>, <span class="n">7.5</span>, <span class="n">4.0</span>), <span class="n">1800.0</span>, <span class="n">5.0</span>, (<span class="n">1.0</span>, <span class="n">0.68</span>, <span class="n">0.38</span>), (-<span class="n">62</span>, <span class="n">0</span>, <span class="n">148</span>))
461+
light(<span class="s">&quot;Wedge&quot;</span>, (<span class="n">4.0</span>, <span class="n">10.5</span>, <span class="n">7.0</span>), <span class="n">1500.0</span>, <span class="n">9.0</span>, (<span class="n">1.0</span>, <span class="n">0.76</span>, <span class="n">0.5</span>), (-<span class="n">65</span>, <span class="n">0</span>, <span class="n">190</span>))
462+
463+
aim = bpy.data.objects.new(<span class="s">&quot;Aim&quot;</span>, <span class="k">None</span>)
464+
aim.location = (<span class="n">0.0</span>, -<span class="n">0.4</span>, <span class="n">0.05</span>)
465+
scene.collection.objects.link(aim)
413466
cam_data = bpy.data.cameras.new(<span class="s">&quot;Cam&quot;</span>); cam_data.lens = <span class="n">50.0</span>
414467
cam = bpy.data.objects.new(<span class="s">&quot;Cam&quot;</span>, cam_data)
415-
cam.location = (<span class="n">0.0</span>, -<span class="n">8.6</span>, <span class="n">4.6</span>)
416-
cam.rotation_euler = (math.radians(<span class="n">62</span>), <span class="n">0.0</span>, <span class="n">0.0</span>)
468+
cam.location = (<span class="n">7.2</span>, -<span class="n">11.8</span>, <span class="n">7.4</span>)
469+
con = cam.constraints.new(<span class="s">&#x27;TRACK_TO&#x27;</span>)
470+
con.target = aim
471+
con.track_axis = <span class="s">&#x27;TRACK_NEGATIVE_Z&#x27;</span>
472+
con.up_axis = <span class="s">&#x27;UP_Y&#x27;</span>
417473
scene.collection.objects.link(cam)
418474
scene.camera = cam
475+
scene.view_settings.view_transform = <span class="s">&#x27;Standard&#x27;</span>
419476

420477
scene.render.engine = <span class="s">&#x27;CYCLES&#x27;</span> <span class="k">if</span> engine == <span class="s">&#x27;cycles&#x27;</span> <span class="k">else</span> eevee_engine_id()
421478
<span class="k">if</span> engine == <span class="s">&#x27;cycles&#x27;</span>:
@@ -469,7 +526,7 @@ <h2>Source</h2>
469526
</main>
470527
<dialog class="lightbox" id="lightbox" aria-label="Full-size render">
471528
<button class="lightbox-close" type="button" autofocus>Close</button>
472-
<img src="../assets/wave-displace-hero.webp" alt="A blue grid surface displaced into rolling sine-wave hills." />
529+
<img src="../assets/wave-displace-hero.webp" alt="A blue tile whose top is a grid displaced into rolling sine-wave hills, standing on a dark studio floor." />
473530
</dialog>
474531
<footer>
475532
<div class="statusbar">

‎examples/gallery.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@
6060
"name": "wave-displace",
6161
"dir": "examples/wave-displace",
6262
"teaches": "Bulk vertex IO at real scale — 9,409 vertices displaced into a standing wave with one foreach_get and one foreach_set, no per-vertex access.",
63-
"alt": "A blue grid surface displaced into rolling sine-wave hills.",
63+
"alt": "A blue tile whose top is a grid displaced into rolling sine-wave hills, standing on a dark studio floor.",
6464
"witnessesFix": "The bulk path is correct, not just fast: the Z span matches the wave amplitude and every vertex matches the closed-form wave, so a stride bug in the flat buffer cannot hide.",
6565
"hero": "docs/gallery/assets/wave-displace-hero.webp",
6666
"preview": "examples/wave-displace/preview.webp",

‎examples/wave-displace/README.md‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,19 @@ the flat grid gained the expected Z span (the write actually landed) and that **
1111
vertex matches the closed-form wave, so a stride or interleave bug in the flat buffer
1212
cannot hide behind a lucky probe.
1313

14-
## Framing deviation
15-
16-
Edge-to-edge field — the displaced sheet fills the frame and crops at the left,
17-
right, and bottom edges so the wave reads as a surface, not an object on a
18-
stage (measured fill 1.000x/0.817y with edge touch on three sides). If wired
19-
to `examples/gallery_framing.py`, call it with
20-
`deviation="edge-to-edge wave field; the fill is the point"`.
14+
## Staging
15+
16+
The still used to be an edge-to-edge field: the sheet cropped at the left,
17+
right and bottom edges on a black void, so nothing showed where the surface
18+
ended or what it stood on. `gallery_framing` has no `deviation=` flag any more,
19+
so that framing could not be gated at all.
20+
21+
The render path now stages a **copy** of the checked grid. Its boundary is
22+
extruded straight down to a flat base 0.30 m below the deepest trough, so the
23+
wave is the top face of a cast tile standing on the studio floor, framed whole.
24+
The checked `Wave` object is left exactly as asserted and hidden from the
25+
render. The copy is render-only and never enters `check()`. Measured framing on
26+
5.2.1: fill 0.753 x / 0.761 y, every margin ≥ 0.117.
2127

2228
## Run
2329

-1.77 KB
Loading

0 commit comments

Comments
 (0)