nx_gsplat_density_gate.nx source

1// nx_gsplat_density_gate.nx -- ADAPTIVE DENSITY: does adding primitives where the residual asks for 2// them actually reconstruct better, or is it tessellating noise? 3// 4// *** THE ACCEPT RULE, PRE-DECLARED BEFORE THE IMPLEMENTATION WAS WRITTEN *** 5// A before/after comparison is NOT good enough here and the reason is specific: densification changes 6// the primitive count, so "loss fell after densifying" is satisfied by simply fitting longer. The two 7// arms therefore get the SAME TOTAL FITTING BUDGET and differ only in whether density is adapted: 8// ARM A (control): 2*FD_STEPS gradient steps at the starting count, no densification 9// ARM B : FD_STEPS steps, ONE densify, FD_STEPS steps 10// ACCEPT iff lossB < lossA. Densification then has to earn its result against the fitter working 11// equally hard without it -- which is the only comparison that can distinguish adapting density from 12// spending more iterations. 13// 14// *** REACHABILITY IS ASSERTED FIRST, ARITHMETICALLY, BEFORE ANY ARM IS BELIEVED -- AND IT IS TWO 15// *** QUESTIONS, NOT ONE. THIS GATE'S FIRST RED PROVED THAT, AGAINST ITS OWN AUTHOR. 16// v1 built a fixture whose third feature lay BEYOND every primitive's support and asserted exactly 17// that as its reachability tooth. The tooth PASSED and the run came back RED with gmean=0 -- because 18// the gradient is accumulated ONLY over each primitive's own footprint, so a feature that no primitive 19// touches contributes NOTHING to any gradient. The densifier could not feel the residual it was being 20// asked to fix. THE FIXTURE PROVED THE WRONG REACHABILITY, AND THE TOOTH CERTIFIED IT. 21// T0a SIGNAL reachable -- the unresolved detail must lie INSIDE the covering primitive's support, 22// or no gradient carries it and no criterion can ever fire. 23// T0b IMPROVEMENT reachable -- that detail must be separated by more than the information floor of 24// one pixel, or more primitives cannot represent what one cannot. 25// Both are computed from the LIVE conic (gs_splat_rx on the rendered pa), never from a comment. 26// ⚠AND THE UNDERLYING LIMIT IS REAL AND SHARED WITH PUBLISHED 3DGS: densification GROWS primitives 27// where support already exists; it does not DISCOVER regions nothing covers. Those are the business of 28// initialisation (a point cloud), not of adaptive density. Naming it here so the next reader does not 29// re-file this fixture bug as a densifier bug. 30// 31// *** THE ANTI-VACUITY TOOTH, AND THE FAILURE IT IS BUILT FROM *** 32// The sibling gate's T14 v1 asserted only `mv_full > 0` -- a bound ANY number satisfies -- and so it 33// PASSED on a result 46 billion units out. The vacuous-tooth defect, committed inside the gate built to 34// prevent it. The bounds here are ones only a working implementation can meet: 35// T4 out > in -- a "densified" run that silently added nothing FAILS 36// T6 lossB < lossA -- at equal budget; a fit that ends no better than the control has bought 37// nothing, and one that ends WORSE has diverged 38// T7 both at once -- adding primitives without reducing residual IS tessellating noise, so 39// neither half alone is allowed to carry the verdict 40// T6's bound is the CONTROL's own measured loss, not a chosen epsilon -- there is no tunable number in 41// this gate's accept rule at all. 42// 43// *** A DECLARED LIMIT OF THE DERIVED RULE, FOUND WHILE BUILDING THIS FIXTURE *** 44// The densify bar is the population's own MEAN gradient. With a population of ONE, nothing can exceed 45// its own mean, so a single-primitive scene NEVER densifies. That is a real property of a 46// parameter-free bar, not a bug, and it is why this fixture starts at two primitives rather than one. 47// It is declared here and in the organ header rather than left for a reader to discover as a mystery. 48// license_tier: ORIGINAL expect_exit: 0 49import "nx_syscalls.nx" 50import "nx_itrig.nx" 51import "nx_gsplat.nx" 52import "nx_gsplat_density.nx" 53import "nx_gate_verdict.nx" 54 55const FD_NGMAX: i64 = 16 56const FD_START: i64 = 2 57const FD_TRUTH: i64 = 3 58const FD_STEPS: i64 = 10 59const FD_CAMZ: i64 = 30 60const FD_RTAN: i64 = 560 61// FD_PAIR: half the separation of the CLOSE pair -- the detail one primitive cannot resolve. It must 62// be small enough that the covering splat's support spans both (or its gradient never feels them) and 63// large enough to exceed the one-pixel information floor (or two primitives cannot beat one). T0a/T0b 64// recompute BOTH requirements from the live conic and fail if this value does not deliver them. 65const FD_PAIR: i64 = 400 66// FD_FAR: the third feature, placed well clear so it is cleanly covered by its own primitive and 67// contributes a near-zero gradient -- which is what makes the population mean DISCRIMINATE. 68const FD_FAR: i64 = 5000 69const FD_TILT: i64 = 181 70const FD_W64: i64 = 8 71const FD_BGR: i64 = 26 72const FD_BGG: i64 = 28 73const FD_BGB: i64 = 44 74const FD_OP: i64 = 200 75 76func fd_abs(v: i64) -> i64 { if v < 0 { return 0 - v } return v } 77 78func fd_truth(g: *i64) -> i64 { 79 // THE CLOSE PAIR: two DIFFERENTLY-COLOURED features that one splat cannot represent, because a 80 // single gaussian carries a single colour. The residual at n=1 is therefore irreducible BY 81 // CONSTRUCTION rather than by luck -- and it sits inside one support, so the gradient can feel it. 82 gs_set_aniso(g, 0, 0 - FD_PAIR, 0, 0, FD_TILT, 0, FD_TILT, FD_RTAN, 220, 90, 90, FD_OP) 83 gs_set_aniso(g, 1, FD_PAIR, 0, 0, FD_TILT, 0, FD_TILT, FD_RTAN, 90, 220, 90, FD_OP) 84 // the far feature, cleanly coverable by a single primitive 85 gs_set_aniso(g, 2, FD_FAR, 0, 0, FD_TILT, 0, FD_TILT, FD_RTAN, 90, 90, 220, FD_OP) 86 return FD_TRUTH 87} 88 89// The start state puts ONE primitive on the MIDPOINT of the close pair -- its support spans both, so 90// their unresolved detail enters ITS gradient -- and one primitive exactly on the far feature, whose 91// gradient is therefore near zero. That asymmetry is what lets the population MEAN discriminate: with 92// two primitives of equal gradient nothing can exceed their mean, and nothing would ever densify. 93func fd_start(g: *i64) -> i64 { 94 gs_set_aniso(g, 0, 0, 0, 0, FD_TILT, 0, FD_TILT, FD_RTAN, 155, 155, 90, FD_OP) 95 gs_set_aniso(g, 1, FD_FAR, 0, 0, FD_TILT, 0, FD_TILT, FD_RTAN, 90, 90, 220, FD_OP) 96 return FD_START 97} 98 99func fd_copy(dst: *i64, src: *i64, n: i64) -> i64 { 100 var i: i64 = 0 101 while i < n { dst[i] = src[i]; i = i + 1 } 102 return 0 103} 104 105func main() -> i64 { 106 let ctr: *i64 = gv_ctr() 107 gv_head("nx_gsplat_density_gate -- adaptive density must beat the SAME fitting budget spent without it" as *u8) 108 109 let st: i64 = gs_stride_aniso() 110 let vw: i64 = gs_w() 111 let vh: i64 = gs_h() 112 let focal: i64 = gs_focal_for(vh) 113 let npx: i64 = vw * vh 114 115 let truth: *i64 = sys_mmap(FD_NGMAX*st*FD_W64) as *i64 116 let armA: *i64 = sys_mmap(FD_NGMAX*st*FD_W64) as *i64 117 let armB: *i64 = sys_mmap(FD_NGMAX*st*FD_W64) as *i64 118 let outbuf: *i64 = sys_mmap(FD_NGMAX*st*FD_W64) as *i64 119 let target: *i64 = sys_mmap(npx*FD_W64) as *i64 120 let fb: *i64 = sys_mmap(npx*FD_W64) as *i64 121 let acc: *i64 = sys_mmap(npx*6*FD_W64) as *i64 122 let trans: *i64 = sys_mmap(npx*FD_W64) as *i64 123 let depth: *i64 = sys_mmap(FD_NGMAX*FD_W64) as *i64 124 let sxb: *i64 = sys_mmap(FD_NGMAX*FD_W64) as *i64 125 let syb: *i64 = sys_mmap(FD_NGMAX*FD_W64) as *i64 126 let pa: *i64 = sys_mmap(FD_NGMAX*FD_W64) as *i64 127 let pb: *i64 = sys_mmap(FD_NGMAX*FD_W64) as *i64 128 let pc: *i64 = sys_mmap(FD_NGMAX*FD_W64) as *i64 129 let pdet: *i64 = sys_mmap(FD_NGMAX*FD_W64) as *i64 130 let order: *i64 = sys_mmap(FD_NGMAX*FD_W64) as *i64 131 let count: *i64 = sys_mmap((gs_nb()+2)*FD_W64) as *i64 132 let explut: *i64 = sys_mmap(gs_expn()*FD_W64) as *i64 133 let gradbuf: *i64 = sys_mmap(FD_NGMAX*3*FD_W64) as *i64 134 let wnorm: *i64 = sys_mmap(FD_NGMAX*FD_W64) as *i64 135 let m2: *i64 = sys_mmap(2*FD_W64) as *i64 136 let stats: *i64 = sys_mmap(gd_stat_count()*FD_W64) as *i64 137 gs_build_explut(explut) 138 139 // ---- the target: three features ------------------------------------------------------------- 140 let ngt: i64 = fd_truth(truth) 141 let visT: i64 = gs_render_aniso_at(truth, ngt, 0, FD_CAMZ, target, acc, trans, depth, sxb, syb, pa, pb, pc, pdet, order, count, explut, FD_BGR, FD_BGG, FD_BGB, vw, vh, focal) 142 var litT: i64 = 0 143 var q: i64 = 0 144 while q < npx { if target[q] != 0 { litT = litT + 1 } q = q + 1 } 145 146 // ---- T0: REACHABILITY, from the LIVE conic --------------------------------------------------- 147 // the third feature must lie beyond the support of a primitive sitting on its neighbour, or more 148 // primitives could not help and every later number would be about the fixture, not the method. 149 // the covering primitive carries the same rtan as the truth features, so the truth conic gives its 150 // support radius directly -- measured from the LIVE render, never restated from a constant. 151 let rx_cov: i64 = gs_splat_rx(pa[0]) 152 let pair_px: i64 = fd_abs(sxb[1] - sxb[0]) 153 gv_puts(" reachability: pair_sep_px=" as *u8); gv_num(pair_px) 154 gv_puts(" covering_support_px=" as *u8); gv_num(rx_cov) 155 gv_puts(" info_floor_px=1\n" as *u8) 156 gv_check("T0a SIGNAL REACHABLE: the unresolved pair lies INSIDE the covering primitive's support, so the residual actually ENTERS its gradient" as *u8, pair_px < rx_cov, ctr) 157 gv_check("T0b IMPROVEMENT REACHABLE: the pair is separated by MORE than one pixel, so two primitives can represent what one cannot" as *u8, pair_px > 1, ctr) 158 159 gv_puts(" fixture: truth_visible=" as *u8); gv_num(visT); gv_puts(" of " as *u8); gv_num(ngt) 160 gv_puts(" target_lit=" as *u8); gv_num(litT); gv_puts("\n" as *u8) 161 gv_check("T1 fixture-reached-the-condition: every truth primitive rendered and the target carries lit pixels" as *u8, visT == ngt, ctr) 162 gv_check("T1b target is non-empty (a loss against a blank target would be meaningless)" as *u8, litT > 0, ctr) 163 164 // ---- ARM A (control): the SAME total budget, no densification --------------------------------- 165 fd_copy(armA, truth, FD_NGMAX*st) 166 let ngA: i64 = fd_start(armA) 167 var s: i64 = 0 168 var lossA: i64 = 0 169 while s < 2*FD_STEPS { 170 lossA = gs_pos_grad_step_aniso(armA, ngA, target, 0, FD_CAMZ, fb, acc, trans, depth, sxb, syb, pa, pb, pc, pdet, order, count, explut, gradbuf, wnorm, vw, vh, 1) 171 s = s + 1 172 } 173 174 // ---- ARM B: half the budget, ONE densify, half the budget ------------------------------------ 175 fd_copy(armB, truth, FD_NGMAX*st) 176 var ngB: i64 = fd_start(armB) 177 let ngB_in: i64 = ngB 178 s = 0 179 var lossB: i64 = 0 180 while s < FD_STEPS { 181 lossB = gs_pos_grad_step_aniso(armB, ngB, target, 0, FD_CAMZ, fb, acc, trans, depth, sxb, syb, pa, pb, pc, pdet, order, count, explut, gradbuf, wnorm, vw, vh, 1) 182 s = s + 1 183 } 184 let ngB2: i64 = gs_densify(armB, ngB, FD_NGMAX, depth, pa, pc, gradbuf, outbuf, m2, stats) 185 if ngB2 > 0 { ngB = ngB2 } 186 s = 0 187 while s < FD_STEPS { 188 lossB = gs_pos_grad_step_aniso(armB, ngB, target, 0, FD_CAMZ, fb, acc, trans, depth, sxb, syb, pa, pb, pc, pdet, order, count, explut, gradbuf, wnorm, vw, vh, 1) 189 s = s + 1 190 } 191 192 let s_in: i64 = stats[0] 193 let s_kept: i64 = stats[1] 194 let s_split: i64 = stats[2] 195 let s_clone: i64 = stats[3] 196 let s_prune: i64 = stats[4] 197 let s_out: i64 = stats[5] 198 let s_gmean: i64 = stats[6] 199 let s_rmean: i64 = stats[7] 200 let s_vis: i64 = stats[8] 201 202 gv_puts(" densify: in=" as *u8); gv_num(s_in) 203 gv_puts(" kept=" as *u8); gv_num(s_kept) 204 gv_puts(" split=" as *u8); gv_num(s_split) 205 gv_puts(" cloned=" as *u8); gv_num(s_clone) 206 gv_puts(" pruned=" as *u8); gv_num(s_prune) 207 gv_puts(" -> out=" as *u8); gv_num(s_out); gv_puts("\n" as *u8) 208 gv_puts(" derived bars: gmean=" as *u8); gv_num(s_gmean) 209 gv_puts(" rmean=" as *u8); gv_num(s_rmean) 210 gv_puts(" visible=" as *u8); gv_num(s_vis); gv_puts("\n" as *u8) 211 212 gv_check("T2 the classification PARTITIONS the input: kept+split+cloned+pruned == in, and in > 0" as *u8, s_in > 0 && s_kept + s_split + s_clone + s_prune == s_in, ctr) 213 gv_check("T3 the emit ARITHMETIC holds: out == kept + 2*split + 2*cloned (a split and a clone each yield two)" as *u8, s_out == s_kept + 2*s_split + 2*s_clone, ctr) 214 gv_check("T4 ANTI-VACUITY: densification actually ADDED primitives -- a run that silently added nothing fails here" as *u8, s_out > s_in, ctr) 215 gv_check("T5 the derived bars came from a NON-EMPTY population (a mean over zero primitives must never be used)" as *u8, s_vis > 0 && s_gmean > 0 && s_rmean > 0, ctr) 216 217 // T5b exists because the MUTATION BITE exposed a blind spot in the stats themselves: with the 218 // criterion neutered, out==in and BOTH arms produced byte-identical losses -- indistinguishable 219 // from a scene that legitimately needed no densification. above_bar separates them, and this tooth 220 // asserts the criterion actually SELECTED something rather than the emit having done the work. 221 let s_above: i64 = stats[GD_S_ABOVEBAR] 222 gv_puts(" criterion: above_bar=" as *u8); gv_num(s_above) 223 gv_puts(" of visible=" as *u8); gv_num(s_vis); gv_puts("\n" as *u8) 224 gv_check("T5b the CRITERION fired: at least one primitive exceeded the derived gradient bar, and fewer than all did (a bar everything clears selects nothing)" as *u8, s_above > 0 && s_above < s_vis, ctr) 225 226 // T5b exists because the MUTATION BITE exposed a blind spot in the stats themselves: with the 227 // criterion neutered, out==in and BOTH arms produced byte-identical losses -- indistinguishable 228 // from a scene that legitimately needed no densification. above_bar separates them, and this tooth 229 // asserts the criterion actually SELECTED something rather than the emit having done the work. 230 let s_above: i64 = stats[10] 231 gv_puts(" criterion: above_bar=" as *u8); gv_num(s_above) 232 gv_puts(" of visible=" as *u8); gv_num(s_vis); gv_puts("\n" as *u8) 233 gv_check("T5b the CRITERION fired: at least one primitive exceeded the derived gradient bar, and fewer than all of them did (a bar everything clears selects nothing)" as *u8, s_above > 0 && s_above < s_vis, ctr) 234 235 gv_puts(" ARM A (control, " as *u8); gv_num(2*FD_STEPS); gv_puts(" steps, n=" as *u8); gv_num(ngA) 236 gv_puts("): loss=" as *u8); gv_num(lossA); gv_puts("\n" as *u8) 237 gv_puts(" ARM B (densified, " as *u8); gv_num(2*FD_STEPS); gv_puts(" steps, n=" as *u8); gv_num(ngB_in) 238 gv_puts("->" as *u8); gv_num(ngB); gv_puts("): loss=" as *u8); gv_num(lossB); gv_puts("\n" as *u8) 239 240 gv_check("T6 THE LOAD-BEARING TOOTH: at EQUAL fitting budget the densified arm reconstructs BETTER than the control" as *u8, lossB < lossA, ctr) 241 gv_check("T7 NOT TESSELLATING NOISE: primitives were added AND the residual fell -- neither half alone carries the verdict" as *u8, s_out > s_in && lossB < lossA, ctr) 242 243 // ---- T8/T9: the prune rule, bitten BOTH ways ------------------------------------------------- 244 // op*255 < GFXA is the format's own visibility quantum. A primitive below it is pruned; one above 245 // it must NOT be, or the rule would be deleting things that can still change a pixel. 246 let invis_op: i64 = 0 247 let vis_op: i64 = gs_fxa() / 255 + 1 248 gv_puts(" prune quantum: op*255 < " as *u8); gv_num(gs_fxa()) 249 gv_puts(" | invisible_op=" as *u8); gv_num(invis_op) 250 gv_puts(" visible_op=" as *u8); gv_num(vis_op); gv_puts("\n" as *u8) 251 gv_bite("T8 neg-control: a primitive below the format's visibility quantum is PRUNED, one above it is NOT" as *u8, gd_invisible(invis_op), gd_invisible(vis_op), ctr) 252 253 // ---- T10: capacity overflow REFUSES BY NAME rather than truncating ---------------------------- 254 fd_copy(armB, truth, FD_NGMAX*st) 255 let ngC: i64 = fd_start(armB) 256 let x0: i64 = armB[0] 257 lossB = gs_pos_grad_step_aniso(armB, ngC, target, 0, FD_CAMZ, fb, acc, trans, depth, sxb, syb, pa, pb, pc, pdet, order, count, explut, gradbuf, wnorm, vw, vh, 1) 258 let rc: i64 = gs_densify(armB, ngC, 1, depth, pa, pc, gradbuf, outbuf, m2, stats) 259 gv_puts(" overflow: ngmax=1 rc=" as *u8); gv_num(rc) 260 gv_puts(" refused=" as *u8); gv_num(stats[9]) 261 gv_puts(" gauss_x0_unchanged=" as *u8); if armB[0] == x0 { gv_num(1) } else { gv_num(0) } 262 gv_puts("\n" as *u8) 263 gv_check("T9 capacity overflow REFUSES BY NAME (rc=-1, refused flag set) instead of silently truncating the densification" as *u8, rc == 0 - 1 && stats[9] == 1, ctr) 264 gv_check("T10 a REFUSED densification leaves the primitive array UNTOUCHED" as *u8, armB[0] == x0, ctr) 265 266 return gv_verdict("NX-GSPLAT-DENSITY" as *u8, ctr, "adapting density beats the same fitting budget spent without it, and every bar is derived from the population or the format" as *u8) 267}