Repository navigation
Expand file tree
/
Copy pathindex.html
More file actions
873 lines (793 loc) · 67.7 KB
/
Copy pathindex.html
File metadata and controls
873 lines (793 loc) · 67.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>collision-hull-proxy — Examples — Blender Developer Tools</title>
<meta name="description" content="A fire hydrant street prop inside its compound collision shell: four convex pieces hulled by bmesh.ops.convex_hull from a coarse inflated cage. The dense render mesh is never hulled - its hull would measure 380 faces, over the 255-face per-piece engine budget. Closed-form plane tests prove containment, convexity, watertightness, outward winding, and Euler characteristic 2 per piece." />
<link rel="canonical" href="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/collision-hull-proxy/" />
<link rel="icon" href="../../assets/favicon.svg" type="image/svg+xml" />
<meta name="theme-color" content="#1a1b1e" />
<meta name="color-scheme" content="dark" />
<meta property="og:type" content="website" />
<meta property="og:title" content="collision-hull-proxy — Examples — Blender Developer Tools" />
<meta property="og:description" content="A fire hydrant street prop inside its compound collision shell: four convex pieces hulled by bmesh.ops.convex_hull from a coarse inflated cage. The dense render mesh is never hulled - its hull would measure 380 faces, over the 255-face per-piece engine budget. Closed-form plane tests prove containment, convexity, watertightness, outward winding, and Euler characteristic 2 per piece." />
<meta property="og:url" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/collision-hull-proxy/" />
<meta property="og:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/collision-hull-proxy-hero.webp" />
<meta property="og:image:width" content="1280" />
<meta property="og:image:height" content="720" />
<meta property="og:image:alt" content="collision-hull-proxy: the example's own headless render" />
<meta property="og:site_name" content="Blender Developer Tools" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="collision-hull-proxy — Examples — Blender Developer Tools" />
<meta name="twitter:description" content="A fire hydrant street prop inside its compound collision shell: four convex pieces hulled by bmesh.ops.convex_hull from a coarse inflated cage. The dense render mesh is never hulled - its hull would measure 380 faces, over the 255-face per-piece engine budget. Closed-form plane tests prove containment, convexity, watertightness, outward winding, and Euler characteristic 2 per piece." />
<meta name="twitter:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/collision-hull-proxy-hero.webp" />
<meta name="twitter:image:alt" content="collision-hull-proxy: the example's own headless render" />
<style>
/* fonts are deployed by the landing build (docs/fonts/) */
@font-face { font-family: 'Barlow Condensed'; font-weight: 600; font-display: swap;
src: url('../../fonts/barlow-condensed-600.woff2') format('woff2'); }
@font-face { font-family: 'Inter'; font-weight: 400; font-display: swap;
src: url('../../fonts/inter-regular.woff2') format('woff2'); }
@font-face { font-family: 'Inter'; font-weight: 500; font-display: swap;
src: url('../../fonts/inter-medium.woff2') format('woff2'); }
@font-face { font-family: 'JetBrains Mono'; font-weight: 400; font-display: swap;
src: url('../../fonts/jetbrains-mono-regular.woff2') format('woff2'); }
/* Blender-viewport system, shared with the landing page. Dark only. */
:root {
color-scheme: dark;
--bg: #1a1b1e; --surface: #222327; --surface-2: #2a2b30; --bg2: #131417;
--border: #3a3b40; --text: #e8e9eb; --text-dim: #9698a0;
--select: #ff8c19; --ok: #6dc96d;
--radius: 4px; --radius-lg: 6px; --maxw: 1080px;
--font-display: 'Barlow Condensed', 'Arial Narrow', sans-serif;
--font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
--font-mono: 'JetBrains Mono', ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
--code-k: #ff7b72; --code-s: #a5d6ff; --code-c: #9698a0; --code-n: #79c0ff;
}
* { box-sizing: border-box; margin: 0; padding: 0; }
html { scroll-behavior: smooth; }
body { font-family: var(--font-sans); background: var(--bg); color: var(--text);
line-height: 1.6; min-height: 100vh; -webkit-font-smoothing: antialiased; }
a { color: var(--select); text-decoration: none; }
a:hover { text-decoration: underline; }
:focus-visible { outline: 2px solid var(--select); outline-offset: 2px; border-radius: 3px; }
::selection { background: color-mix(in srgb, var(--select) 40%, transparent); }
.skip { position: absolute; left: -999px; top: 0; background: var(--select); color: #1a1b1e;
padding: 0.5rem 1rem; border-radius: var(--radius); z-index: 10; font-weight: 500; }
.skip:focus { left: 0.5rem; top: 0.5rem; }
.hud { font-family: var(--font-mono); font-size: 0.6875rem; letter-spacing: 0.04em;
color: var(--text-dim); text-transform: uppercase; }
.topbar { position: sticky; top: 0; z-index: 5; display: flex; align-items: center;
justify-content: space-between; gap: 1rem; padding: 0 1.25rem; height: 46px;
background: color-mix(in srgb, var(--surface) 92%, transparent);
backdrop-filter: blur(10px); border-bottom: 1px solid var(--border); }
.topbar .back { color: var(--text-dim); font-size: 0.8125rem; font-weight: 500; }
.topbar .back:hover { color: var(--select); text-decoration: none; }
.topbar-right { display: flex; align-items: center; gap: 0.85rem; }
.topbar-right .ghlink { color: var(--text-dim); font-size: 0.8125rem; font-weight: 500; }
.topbar-right .ghlink:hover { color: var(--select); text-decoration: none; }
header.hero { max-width: var(--maxw); margin: 0 auto; padding: 2.75rem 1.25rem 1.25rem; }
header.hero h1 { font-family: var(--font-display); font-weight: 600; text-transform: uppercase;
font-size: clamp(2.2rem, 5vw, 3.4rem); letter-spacing: 0.005em; line-height: 0.98; }
header.hero p { color: var(--text-dim); max-width: 62ch; margin-top: 0.7rem; font-size: 1rem; }
/* ---- index: sticky controls (search, density toggle, tag chips) ---- */
.controls { position: sticky; top: 46px; z-index: 4;
background: color-mix(in srgb, var(--bg) 94%, transparent);
backdrop-filter: blur(10px); -webkit-backdrop-filter: blur(10px);
border-bottom: 1px solid var(--border); }
.controls-inner { max-width: var(--maxw); margin: 0 auto; padding: 0.55rem 1.25rem 0.6rem;
display: flex; flex-direction: column; gap: 0.5rem; }
.controls-row { display: flex; align-items: center; gap: 0.6rem; flex-wrap: wrap; }
.searchwrap { position: relative; flex: 1 1 240px; min-width: 150px; }
.searchwrap input { width: 100%; background: var(--surface-2); border: 1px solid var(--border);
color: var(--text); border-radius: var(--radius); padding: 0.34rem 1.9rem 0.34rem 0.7rem;
font-family: var(--font-sans); font-size: 0.85rem; line-height: 1.4; }
.searchwrap input:focus { border-color: var(--select); outline: none; }
.searchwrap input::placeholder { color: var(--text-dim); }
.searchwrap input::-webkit-search-cancel-button { -webkit-appearance: none; appearance: none; }
.q-clear { position: absolute; right: 0.2rem; top: 50%; transform: translateY(-50%);
background: none; border: none; color: var(--text-dim); font-size: 1.05rem; line-height: 1;
cursor: pointer; padding: 0.25rem 0.45rem; border-radius: 3px; }
.q-clear:hover { color: var(--select); }
.count { font-family: var(--font-mono); font-size: 0.68rem; letter-spacing: 0.04em;
text-transform: uppercase; color: var(--text-dim); white-space: nowrap; }
.density { display: flex; border: 1px solid var(--border); border-radius: var(--radius);
overflow: hidden; }
.density-btn { background: var(--surface-2); border: none; color: var(--text-dim); cursor: pointer;
font-family: var(--font-mono); font-size: 0.68rem; letter-spacing: 0.04em;
text-transform: uppercase; padding: 0.36rem 0.7rem; transition: color 0.15s, background 0.15s; }
.density-btn + .density-btn { border-left: 1px solid var(--border); }
.density-btn:hover { color: var(--select); }
.density-btn.active { background: var(--select); color: #1a1b1e; }
.tags-toggle { display: none; background: var(--surface-2); border: 1px solid var(--border);
color: var(--text-dim); border-radius: 3px; padding: 0.3rem 0.7rem; cursor: pointer;
font-family: var(--font-mono); font-size: 0.7rem; letter-spacing: 0.04em; text-transform: uppercase; }
.tags-toggle:hover, .tags-toggle.has-active { color: var(--select); border-color: var(--select); }
/* Tag chips wrap by default (no-JS safe). With JS the row becomes a scroll
strip on wide viewports and collapses behind the Tags toggle on narrow
ones, so the sticky bar never eats the mobile viewport. */
.chips { display: flex; flex-wrap: wrap; gap: 0.4rem; }
html.js .chips { flex-wrap: nowrap; overflow-x: auto; padding-bottom: 0.25rem;
scrollbar-width: thin; scrollbar-color: var(--border) transparent; }
html.js .chips::-webkit-scrollbar { height: 5px; }
html.js .chips::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
.chip { background: var(--surface-2); border: 1px solid var(--border); color: var(--text-dim);
border-radius: 3px; padding: 0.22rem 0.7rem; font-size: 0.72rem; font-weight: 400;
font-family: var(--font-mono); cursor: pointer; white-space: nowrap; flex: 0 0 auto;
transition: color 0.15s, border-color 0.15s; }
.chip:hover { color: var(--select); border-color: var(--select); }
.chip.active { color: #1a1b1e; background: var(--select); border-color: var(--select); }
@media (max-width: 719px) {
html.js .tags-toggle { display: inline-block; }
html.js .chips { display: none; }
html.js .chips.open { display: flex; flex-wrap: wrap; overflow-y: auto; max-height: 40vh; }
}
/* Compact density: hero + name + one-line teaser. The description and
WITNESSES text stay in the DOM (searchable, screen-reader reachable,
present with JS disabled when the class is never applied) but are
visually collapsed. Applied only by JS via the density-compact class. */
html.density-compact .grid { gap: 1rem; }
html.density-compact .card-body { padding: 0.65rem 0.9rem 0.7rem; }
html.density-compact .card-body h2 { font-size: 0.88rem; margin-bottom: 0.15rem; }
html.density-compact .teaches { font-size: 0.8rem; color: var(--text-dim); margin-bottom: 0;
white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
html.density-compact .witnesses { position: absolute; width: 1px; height: 1px; margin: -1px;
padding: 0; overflow: hidden; clip: rect(0 0 0 0); clip-path: inset(50%); white-space: nowrap; }
html.density-compact .card-link { display: none; }
.noresults { color: var(--text-dim); text-align: center; padding: 3rem 1rem; font-size: 0.95rem; }
.noresults .chip { margin-left: 0.6rem; }
.to-top { position: fixed; right: 1.25rem; bottom: 1.25rem; z-index: 6; cursor: pointer;
background: var(--surface-2); border: 1px solid var(--border); color: var(--text-dim);
border-radius: var(--radius); padding: 0.45rem 0.75rem;
font-family: var(--font-mono); font-size: 0.7rem; letter-spacing: 0.04em;
text-transform: uppercase; opacity: 0; visibility: hidden;
transition: opacity 0.2s, visibility 0.2s, color 0.15s, border-color 0.15s; }
.to-top.show { opacity: 1; visibility: visible; }
.to-top:hover { color: var(--select); border-color: var(--select); }
main { max-width: var(--maxw); margin: 0 auto; padding: 1rem 1.25rem 2rem; }
.grid { display: grid; grid-template-columns: 1fr; gap: 1.5rem; align-items: stretch; }
.card { background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius-lg);
overflow: hidden; display: flex; flex-direction: column;
outline: 2px solid transparent; outline-offset: -1px;
transition: outline-color 0.12s ease, border-color 0.12s ease; }
.card:hover { border-color: var(--select); outline-color: var(--select); }
.card.hidden { display: none; }
.card-media { display: block; background: var(--bg2); line-height: 0; }
.card-media img { display: block; width: 100%; aspect-ratio: 16 / 9; object-fit: cover; }
.card-body { padding: 1.15rem 1.4rem 1.45rem; display: flex; flex-direction: column; flex: 1 1 auto; }
.card-body h2 { font-family: var(--font-mono); font-size: 1rem; font-weight: 400; margin-bottom: 0.5rem; }
.card-body h2 a { color: var(--text); }
.card-body h2 a:hover { color: var(--select); text-decoration: none; }
.teaches { color: var(--text); margin-bottom: 0.7rem; font-size: 0.92rem; }
.witnesses { color: var(--text-dim); font-size: 0.85rem; margin-bottom: 1rem; }
.tag { display: inline-block; font-family: var(--font-mono); font-size: 0.62rem; text-transform: uppercase;
letter-spacing: 0.06em; color: var(--select); border: 1px solid color-mix(in srgb, var(--select) 55%, transparent);
border-radius: 3px; padding: 0.08rem 0.5rem; margin-right: 0.4rem; vertical-align: 1px; }
.card-link { font-weight: 600; font-size: 0.95rem; margin-top: auto; }
/* ---- detail page ---- */
.detail-hero { border: 1px solid var(--border); border-radius: var(--radius-lg); overflow: hidden;
background: var(--bg2); padding: 0; display: block; width: 100%; cursor: zoom-in; line-height: 0; }
.detail-hero img { display: block; width: 100%; aspect-ratio: 16 / 9; object-fit: cover; }
.zoom-hint { color: var(--text-dim); font-size: 0.78rem; margin-top: 0.4rem; }
.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0);
white-space: nowrap; }
.callout { border: 1px solid color-mix(in srgb, var(--select) 45%, var(--border));
border-left: 3px solid var(--select); border-radius: var(--radius);
background: color-mix(in srgb, var(--select) 7%, var(--surface));
padding: 0.85rem 1.1rem; margin: 1.5rem 0; font-size: 0.95rem; }
.runline { display: flex; align-items: stretch; gap: 0.5rem; margin: 1.5rem 0; }
.runline pre { flex: 1 1 auto; background: var(--surface-2); border: 1px solid var(--border);
border-radius: var(--radius); padding: 0.7rem 0.9rem; overflow-x: auto;
font-family: var(--font-mono); font-size: 0.83rem; line-height: 1.5; }
.copy-btn { flex: 0 0 auto; background: var(--surface-2); border: 1px solid var(--border);
color: var(--text-dim); border-radius: var(--radius); padding: 0 0.85rem; cursor: pointer;
font-family: var(--font-sans); font-size: 0.82rem; font-weight: 500; transition: color 0.15s, border-color 0.15s; }
.copy-btn:hover { color: var(--select); border-color: var(--select); }
.detail-section { margin-top: 2.25rem; }
.detail-section > h2 { font-family: var(--font-display); font-weight: 600; text-transform: uppercase;
font-size: 1.45rem; letter-spacing: 0.005em; padding-bottom: 0.5rem;
border-bottom: 1px solid var(--border); margin-bottom: 1rem; }
.md h1, .md h2, .md h3 { letter-spacing: -0.01em; margin: 1.4rem 0 0.6rem; line-height: 1.25; }
.md h1 { font-size: 1.35rem; } .md h2 { font-size: 1.15rem; } .md h3 { font-size: 1rem; }
.md p { margin: 0.7rem 0; }
.md ul, .md ol { margin: 0.7rem 0 0.7rem 1.4rem; }
.md li { margin: 0.3rem 0; }
.md .table-wrap { overflow-x: auto; margin: 0.9rem 0; }
.md table { border-collapse: collapse; font-size: 0.86rem; min-width: 100%; }
.md th, .md td { text-align: left; vertical-align: top; padding: 0.4rem 0.75rem 0.4rem 0;
border-bottom: 1px solid var(--border); }
.md th { color: var(--text-dim); font-weight: 600; white-space: nowrap; }
.md code { background: var(--surface-2); border: 1px solid var(--border); padding: 0.08rem 0.35rem;
border-radius: 4px; font-family: var(--font-mono); font-size: 0.84em; }
.md pre { background: var(--surface-2); border: 1px solid var(--border); border-radius: var(--radius);
padding: 0.85rem 1rem; overflow-x: auto; margin: 0.9rem 0; }
.md pre code { background: none; border: none; padding: 0; font-size: 0.83rem; line-height: 1.55; }
.src pre { background: var(--surface-2); border: 1px solid var(--border); border-radius: var(--radius);
padding: 1rem 1.1rem; overflow-x: auto; font-family: var(--font-mono);
font-size: 0.82rem; line-height: 1.55; }
.src .k { color: var(--code-k); } .src .s { color: var(--code-s); }
.src .c { color: var(--code-c); font-style: italic; } .src .n { color: var(--code-n); }
.src-meta { display: flex; justify-content: space-between; align-items: baseline; gap: 1rem;
flex-wrap: wrap; margin-bottom: 0.6rem; color: var(--text-dim); font-size: 0.85rem; }
.src-meta code { font-family: var(--font-mono); font-size: 0.82rem; }
.lightbox { border: 0; margin: 0; padding: 2rem; width: 100%; height: 100%; max-width: none;
max-height: none; background: rgba(0,0,0,0.85); cursor: zoom-out; }
.lightbox[open] { display: flex; align-items: center; justify-content: center; }
.lightbox::backdrop { background: transparent; }
.lightbox img { max-width: 100%; max-height: 100%; border-radius: var(--radius); }
.lightbox-close { position: absolute; top: 0.9rem; right: 0.9rem; background: var(--surface-2);
color: var(--text); border: 1px solid var(--border); border-radius: var(--radius);
font: 500 0.8rem var(--font-sans); padding: 0.4rem 0.75rem; cursor: pointer; }
.lightbox-close:hover { border-color: var(--select); color: var(--select); }
footer { border-top: 1px solid var(--border); background: var(--surface); margin-top: 2rem; }
footer .statusbar { max-width: var(--maxw); margin: 0 auto; padding: 0.55rem 1.25rem;
display: flex; align-items: center; gap: 1rem; flex-wrap: wrap;
font-family: var(--font-mono); font-size: 0.6875rem; letter-spacing: 0.04em;
text-transform: uppercase; color: var(--text-dim); }
footer .statusbar code { font-family: inherit; text-transform: none; }
@media (min-width: 720px) { .grid { grid-template-columns: 1fr 1fr; gap: 1.75rem; } }
@media (min-width: 560px) { html.density-compact .grid { grid-template-columns: 1fr 1fr; gap: 1rem; } }
@media (min-width: 900px) { html.density-compact .grid { grid-template-columns: repeat(3, 1fr); } }
@media (min-width: 1560px) {
html.density-compact .controls-inner,
html.density-compact main { max-width: 1400px; }
html.density-compact .grid { grid-template-columns: repeat(4, 1fr); }
}
@media (prefers-reduced-motion: reduce) {
html { scroll-behavior: auto; }
.card { transition: none; }
.card:hover { transform: none; }
.to-top { transition: none; }
}
</style>
</head>
<body>
<a class="skip" href="#main">Skip to content</a>
<div class="topbar">
<a class="back" href="../"><span aria-hidden="true">←</span> Examples and Showcase</a>
<div class="topbar-right">
<a class="ghlink" href="https://github.com/TMHSDigital/Blender-Developer-Tools">GitHub</a>
</div>
</div>
<header class="hero">
<h1>collision-hull-proxy</h1>
<p>A fire hydrant street prop inside its compound collision shell: four convex pieces hulled by bmesh.ops.convex_hull from a coarse inflated cage. The dense render mesh is never hulled - its hull would measure 380 faces, over the 255-face per-piece engine budget. Closed-form plane tests prove containment, convexity, watertightness, outward winding, and Euler characteristic 2 per piece.</p>
</header>
<main id="main">
<button class="detail-hero" id="heroZoom" type="button" aria-label="Zoom collision-hull-proxy render">
<img src="../assets/collision-hull-proxy-hero.webp" alt="collision-hull-proxy render" width="1280" height="720" />
</button>
<p class="zoom-hint">Rendered headless by the example itself — click to zoom.</p>
<div class="callout"><span class="tag">witnesses</span> A hull of the dense render mesh measures 380 faces, over the 255-face per-piece budget - the cage is a coarser lathe with rings inflated by sec(pi/n) so each cage ring circumscribes its render ring exactly (containment 4.4e-08). Proud details cost cage rows; concave grooves are free under the hull. Piece budgets: body 70, caps 60+60+60, compound 250.</div>
<div class="runline">
<pre id="runCmd">blender --background --python examples/collision-hull-proxy/collision_hull_proxy.py --</pre>
<button class="copy-btn" id="copyRun" type="button">Copy</button>
</div>
<section class="detail-section md">
<p>A runnable example that builds a fire hydrant street prop — lathed barrel, bonnet dome, three outlet caps, operating nut — plus the collision a game prop pipeline ingests: a <strong>compound of four convex hull pieces</strong>, one per part group, each built with <code>bmesh.ops.convex_hull</code> from a coarse collision cage, following <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>.</p>
<p><strong>Pipeline arc neighbor:</strong> LODs in <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/lod-decimate-chain"><code>lod-decimate-chain</code></a>, tangent space in <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/triangulate-tangents"><code>triangulate-tangents</code></a>, export in <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/gltf-export-roundtrip"><code>gltf-export-roundtrip</code></a> — collision bounds are the piece an engine's physics ingest checks first, and the piece whose failure rejects the whole prop.</p>
<p><strong>Scope:</strong> this witnesses the bpy-level contract a prop pipeline relies on (watertight convex pieces that enclose the render mesh within budget). It is not an engine exporter and does not produce a shippable FiveM/engine asset — it proves the geometry properties such an asset must have.</p>
<p><strong>What it witnesses:</strong> engines (GTA/FiveM-style prop workflows included) ingest collision as a <em>compound of convex pieces</em>, each piece under a per-piece face limit (255 is the common cap). The example builds that structure and derives every property from closed forms, per piece:</p>
<ul><li><strong>Containment.</strong> Every render-mesh vertex lies on the inner side of every face plane of its piece's hull — max excursion <strong>4.4e-08</strong> (tol 2e-4). This holds by construction, not luck: the cage is a coarse lathe whose rings are inflated by <code>sec(π/n)</code>, so each n-gon cage ring <em>circumscribes</em> its render ring exactly. Proud details (a rim, a nut) must be paid for in cage rows; concave details (the grooves) are free — the hull bridges over them. That trade-off is the collision-authoring lesson.</li><li><strong>Convexity.</strong> The same plane test restricted to the hull's own vertices (4.8e-08) — what a convex solver assumes when it uploads the piece.</li><li><strong>Watertight + manifold.</strong> Every hull edge borders exactly two faces, and V − E + F = 2: a convex hull is a topological sphere.</li><li><strong>Outward winding.</strong> Positive signed volume by the divergence theorem (body piece 1.022381) — inverted collision is a physics no-op.</li><li><strong>Budget.</strong> Every piece ≤ 255 faces: body 70, pumper 60, side caps 60+60; the compound totals 250. The naive approach fails this — a hull of the <em>dense render mesh</em> measures <strong>380 faces</strong>, over budget, which is why real pipelines hull a cage, never the render mesh.</li></ul>
<p><strong>What each check catches on failure:</strong> an artist editing the render mesh after the hull was generated (probe: pumper lug stretched 2×, exit 3, measured escape 0.730000); inverted hull winding (probe: polygons flipped, exit 5, signed volume −1.022381, the exact negation); a non-watertight piece (probe: one face deleted, exit 4, three border edges).</p>
<p><strong>Version witness:</strong> output is byte-identical on Blender 4.5.11 LTS and 5.1.2 — same piece counts, same volumes, same excursions. <code>bmesh.ops.convex_hull</code> and <code>foreach_get</code> are stable across the pair.</p>
<p>The render shows the prop inside its four faceted translucent hull pieces: if any piece failed to enclose its geometry, painted metal would poke through the shell in frame.</p>
<h2>Run</h2>
<pre><code># Cheap correctness check (no render) — the CI check:
blender --background --python collision_hull_proxy.py --
# Falsifier: shrink hull vertices. Must exit non-zero (containment).
blender --background --python collision_hull_proxy.py -- --shrink-hull
# Also render a still (EEVEE on a GPU host; use --engine cycles on GPU-less hosts):
blender --background --python collision_hull_proxy.py -- --output hydrant.png
blender --background --python collision_hull_proxy.py -- --output hydrant.png --engine cycles</code></pre>
<h2>Exit codes</h2>
<p>Per-script sequential checks. <code>9</code> is a valid check code; there is no rule against it.</p>
<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage</td></tr><tr><td>3</td><td>Render vertex escapes its hull (<code>--shrink-hull</code> lands here)</td></tr><tr><td>4</td><td>Hull edge does not border exactly two faces</td></tr><tr><td>5</td><td>Signed volume ≤ 0 (inverted winding)</td></tr><tr><td>6</td><td>Hull vertex off its own face plane</td></tr><tr><td>7</td><td>Euler characteristic ≠ 2</td></tr><tr><td>8</td><td>Piece over the 255-face collision budget</td></tr><tr><td>9</td><td><code>--output</code> produced no file</td></tr></tbody></table></div>
<p>The <code>blender-smoke</code> workflow runs the check on Blender 5.2 LTS and 4.5 LTS (5.1 on the weekly cron, the <code>needs-5.1</code> PR label, or manual dispatch). Smoke does not pass <code>--output</code> or <code>--shrink-hull</code>.</p>
</section>
<section class="detail-section src">
<h2>Source</h2>
<div class="src-meta">
<code>examples/collision-hull-proxy/collision_hull_proxy.py</code>
<a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/collision-hull-proxy/collision_hull_proxy.py">View on GitHub →</a>
</div>
<pre><span class="s">"""A fire hydrant prop plus its convex collision proxies — a runnable example.
Witnesses the collision contract every game prop pipeline (engines generally,
FiveM/GTA-style prop workflows specifically) depends on: a prop's collision is
a COMPOUND of convex pieces, each piece a watertight, outward-wound hull that
fully encloses its render geometry and stays inside the engine's per-piece
face budget. Each piece is built with `bmesh.ops.convex_hull` from a coarse
collision cage — never from the dense render mesh, whose hull would blow the
budget — and the check derives every property from closed forms:
containment — every render-mesh vertex on the inner side of every face
plane of its piece's hull (max excursion printed, tol 2e-4)
convexity — the same plane test restricted to the hull's own vertices
watertight — every hull edge borders exactly two faces
winding — positive signed volume (divergence theorem)
manifold — Euler characteristic V - E + F == 2 (a convex hull is a
topological sphere)
budget — every piece <= 255 faces (the common per-piece convex limit
engines impose on collision meshes)
The cage is a coarser lathe whose profile rings are inflated by sec(pi / n)
so its n-gon rings circumscribe the render rings exactly — that is why
containment holds with a measured margin of ~0 instead of by luck. Concave
details (grooves) never touch the hull; proud details cost hull faces. That
trade-off IS the collision-authoring lesson.
``--shrink-hull`` scales each hull's vertices by 0.5 and still runs the
containment plane test, so render verts escape. That is the falsifier
(``--same-axis`` in export-preset-axis).
By default it runs only the correctness check (no render) — the CI smoke
check. Pass --output to also render a still:
blender --background --python collision_hull_proxy.py -- # check only
blender --background --python collision_hull_proxy.py -- --shrink-hull # must fail
blender --background --python collision_hull_proxy.py -- --output h.png # + render
"""</span>
<span class="k">import</span> bpy, bmesh, sys, os, math, argparse
<span class="k">from</span> mathutils <span class="k">import</span> Vector
SEGMENTS = <span class="n">48</span> <span class="c"># lathe resolution of the render mesh</span>
CAGE_SEG_BODY = <span class="n">8</span> <span class="c"># collision cage resolutions — the hull face budget</span>
CAGE_SEG_CAP = <span class="n">8</span> <span class="c"># is spent through these, not through SEGMENTS</span>
CAGE_SEG_NUT = <span class="n">5</span>
HULL_BUDGET = <span class="n">255</span> <span class="c"># engine per-piece convex face limit</span>
TOL = <span class="n">2e-4</span> <span class="c"># plane-test tolerance: cage circumscribes render exactly</span>
<span class="c"># ---------------------------------------------------------------------------</span>
<span class="c"># Prop construction. The hydrant is lathed around Z; caps are lathed around Z</span>
<span class="c"># too and tipped onto their sides by the object rotation. All dimensions are</span>
<span class="c"># invented for this prop — no real-world design is referenced.</span>
<span class="c"># ---------------------------------------------------------------------------</span>
<span class="c"># (radius, height) render profile of body + bonnet, bottom pole to top pole.</span>
<span class="c"># Ribs are GROOVES: concave details are free under a convex hull, proud ones</span>
<span class="c"># would have to be paid for in cage rows.</span>
BODY_PROFILE = [
(<span class="n">0.00</span>, <span class="n">0.000</span>),
(<span class="n">0.60</span>, <span class="n">0.000</span>), <span class="c"># base flange edge</span>
(<span class="n">0.60</span>, <span class="n">0.045</span>),
(<span class="n">0.575</span>, <span class="n">0.055</span>), <span class="c"># flange groove (concave)</span>
(<span class="n">0.575</span>, <span class="n">0.070</span>),
(<span class="n">0.60</span>, <span class="n">0.080</span>),
(<span class="n">0.60</span>, <span class="n">0.095</span>), <span class="c"># flange top edge</span>
(<span class="n">0.48</span>, <span class="n">0.115</span>), <span class="c"># taper (convex curve, lies inside the cage chord)</span>
(<span class="n">0.40</span>, <span class="n">0.155</span>),
(<span class="n">0.37</span>, <span class="n">0.205</span>), <span class="c"># neck</span>
(<span class="n">0.35</span>, <span class="n">0.320</span>), <span class="c"># barrel</span>
(<span class="n">0.346</span>, <span class="n">0.545</span>),
(<span class="n">0.328</span>, <span class="n">0.555</span>), <span class="c"># barrel groove (concave)</span>
(<span class="n">0.328</span>, <span class="n">0.575</span>),
(<span class="n">0.346</span>, <span class="n">0.590</span>),
(<span class="n">0.345</span>, <span class="n">0.880</span>), <span class="c"># barrel top</span>
(<span class="n">0.348</span>, <span class="n">0.930</span>),
(<span class="n">0.336</span>, <span class="n">0.950</span>), <span class="c"># upper groove (concave)</span>
(<span class="n">0.336</span>, <span class="n">1.000</span>),
(<span class="n">0.348</span>, <span class="n">1.030</span>),
(<span class="n">0.36</span>, <span class="n">1.090</span>), <span class="c"># shoulder under bonnet</span>
(<span class="n">0.388</span>, <span class="n">1.110</span>), <span class="c"># bonnet brim (proud — paid for with a cage row)</span>
(<span class="n">0.362</span>, <span class="n">1.132</span>), <span class="c"># under-brim tuck (concave)</span>
(<span class="n">0.35</span>, <span class="n">1.150</span>), <span class="c"># bonnet dome (concave curve — cage keeps every row)</span>
(<span class="n">0.30</span>, <span class="n">1.220</span>),
(<span class="n">0.21</span>, <span class="n">1.280</span>),
(<span class="n">0.10</span>, <span class="n">1.315</span>),
(<span class="n">0.00</span>, <span class="n">1.325</span>),
]
<span class="c"># Cage silhouette: every convex corner of the render profile, nothing else.</span>
<span class="c"># sec(pi/8) inflation makes each 8-gon cage ring circumscribe its render ring.</span>
CAGE_BODY_PROFILE = [
(<span class="n">0.00</span>, <span class="n">0.000</span>),
(<span class="n">0.60</span>, <span class="n">0.000</span>),
(<span class="n">0.60</span>, <span class="n">0.095</span>),
(<span class="n">0.37</span>, <span class="n">0.205</span>),
(<span class="n">0.345</span>, <span class="n">0.880</span>),
(<span class="n">0.36</span>, <span class="n">1.090</span>),
(<span class="n">0.388</span>, <span class="n">1.110</span>), <span class="c"># the brim is proud: it must appear in the cage</span>
(<span class="n">0.35</span>, <span class="n">1.150</span>),
(<span class="n">0.30</span>, <span class="n">1.220</span>),
(<span class="n">0.21</span>, <span class="n">1.280</span>),
(<span class="n">0.10</span>, <span class="n">1.315</span>),
(<span class="n">0.00</span>, <span class="n">1.325</span>),
]
NUT_PROFILE = [(<span class="n">0.115</span>, <span class="n">1.325</span>), (<span class="n">0.095</span>, <span class="n">1.44</span>), (<span class="n">0.0</span>, <span class="n">1.44</span>)]
<span class="c"># Side caps at z=0.76, pumper (bigger) at z=0.66. A cap's outlet direction</span>
<span class="c"># equals its azimuth (degrees from +X); the camera sits near azimuth 292, so</span>
<span class="c"># the pumper faces it and the side caps read on the flanks.</span>
SIDE_CAPS = [(<span class="n">0.66</span>, <span class="n">315.0</span>), (<span class="n">0.76</span>, <span class="n">45.0</span>), (<span class="n">0.76</span>, <span class="n">165.0</span>)]
PUMPER = <span class="n">0</span> <span class="c"># index of the large front outlet in SIDE_CAPS</span>
<span class="k">def</span> cap_profiles(r_cap, reach):
<span class="s">"""Render and cage (r, z) profiles for one outlet cap. The rim flare is
1.10x the barrel radius so the dense rim rows lie inside the cage chord."""</span>
render = [
(<span class="n">0.0</span>, <span class="n">0.0</span>),
(r_cap, <span class="n">0.0</span>),
(r_cap, reach - <span class="n">0.05</span>),
(r_cap * <span class="n">1.10</span>, reach - <span class="n">0.03</span>), <span class="c"># rim</span>
(r_cap * <span class="n">1.10</span>, reach),
(r_cap * <span class="n">0.72</span>, reach + <span class="n">0.045</span>), <span class="c"># cap dome</span>
(<span class="n">0.0</span>, reach + <span class="n">0.06</span>),
]
cage = [
(<span class="n">0.0</span>, <span class="n">0.0</span>),
(r_cap, <span class="n">0.0</span>),
(r_cap * <span class="n">1.10</span>, reach - <span class="n">0.03</span>),
(r_cap * <span class="n">1.10</span>, reach),
(r_cap * <span class="n">0.72</span>, reach + <span class="n">0.045</span>),
(<span class="n">0.0</span>, reach + <span class="n">0.06</span>),
]
<span class="k">return</span> render, cage
<span class="k">def</span> signed_volume(me):
<span class="s">"""Divergence-theorem volume; positive when face winding points outward."""</span>
vol = <span class="n">0.0</span>
<span class="k">for</span> p <span class="k">in</span> me.polygons:
vs = [me.vertices[i].co <span class="k">for</span> i <span class="k">in</span> p.vertices]
v0 = vs[<span class="n">0</span>]
<span class="k">for</span> i <span class="k">in</span> range(<span class="n">1</span>, len(vs) - <span class="n">1</span>):
vol += v0.dot(vs[i].cross(vs[i + <span class="n">1</span>])) / <span class="n">6.0</span>
<span class="k">return</span> vol
<span class="k">def</span> lathe_object(name, profile, segments, inflate=<span class="n">1.0</span>):
<span class="s">"""Spin an (r, z) profile around Z. r == 0 ends become pole vertices, so
the mesh closes with fans instead of degenerate rings. `inflate` scales
radii only — the collision cage uses sec(pi / segments) so its polygon
rings circumscribe the render rings exactly."""</span>
me = bpy.data.meshes.new(name)
bm = bmesh.new()
<span class="k">try</span>:
bot = top = <span class="k">None</span>
<span class="k">if</span> profile[<span class="n">0</span>][<span class="n">0</span>] == <span class="n">0.0</span>:
bot = bm.verts.new((<span class="n">0.0</span>, <span class="n">0.0</span>, profile[<span class="n">0</span>][<span class="n">1</span>]))
profile = profile[<span class="n">1</span>:]
<span class="k">if</span> profile[-<span class="n">1</span>][<span class="n">0</span>] == <span class="n">0.0</span>:
top = bm.verts.new((<span class="n">0.0</span>, <span class="n">0.0</span>, profile[-<span class="n">1</span>][<span class="n">1</span>]))
profile = profile[:-<span class="n">1</span>]
rings = []
<span class="k">for</span> i <span class="k">in</span> range(segments):
a = <span class="n">2.0</span> * math.pi * i / segments
ca, sa = math.cos(a), math.sin(a)
rings.append([bm.verts.new((r * inflate * ca, r * inflate * sa, z))
<span class="k">for</span> r, z <span class="k">in</span> profile])
<span class="k">for</span> i <span class="k">in</span> range(segments):
j = (i + <span class="n">1</span>) % segments
<span class="k">for</span> k <span class="k">in</span> range(len(profile) - <span class="n">1</span>):
bm.faces.new((rings[i][k], rings[j][k], rings[j][k + <span class="n">1</span>], rings[i][k + <span class="n">1</span>]))
<span class="k">if</span> bot <span class="k">is</span> <span class="k">not</span> <span class="k">None</span>:
bm.faces.new((rings[j][<span class="n">0</span>], rings[i][<span class="n">0</span>], bot))
<span class="k">if</span> top <span class="k">is</span> <span class="k">not</span> <span class="k">None</span>:
bm.faces.new((rings[i][-<span class="n">1</span>], rings[j][-<span class="n">1</span>], top))
bmesh.ops.recalc_face_normals(bm, faces=bm.faces)
<span class="c"># recalc picks a consistent winding but not a direction; outward is</span>
<span class="c"># pinned below by the same signed-volume form the check uses.</span>
bm.to_mesh(me)
<span class="k">finally</span>:
bm.free()
obj = bpy.data.objects.new(name, me)
bpy.context.collection.objects.link(obj)
<span class="k">if</span> signed_volume(me) < <span class="n">0.0</span>:
<span class="k">for</span> p <span class="k">in</span> me.polygons:
p.flip()
<span class="k">return</span> obj
<span class="k">def</span> make_material(name, color, metallic, roughness):
mat = bpy.data.materials.new(name)
mat.use_nodes = <span class="k">True</span>
bsdf = mat.node_tree.nodes[<span class="s">"Principled BSDF"</span>]
bsdf.inputs[<span class="s">"Base Color"</span>].default_value = (*color, <span class="n">1.0</span>)
bsdf.inputs[<span class="s">"Metallic"</span>].default_value = metallic
bsdf.inputs[<span class="s">"Roughness"</span>].default_value = roughness
<span class="k">return</span> mat
<span class="k">def</span> build_hydrant():
<span class="s">"""Builds the prop and its collision cages. Returns a list of collision
groups: {"name", "render": [objects], "cage": [objects]} — one convex
hull piece per group, the compound-collision structure engines ingest."""</span>
bpy.ops.wm.read_factory_settings(use_empty=<span class="k">True</span>)
red = make_material(<span class="s">"EnamelRed"</span>, (<span class="n">0.48</span>, <span class="n">0.035</span>, <span class="n">0.022</span>), <span class="n">0.15</span>, <span class="n">0.30</span>)
yellow = make_material(<span class="s">"EnamelYellow"</span>, (<span class="n">0.82</span>, <span class="n">0.53</span>, <span class="n">0.05</span>), <span class="n">0.15</span>, <span class="n">0.32</span>)
iron = make_material(<span class="s">"CastIron"</span>, (<span class="n">0.05</span>, <span class="n">0.052</span>, <span class="n">0.06</span>), <span class="n">0.9</span>, <span class="n">0.48</span>)
iron_light = make_material(<span class="s">"CastIronLight"</span>, (<span class="n">0.14</span>, <span class="n">0.145</span>, <span class="n">0.16</span>), <span class="n">0.85</span>, <span class="n">0.42</span>)
inflate_body = <span class="n">1.0</span> / math.cos(math.pi / CAGE_SEG_BODY)
inflate_cap = <span class="n">1.0</span> / math.cos(math.pi / CAGE_SEG_CAP)
inflate_nut = <span class="n">1.0</span> / math.cos(math.pi / CAGE_SEG_NUT)
<span class="c"># --- body group: body + bonnet + operating nut ---</span>
body = lathe_object(<span class="s">"Body"</span>, BODY_PROFILE, SEGMENTS)
body.data.materials.append(red)
body.data.materials.append(yellow)
<span class="k">for</span> p <span class="k">in</span> body.data.polygons: <span class="c"># the bonnet dome is the yellow profile tail</span>
<span class="k">if</span> p.center.z > <span class="n">1.09</span>:
p.material_index = <span class="n">1</span>
nut = lathe_object(<span class="s">"Nut"</span>, NUT_PROFILE, <span class="n">5</span>)
nut.data.materials.append(iron_light)
body_cage = lathe_object(<span class="s">"BodyCage"</span>, CAGE_BODY_PROFILE, CAGE_SEG_BODY, inflate_body)
nut_cage = lathe_object(<span class="s">"NutCage"</span>, NUT_PROFILE, CAGE_SEG_NUT, inflate_nut)
groups = [{<span class="s">"name"</span>: <span class="s">"body"</span>, <span class="s">"render"</span>: [body, nut], <span class="s">"cage"</span>: [body_cage, nut_cage]}]
<span class="c"># --- one group per outlet cap ---</span>
<span class="k">for</span> idx, (z, azim) <span class="k">in</span> enumerate(SIDE_CAPS):
big = idx == PUMPER
r_cap = <span class="n">0.19</span> <span class="k">if</span> big <span class="k">else</span> <span class="n">0.145</span>
reach = <span class="n">0.62</span> <span class="k">if</span> big <span class="k">else</span> <span class="n">0.56</span>
prof_r, prof_c = cap_profiles(r_cap, reach)
cap = lathe_object(<span class="s">"PumperCap"</span> <span class="k">if</span> big <span class="k">else</span> <span class="s">f"</span><span class="s">SideCap</span>{idx}<span class="s">"</span>, prof_r, <span class="n">24</span>)
cap.data.materials.append(red)
lug_prof = [(<span class="n">0.075</span>, reach + <span class="n">0.05</span>), (<span class="n">0.07</span>, reach + <span class="n">0.11</span>), (<span class="n">0.0</span>, reach + <span class="n">0.11</span>)]
lug = lathe_object(<span class="s">f"</span><span class="s">Lug</span>{idx}<span class="s">"</span>, lug_prof, <span class="n">6</span>)
lug.data.materials.append(iron)
cap_cage = lathe_object(<span class="s">f"</span><span class="s">CapCage</span>{idx}<span class="s">"</span>, prof_c, CAGE_SEG_CAP, inflate_cap)
lug_cage = lathe_object(<span class="s">f"</span><span class="s">LugCage</span>{idx}<span class="s">"</span>, lug_prof, CAGE_SEG_CAP, inflate_cap)
rot = (math.radians(<span class="n">90</span>), <span class="n">0.0</span>, math.radians(azim + <span class="n">90.0</span>))
<span class="k">for</span> o <span class="k">in</span> (cap, lug, cap_cage, lug_cage):
o.rotation_euler = rot
o.location = (<span class="n">0.0</span>, <span class="n">0.0</span>, z)
groups.append({<span class="s">"name"</span>: <span class="s">"pumper"</span> <span class="k">if</span> big <span class="k">else</span> <span class="s">f"</span><span class="s">side</span>{idx}<span class="s">"</span>,
<span class="s">"render"</span>: [cap, lug], <span class="s">"cage"</span>: [cap_cage, lug_cage]})
<span class="k">return</span> groups
<span class="c"># ---------------------------------------------------------------------------</span>
<span class="c"># Hull construction and the contract checks.</span>
<span class="c"># ---------------------------------------------------------------------------</span>
<span class="k">def</span> collect_points(objects):
<span class="s">"""World-space vertex cloud, read via foreach_get."""</span>
bpy.context.view_layer.update() <span class="c"># matrix_world lags RNA writes until evaluated</span>
pts = []
<span class="k">for</span> o <span class="k">in</span> objects:
me = o.data
buf = [<span class="n">0.0</span>] * (len(me.vertices) * <span class="n">3</span>)
me.vertices.foreach_get(<span class="s">"co"</span>, buf)
mw = o.matrix_world
<span class="k">for</span> i <span class="k">in</span> range(<span class="n">0</span>, len(buf), <span class="n">3</span>):
pts.append(mw @ Vector((buf[i], buf[i + <span class="n">1</span>], buf[i + <span class="n">2</span>])))
<span class="k">return</span> pts
<span class="k">def</span> build_hull(name, points):
<span class="s">"""Convex hull of a point cloud via bmesh.ops.convex_hull."""</span>
me = bpy.data.meshes.new(name)
bm = bmesh.new()
<span class="k">try</span>:
verts = [bm.verts.new(p) <span class="k">for</span> p <span class="k">in</span> points]
bmesh.ops.convex_hull(bm, input=verts)
<span class="c"># the op leaves interior input verts behind; drop any vert not</span>
<span class="c"># referenced by a face so V - E + F is meaningful</span>
used = {v <span class="k">for</span> f <span class="k">in</span> bm.faces <span class="k">for</span> v <span class="k">in</span> f.verts}
<span class="k">for</span> v <span class="k">in</span> list(bm.verts):
<span class="k">if</span> v <span class="k">not</span> <span class="k">in</span> used:
bm.verts.remove(v)
bmesh.ops.recalc_face_normals(bm, faces=bm.faces)
bm.to_mesh(me)
<span class="k">finally</span>:
bm.free()
obj = bpy.data.objects.new(name, me)
bpy.context.collection.objects.link(obj)
<span class="k">return</span> obj
<span class="k">def</span> max_plane_excursion(me, points):
<span class="s">"""Largest signed distance of any point to the OUTER side of any face
plane. <= 0 means every point is inside or on the hull."""</span>
worst = -math.inf
where = <span class="k">None</span>
<span class="k">for</span> p <span class="k">in</span> me.polygons:
n = p.normal
c = p.center
<span class="k">for</span> q <span class="k">in</span> points:
d = (q - c).dot(n)
<span class="k">if</span> d > worst:
worst = d
where = (p.index, tuple(round(v, <span class="n">4</span>) <span class="k">for</span> v <span class="k">in</span> q))
<span class="k">return</span> worst, where
<span class="k">def</span> check(pieces):
<span class="s">"""pieces: [(group_name, hull_obj, render_points)]. Returns exit code."""</span>
total_faces = <span class="n">0</span>
<span class="k">for</span> name, hull, points <span class="k">in</span> pieces:
me = hull.data
nv, ne, nf = len(me.vertices), len(me.edges), len(me.polygons)
total_faces += nf
bm = bmesh.new() <span class="c"># watertight: every edge borders exactly two faces</span>
<span class="k">try</span>:
bm.from_mesh(me)
bad_edges = sum(<span class="n">1</span> <span class="k">for</span> e <span class="k">in</span> bm.edges <span class="k">if</span> len(e.link_faces) != <span class="n">2</span>)
<span class="k">finally</span>:
bm.free()
<span class="k">if</span> bad_edges:
print(<span class="s">f"</span><span class="s">ERROR: piece </span>{name}<span class="s">: </span>{bad_edges}<span class="s"> hull edge(s) do not border </span><span class="s">"</span>
<span class="s">f"</span><span class="s">exactly two faces — proxy is not watertight</span><span class="s">"</span>, file=sys.stderr)
<span class="k">return</span> <span class="n">4</span>
vol = signed_volume(me) <span class="c"># winding: positive signed volume</span>
<span class="k">if</span> vol <= <span class="n">0.0</span>:
print(<span class="s">f"</span><span class="s">ERROR: piece </span>{name}<span class="s">: signed volume </span>{vol:<span class="s">.6f</span>}<span class="s"> <= 0 — hull </span><span class="s">"</span>
<span class="s">f"</span><span class="s">winding is inverted</span><span class="s">"</span>, file=sys.stderr)
<span class="k">return</span> <span class="n">5</span>
contain_err, where = max_plane_excursion(me, points)
<span class="k">if</span> contain_err > TOL:
print(<span class="s">f"</span><span class="s">ERROR: piece </span>{name}<span class="s">: render vertex escapes its hull by </span><span class="s">"</span>
<span class="s">f"</span>{contain_err:<span class="s">.6f</span>}<span class="s"> (tol </span>{TOL}<span class="s">) at face </span>{where[<span class="n">0</span>]}<span class="s">, point </span><span class="s">"</span>
<span class="s">f"</span>{where[<span class="n">1</span>]}<span class="s"> — proxy does not enclose the render mesh</span><span class="s">"</span>,
file=sys.stderr)
<span class="k">return</span> <span class="n">3</span>
hull_pts = [v.co.copy() <span class="k">for</span> v <span class="k">in</span> me.vertices]
hull_err, _ = max_plane_excursion(me, hull_pts)
<span class="k">if</span> hull_err > TOL:
print(<span class="s">f"</span><span class="s">ERROR: piece </span>{name}<span class="s">: hull vertex off its own face plane by </span><span class="s">"</span>
<span class="s">f"</span>{hull_err:<span class="s">.6f</span>}<span class="s"> — proxy is not convex</span><span class="s">"</span>, file=sys.stderr)
<span class="k">return</span> <span class="n">6</span>
euler = nv - ne + nf <span class="c"># a convex hull is a topological sphere</span>
<span class="k">if</span> euler != <span class="n">2</span>:
print(<span class="s">f"</span><span class="s">ERROR: piece </span>{name}<span class="s">: Euler characteristic </span>{euler}<span class="s"> != 2 — </span><span class="s">"</span>
<span class="s">f"</span><span class="s">hull is not a closed manifold sphere</span><span class="s">"</span>, file=sys.stderr)
<span class="k">return</span> <span class="n">7</span>
<span class="k">if</span> nf > HULL_BUDGET:
print(<span class="s">f"</span><span class="s">ERROR: piece </span>{name}<span class="s">: </span>{nf}<span class="s"> faces, over the </span>{HULL_BUDGET}<span class="s">-face </span><span class="s">"</span>
<span class="s">f"</span><span class="s">per-piece collision budget</span><span class="s">"</span>, file=sys.stderr)
<span class="k">return</span> <span class="n">8</span>
print(<span class="s">f"</span><span class="s">piece </span>{name}<span class="s">: verts=</span>{nv}<span class="s"> edges=</span>{ne}<span class="s"> faces=</span>{nf}<span class="s"> watertight=True </span><span class="s">"</span>
<span class="s">f"</span><span class="s">euler=2 volume=</span>{vol:<span class="s">.6f</span>}<span class="s"> containment=</span>{contain_err:<span class="s">.3e</span>}<span class="s"> </span><span class="s">"</span>
<span class="s">f"</span><span class="s">convexity=</span>{hull_err:<span class="s">.3e</span>}<span class="s"> budget=</span>{nf}<span class="s"><=</span>{HULL_BUDGET}<span class="s">"</span>)
print(<span class="s">f"</span><span class="s">compound: pieces=</span>{len(pieces)}<span class="s"> total_faces=</span>{total_faces}<span class="s"> </span><span class="s">"</span>
<span class="s">f"</span><span class="s">(per-piece budget </span>{HULL_BUDGET}<span class="s">; engine ingests the compound)</span><span class="s">"</span>)
<span class="k">return</span> <span class="n">0</span>
<span class="c"># ---------------------------------------------------------------------------</span>
<span class="c"># Render: dark-studio staging per docs/VISUAL-STYLE.md. The hull pieces draw</span>
<span class="c"># as faceted translucent shells with a thin wire overlay; if a piece failed</span>
<span class="c"># to enclose its geometry, painted metal would poke through the shell.</span>
<span class="c"># ---------------------------------------------------------------------------</span>
<span class="k">def</span> eevee_engine_id():
<span class="k">return</span> <span class="s">'BLENDER_EEVEE'</span> <span class="k">if</span> bpy.app.version >= (<span class="n">5</span>, <span class="n">0</span>, <span class="n">0</span>) <span class="k">else</span> <span class="s">'BLENDER_EEVEE_NEXT'</span>
<span class="k">def</span> render_still(groups, pieces, path, engine):
scene = bpy.context.scene
<span class="k">for</span> g <span class="k">in</span> groups:
<span class="k">for</span> o <span class="k">in</span> g[<span class="s">"render"</span>]:
<span class="k">for</span> p <span class="k">in</span> o.data.polygons:
p.use_smooth = <span class="k">True</span>
<span class="k">for</span> g <span class="k">in</span> groups: <span class="c"># cages exist only to build hulls; never rendered</span>
<span class="k">for</span> o <span class="k">in</span> g[<span class="s">"cage"</span>]:
o.hide_render = <span class="k">True</span>
<span class="c"># translucent shell: Transparent mixed over Principled works identically</span>
<span class="c"># in EEVEE and Cycles without touching blend-method RNA (renamed in 4.2)</span>
shell = bpy.data.materials.new(<span class="s">"HullShell"</span>)
shell.use_nodes = <span class="k">True</span>
nt = shell.node_tree
nt.nodes.clear()
out = nt.nodes.new(<span class="s">"ShaderNodeOutputMaterial"</span>)
mix = nt.nodes.new(<span class="s">"ShaderNodeMixShader"</span>)
mix.inputs[<span class="n">0</span>].default_value = <span class="n">0.14</span> <span class="c"># 86% transparent: output =</span>
<span class="c"># (1-Fac)*Transparent + Fac*Principled</span>
transp = nt.nodes.new(<span class="s">"ShaderNodeBsdfTransparent"</span>)
bsdf = nt.nodes.new(<span class="s">"ShaderNodeBsdfPrincipled"</span>)
bsdf.inputs[<span class="s">"Base Color"</span>].default_value = (<span class="n">0.16</span>, <span class="n">0.55</span>, <span class="n">0.75</span>, <span class="n">1.0</span>)
bsdf.inputs[<span class="s">"Roughness"</span>].default_value = <span class="n">0.12</span>
nt.links.new(transp.outputs[<span class="n">0</span>], mix.inputs[<span class="n">1</span>])
nt.links.new(bsdf.outputs[<span class="n">0</span>], mix.inputs[<span class="n">2</span>])
nt.links.new(mix.outputs[<span class="n">0</span>], out.inputs[<span class="n">0</span>])
wire_mat = make_material(<span class="s">"HullWire"</span>, (<span class="n">0.35</span>, <span class="n">0.85</span>, <span class="n">1.0</span>), <span class="n">0.0</span>, <span class="n">0.4</span>)
wbsdf = wire_mat.node_tree.nodes[<span class="s">"Principled BSDF"</span>]
wbsdf.inputs[<span class="s">"Emission Color"</span>].default_value = (<span class="n">0.2</span>, <span class="n">0.65</span>, <span class="n">0.85</span>, <span class="n">1.0</span>)
wbsdf.inputs[<span class="s">"Emission Strength"</span>].default_value = <span class="n">0.6</span>
<span class="k">for</span> name, hull, _ <span class="k">in</span> pieces:
hull.data.materials.append(shell)
<span class="k">for</span> p <span class="k">in</span> hull.data.polygons:
p.use_smooth = <span class="k">False</span> <span class="c"># facets must read as facets</span>
hull.data.materials.append(wire_mat)
wire = bpy.data.objects.new(<span class="s">f"</span>{name}<span class="s">Wire</span><span class="s">"</span>, hull.data)
mod = wire.modifiers.new(<span class="s">"Wire"</span>, <span class="s">'WIREFRAME'</span>)
mod.thickness = <span class="n">0.010</span>
mod.material_offset = <span class="n">1</span>
scene.collection.objects.link(wire)
floor_me = bpy.data.meshes.new(<span class="s">"Floor"</span>)
bm = bmesh.new()
<span class="k">try</span>:
bmesh.ops.create_grid(bm, x_segments=<span class="n">1</span>, y_segments=<span class="n">1</span>, size=<span class="n">30.0</span>)
bm.to_mesh(floor_me)
<span class="k">finally</span>:
bm.free()
fmat = make_material(<span class="s">"Studio"</span>, (<span class="n">0.03</span>, <span class="n">0.032</span>, <span class="n">0.037</span>), <span class="n">0.0</span>, <span class="n">0.7</span>)
floor_me.materials.append(fmat)
floor = bpy.data.objects.new(<span class="s">"Floor"</span>, floor_me)
scene.collection.objects.link(floor)
wall = bpy.data.objects.new(<span class="s">"Wall"</span>, floor_me.copy())
wall.location = (<span class="n">0.0</span>, <span class="n">11.0</span>, <span class="n">0.0</span>)
wall.rotation_euler = (math.radians(<span class="n">90</span>), <span class="n">0.0</span>, <span class="n">0.0</span>)
scene.collection.objects.link(wall)
world = bpy.data.worlds.new(<span class="s">"World"</span>)
world.use_nodes = <span class="k">True</span>
world.node_tree.nodes[<span class="s">"Background"</span>].inputs[<span class="s">"Color"</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>)
scene.world = world
<span class="k">def</span> light(name, loc, energy, size, col, rot):
ld = bpy.data.lights.new(name, <span class="s">'AREA'</span>)
ld.energy = energy; ld.size = size; ld.color = col
ob = bpy.data.objects.new(name, ld)
ob.location = loc
ob.rotation_euler = tuple(math.radians(a) <span class="k">for</span> a <span class="k">in</span> rot)
scene.collection.objects.link(ob)
<span class="c"># key/fill/rim/wedge per docs/VISUAL-STYLE.md</span>
light(<span class="s">"Key"</span>, (-<span class="n">3.5</span>, -<span class="n">4.5</span>, <span class="n">5.5</span>), <span class="n">500.0</span>, <span class="n">4.5</span>, (<span class="n">1.0</span>, <span class="n">0.96</span>, <span class="n">0.9</span>), (<span class="n">48</span>, <span class="n">0</span>, -<span class="n">35</span>))
light(<span class="s">"Fill"</span>, (<span class="n">5.0</span>, -<span class="n">3.5</span>, <span class="n">2.5</span>), <span class="n">130.0</span>, <span class="n">9.0</span>, (<span class="n">0.75</span>, <span class="n">0.85</span>, <span class="n">1.0</span>), (<span class="n">65</span>, <span class="n">0</span>, <span class="n">50</span>))
light(<span class="s">"Rim"</span>, (<span class="n">1.5</span>, <span class="n">4.5</span>, <span class="n">3.5</span>), <span class="n">300.0</span>, <span class="n">3.0</span>, (<span class="n">0.6</span>, <span class="n">0.78</span>, <span class="n">1.0</span>), (-<span class="n">55</span>, <span class="n">0</span>, <span class="n">170</span>))
light(<span class="s">"Wedge"</span>, (<span class="n">2.5</span>, <span class="n">5.5</span>, <span class="n">4.0</span>), <span class="n">380.0</span>, <span class="n">6.0</span>, (<span class="n">1.0</span>, <span class="n">0.76</span>, <span class="n">0.5</span>), (-<span class="n">68</span>, <span class="n">0</span>, <span class="n">190</span>))
<span class="c"># small warm glint off the camera-left shoulder: lifts the pumper cap face</span>
light(<span class="s">"Glint"</span>, (-<span class="n">1.5</span>, -<span class="n">4.0</span>, <span class="n">3.5</span>), <span class="n">260.0</span>, <span class="n">2.0</span>, (<span class="n">1.0</span>, <span class="n">0.9</span>, <span class="n">0.75</span>), (<span class="n">55</span>, <span class="n">0</span>, -<span class="n">15</span>))
cam_data = bpy.data.cameras.new(<span class="s">"Cam"</span>)
cam_data.lens = <span class="n">52.0</span>
cam = bpy.data.objects.new(<span class="s">"Cam"</span>, cam_data)
cam.location = (<span class="n">2.05</span>, -<span class="n">4.5</span>, <span class="n">1.85</span>)
scene.collection.objects.link(cam)
target = bpy.data.objects.new(<span class="s">"Aim"</span>, <span class="k">None</span>)
target.location = (<span class="n">0.0</span>, <span class="n">0.0</span>, <span class="n">0.72</span>)
scene.collection.objects.link(target)
con = cam.constraints.new(<span class="s">'TRACK_TO'</span>)
con.target = target
scene.camera = cam
scene.render.engine = <span class="s">'CYCLES'</span> <span class="k">if</span> engine == <span class="s">'cycles'</span> <span class="k">else</span> eevee_engine_id()
<span class="k">if</span> engine == <span class="s">'cycles'</span>:
scene.cycles.samples = <span class="n">64</span>
<span class="k">else</span>:
<span class="k">try</span>:
scene.eevee.taa_render_samples = <span class="n">64</span>
<span class="k">except</span> AttributeError:
<span class="k">pass</span>
scene.render.resolution_x = <span class="n">1280</span>
scene.render.resolution_y = <span class="n">720</span>
scene.render.image_settings.file_format = <span class="s">'PNG'</span>
scene.render.filepath = path
<span class="c"># AgX would flatten the enamel toward pastel (docs/VISUAL-STYLE.md)</span>
scene.view_settings.view_transform = <span class="s">'Standard'</span>
bpy.ops.render.render(write_still=<span class="k">True</span>)
<span class="k">return</span> os.path.exists(path) <span class="k">and</span> os.path.getsize(path) > <span class="n">0</span>
<span class="k">def</span> main():
argv = sys.argv[sys.argv.index(<span class="s">"--"</span>) + <span class="n">1</span>:] <span class="k">if</span> <span class="s">"--"</span> <span class="k">in</span> sys.argv <span class="k">else</span> []
p = argparse.ArgumentParser()
p.add_argument(<span class="s">"--output"</span>, default=<span class="k">None</span>, help=<span class="s">"optional: render a still PNG here"</span>)
p.add_argument(<span class="s">"--engine"</span>, default=<span class="s">"eevee"</span>, choices=(<span class="s">"eevee"</span>, <span class="s">"cycles"</span>),
help=<span class="s">"render engine for --output (cycles for GPU-less hosts)"</span>)
p.add_argument(<span class="s">"--shrink-hull"</span>, action=<span class="s">"store_true"</span>,
help=<span class="s">"scale hull vertices by 0.5 (must fail)"</span>)
args = p.parse_args(argv)
groups = build_hydrant()
pieces = []
<span class="k">for</span> g <span class="k">in</span> groups:
hull = build_hull(<span class="s">f"</span>{g[<span class="s">'name'</span>]}<span class="s">Hull</span><span class="s">"</span>, collect_points(g[<span class="s">"cage"</span>]))
<span class="k">if</span> args.shrink_hull:
<span class="k">for</span> v <span class="k">in</span> hull.data.vertices:
v.co *= <span class="n">0.5</span>
hull.data.update()
pieces.append((g[<span class="s">"name"</span>], hull, collect_points(g[<span class="s">"render"</span>])))
code = check(pieces)
<span class="k">if</span> code:
<span class="k">return</span> code
<span class="k">if</span> args.output:
<span class="k">if</span> <span class="k">not</span> render_still(groups, pieces, os.path.abspath(args.output), args.engine):
print(<span class="s">"ERROR: render produced no file"</span>, file=sys.stderr)
<span class="k">return</span> <span class="n">9</span>
print(<span class="s">f"</span><span class="s">rendered still </span>{args.output}<span class="s">"</span>)
print(<span class="s">"collision-hull-proxy OK"</span>)
<span class="k">return</span> <span class="n">0</span>
<span class="k">if</span> __name__ == <span class="s">"__main__"</span>:
<span class="k">try</span>:
sys.exit(main())
<span class="k">except</span> Exception <span class="k">as</span> e:
<span class="k">import</span> traceback; traceback.print_exc(); print(<span class="s">f"</span><span class="s">FATAL: </span>{e}<span class="s">"</span>, file=sys.stderr); sys.exit(<span class="n">1</span>)
</pre>
</section>
</main>
<dialog class="lightbox" id="lightbox" aria-label="Full-size render">
<button class="lightbox-close" type="button" autofocus>Close</button>
<img src="../assets/collision-hull-proxy-hero.webp" alt="collision-hull-proxy render, full size" />
</dialog>
<footer>
<div class="statusbar">
<span>generated from <code>examples/gallery.json</code></span>
<span>CC-BY-NC-ND-4.0</span>
<span style="color: var(--ok);">exit 0</span>
</div>
</footer>
<script>
(function () {
var hero = document.getElementById('heroZoom');
var box = document.getElementById('lightbox');
if (hero && box) {
// <dialog>.showModal() traps focus, closes on Escape, and returns
// focus to the hero button on close. Any click inside closes it.
hero.addEventListener('click', function () { box.showModal(); });
box.addEventListener('click', function () { box.close(); });
}
var copy = document.getElementById('copyRun');
if (copy) {
copy.addEventListener('click', function () {
var cmd = document.getElementById('runCmd').textContent;
navigator.clipboard.writeText(cmd).then(function () {
copy.textContent = 'Copied!';
setTimeout(function () { copy.textContent = 'Copy'; }, 1500);
});
});
}
})();
</script>
</body>
</html>