nx_gsplat_frommesh_gate.nx source

1// nx_gsplat_frommesh_gate.nx -- THE GATE FOR MESH -> GAUSSIANS (gs_from_mesh, landed 2026-09-04). 2// 3// The subject is the ingest edge of the splat lane: the estate could render, fit, densify and cage-bind 4// gaussians but could not MAKE them from a mesh, so an authored sculpt could not enter the representation. 5// 6// ★ANTI-VACUITY IS THE POINT OF THIS FILE. A converter that emitted one fixed blob per triangle, ignored 7// the density argument, painted every splat one colour and picked a constant radius would still "produce 8// gaussians" and would pass any tooth that only counted them. So the load-bearing teeth are the ones such 9// an implementation FAILS: density must move the count (T2), density must move the radius INVERSELY (T6), 10// two faces of different size must get the SAME radius at one density (T7 -- uniform coverage is the whole 11// reason the radius is derived rather than picked), and a three-coloured face must yield more than one 12// splat colour (T5). 13// 14// ⚠T6/T7 ARE AN ARITHMETIC IDENTITY, NOT A HOPE: side = isqrt(density*area/GFX^2) and rtan = 15// isqrt(area/nsamp), so rtan reduces to GFX/isqrt(density) -- INDEPENDENT of area. That is why a bigger 16// face gets more splats of the same size instead of bigger splats, and it is checked as an identity. 17// MEASURED on the first run: rtan 32 at density 1024 and 16 at 4096, which is GFX/isqrt(density) exactly. 18// 19// ⚠NEGATIVE CONTROLS CARRIED: an empty mesh must yield nothing rather than fabricate (NC1), and a 20// degenerate zero-area triangle must be skipped without crashing and without inventing a surfel (NC2). 21// 22// ⚠⚠EVERY CONJUNCT IS BUILT WITH NESTED ifs, NEVER WITH gv_env_pair. That helper PRINTS a pair and 23// RETURNS 0, so passing it as a condition feeds the tooth a constant zero. v1 of this gate did exactly 24// that and read 7/12 RED with `[1,1]` printed ahead of every failure -- the pair values proving BOTH 25// conjuncts were true while the tooth recorded FAIL. A helper whose return value is not its meaning is 26// the cheapest way to build a gate that lies in the safe direction. 27// 28// nx_gsplat_frommesh_gate 29// license_tier: ORIGINAL expect_exit: 0 No hw writes (Rule 26). 30import "nx_gsplat.nx" 31import "nx_gate_verdict.nx" 32 33const FG_TS: i64 = 18 // triangle record stride, mirrored from gs_tri_stride() 34const FG_GS: i64 = 12 // anisotropic gaussian stride (GSTA) 35const FG_CAP: i64 = 4096 // fixture gaussian capacity 36const FG_STATS: i64 = 4 37const FG_UNIT: i64 = 1024 // one model unit in GFX fixed point 38const FG_DENSITY: i64 = 1024 // baseline samples per unit area 39const FG_DENSITY_4X: i64 = 4096 // 4x density: shrinks the radius, grows the count 40const FG_OPACITY: i64 = 200 41const FG_COL_R: i64 = 240 42const FG_COL_G: i64 = 120 43const FG_COL_B: i64 = 30 44const FG_NORMAL_UNIT: i64 = 256 // GFXA: a unit normal component 45const FG_SMALL_CAP: i64 = 3 // deliberately smaller than the fixture requests, to force truncation 46const FG_TRIBUF: i64 = 8 // triangles the fixture buffer holds 47 48// one right triangle in the z=0 plane, scaled by sc, with three DIFFERENT vertex colours 49func fg_tri(tris: *i64, t: i64, sc: i64) -> i64 { 50 let b: i64 = t * FG_TS 51 tris[b]=0; tris[b+1]=0; tris[b+2]=0; tris[b+3]=FG_COL_R; tris[b+4]=0; tris[b+5]=0 52 tris[b+6]=sc; tris[b+7]=0; tris[b+8]=0; tris[b+9]=0; tris[b+10]=FG_COL_G; tris[b+11]=0 53 tris[b+12]=0; tris[b+13]=sc; tris[b+14]=0; tris[b+15]=0; tris[b+16]=0; tris[b+17]=FG_COL_B 54 return 0 55} 56 57// a face with zero area: two of its edges are collinear, so the cross product vanishes 58func fg_degenerate(tris: *i64, t: i64) -> i64 { 59 let b: i64 = t * FG_TS 60 var i: i64 = 0 61 while i < FG_TS { tris[b+i] = 0; i = i + 1 } 62 tris[b+6] = FG_UNIT 63 tris[b+12] = FG_UNIT 64 return 0 65} 66 67func main(argc: i64, argv: *i64) -> i64 { 68 let ctr: *i64 = gv_ctr() 69 gv_head("nx_gsplat_frommesh_gate -- a mesh becomes gaussians, and every quantity is derived" as *u8) 70 71 let tris: *i64 = sys_mmap(FG_TS * FG_TRIBUF * 8) as *i64 72 let g1: *i64 = sys_mmap(FG_CAP * FG_GS * 8) as *i64 73 let g2: *i64 = sys_mmap(FG_CAP * FG_GS * 8) as *i64 74 let g3: *i64 = sys_mmap(FG_CAP * FG_GS * 8) as *i64 75 let g4: *i64 = sys_mmap(FG_CAP * FG_GS * 8) as *i64 76 let g5: *i64 = sys_mmap(FG_CAP * FG_GS * 8) as *i64 77 let s1: *i64 = sys_mmap(FG_STATS * 8) as *i64 78 let s2: *i64 = sys_mmap(FG_STATS * 8) as *i64 79 let s3: *i64 = sys_mmap(FG_STATS * 8) as *i64 80 let s4: *i64 = sys_mmap(FG_STATS * 8) as *i64 81 let s5: *i64 = sys_mmap(FG_STATS * 8) as *i64 82 let s6: *i64 = sys_mmap(FG_STATS * 8) as *i64 83 let s7: *i64 = sys_mmap(FG_STATS * 8) as *i64 84 85 fg_tri(tris, 0, FG_UNIT) 86 let n1: i64 = gs_from_mesh(tris, 1, g1, FG_CAP, FG_DENSITY, FG_OPACITY, s1) 87 var t1: i64 = 0 88 if s1[0] == 1 { if n1 > 0 { t1 = 1 } } 89 gv_check("T1 COVERAGE: the face is visited and yields at least one surfel -- no face silently vanishes" as *u8, t1, ctr) 90 91 let n2: i64 = gs_from_mesh(tris, 1, g2, FG_CAP, FG_DENSITY_4X, FG_OPACITY, s2) 92 var t2: i64 = 0 93 if n2 > n1 { t2 = 1 } 94 gv_check("T2 DENSITY DRIVES THE COUNT: 4x density yields strictly more surfels -- the argument does work" as *u8, t2, ctr) 95 96 var t3: i64 = 1 97 var t4: i64 = 1 98 var i: i64 = 0 99 while i < n1 { 100 if g1[i*FG_GS+2] != 0 { t3 = 0 } 101 if g1[i*FG_GS+3] != 0 { t4 = 0 } 102 if g1[i*FG_GS+4] != 0 { t4 = 0 } 103 if g1[i*FG_GS+5] != FG_NORMAL_UNIT { t4 = 0 } 104 i = i + 1 105 } 106 gv_check("T3 ON-SURFACE: every surfel lies in the face plane, none floats off it" as *u8, t3, ctr) 107 gv_check("T4 ORIENTATION: every surfel carries the FACE normal as a unit vector, not a guess" as *u8, t4, ctr) 108 109 var t5: i64 = 0 110 i = 1 111 while i < n1 { 112 if g1[i*FG_GS+7] != g1[7] { t5 = 1 } 113 if g1[i*FG_GS+8] != g1[8] { t5 = 1 } 114 i = i + 1 115 } 116 gv_check("T5 COLOUR INTERPOLATES ACROSS THE FACE: a three-coloured triangle is not painted one colour" as *u8, t5, ctr) 117 118 let r1: i64 = g1[6] 119 let r2: i64 = g2[6] 120 var t6: i64 = 0 121 if r2 < r1 { t6 = 1 } 122 gv_check("T6 RADIUS RIDES DENSITY INVERSELY: 4x the samples means a smaller disk, never a picked constant" as *u8, t6, ctr) 123 124 fg_tri(tris, 0, FG_UNIT * 2) 125 let n3: i64 = gs_from_mesh(tris, 1, g3, FG_CAP, FG_DENSITY, FG_OPACITY, s3) 126 var t7: i64 = 0 127 if n3 > n1 { if g3[6] == r1 { t7 = 1 } } 128 gv_check("T7 UNIFORM COVERAGE: a face 4x the area gets MORE surfels of the SAME size, not bigger ones" as *u8, t7, ctr) 129 130 let n4: i64 = gs_from_mesh(tris, 1, g4, FG_CAP, FG_DENSITY, FG_OPACITY, s4) 131 var t8: i64 = 1 132 if n4 != n3 { t8 = 0 } 133 i = 0 134 while i < n3 * FG_GS { if g4[i] != g3[i] { t8 = 0 } i = i + 1 } 135 gv_check("T8 DETERMINISTIC: the same mesh converts to the same cloud, byte for byte, with no RNG" as *u8, t8, ctr) 136 137 let n5: i64 = gs_from_mesh(tris, 1, g5, FG_SMALL_CAP, FG_DENSITY, FG_OPACITY, s5) 138 gv_check_eq("T9 NO SILENT CAP: a full buffer is REPORTED truncated, never quietly short" as *u8, s5[1], 1, ctr) 139 var t9b: i64 = 0 140 if n5 == FG_SMALL_CAP { if s5[2] > n5 { t9b = 1 } } 141 gv_check("T9b the cap is honoured exactly and the request is still reported in full" as *u8, t9b, ctr) 142 143 let n6: i64 = gs_from_mesh(tris, 0, g5, FG_CAP, FG_DENSITY, FG_OPACITY, s6) 144 var nc1: i64 = 0 145 if n6 == 0 { if s6[1] == 0 { nc1 = 1 } } 146 gv_check("neg-control-empty-mesh-fabricates-nothing" as *u8, nc1, ctr) 147 148 fg_degenerate(tris, 0) 149 let n7: i64 = gs_from_mesh(tris, 1, g5, FG_CAP, FG_DENSITY, FG_OPACITY, s7) 150 var nc2: i64 = 0 151 if n7 == 0 { if s7[0] == 1 { nc2 = 1 } } 152 gv_check("neg-control-degenerate-face-skipped-not-crashed-not-invented" as *u8, nc2, ctr) 153 154 gv_values_head() 155 gv_kv("triangle_stride" as *u8, gs_tri_stride()) 156 gv_kv("stats_slots" as *u8, gs_fm_stats()) 157 gv_kv("gaussians_unit_face" as *u8, n1) 158 gv_kv("gaussians_4x_density" as *u8, n2) 159 gv_kv("gaussians_double_face" as *u8, n3) 160 gv_kv("rtan_density_1x" as *u8, r1) 161 gv_kv("rtan_density_4x" as *u8, r2) 162 gv_kv("rtan_double_face" as *u8, g3[6]) 163 gv_kv("capped_written" as *u8, n5) 164 gv_kv("capped_requested" as *u8, s5[2]) 165 gv_kv("normal_z_fx256" as *u8, g1[5]) 166 167 return gv_verdict("GSPLAT-FROMMESH-GATE" as *u8, ctr, 168 "a mesh becomes oriented surfels: coverage, on-surface, face normal, interpolated colour, derived radius, determinism, announced cap" as *u8) 169}