Files
RuView/v2/crates/ruview-offaxis/benches/offaxis.rs
Claude 3161af52da feat(offaxis): clean-room Kooima off-axis projection in Rust/WASM (ADR-324)
New leaf crate v2/crates/ruview-offaxis implementing ADR-324's projection
core from the published math only (Kooima 2008 generalized perspective
projection; Casiez 2012 one-euro filter) — no code from the unlicensed
prior-art repo. Dependency-free native core; wasm-bindgen surface gated to
wasm32 (cdylib+rlib, ~54 KB wasm after bindgen).

- projection: Screen (3 corners, any orientation) + off_axis() -> typed
  errors, never NaN matrices; column-major f64 (three.js Matrix4 layout).
  Tests pin the defining invariants: screen corners -> NDC corners for a
  grid of eye positions and tilted screens; screen-plane points are
  eye-invariant; centered eye reduces to the symmetric frustum; near/far
  map to NDC -1/+1.
- filter: one-euro with injected timestamps (no clock in crate);
  monotonicity/convergence/NaN-rejection tests.
- rf: field-peak extraction mirroring field_localize.rs constants
  (X_SCALE 0.6, Z_SCALE 0.5, PEAK_THRESHOLD 0.35) and the Tier B
  coarse-parallax stage (deadband, gain, hard clamp) so over-claiming is
  impossible at the API level. No accuracy numbers asserted.
- wasm: OffAxisCamera + RfParallax bindgen classes; per-frame updates hold
  last good state instead of throwing.
- benches (criterion): full Tier B frame ~598 ns; argmax scan optimized
  -18%/-33% (20x20/100x100). MEASURED table + reproducer in README.
- examples/three.js/demos/07-off-axis-window.html: demo with SYNTHETIC
  mouse simulator and labeled RF Tier B mode ('coarse body parallax - not
  head tracking'), physical calibration panel, /ws/sensing input, and a
  build-instructions overlay when the local pkg/ output is missing
  (generated artifacts stay uncommitted; .gitignore entry added).
- Validated 23 unit tests + doctest, clippy clean, wasm32 release build,
  Node smoke test of the bindgen output, and a headless-Chromium run of
  the demo (engine load, eye response, mode labels, ws failure path).
- ADR-324: header + section 2.5 amendment recording the Rust/WASM core.

Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01BU3NcEgTpAVvu5QGtw4czT
2026-08-16 23:52:43 +00:00

85 lines
2.7 KiB
Rust

//! Criterion benchmarks for the per-frame hot path (ADR-324).
//!
//! Reproducer: `cd v2 && cargo bench -p ruview-offaxis`
//! Any numbers quoted from this bench are MEASURED on the machine that ran
//! that command; re-run locally before relying on them.
use criterion::{black_box, criterion_group, criterion_main, Criterion};
use ruview_offaxis::{
field_peak, off_axis, CoarseParallax, CoarseParallaxConfig, OneEuro3, OneEuroConfig, Screen,
Vec3,
};
fn bench_projection(c: &mut Criterion) {
let screen = Screen::centered(0.6, 0.34).unwrap();
c.bench_function("off_axis_projection", |b| {
let mut t = 0.0_f64;
b.iter(|| {
t += 0.016;
let eye = Vec3::new(0.1 * t.sin(), 0.05 * t.cos(), 0.65);
black_box(off_axis(black_box(&screen), black_box(eye), 0.05, 100.0).unwrap())
})
});
c.bench_function("off_axis_view_projection_combined", |b| {
let eye = Vec3::new(0.1, -0.03, 0.65);
let oa = off_axis(&screen, eye, 0.05, 100.0).unwrap();
b.iter(|| black_box(black_box(&oa).view_projection()))
});
}
fn bench_filter(c: &mut Criterion) {
c.bench_function("one_euro3_step", |b| {
let mut f = OneEuro3::new(OneEuroConfig::default());
let mut t = 0.0_f64;
b.iter(|| {
t += 0.016;
black_box(f.filter(Vec3::new(t.sin(), t.cos(), 0.65), t))
})
});
}
fn make_grid(nx: usize, nz: usize) -> Vec<f32> {
// Deterministic pseudo-field with one hot cell.
let mut v: Vec<f32> = (0..nx * nz).map(|i| 0.05 + (i % 7) as f32 * 0.01).collect();
v[(nz / 3) * nx + nx / 4] = 0.9;
v
}
fn bench_field_peak(c: &mut Criterion) {
let g20 = make_grid(20, 20);
c.bench_function("field_peak_20x20", |b| {
b.iter(|| black_box(field_peak(black_box(&g20), 20, 20)))
});
let g100 = make_grid(100, 100);
c.bench_function("field_peak_100x100", |b| {
b.iter(|| black_box(field_peak(black_box(&g100), 100, 100)))
});
}
fn bench_full_tier_b_frame(c: &mut Criterion) {
// The whole Tier B per-frame path: grid scan → parallax → projection.
let screen = Screen::centered(0.6, 0.34).unwrap();
let g20 = make_grid(20, 20);
c.bench_function("tier_b_full_frame_20x20", |b| {
let mut cp = CoarseParallax::new(CoarseParallaxConfig::default());
let mut t = 0.0_f64;
b.iter(|| {
t += 0.016;
let peak = field_peak(black_box(&g20), 20, 20);
let eye = cp.update(peak, t);
black_box(off_axis(&screen, eye, 0.05, 100.0).unwrap())
})
});
}
criterion_group!(
benches,
bench_projection,
bench_filter,
bench_field_peak,
bench_full_tier_b_frame
);
criterion_main!(benches);