gsplat 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 380bbee36a191ee5993fdbe80cc1f17004fe6093e097147fb6cb293014bb8f12
+  data.tar.gz: 379b3699938c1bab39047397b1a7ee8840a14a6f4e56ea29fd5c61d304f64497
+SHA512:
+  metadata.gz: 6640f9ec52a5fd288ceb42bfb7c2a4a6a8f40090b50f109a2b586786fb6622a5789ebc51a34549c1239cec0cc27e46c29bc18da53e26c353f1b98fae6422a2fd
+  data.tar.gz: 2cd29f80081730b1692f06c64a4a86b384876b0a1a184a697df6879bf1da10c8e527474e7fcf12ff278f52e8e494ba191bb86660a8768c7e6dc01d11fd02836e

data/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,236 @@
+# Gsplat
+
+[![CI](https://github.com/ydah/gsplat/actions/workflows/main.yml/badge.svg)](https://github.com/ydah/gsplat/actions/workflows/main.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE.txt)
+
+Gsplat is a differentiable 3D Gaussian Splatting renderer and trainer for CRuby. It provides a
+portable `Numo::NArray` implementation, an optional C/OpenMP fast path, reverse-mode automatic
+differentiation, and training and IO utilities modeled after Python
+[`gsplat`](https://github.com/nerfstudio-project/gsplat).
+
+Gsplat currently runs on CPU. It is intended for Ruby-native graphics pipelines, reference
+implementations, inspection of the rendering equations, and small training jobs.
+
+## Features
+
+- Differentiable dense 3D Gaussian projection and tiled alpha compositing.
+- 3DGS and 2DGS APIs with RGB, arbitrary features, spherical harmonics, depth, and normals.
+- Pinhole, orthographic, equidistant fisheye, and OpenCV-distorted cameras.
+- Adam, SelectiveAdam, Default densification, MCMC strategy, and multi-view training.
+- COLMAP, Inria PLY, NPY/NPZ checkpoints, image IO, and PNG parameter compression.
+- Portable Ruby backend and native float32/OpenMP kernels with automatic fallback.
+
+## Installation
+
+Add Gsplat to your application's `Gemfile`:
+
+```ruby
+gem "gsplat"
+```
+
+Then install dependencies:
+
+```bash
+bundle install
+```
+
+Or install the gem directly:
+
+```bash
+gem install gsplat
+```
+
+### Requirements
+
+- CRuby 3.2 or newer.
+- A C compiler for `numo-narray` and the packaged native extension.
+- OpenMP is optional and enables parallel native raster kernels.
+- Image loading and writing require either `ruby-vips` (recommended) or `chunky_png`.
+
+The source checkout includes `chunky_png` for its runnable examples. JRuby and TruffleRuby are not
+release targets.
+
+### Backend selection
+
+The default `:auto` backend uses the native extension when it is available and otherwise falls back
+to Ruby with a one-time warning.
+
+```ruby
+Gsplat.backend = :auto
+Gsplat.backend = :ruby
+Gsplat.backend = :native
+```
+
+The same selection can be made with `GSPLAT_BACKEND=auto|ruby|native`. Use `Numo::SFloat` for native
+kernels. `Numo::DFloat` is supported for numerical checks and uses the Ruby formulas where needed.
+
+## Usage
+
+### Quick start
+
+The following complete example renders one Gaussian and differentiates the image with respect to
+its color.
+
+<!-- quickstart:start -->
+```ruby
+require "gsplat"
+
+f = Numo::SFloat
+colors = Gsplat::Autograd::Variable.new(f[[1.0, 0.2, 0.1]], requires_grad: true)
+
+rendered, alphas, meta = Gsplat.rasterization(
+  means: f[[0.0, 0.0, 2.0]],
+  quats: f[[1.0, 0.0, 0.0, 0.0]], # wxyz
+  scales: f[[0.25, 0.25, 0.25]],
+  opacities: f[0.8],               # activated opacity
+  colors: colors,
+  viewmats: f.eye(4).reshape(1, 4, 4),
+  ks: f[[[8.0, 0.0, 2.0], [0.0, 8.0, 2.0], [0.0, 0.0, 1.0]]],
+  width: 4,
+  height: 4
+)
+
+rendered.backward(f.ones(*rendered.data.shape))
+p [rendered.data.shape, alphas.data.shape, meta.fetch(:radii).shape, colors.grad.shape]
+```
+<!-- quickstart:end -->
+
+Output:
+
+```text
+[[1, 4, 4, 3], [1, 4, 4, 1], [1, 1, 2], [1, 3]]
+```
+
+### Data conventions
+
+- Quaternions use `wxyz` order and are normalized when converted to rotations.
+- `viewmats [C,4,4]` transform world coordinates into camera coordinates.
+- Cameras look along positive Z; pixels are sampled at `(x + 0.5, y + 0.5)`.
+- Rendering receives activated positive scales and 0–1 opacities.
+- Colors are `[N,D]` or `[C,N,D]`. Spherical harmonic coefficients are `[N,K,D]`.
+- Dense color outputs are `[C,H,W,D]`, alpha is `[C,H,W,1]`, and radii are `[C,N,2]`.
+- An `Autograd::Variable` records a graph. Non-scalar outputs require an explicit backward gradient.
+
+### Image fitting
+
+From a source checkout, run the deterministic image-fitting example:
+
+```bash
+bundle exec ruby examples/fit_image.rb --gaussians 2000 --steps 300
+```
+
+### Runnable sample data
+
+The repository includes a tiny synthetic COLMAP dataset and its matching Inria PLY, so the
+multi-view examples run without downloading external data or supplying arguments:
+
+```bash
+bundle exec ruby examples/simple_trainer.rb
+bundle exec ruby examples/render_path.rb
+```
+
+The trainer uses 10 steps and writes `results/sample/splats.ply`. The renderer creates 12 images in
+`renders/sample/` from the bundled PLY. To render the newly trained PLY instead, pass
+`--ply results/sample/splats.ply`. Rebuild the checked-in data at any time with:
+
+```bash
+bundle exec ruby examples/generate_sample_data.rb
+```
+
+### Training a COLMAP capture
+
+Prepare `sparse/0/{cameras,images,points3D}.bin` and an `images/` directory, then run:
+
+```bash
+bundle exec ruby examples/simple_trainer.rb \
+  --data /path/to/capture \
+  --output results/capture \
+  --steps 30000 \
+  --data-factor 1
+```
+
+Use `--strategy mcmc` for relocation-based densification. The trainer writes NPZ checkpoints and an
+Inria-compatible `splats.ply`. Render an orbit from that PLY with:
+
+```bash
+bundle exec ruby examples/render_path.rb \
+  --ply results/capture/splats.ply \
+  --output results/capture/path \
+  --frames 120
+```
+
+## API compatibility
+
+| Python gsplat | Ruby |
+|---|---|
+| `gsplat.rasterization(...)` | `Gsplat.rasterization(...)` |
+| `gsplat.rasterization_2dgs(...)` | `Gsplat.rasterization_2dgs(...)` |
+| `gsplat.spherical_harmonics(...)` | `Gsplat.spherical_harmonics(...)` |
+| `gsplat.quat_scale_to_covar_preci(...)` | `Gsplat.quat_scale_to_covar_preci(...)` |
+| `gsplat.fully_fused_projection(...)` | `Gsplat.fully_fused_projection(...)` |
+| `gsplat.isect_tiles(...)` | `Gsplat.isect_tiles(...)` |
+| `gsplat.isect_offset_encode(...)` | `Gsplat.isect_offset_encode(...)` |
+| `gsplat.rasterize_to_pixels(...)` | `Gsplat.rasterize_to_pixels(...)` |
+| `gsplat.rasterize_to_indices_in_range(...)` | `Gsplat.rasterize_to_indices_in_range(...)` |
+| `gsplat.strategy.DefaultStrategy` | `Gsplat::Strategy::Default` |
+| `gsplat.strategy.MCMCStrategy` | `Gsplat::Strategy::MCMC` |
+| `gsplat.compression.PngCompression` | `Gsplat::Compression::Png` |
+| `torch.optim.Adam` | `Gsplat::Optim::Adam` |
+| `examples/simple_trainer.py` | `Gsplat::Training::Trainer` / `examples/simple_trainer.rb` |
+
+See [the migration guide](docs/MIGRATION.md) for differences in shapes, activation, autograd, and
+training.
+
+## Limitations
+
+- Rendering and training are CPU-only; CUDA/GPU execution is not implemented.
+- Rendering is dense. Packed/sparse gradients and distributed rendering are not implemented.
+- 2DGS auxiliary geometry is API-compatible but approximates the upstream ray-splat transform.
+- Eval3d uses a shared Ruby reference implementation and a numerical geometry VJP.
+- Complete upstream raster parity still requires the documented external CUDA golden-data run.
+
+## Documentation
+
+- [Python migration guide](docs/MIGRATION.md)
+- [Architecture Decision Records](docs/DECISIONS.md)
+- [Benchmarks](docs/BENCHMARKS.md)
+- [Acceptance status](docs/ACCEPTANCE.md)
+- [Implementation progress](docs/PROGRESS.md)
+- [Golden-data tooling](tools/README.md)
+
+Generate the API reference locally with `bundle exec yard doc`.
+
+## Development
+
+Clone the repository and install the development dependencies:
+
+```bash
+git clone https://github.com/ydah/gsplat.git
+cd gsplat
+bundle install
+bundle exec rake compile
+```
+
+Run the validation suite:
+
+```bash
+GSPLAT_BACKEND=ruby bundle exec rake test
+OMP_NUM_THREADS=8 GSPLAT_BACKEND=native bundle exec rake test
+bundle exec rubocop --no-server --cache false
+bundle exec yard stats
+gem build gsplat.gemspec
+```
+
+Golden-data generation is pinned to Python gsplat 1.5.3. See
+[`tools/README.md`](tools/README.md) for CPU and CUDA commands.
+
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/ydah/gsplat). Keep behavior changes covered by tests. Changes that
+establish or replace a long-lived architectural contract should include an
+[ADR](docs/DECISIONS.md) created from the repository template.
+
+## License
+
+Gsplat is available under the [Apache License 2.0](LICENSE.txt).

data/docs/ACCEPTANCE.md

@@ -0,0 +1,60 @@
+# Acceptance status
+
+This report maps the design goals G1–G6 to reproducible evidence as of 2026-07-24. “Partial” means
+the implementation and local tests exist but the exact external dataset/hardware gate has not run.
+
+| Goal | Status | Evidence |
+|---|---|---|
+| G1: Python forward parity | Partial | 47-case pinned generator; analytic forward cases; reference compositor and backend-equivalence tests. CUDA-generated NPZ files are unavailable on this host, so their tests are documented skips. |
+| G2: backward parity | Partial | Float64 central differences for covariance, SH, projection, rasterization, distortion, losses, and eval3d; tile-vs-reference VJPs. Python/CUDA gradient fixtures remain pending with G1. |
+| G3: single-image convergence | Pass | `ImageFitterTest#test_self_consistency_fit_improves_psnr`: 11.772 → 30.878 dB in 20 monotonic reduced steps. The 50k/512²/2,000-step native timing also completes in 157.457 s. |
+| G4: COLMAP training quality | Partial | Binary/text parser parity, 100-point fixture, actual fixture-based Trainer smoke path, and an eight-view synthetic Trainer reaching ≥28 dB in 80 steps. No Mip-NeRF 360/real-capture 30k quality run is available. |
+| G5: compatible API surface | Pass within v1 scope | README mapping, migration guide, executable quick start, YARD 100%, low-level wrappers, strategies, optimizer, Trainer, IO, compression, 2DGS and eval3d surfaces. Unsupported upstream options are explicitly listed. |
+| G6: Ruby-only completeness | Pass | Full suite passes with `GSPLAT_BACKEND=ruby`; the same full suite passes with explicit native selection. CI now builds the extension and runs both paths, while auto mode retains the Ruby fallback. |
+
+## Local verification
+
+```text
+Ruby selection:   188 tests, 1,041 assertions, 0 failures, 22 documented skips
+Native selection: 188 tests, 1,041 assertions, 0 failures, 22 documented skips
+YARD:             129 methods, 125 attributes, 22 constants, undocumented 0
+RuboCop:          132 files, no offenses
+```
+
+## Golden-data gate
+
+`tools/generate_golden.py` is pinned to Python gsplat 1.5.3, uses seed 42, records provenance, and
+caps compressed output at 50 MiB. The local host has no CUDA and a prior temporary PyTorch install
+exceeded available disk. Consequently, tests calling `golden(...)` skip with a pointer to
+`tools/README.md`; no Ruby-generated fixture is accepted as a replacement.
+
+Run this on a compatible CUDA host to close G1/G2:
+
+```bash
+python3 -m venv .venv-golden
+.venv-golden/bin/pip install -r tools/requirements.txt
+.venv-golden/bin/python tools/generate_golden.py --device cuda --require-all
+bundle exec rake test
+```
+
+## CI matrix
+
+`.github/workflows/main.yml` runs:
+
+- RuboCop and the 100% YARD gate on Ruby 4.0.
+- The full Ruby backend suite on CRuby 3.2, 3.3, 3.4, and 4.0.
+- A native extension build and the full native suite on CRuby 4.0 with OpenMP workers.
+- Focused image-fit, multi-view Trainer, and all-example smoke tests.
+
+The same workflow runs on pushes, pull requests, manual dispatch, and a weekly scheduled trigger.
+Local equivalents pass; hosted status can only be confirmed after pushing the commit.
+
+## Release interpretation
+
+The package is functionally releasable for the documented CPU/dense scope. Strict completion of the
+original cross-implementation and real-capture goals still requires:
+
+1. Generating and committing the CUDA golden set, then resolving any mismatches.
+2. Running a representative real COLMAP capture for 30,000 steps and recording quality/time.
+
+These are external validation gates, not silently treated as passed.

data/docs/BENCHMARKS.md

@@ -0,0 +1,79 @@
+# Benchmark results
+
+## Environment
+
+- Date: 2026-07-24
+- Ruby: CRuby 4.0.0
+- Platform: arm64-darwin24 (Apple Silicon)
+- Native workers: `OMP_NUM_THREADS=8`
+- Dtype: `Numo::SFloat`
+- Scene seed: 42
+
+`benchmarks/bench_rasterize.rb` contains all four workloads from design section 9.1. Use `--list`
+to inspect them and `--quick` for CI-sized smoke runs.
+
+## Raster forward and backward
+
+Commands:
+
+```bash
+bundle exec ruby -Ilib benchmarks/bench_rasterize.rb \
+  --scenario raster --backend ruby --iterations 1
+
+OMP_NUM_THREADS=8 bundle exec ruby -Ilib benchmarks/bench_rasterize.rb \
+  --scenario raster --backend native --iterations 3
+```
+
+Workload: 100,000 Gaussians, one 800×800 camera, RGB, float32. Each measurement follows one warm-up.
+Forward+backward includes a fresh forward, both color/alpha VJPs, and `absgrad`.
+
+| Backend | Forward | Target | Forward + backward | Target | Result |
+|---|---:|---:|---:|---:|---|
+| Ruby | 3,527.990 ms | ≤ 10,000 ms | 8,047.024 ms | ≤ 30,000 ms | Pass |
+| Native, 8 workers | 30.419 ms | ≤ 150 ms | 112.573 ms | ≤ 400 ms | Pass |
+
+Native samples over three measured calls were 28.901–32.861 ms forward and
+109.907–114.240 ms combined. The speedup over Ruby was approximately 116× forward and 71× combined
+for this scene.
+
+## Image fitting
+
+Command:
+
+```bash
+OMP_NUM_THREADS=8 bundle exec ruby -Ilib benchmarks/bench_rasterize.rb \
+  --scenario fit_image --backend native
+```
+
+Workload: 50,000 Gaussians, 512×512 image, 2,000 optimization steps, float32. The timed run completed
+in 157.457 seconds (2 minutes 37.5 seconds), passing the ≤30 minute design target.
+
+This timing workload optimizes only colors in a deterministic self-consistency scene. Its final
+PSNR was 16.799 dB; that value is not the convergence acceptance case. The reduced convergence test
+uses 64 Gaussians at 8×8 and reaches 30.878 dB in 20 monotonic steps.
+
+## COLMAP training
+
+The benchmark scenario loads a real COLMAP directory and runs the production `Training::Trainer`:
+
+```bash
+ruby -Ilib benchmarks/bench_rasterize.rb \
+  --scenario colmap --backend native --data /path/to/capture --steps 30000
+```
+
+The complete 30,000-step, several-hundred-thousand-Gaussian benchmark was not run because no real
+capture with reference images is present on this host. The execution path was smoke-tested with the
+three-camera/100-point COLMAP fixture plus temporary 640×480 PNGs: one native step, including full
+evaluation before and after training, completed in 2.584 seconds.
+
+This smoke result demonstrates that the scenario and image/point pipeline execute; it is not a
+substitute for the design's overnight wall-time or real-capture quality gate.
+
+## Reproducing and extending
+
+Override workload sizes with `--gaussians`, `--width`, `--height`, `--steps`, and `--iterations`.
+Use `--json PATH` to save the complete environment/result object. The benchmark rejects zero or
+negative dimensions and never changes the mathematical rasterization thresholds.
+
+The older operation-attribution and OpenMP scaling measurements remain in
+[`PROFILE.md`](PROFILE.md).

data/docs/DECISIONS.md

@@ -0,0 +1,52 @@
+# Architecture Decision Records
+
+Architecture Decision Records (ADRs) capture significant technical decisions, their context, and
+their consequences. The individual records live in [`docs/decisions/`](decisions/) and are never
+deleted; a later ADR supersedes an earlier decision when the architecture changes.
+
+This structure follows the concise format used by
+[ydah/ibex](https://github.com/ydah/ibex/tree/main/docs/decisions).
+
+## Index
+
+| ADR | Status | Date | Decision |
+|---|---|---|---|
+| [0001](decisions/0001-pin-golden-reference-and-cpu-validation.md) | Accepted | 2026-07-23 | Pin the golden reference and define CPU-only validation |
+| [0002](decisions/0002-retain-ruby-fallbacks-for-native-backend.md) | Accepted | 2026-07-23 | Retain exact Ruby fallbacks for the native backend |
+| [0003](decisions/0003-share-projection-for-distorted-cameras.md) | Accepted | 2026-07-23 | Share the Ruby projection for distorted cameras |
+| [0004](decisions/0004-use-portable-world-space-reference-paths.md) | Accepted | 2026-07-24 | Use one portable reference for world-space extension paths |
+| [0005](decisions/0005-reuse-ewa-core-for-2dgs.md) | Accepted | 2026-07-24 | Reuse the differentiable EWA core for 2DGS |
+| [0006](decisions/0006-keep-eval3d-as-portable-reference.md) | Accepted | 2026-07-24 | Keep eval3d as a portable reference path |
+| [0007](decisions/0007-share-compositor-semantics-for-contribution-indices.md) | Accepted | 2026-07-24 | Share compositor semantics for contribution indices |
+## When an ADR is required
+
+Write an ADR when a change introduces a meaningful trade-off or establishes a long-lived contract,
+including:
+
+- public API, serialized format, or compatibility policy changes;
+- backend ownership, fallback, precision, or performance boundaries;
+- algorithm choices whose rejected alternatives may be reconsidered;
+- validation policy changes or accepted differences from the upstream implementation;
+- decisions that supersede or deprecate an existing ADR.
+
+Routine implementation details that follow an accepted decision do not need another ADR.
+
+## Creating an ADR
+
+1. Copy [`0000-template.md`](decisions/0000-template.md).
+2. Use the next four-digit number and a lowercase kebab-case filename:
+   `NNNN-short-decision-title.md`.
+3. Keep the title number equal to the filename number and use an ISO `YYYY-MM-DD` date.
+4. Add the ADR to the index in the same change.
+5. Run `bundle exec ruby -Itest test/architecture_decision_records_test.rb`.
+
+## Status lifecycle
+
+- `Proposed`: under review and not yet authoritative.
+- `Accepted`: active architecture.
+- `Rejected`: considered but not adopted.
+- `Deprecated`: retained for history but no longer recommended.
+- `Superseded by NNNN`: replaced by a newer ADR.
+
+Do not rewrite an accepted ADR to represent a different decision. Add a new ADR, mark the old one
+`Superseded by NNNN`, and link the records from their context or consequences.