gsplat 1.0.0

data/docs/MIGRATION.md

@@ -0,0 +1,117 @@
+# Migrating from Python gsplat
+
+The Ruby API keeps upstream operation names and tensor layouts where Numo::NArray can represent them
+directly. The main changes are Ruby keyword syntax, an explicit lightweight autograd wrapper, and a
+CPU-only dense execution model.
+
+## Rendering call
+
+Python:
+
+```python
+rendered, alphas, meta = rasterization(
+    means, quats, scales, opacities, colors, viewmats, Ks, width, height,
+    render_mode="RGB", packed=False,
+)
+```
+
+Ruby:
+
+```ruby
+rendered, alphas, meta = Gsplat.rasterization(
+  means: means,
+  quats: quats,
+  scales: scales,
+  opacities: opacities,
+  colors: colors,
+  viewmats: viewmats,
+  ks: intrinsics,
+  width: width,
+  height: height,
+  render_mode: "RGB",
+  packed: false
+)
+```
+
+`Ks` becomes the idiomatic keyword `ks`. Hash keys in metadata are symbols, for example
+`meta[:means2d]`, `meta[:radii]`, and `meta[:isect_offsets]`.
+
+## Tensor and autograd mapping
+
+| PyTorch | Ruby |
+|---|---|
+| `torch.float32` / `torch.float64` | `Numo::SFloat` / `Numo::DFloat` |
+| `tensor.requires_grad_(True)` | `Autograd::Variable.new(array, requires_grad: true)` |
+| `tensor.detach()` | `variable.data` |
+| `tensor.grad` | `variable.grad` |
+| `optimizer.zero_grad()` | `optimizer.zero_grad!` or `variable.zero_grad!` |
+| `with torch.no_grad()` | `Gsplat::Autograd.no_grad { ... }` |
+| `loss.backward()` | `loss.backward` |
+| `output.backward(weight)` | `output.backward(weight)` |
+
+Numo arrays do not carry device or graph state. Only `Autograd::Variable` does. Mixed calls return
+Variables when any differentiable input requires gradients, otherwise they return raw Numo arrays.
+
+The package supports camera batches `[C,...]`, not arbitrary leading batch dimensions. It uses dense
+`[C,N,...]` intermediates. `packed: true` is accepted for call compatibility but warns and executes
+dense mode; sparse gradients are unavailable.
+
+## Geometry and activation
+
+- Quaternion order is `wxyz`.
+- Rendering takes activated `scales > 0` and `opacities` in the 0–1 range.
+- Trainer parameter hashes store `:scales` as log-scales and `:opacities` as logits, matching the
+  optimization convention in the upstream examples.
+- Direct `covars [N,3,3]` or packed symmetric `covars [N,6]` replace `quats`/`scales` on the normal
+  2D raster path.
+- Views are world-to-camera `[C,4,4]`; camera forward is positive Z.
+
+## Render modes and metadata
+
+The following modes are available: `RGB`, `D`, `ED`, `RGB+D`, `RGB+ED`, `d`, `Ed`, `RGB-d`, and
+`RGB-Ed`. Uppercase depth uses projected Gaussian depth; lowercase depth is per-ray hit distance.
+
+`absgrad: true` updates `meta[:means2d_absgrad]` after backward. World-space normals requested through
+`with_eval3d: true, return_normals: true` are returned as `meta[:normals]`.
+
+## Optimizers and strategies
+
+An upstream parameter dictionary maps naturally to a Ruby symbol-keyed Hash:
+
+```ruby
+params = {
+  means: means_variable,
+  quats: quats_variable,
+  scales: log_scales_variable,
+  opacities: logits_variable,
+  sh0: direct_sh_variable,
+  shN: remaining_sh_variable
+}
+```
+
+`Gsplat::Strategy::Default` and `Gsplat::Strategy::MCMC` use the same lifecycle around backward. All
+structural edits must go through `Gsplat::Strategy::Ops` so parameter rows and Adam moments remain
+aligned. `Gsplat::Optim::SelectiveAdam` accepts a first-axis visibility mask for visible-only updates.
+
+## IO mapping
+
+| Python workflow | Ruby API |
+|---|---|
+| COLMAP parser | `Gsplat::IO::Colmap.read` |
+| Inria PLY export/import | `Gsplat::IO::Ply.write` / `.read` |
+| training checkpoint | `Gsplat::IO::Checkpoint.save` / `.restore!` |
+| NumPy fixture exchange | `Gsplat::IO::Npy.read`, `.write`, `.read_npz`, `.write_npz` |
+| PNG parameter compression | `Gsplat::Compression::Png#compress` / `#decompress` |
+
+NPY/NPZ supports the dtypes used by this project and C-order arrays. It intentionally does not load
+arbitrary NumPy object arrays or Fortran-order payloads.
+
+## Unsupported upstream options
+
+There is no CUDA device backend, distributed rendering, arbitrary leading batch support, packed/sparse
+execution, F-theta/lidar cameras, rolling shutter, custom rays, unscented-transform projection,
+renderer configs, extra signals, or LPIPS in version 1.0.
+
+The current 2DGS auxiliary buffers are compatible in shape but approximate upstream ray-splat
+geometry. Eval3d is pinhole/classic only and uses a numerical geometry VJP. Check
+`docs/DECISIONS.md` when exact cross-implementation parity is required.

data/docs/PROFILE.md

@@ -0,0 +1,75 @@
+# Performance Profile
+
+## Ruby baseline — 2026-07-23
+
+Command:
+
+```bash
+bundle exec ruby -Ilib benchmarks/profile_ruby.rb
+```
+
+Environment: CRuby 4.0.0, arm64-darwin24. Deterministic scene: 1,000 Gaussians, one 64×48
+camera, SH degree 3, five measured iterations after one warm-up.
+
+| Operation | Mean time |
+|---|---:|
+| Projection | 1.010 ms |
+| Spherical harmonics | 0.393 ms |
+| Tile intersections and sort | 2.505 ms |
+| Rasterization forward | 58.350 ms |
+
+Rasterization accounts for about 93.7% of the summed operation time. Tile intersection generation
+is the second-largest component. This satisfies the P10 profiling prerequisite and fixes the native
+implementation order: bridge first, projection/SH for coverage, intersection sort, then the
+dominant raster forward/backward path. These numbers are a small-scene attribution profile, not
+the final P12 throughput benchmark.
+
+## Native projection and SH — 2026-07-23
+
+With the P10-2 extension loaded (`GSPLAT_BACKEND=auto`) on the same workload:
+
+| Operation | Ruby | Native/auto | Speedup |
+|---|---:|---:|---:|
+| Projection | 1.010 ms | 0.257 ms | 3.9× |
+| Spherical harmonics | 0.393 ms | 0.043 ms | 9.1× |
+
+The C paths cover contiguous float32 forward calls. Float64, masked SH, and analytic backward use
+the Ruby implementation to preserve the existing numerical behavior.
+
+## Native intersections — 2026-07-23
+
+The P10-3 kernel adds float32 tile-bound enumeration, 64-bit key generation, stable LSD radix sort,
+and tile-offset encoding. It retains the same key layout and ordering as the Ruby implementation.
+
+| Operation | Ruby | Native/auto | Speedup |
+|---|---:|---:|---:|
+| Tile intersections and sort | 2.505 ms | 0.045 ms | 55.7× |
+
+The measurement uses the same 1,000-Gaussian workload as the baseline. Float64 inputs retain the
+Ruby path so numerical gradient tests continue to exercise the reference implementation.
+
+## Native rasterization — 2026-07-23
+
+The float32 forward and backward tile kernels release the GVL. Forward owns disjoint pixel tiles.
+Backward uses atomic scatter-add under OpenMP; this keeps memory at `O(N × D)` rather than allocating
+one full gradient buffer per worker. On the 1,000-Gaussian, 64×48 profile:
+
+| Operation | Ruby | Native (1 thread) | Speedup |
+|---|---:|---:|---:|
+| Raster forward | 55.821 ms | 2.284 ms | 24.4× |
+| Raster backward + absgrad | 136.854 ms | 2.700 ms | 50.7× |
+
+The required 100,000-Gaussian, 800×800 float32 workload gives:
+
+| OpenMP threads | Forward | Backward + absgrad | Combined |
+|---:|---:|---:|---:|
+| 1 | 114.012 ms | 279.790 ms | 393.802 ms |
+| 2 | 57.751 ms | 148.111 ms | 205.862 ms |
+| 4 | 30.446 ms | 83.138 ms | 113.584 ms |
+| 8 | 29.643 ms | 79.252 ms | 108.895 ms |
+
+This meets the 150 ms forward and 400 ms combined design targets even at one thread. The measured
+3.5× backward scaling from one to eight workers supports the bounded-memory atomic strategy. Scaling
+flattens after four workers on this Apple Silicon host, so higher thread counts are not assumed to
+improve throughput. Homebrew `libomp` is auto-detected on Apple Clang; other builds remain functional
+without OpenMP.

data/docs/PROGRESS.md

@@ -0,0 +1,199 @@
+# Implementation Progress
+
+This file is the restart point for implementation sessions. Read it after `README.md`.
+
+| Task | Status | Completed | Notes |
+|---|---|---|---|
+| P0-1 | Complete | 2026-07-23 | Gem foundation; 4 tests, 7 assertions |
+| P0-2 | Complete | 2026-07-23 | Backend registry, selection, environment override, one-time fallback warning |
+| P0-3 | Complete | 2026-07-23 | NPY v1.0 and stored/deflated NPZ; NumPy 2.3.1 interoperability verified |
+| P0-4 | Complete (alternate DoD) | 2026-07-23 | 47-case generator and dependency-free dry run; CUDA goldens pending CUDA host |
+| P0-5 | Complete | 2026-07-23 | allclose/golden/backend test helpers and Ruby 3.2–4.0 CI matrix |
+| P1-1 | Complete | 2026-07-23 | Autograd Variable/Function/Context, branching, multi-output, no_grad, graph release |
+| P1-2 | Complete | 2026-07-23 | Batched quaternion VJPs and closed-form 2x2/3x3 matrix operations |
+| P1-3 | Complete (golden pending) | 2026-07-23 | Covariance/precision fwd+bwd, triu output, float64 gradcheck |
+| P2-1 | Complete (golden pending) | 2026-07-23 | SH degrees 0–4, masks, arbitrary channels, analytic direction/coefficient VJPs |
+| P3-1 | Complete (golden pending) | 2026-07-23 | Pinhole forward, world/camera primitives, culling and compensation |
+| P3-2 | Complete (golden pending) | 2026-07-23 | Analytic projection VJPs for means, covariance, quaternion and scale |
+| P3-3 | Complete (golden pending) | 2026-07-23 | Orthographic forward/backward and camera-model dispatch |
+| P4-1 | Complete (golden pending) | 2026-07-23 | Tile AABBs, 64-bit intersection keys, sorting and prefix offsets |
+| P5-1 | Complete | 2026-07-23 | Brute-force alpha compositor with arbitrary channels and backgrounds |
+| P5-2 | Complete (golden pending) | 2026-07-23 | Vectorized tile compositor, masks, partial edge tiles and retained last ids |
+| P6-1 | Complete (golden pending) | 2026-07-23 | Reverse tile scan VJPs and brute-force gradient cross-check |
+| P6-2 | Complete (golden pending) | 2026-07-23 | Optional per-pixel absolute mean-gradient accumulation |
+| P7-1 | Complete (golden pending) | 2026-07-23 | High-level render modes, SH, antialiasing, depth normalization and metadata |
+| P7-2 | Complete | 2026-07-23 | Self-consistency image fitter, 128px fixture and monotonic PSNR E2E |
+| P8-1 | Complete | 2026-07-23 | Adam groups, bias correction, editable state and exponential scheduling |
+| P8-2 | Complete | 2026-07-23 | Strategy lifecycle and synchronized duplicate/split/remove/reset operations |
+| P8-3 | Complete (golden pending) | 2026-07-23 | Default densification statistics, growth, pruning and opacity reset |
+| P8-4 | Complete (golden pending) | 2026-07-23 | Closed-form relocation, weighted sampling, covariance noise and MCMC strategy |
+| P9-1 | Complete | 2026-07-23 | Inria PLY writer and arbitrary-order ASCII/binary little-endian reader |
+| P9-2 | Complete | 2026-07-23 | COLMAP bin/txt cameras, images and 100-point fixture with pose conversion |
+| P9-3 | Complete (golden pending) | 2026-07-23 | k-NN initialization, SH color helpers, scene scale and differentiable SSIM |
+| P9-4 | Complete | 2026-07-23 | NPZ training checkpoints and vips/chunky_png RGB image IO |
+| P9-5 | Complete | 2026-07-23 | Multi-view Trainer, staged SH, strategy hooks and training/render CLIs |
+| P10-1 | Complete | 2026-07-23 | Optional C extension, Numo bridge, GVL release and build fallback |
+| P10-2 | Complete (hybrid) | 2026-07-23 | C float32 projection/SH forward; analytic backward and float64 fallback |
+| P10-3 | Complete | 2026-07-23 | C tile enumeration, stable 64-bit radix sort and offset encoding |
+| P10-4 | Complete | 2026-07-23 | GVL-free OpenMP raster forward/backward with atomic scatter-add |
+| P11-1 | Complete (golden pending) | 2026-07-23 | N-D features, differentiable channel chunking and radius clipping |
+| P11-2 | Complete (golden pending) | 2026-07-23 | Full and packed direct covariance forward/backward across the renderer |
+| P11-3 | Complete (golden pending) | 2026-07-23 | Axis-aligned elliptical radii in Ruby/native projection and metadata |
+| P11-4 | Complete | 2026-07-23 | Morton grid sort, PNG quantization, SH K-means and compatible metadata layout |
+| P11-5 | Complete (golden pending) | 2026-07-23 | Fisheye and OpenCV radial/tangential/thin-prism projection with VJPs |
+| P11-6 | Complete (golden pending) | 2026-07-24 | Euclidean center sorting and per-pixel anisotropic ray-hit distance modes |
+| P11-7 | Complete | 2026-07-24 | First-axis visibility-masked Adam parameter and moment updates |
+| P11-8 | Complete (golden pending) | 2026-07-24 | 2DGS API, auxiliary geometry buffers and Trainer mode |
+| P11-9 | Complete (golden pending) | 2026-07-24 | World-space color evaluation, ray-facing accumulated normals and numerical VJPs |
+| P11-10 | Complete (golden pending) | 2026-07-24 | Iterative per-pixel Gaussian contribution-index enumeration |
+| P12-1 | Complete | 2026-07-24 | README/Migration guide, executable quick start, example smoke tests and 100% public YARD coverage |
+| P12-2 | Complete (external gates recorded) | 2026-07-24 | Design workloads, benchmark results, enabled CI matrix and G1–G6 acceptance report |
+| P12-3 | Complete | 2026-07-24 | Version 1.0.0, Apache-2.0, release metadata, gem build and clean native install/render verified |
+
+## Phase gates
+
+### P0 — Complete (alternate golden-data gate)
+
+- Full suite: 25 tests, 91 assertions, no failures or skips.
+- RuboCop: no offenses.
+- Golden status: generator dry-run and syntax checks pass; complete CUDA output remains pending per
+  `tools/README.md` because this host has no CUDA and the temporary PyTorch install exceeded disk capacity.
+- Design differences: recorded in `docs/DECISIONS.md`.
+
+### P1 — Complete (golden-data gate pending)
+
+- L1/L2: analytic properties and float64 central differences pass.
+- L3: `quat_covar_full.npz` test is present and skipped until `tools/README.md` CUDA generation is run.
+- Full suite and lint evidence are recorded in the P1-3 commit.
+
+### P2 — Complete (golden-data gate pending)
+
+- L1/L2: known degree-zero/degree-one values and float64 direction/coefficient central differences pass.
+- Masks suppress forward values and their corresponding VJPs; channels are not restricted to RGB.
+- L3: `sh_deg3.npz` test is present and skipped until `tools/README.md` golden generation is run.
+- Full suite: 52 tests, 130 assertions, no failures, 2 documented golden-data skips.
+- RuboCop: no offenses.
+
+### P3 — Complete (golden-data gate pending)
+
+- L1/L2: hand-calculated pinhole/orthographic cases and float64 central differences pass.
+- Covariance-direct and quaternion/scale paths both propagate analytic gradients.
+- L3: pinhole and orthographic tests are present and skip until golden generation is run.
+- Projection radii use the upstream `[C,N,2]` axis-aligned elliptical representation.
+- Full suite: 63 tests, 155 assertions, no failures, 5 documented golden-data skips.
+- RuboCop: no offenses.
+
+### P4 — Complete (golden-data gate pending)
+
+- L1: exact handcrafted tile counts, 64-bit keys, flattened ids and empty-tile offsets pass.
+- Elliptical radii are primary; legacy scalar radii remain accepted by the low-level intersection API.
+- L3: `isect_c3_n1000.npz` coverage is present and skips until golden generation is run.
+- Full suite: 68 tests, 163 assertions, no failures, 6 documented golden-data skips.
+- RuboCop: no offenses.
+
+### P5 — Complete (golden-data gate pending)
+
+- L1/L4: single-pixel analytical cases and tile-vs-brute-force image comparisons pass.
+- Partial edge tiles, arbitrary channels, backgrounds and tile masks are covered.
+- L3: `raster_rgb.npz` forward coverage is present and skips until CUDA golden generation is run.
+- Full suite: 75 tests, 175 assertions, no failures, 7 documented golden-data skips.
+- RuboCop: no offenses.
+
+### P6 — Complete (golden-data gate pending)
+
+- L2: float64 central differences pass for means, conics, colors, opacities and backgrounds.
+- L4: tile and brute-force backward gradients match exactly on the reference scene.
+- `absgrad` accumulates absolute per-pixel mean contributions and allocates no buffer when disabled.
+- L3: raster gradients and absolute gradients skip until CUDA golden generation is run.
+- Full suite: 81 tests, 190 assertions, no failures, 9 documented golden-data skips.
+- RuboCop: no offenses.
+
+### P7 — Complete (golden-data gate pending)
+
+- High-level RGB/depth modes, SH, antialiasing, metadata and end-to-end gradients pass.
+- The reduced image-fit E2E improves monotonically from 11.77 dB to 28.89 dB in 12 steps.
+- A 128×128 PPM fixture and a configurable 2,000-Gaussian/300-step example are included.
+- L3 render fixtures remain pending CUDA golden generation.
+- Full suite: 88 tests, 248 assertions, no failures, 9 documented golden-data skips.
+- RuboCop: no offenses.
+
+### P8 — Complete (golden-data gate pending)
+
+- Adam bias correction, exponential scheduling and synchronized structural state edits pass.
+- Default strategy growth/pruning and MCMC relocation/growth/noise paths are covered.
+- MCMC equation 9 is verified analytically; noise mean/variance and a reduced image fit pass.
+- L3 strategy and relocation fixtures remain pending CUDA golden generation.
+- Full suite: 109 tests, 323 assertions, no failures, 11 documented golden-data skips.
+- RuboCop: no offenses.
+
+### P9 — Complete (golden-data gate pending)
+
+- Inria PLY and COLMAP bin/txt parsing pass round-trip and paired-fixture tests.
+- k-NN initialization, scene scale, L1/SSIM/PSNR, checkpoint restart, and optional image backends pass.
+- The eight-view synthetic Trainer E2E exceeds 28 dB in 80 steps; the production default remains 30,000 steps.
+- `simple_trainer.rb` and `render_path.rb` provide the documented real-COLMAP workflow and bundled sample data.
+- L3 SSIM remains pending golden generation; the source bundle uses chunky_png to exercise image IO.
+- Full suite: 131 tests, 817 assertions, no failures, 14 documented skips.
+- RuboCop: no offenses.
+
+### P10-3 — Complete
+
+- Native float32 intersections exactly match the Ruby keys, flattened ids, counts and offsets.
+- The stable eight-pass radix sort preserves key/id pairing and runs without the Ruby GVL.
+- The 1,000-Gaussian profile improves from 2.505 ms to 0.045 ms (55.7×).
+- Full suite: 136 tests, 836 assertions, no failures, 14 documented skips.
+- RuboCop: no offenses.
+
+### P10 — Complete
+
+- Contiguous float32 projection, SH, intersections, raster forward and raster backward use C kernels.
+- Raster forward owns disjoint tiles; backward uses bounded-memory atomic scatter-add and supports
+  arbitrary channels, backgrounds, masks and absolute mean gradients.
+- At 100k Gaussians and 800×800, 8-thread forward is 29.643 ms and combined forward/backward is
+  108.895 ms, within the 150/400 ms design targets.
+- The explicit `:native` suite passes with one and eight OpenMP threads.
+- Full suite: 137 tests, 845 assertions, no failures, 14 documented skips.
+- RuboCop: no offenses.
+
+### P11 — Complete (golden-data gate pending)
+
+- Extended rendering covers feature chunking, direct covariance, elliptical radii, distorted/fisheye
+  cameras, distance modes, eval3d normals, 2DGS, SelectiveAdam, and contribution enumeration.
+- Each extension has analytic/property coverage and a pinned Python generator case where upstream
+  execution is required. CUDA fixtures remain the documented external gate.
+- Both backend selections pass the same 181-test, 977-assertion suite with 22 documented skips.
+- RuboCop: no offenses.
+
+### P12-1 — Complete
+
+- README includes installation, executable quick start, conventions, API mapping, feature status,
+  limitations, and the three production examples. `docs/MIGRATION.md` covers Python migration.
+- `test/readme_test.rb` executes the exact quick-start fence. Example smoke tests run a real image-fit
+  step, parse all COLMAP fixture records, and validate a PLY orbit setup without optional image gems.
+- `yard stats`: 40 files, 129 methods, 124 attributes, 22 constants, undocumented 0 (100%).
+- Ruby and native selections: 186 tests, 1,005 assertions, no failures, 22 documented skips.
+- RuboCop: 130 files, no offenses.
+
+### P12-2 — Complete (external validation pending)
+
+- The 100k/800×800 workload passes all timing targets: Ruby 3,527.990/8,047.024 ms and
+  native 30.419/112.573 ms for forward/combined forward+backward.
+- The full 50k/512²/2,000-step native image fit completes in 157.457 seconds versus the
+  30-minute target. The COLMAP benchmark path completes a one-step fixture smoke run.
+- `docs/BENCHMARKS.md` records commands and limitations; `docs/ACCEPTANCE.md` maps G1–G6 to evidence.
+  CUDA golden parity (G1/G2) and real-capture 30k quality (G4) remain explicit external gates.
+- CI now runs Ruby 3.2–4.0, native build/full suite, documentation, and focused E2E jobs.
+- Ruby and native selections: 188 tests, 1,041 assertions, no failures, 22 documented skips.
+- YARD: undocumented 0 (100%). RuboCop: 132 files, no offenses. Workflow YAML parses successfully.
+
+### P12-3 — Complete
+
+- Version 1.0.0, release metadata, a bounded runtime dependency, and the release file manifest are
+  covered by `test/gemspec_test.rb`.
+- `gem build gsplat.gemspec` produces `gsplat-1.0.0.gem`. Installing that artifact into an empty
+  temporary gem home compiles and loads the native extension, then completes a 1×1 render without
+  loading files from the working tree.
+- Ruby and native selections: 196 tests, 1,166 assertions, no failures, 22 documented skips.
+- YARD: undocumented 0 (100%). RuboCop: 134 files, no offenses.
+- Following explicit confirmation, the source license and gem metadata use Apache-2.0. No gem has
+  been published.

data/docs/decisions/0000-template.md

@@ -0,0 +1,17 @@
+# NNNN: Decision title
+
+- Status: Proposed
+- Date: YYYY-MM-DD
+
+## Context
+
+Describe the question, constraints, and forces that make the decision necessary.
+
+## Decision
+
+Describe the chosen approach and the important alternatives that were not selected.
+
+## Consequences
+
+Describe the positive and negative consequences, follow-up work, and conditions that could cause
+this decision to be revisited.

data/docs/decisions/0001-pin-golden-reference-and-cpu-validation.md

@@ -0,0 +1,27 @@
+# 0001: Pin the golden reference and define CPU-only validation
+
+- Status: Accepted
+- Date: 2026-07-23
+
+## Context
+
+Golden data must remain reproducible while the upstream `main` branch and its public tensor shapes
+continue to evolve. The development host also has no CUDA device, so it cannot execute the complete
+upstream rasterizer locally.
+
+## Decision
+
+- Pin Python reference data to the latest official release, `gsplat==1.5.3` (tag commit
+  `937e29912570c372bed6747a5c9bf85fed877bae`), instead of a moving `main` branch.
+- Use the upstream 1.5.3 elliptical radii shape `[C,N,2]` in projection and golden files. The
+  low-level intersection operation continues to accept legacy scalar radii.
+- Do not create golden `last_ids`, because upstream 1.5.3 does not expose that internal rasterizer
+  value. Raster goldens store public outputs, all public input gradients, and `means2d.absgrad`.
+- Use the dependency-free generator dry run as the local P0-4 gate. Keep CPU partial-generation and
+  the required CUDA command documented in `tools/README.md`.
+
+## Consequences
+
+Golden inputs and public output contracts are reproducible against an immutable upstream version.
+Local development can validate the generator and all CPU-owned behavior, while complete raster
+parity remains an explicit external CUDA acceptance gate.

data/docs/decisions/0002-retain-ruby-fallbacks-for-native-backend.md

@@ -0,0 +1,26 @@
+# 0002: Retain exact Ruby fallbacks for the native backend
+
+- Status: Accepted
+- Date: 2026-07-23
+
+## Context
+
+The native backend must accelerate production float32 training without creating a second,
+divergent implementation of every derivative and compatibility path. Raster backward must also
+remain within a practical memory bound at the 100k-Gaussian benchmark scale.
+
+## Decision
+
+- Target contiguous `Numo::SFloat` arrays in native kernels.
+- Keep float64 gradchecks, masked spherical harmonics, and analytic projection/SH backward on the
+  Ruby implementation. Selecting `:native` remains functionally complete through these fallbacks.
+- Label performance results for these paths as hybrid and measure accelerated operations
+  explicitly.
+- Use OpenMP atomic scatter-add in raster backward instead of per-worker full gradient buffers.
+
+## Consequences
+
+The native backend accelerates the high-volume path while preserving one authoritative copy of
+complex derivative formulas. Atomic scatter-add avoids `O(workers × N × channels)` temporary
+memory. Its measured 100k/800×800 raster backward improves from 279.790 ms with one worker to
+79.252 ms with eight workers, at the cost of atomic-update contention.

data/docs/decisions/0003-share-projection-for-distorted-cameras.md

@@ -0,0 +1,26 @@
+# 0003: Share the Ruby projection for distorted cameras
+
+- Status: Accepted
+- Date: 2026-07-23
+
+## Context
+
+Equidistant fisheye and OpenCV distortion add calibration-sensitive formulas and numerical
+derivatives. Independent Ruby and native implementations would increase the risk of camera-model
+drift without improving the established pinhole performance path.
+
+## Decision
+
+- Use one float32/float64 Ruby implementation of equidistant fisheye and OpenCV
+  radial/tangential/thin-prism projection for both backend selections.
+- Delegate these camera models to the Ruby path when `:native` is selected.
+- Follow gsplat 1.5.3's rational pinhole coefficient order: `k1..k3` form the numerator and
+  `k4..k6` form the denominator. Fisheye coefficients multiply `theta^3..theta^9`.
+- Treat distortion coefficients as calibration constants. Propagate gradients to Gaussian
+  geometry, but do not optimize coefficients or intrinsics in this phase.
+
+## Consequences
+
+Both backend selections have identical distorted-camera semantics and numerical derivatives. These
+models run at reference speed; the optimized pinhole path and its analytic/native backward remain
+unchanged.

data/docs/decisions/0004-use-portable-world-space-reference-paths.md

@@ -0,0 +1,26 @@
+# 0004: Use one portable reference for world-space extension paths
+
+- Status: Accepted
+- Date: 2026-07-24
+
+## Context
+
+Hit-distance rendering and local depth ordering require anisotropic Gaussian evaluation in world
+space. They extend the renderer beyond the performance-oriented 2D EWA core and introduce geometry
+derivatives that would be costly to duplicate across backends.
+
+## Decision
+
+- Evaluate hit-distance modes against the anisotropic Gaussian in world space and replace the final
+  feature channel with the per-pixel closest-approach distance, matching the upstream eval3d
+  definition.
+- Use the same Ruby implementation for both backend selections and a dtype-aware central-difference
+  geometry VJP. Keep the core 2D raster path analytic and native-accelerated.
+- Make `global_z_order: false` sort projected centers by camera-space Euclidean distance. Continue
+  near/far culling by camera z and propagate the Euclidean-norm VJP to means.
+
+## Consequences
+
+The extension remains differentiable and behaviorally identical under `:ruby` and `:native`
+without maintaining two world-space evaluators. It prioritizes semantic coverage over large-scene
+speed and leaves the established fast raster path untouched.

data/docs/decisions/0005-reuse-ewa-core-for-2dgs.md

@@ -0,0 +1,24 @@
+# 0005: Reuse the differentiable EWA core for 2DGS
+
+- Status: Accepted
+- Date: 2026-07-24
+
+## Context
+
+The Ruby API needs a portable 2DGS-compatible surface and Trainer mode, but an exact upstream
+ray-splat transform and median-crossing compositor cannot be validated on this CPU-only host.
+
+## Decision
+
+- Preserve the upstream seven-value return structure and metadata names.
+- Reuse the established differentiable EWA footprint and compositor for color and alpha.
+- Derive oriented camera normals, normalized surface normals, a depth-opacity distortion signal,
+  and expected depth as the median approximation.
+- Treat exact ray-splat transforms, median crossing, and distortion accumulation as part of the
+  pending CUDA golden gate rather than claiming numerical identity.
+
+## Consequences
+
+2DGS color/alpha rendering and Trainer optimization remain differentiable on both backends with a
+stable public shape. Auxiliary geometry buffers are approximate and must not be presented as an
+exact substitute for upstream 2DGS until the external parity gate can be completed.

data/docs/decisions/0006-keep-eval3d-as-portable-reference.md

@@ -0,0 +1,25 @@
+# 0006: Keep eval3d as a portable reference path
+
+- Status: Accepted
+- Date: 2026-07-24
+
+## Context
+
+`with_eval3d` generalizes the world-space evaluator from
+[ADR 0004](0004-use-portable-world-space-reference-paths.md) to arbitrary color features, and
+`return_normals` adds view-oriented Gaussian normals. These semantics are more important than
+duplicating them in the native raster kernels before CUDA parity is available.
+
+## Decision
+
+- Accumulate arbitrary features with the world-space evaluator.
+- For normals, use the quaternion's canonical +Z axis, flip it toward the ray, and accumulate it
+  with the same alpha weights as color.
+- Support pinhole cameras and classic rasterization.
+- Share the Ruby evaluator and numerical geometry VJP between backend selections.
+
+## Consequences
+
+The performance-oriented 2D raster kernels remain unchanged, while eval3d values and geometry stay
+differentiable and portable. The analytic single-ray case validates values and quaternion
+gradients locally; full CUDA color, alpha, and normal parity remains a generated-golden gate.

data/docs/decisions/0007-share-compositor-semantics-for-contribution-indices.md

@@ -0,0 +1,25 @@
+# 0007: Share compositor semantics for contribution indices
+
+- Status: Accepted
+- Date: 2026-07-24
+
+## Context
+
+`rasterize_to_indices_in_range` exposes iterative per-pixel contribution analysis. Its range
+coordinates, ordering, and termination rules must match the regular compositor or analysis results
+will disagree with rendered pixels.
+
+## Decision
+
+- Interpret range bounds as batches of `tile_size²` entries within each tile's sorted intersection
+  list, matching the upstream iterative rasterizer rather than indexing global intersections.
+- Preserve image-major, pixel-major, then depth order.
+- Apply the compositor's alpha skip, clamp, and exclusive transmittance stop.
+- Use the portable Ruby enumerator for both backend selections and do not record an autograd graph
+  for integer analysis outputs.
+
+## Consequences
+
+Contribution enumeration is deterministic and agrees with regular rasterization semantics. It runs
+at reference speed under either backend and intentionally produces non-differentiable integer
+indices.

data/examples/data/README.md

@@ -0,0 +1,14 @@
+# Example data
+
+This directory contains a deterministic 16-Gaussian scene for the runnable examples:
+
+- `colmap/` is a three-view COLMAP text dataset with 16×16 PNG images.
+- `splats.ply` is the corresponding Inria-layout Gaussian model.
+
+Regenerate both assets from the repository root:
+
+```bash
+bundle exec ruby examples/generate_sample_data.rb
+```
+
+The scene is generated entirely by Gsplat and contains no third-party data.

data/examples/data/colmap/sparse/0/cameras.txt

@@ -0,0 +1,2 @@
+# One PINHOLE camera shared by all sample views.
+1 PINHOLE 16 16 16 16 8 8

data/examples/data/colmap/sparse/0/images.txt

@@ -0,0 +1,6 @@
+# Each registered image is followed by an empty POINTS2D line.
+1 1 0 0 0 -0.120000 0 0 1 view_000.png
+
+2 1 0 0 0 0.000000 0 0 1 view_001.png
+
+3 1 0 0 0 0.120000 0 0 1 view_002.png

data/examples/data/colmap/sparse/0/points3D.txt

@@ -0,0 +1,17 @@
+# Synthetic colored seed points.
+1 -0.875 -0.875 2 0 51 255 0
+2 -0.375 -0.875 2 17 60 238 0
+3 0.125 -0.875 2 34 68 221 0
+4 0.625 -0.875 2 51 77 204 0
+5 -0.875 -0.375 2 68 85 187 0
+6 -0.375 -0.375 2 85 94 170 0
+7 0.125 -0.375 2 102 102 153 0
+8 0.625 -0.375 2 119 111 136 0
+9 -0.875 0.125 2 136 119 119 0
+10 -0.375 0.125 2 153 128 102 0
+11 0.125 0.125 2 170 136 85 0
+12 0.625 0.125 2 187 144 68 0
+13 -0.875 0.625 2 204 153 51 0
+14 -0.375 0.625 2 221 161 34 0
+15 0.125 0.625 2 238 170 17 0
+16 0.625 0.625 2 255 178 0 0