|
| 1 | +# 3DGS Error Certification Pillars Plan — ndarray |
| 2 | + |
| 3 | +## Goal |
| 4 | + |
| 5 | +Use `ndarray::hpc::pillar` as the executable certification layer for 3DGS rendering decisions. |
| 6 | + |
| 7 | +The purpose is to make approximation decisions inspectable: |
| 8 | + |
| 9 | +```text |
| 10 | +splat/tile approximation |
| 11 | + -> |
| 12 | +measured error components |
| 13 | + -> |
| 14 | +certificate |
| 15 | + -> |
| 16 | +render/refine/reject decision |
| 17 | +``` |
| 18 | + |
| 19 | +## Existing anchor |
| 20 | + |
| 21 | +The `src/hpc/pillar` module already separates: |
| 22 | + |
| 23 | +- cognitive-architecture pillars migrated from `lance-graph/crates/jc` |
| 24 | +- substrate-native pillars for ndarray |
| 25 | + |
| 26 | +The 3DGS rebuild should make this module useful at runtime and in CI without moving policy into the renderer. |
| 27 | + |
| 28 | +## Certificate model |
| 29 | + |
| 30 | +Add a lightweight certificate DTO under `src/hpc/pillar/cert.rs` or equivalent: |
| 31 | + |
| 32 | +```rust |
| 33 | +pub struct ErrorCertificate { |
| 34 | + pub geometric_error_px: f32, |
| 35 | + pub sampling_error: f32, |
| 36 | + pub covariance_error: f32, |
| 37 | + pub quantization_error: f32, |
| 38 | + pub dependence_inflation: f32, |
| 39 | + pub total_error_px: f32, |
| 40 | + pub confidence: f32, |
| 41 | + pub passed: bool, |
| 42 | +} |
| 43 | + |
| 44 | +pub enum CertificateFailure { |
| 45 | + NonPsdCovariance, |
| 46 | + ExcessiveProjectionRadius, |
| 47 | + WeakDependenceTooHigh, |
| 48 | + SamplingDiscrepancyTooHigh, |
| 49 | + QuantizationErrorTooHigh, |
| 50 | + NonFiniteValue, |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +## Pillar mapping |
| 55 | + |
| 56 | +### Pillar 6 / 7: EWA sandwich |
| 57 | + |
| 58 | +Use for 2D and 3D covariance push-forward validation. |
| 59 | + |
| 60 | +Runtime relevance: |
| 61 | + |
| 62 | +- detect non-PSD projected covariances |
| 63 | +- bound projected footprint instability |
| 64 | +- validate scale/quaternion to SPD covariance construction |
| 65 | + |
| 66 | +### Pillar 9: high-dimensional CLT / covariance field |
| 67 | + |
| 68 | +Use for aggregate covariance stability over blocks of splats. |
| 69 | + |
| 70 | +Runtime relevance: |
| 71 | + |
| 72 | +- block-level confidence for large splat groups |
| 73 | +- stability checks for compressed/quantized covariance fields |
| 74 | + |
| 75 | +### Pillar 10: nested distance |
| 76 | + |
| 77 | +Use for tile tree / DN-tree quantization preservation. |
| 78 | + |
| 79 | +Runtime relevance: |
| 80 | + |
| 81 | +- certify that coarse tile summaries preserve downstream selection quality |
| 82 | +- bound error across parent-child aggregation |
| 83 | + |
| 84 | +### Pillar 12: splat invariants |
| 85 | + |
| 86 | +Use as the primary production gate for anisotropic splat construction. |
| 87 | + |
| 88 | +Runtime relevance: |
| 89 | + |
| 90 | +- verify trace/determinant/Frobenius invariants |
| 91 | +- reject malformed scale/quaternion combinations |
| 92 | + |
| 93 | +### Pillar 13: HHTL contraction |
| 94 | + |
| 95 | +Use to certify cascade refinement. |
| 96 | + |
| 97 | +Runtime relevance: |
| 98 | + |
| 99 | +- parent-to-child error contraction |
| 100 | +- safe pruning and skip-LOD decisions |
| 101 | + |
| 102 | +## Runtime API sketch |
| 103 | + |
| 104 | +```rust |
| 105 | +pub fn certify_splat_block( |
| 106 | + block_stats: &SplatBlockStats, |
| 107 | + render_budget: &RenderBudget, |
| 108 | +) -> ErrorCertificate; |
| 109 | + |
| 110 | +pub fn certify_projected_covariance( |
| 111 | + sigma_3d: Spd3, |
| 112 | + camera_jacobian: Mat23, |
| 113 | +) -> CovarianceCertificate; |
| 114 | +``` |
| 115 | + |
| 116 | +## Determinism rules |
| 117 | + |
| 118 | +- Every stochastic probe must use `SplitMix64` or the existing deterministic harness. |
| 119 | +- Every report must include seed, sample count, tolerance, and measured values. |
| 120 | +- Runtime certificates must not depend on wall-clock timing. |
| 121 | +- CI probes must be reproducible across machines within documented tolerances. |
| 122 | + |
| 123 | +## Acceptance criteria |
| 124 | + |
| 125 | +- `cargo test -p ndarray --features std,linalg,pillar,splat3d` |
| 126 | +- Pillar reports are stable over two consecutive runs. |
| 127 | +- 3DGS projection tests can request a certificate and receive structured failure reasons. |
| 128 | +- Certificates can be serialized or converted to debug text for `lance-graph` ingestion. |
| 129 | +- CI separates proof failures from benchmark regressions. |
| 130 | + |
| 131 | +## Open design questions |
| 132 | + |
| 133 | +- Should runtime certificates use `f32` for speed or `f64` for audit output? |
| 134 | +- Should high-cost certification be offline-only, while runtime uses precomputed bounds? |
| 135 | +- Should tile-level certificates live in `lance-graph` and splat-block certificates live here? |
| 136 | + |
| 137 | +Recommended answer: keep primitive splat/block certificates here; aggregate tile certificates in `lance-graph`. |
0 commit comments