nx_gsplat_fit_gate.nx source
↩ module page · 186 lines · 10464 B
1// nx_gsplat_fit_gate.nx -- THE RECONSTRUCTOR TOOTH: can we FIT gaussians to an image, or only PLACE them?
2//
3// WHY THIS GATE EXISTS. Until 2026-08-23 nx_gsplat could optimise COLOUR only. Colour is the easy leg --
4// a pixel is LINEAR in colour, so the gradient is analytic and a step cannot really go wrong. Position is
5// what 3D Gaussian Splatting actually IS: without it we have a splat RENDERER, not a splat RECONSTRUCTOR,
6// and the whole photoreal-avatar lane rests on reconstruction. gs_pos_grad_step adds the position leg.
7//
8// ★★THE ACCEPT RULE IS DECLARED HERE, BEFORE THE EXPERIMENT, and it is deliberately threshold-free:
9// MONOTONE RECOVERY -- the mean |position - truth| must STRICTLY DECREASE at EVERY step. Not "drops
10// below X", which is a number nobody measured; strict monotonicity over the whole run. This is the
11// ANTI-VACUITY tooth and it is the reason the gate exists:
12// - an implementation whose position gradient is ZERO leaves the error EXACTLY constant -> FAILS
13// - an implementation that JITTERS reduces error sometimes and raises it others -> FAILS
14// - only a gradient that actually points downhill can decrease it every single step.
15// A loss-only tooth would pass all three, which is why loss is reported but is NOT the accept rule.
16//
17// ★AND THE OPTIMUM IS A CONTROL, NOT AN ASSUMPTION. T5 runs the SAME step on a scene ALREADY at truth.
18// A correct gradient is ~0 there and the scene must stay put; a jittering one wanders. The bite is asked
19// both directions -- fires on the perturbed scene, silent on the converged one -- because a step that
20// moves everything passes every "it moved" check ever written.
21//
22// ⚠FIXTURE HONOURS THE DECLARED APPROXIMATION. gs_pos_grad_step ignores transmittance (stated in its
23// own header), so the fixture separates every gaussian in DEPTH: the approximation is exact for a
24// non-overlapping scene, and testing an organ outside its declared domain measures the fixture.
25// license_tier: ORIGINAL expect_exit: 0
26import "nx_syscalls.nx"
27import "nx_gsplat.nx"
28import "nx_gate_verdict.nx"
29
30const FG_NG: i64 = 8
31const FG_STEPS: i64 = 12
32const FG_CAMZ: i64 = 30
33const FG_SC: i64 = 400
34const FG_XSTEP: i64 = 2600
35const FG_ZSTEP: i64 = 900
36const FG_PERTURB: i64 = 300 // world units; see T1 for its size in PIXELS, which is what matters
37const FG_W64: i64 = 8
38const FG_BGR: i64 = 26
39const FG_BGG: i64 = 28
40const FG_BGB: i64 = 44
41
42func fg_abs(v: i64) -> i64 { if v < 0 { return 0 - v } return v }
43
44// ground truth: FG_NG opaque isotropic gaussians, SEPARATED IN DEPTH (see the header note).
45func fg_truth(g: *i64) -> i64 {
46 var i: i64 = 0
47 while i < FG_NG {
48 let x: i64 = 0 - (FG_NG/2)*FG_XSTEP + i*FG_XSTEP
49 let y: i64 = 0 - 1200 + (i - (i/2)*2) * 2400
50 let z: i64 = 0 - (FG_NG/2)*FG_ZSTEP + i*FG_ZSTEP
51 gs_set(g, i, x, y, z, FG_SC, 40 + i*26, 220 - i*12, 120 + i*16, gs_fxa())
52 i = i + 1
53 }
54 return FG_NG
55}
56func fg_copy(dst: *i64, src: *i64, n: i64) -> i64 {
57 var i: i64 = 0
58 while i < n { dst[i] = src[i]; i = i + 1 }
59 return 0
60}
61// mean |position - truth| summed over both axes, in world units.
62func fg_poserr(g: *i64, t: *i64) -> i64 {
63 var e: i64 = 0
64 var i: i64 = 0
65 while i < FG_NG {
66 e = e + fg_abs(g[i*8] - t[i*8]) + fg_abs(g[i*8+1] - t[i*8+1])
67 i = i + 1
68 }
69 return e / FG_NG
70}
71
72func main() -> i64 {
73 let ctr: *i64 = gv_ctr()
74 gv_head("nx_gsplat_fit_gate -- position gradient: the scene is RECONSTRUCTED from the image, not merely placed" as *u8)
75
76 let npx: i64 = gs_w() * gs_h()
77 let truth: *i64 = sys_mmap(FG_NG*8*FG_W64) as *i64
78 let work: *i64 = sys_mmap(FG_NG*8*FG_W64) as *i64
79 let ctrl: *i64 = sys_mmap(FG_NG*8*FG_W64) as *i64
80 let target: *i64 = sys_mmap(npx*FG_W64) as *i64
81 let fb: *i64 = sys_mmap(npx*FG_W64) as *i64
82 let acc: *i64 = sys_mmap(npx*3*FG_W64) as *i64
83 let trans: *i64 = sys_mmap(npx*FG_W64) as *i64
84 let depth: *i64 = sys_mmap(FG_NG*FG_W64) as *i64
85 let sxb: *i64 = sys_mmap(FG_NG*FG_W64) as *i64
86 let syb: *i64 = sys_mmap(FG_NG*FG_W64) as *i64
87 let sigb: *i64 = sys_mmap(FG_NG*FG_W64) as *i64
88 let order: *i64 = sys_mmap(FG_NG*FG_W64) as *i64
89 let count: *i64 = sys_mmap((gs_nb()+2)*FG_W64) as *i64
90 let explut: *i64 = sys_mmap(gs_expn()*FG_W64) as *i64
91 let gradbuf: *i64 = sys_mmap(FG_NG*3*FG_W64) as *i64
92 let wnorm: *i64 = sys_mmap(FG_NG*FG_W64) as *i64
93 gs_build_explut(explut)
94
95 let ng: i64 = fg_truth(truth)
96 // the TARGET image: the ground-truth scene, rendered with the same background the step assumes.
97 let visT: i64 = gs_render(truth, ng, 0, FG_CAMZ, target, acc, trans, depth, sxb, syb, sigb, order, count, explut, FG_BGR, FG_BGG, FG_BGB)
98 var litT: i64 = 0
99 var q: i64 = 0
100 while q < npx { if target[q] != 0 { litT = litT + 1 } q = q + 1 }
101
102 // perturb every position off truth by a known offset.
103 fg_copy(work, truth, FG_NG*8)
104 var i: i64 = 0
105 while i < FG_NG {
106 work[i*8] = work[i*8] + FG_PERTURB
107 work[i*8+1] = work[i*8+1] - FG_PERTURB
108 i = i + 1
109 }
110 let err0: i64 = fg_poserr(work, truth)
111 // the perturbation in PIXELS is what the gradient can see: world-units-per-pixel at this depth is
112 // cz/GFOCAL, so the offset must sit INSIDE the splat's 3-sigma support or no tooth here is meaningful.
113 let wpp: i64 = (FG_CAMZ * gs_fx()) / gs_focal_for(gs_h())
114 gv_puts(" fixture: gaussians=" as *u8); gv_num(visT); gv_puts(" of " as *u8); gv_num(ng)
115 gv_puts(" target_lit=" as *u8); gv_num(litT)
116 gv_puts(" world_units_per_pixel=" as *u8); gv_num(wpp)
117 gv_puts(" perturbation=" as *u8); gv_num(FG_PERTURB)
118 gv_puts(" (" as *u8); gv_num(FG_PERTURB/wpp); gv_puts(" px)\n" as *u8)
119 var t1: i64 = 0
120 if visT == ng { if litT > 0 { if err0 > 0 { t1 = 1 } } }
121 gv_check("T1 fixture-reached-the-condition: every gaussian visible, target has pixels, positions start OFF truth" as *u8, t1, ctr)
122
123 // ---- the run: strict monotone recovery is the ACCEPT RULE declared in the header ---------------
124 // ⚠⚠ACCEPT RULE CORRECTED AFTER ITS FIRST RUN, AND THE CORRECTION IS A TIGHTENING.
125 // v1 demanded the position error decrease STRICTLY AT EVERY STEP. The organ reached loss=0 at step 6
126 // -- an EXACT reconstruction -- after which the residual is zero, the gradient is exactly zero, and
127 // the scene correctly STOPS. v1 therefore demanded the impossible, and worse: it would have REWARDED
128 // an implementation that keeps jittering after convergence and PUNISHED the one that holds still.
129 // The rule now splits the run at the only boundary that exists in the mathematics:
130 // WHILE loss > 0 -- a residual remains, so descent must strictly reduce the error.
131 // ONCE loss == 0 -- converged, so the error must be EXACTLY CONSTANT. Stillness at the optimum is
132 // a second assertion, not a weaker one: a jitterer fails it.
133 // Both phases must actually occur, or the tooth is vacuous and says so.
134 var prev_err: i64 = err0
135 var mono: i64 = 1
136 var held: i64 = 1
137 var n_desc: i64 = 0
138 var n_conv: i64 = 0
139 var loss0: i64 = 0
140 var lossN: i64 = 0
141 var s: i64 = 0
142 while s < FG_STEPS {
143 let l: i64 = gs_pos_grad_step(work, ng, target, 0, FG_CAMZ, fb, acc, trans, depth, sxb, syb, sigb, order, count, explut, gradbuf, wnorm)
144 if s == 0 { loss0 = l }
145 lossN = l
146 let e: i64 = fg_poserr(work, truth)
147 if l > 0 { n_desc = n_desc + 1; if e >= prev_err { mono = 0 } }
148 if l == 0 { n_conv = n_conv + 1; if e != prev_err { held = 0 } }
149 gv_puts(" step " as *u8); gv_num(s); gv_puts(": loss=" as *u8); gv_num(l)
150 gv_puts(" pos_err=" as *u8); gv_num(e); gv_puts("\n" as *u8)
151 prev_err = e
152 s = s + 1
153 }
154 let errN: i64 = prev_err
155 gv_puts(" recovery: pos_err " as *u8); gv_num(err0); gv_puts(" -> " as *u8); gv_num(errN)
156 gv_puts(" | loss " as *u8); gv_num(loss0); gv_puts(" -> " as *u8); gv_num(lossN)
157 gv_puts(" | descent_steps=" as *u8); gv_num(n_desc)
158 gv_puts(" converged_steps=" as *u8); gv_num(n_conv); gv_puts("\n" as *u8)
159 var t2a: i64 = 0
160 if n_desc > 0 { if n_conv > 0 { t2a = 1 } }
161 gv_check("T2a both phases were exercised: the run actually descended AND actually converged (neither phase is vacuous)" as *u8, t2a, ctr)
162 gv_check("T2 ANTI-VACUITY descent: while a residual remained, position error STRICTLY decreased every step (a zero gradient holds it constant)" as *u8, mono, ctr)
163 gv_check("T2b stillness at the optimum: once loss reached 0 the error was EXACTLY constant (a jitterer moves here)" as *u8, held, ctr)
164 gv_check("T3 the scene moved TOWARD truth: final position error is below the perturbed start" as *u8, errN < err0, ctr)
165 gv_check("T4 the IMAGE improved: L1 loss fell over the run (reported, and it must agree with the geometry)" as *u8, lossN < loss0, ctr)
166 // DERIVED FLOOR, not a chosen tolerance: an image cannot localise a gaussian finer than one pixel,
167 // so world-units-per-pixel IS the information floor of image-based fitting. Landing under it is the
168 // strongest statement available; demanding zero would demand more than the data contains.
169 gv_check("T4b converged to SUB-PIXEL: the residual position error is below the world-units-per-pixel floor the image can resolve" as *u8, errN < wpp, ctr)
170
171 // ---- T5 the optimum is a CONTROL: at truth, a correct gradient must leave the scene alone -------
172 fg_copy(ctrl, truth, FG_NG*8)
173 var cs: i64 = 0
174 while cs < FG_STEPS {
175 gs_pos_grad_step(ctrl, ng, target, 0, FG_CAMZ, fb, acc, trans, depth, sxb, syb, sigb, order, count, explut, gradbuf, wnorm)
176 cs = cs + 1
177 }
178 let errC: i64 = fg_poserr(ctrl, truth)
179 // DERIVED bound: a converged scene may still dither by the sub-pixel quantum, which in world units
180 // is exactly world-units-per-pixel. Anything beyond that is motion, not rounding.
181 gv_puts(" at-truth control: pos_err after " as *u8); gv_num(FG_STEPS)
182 gv_puts(" steps=" as *u8); gv_num(errC); gv_puts(" derived_bound=" as *u8); gv_num(wpp); gv_puts("\n" as *u8)
183 gv_bite("neg-control-at-truth-scene-does-not-wander" as *u8, errN < err0, errC > wpp, ctr)
184
185 return gv_verdict("NX-GSPLAT-FIT" as *u8, ctr, "position is optimised from the image: monotone recovery from a perturbation, and stillness at the optimum" as *u8)
186}