perf(kpm): box-filter Pyramid downsample — criterion benchmark + SIMD (#211)

* perf(kpm): add criterion benchmark for Pyramid downsample (#131)

Establish the scalar baseline for the pyramid downsample trilogy so the
SIMD path (#132) and any chunked-layout work (#133) can prove speedups
against stable numbers.

- Promote the private `downsample` to `pub fn downsample_scalar` and add
  a `pub fn downsample` dispatcher (scalar-only for now; #132 wires in
  the SIMD paths). Both are `pub` so the criterion bench (a separate
  crate) can measure them directly; `Pyramid::build` is the stable API.
- Add `crates/core/benches/pyramid_bench.rs` benchmarking
  `downsample_scalar` and `Pyramid::build` (num_levels=4) at 640x480,
  1280x720 and 1920x1080 with a fixed-seed PRNG input.
- Wire `[[bench]] name = "pyramid_bench"` into Cargo.toml.

Baseline (median, this machine):
  downsample     640x480  ~116 us | 1280x720 ~341 us | 1920x1080 ~884 us
  pyramid_build  640x480  ~159 us | 1280x720 ~597 us | 1920x1080 ~1.87 ms

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* perf(kpm): SIMD path for Pyramid downsample (AVX2/SSE4.1/wasm32) (#132)

Add runtime-dispatched SIMD implementations of the pyramid downsample,
each byte-identical to the scalar baseline established in #131.

- `downsample_avx2`: 32 output cols/iter via 256-bit lanes
  (`maddubs` horizontal pairwise add + `packus` + `permute4x64` to undo
  the per-lane interleave).
- `downsample_sse41`: 16 output cols/iter via 128-bit lanes.
- `downsample_wasm`: 16 output cols/iter via `simd128`
  (`extadd_pairwise_u8x16` + `narrow`).
- `downsample` dispatches AVX2 -> SSE4.1 -> scalar on x86_64 (runtime
  `is_x86_feature_detected!`) and simd128 on wasm32; scalar remains the
  fallback. Each `unsafe` site carries a `// SAFETY:` comment.
- Shared `downsample_dims` + `downsample_row_tail_scalar` helpers define
  the rounding in one place; the SIMD main loops handle full blocks and
  defer the per-row remainder to the scalar tail.
- Block counts are sized so loads/stores stay in bounds for any
  dimension (incl. odd / sub-block widths).

Correctness: property tests compare each SIMD path against scalar over 16
sizes (odd dims, tiny images, block boundaries) plus a dispatcher-parity
test. `cargo clippy --all-targets --all-features -- -D warnings` clean.

Speedup (downsample, median ns -> us, this machine):
  640x480    scalar 85.8 | sse41 7.4 (11.6x) | avx2 5.8 (14.7x)
  1280x720   scalar 251  | sse41 25.0 (10.0x) | avx2 18.6 (13.5x)
  1920x1080  scalar 773  | sse41 96.1 (8.0x)  | avx2 75.9 (10.2x)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(kpm): exhaustive width-sweep parity for SIMD downsample (#132)

Add a 2..=160 column sweep (x4 row counts) comparing both the AVX2 and
SSE4.1 paths against scalar, covering every remainder case of the 16- and
32-wide main loops. Strengthens confidence beyond the hand-picked sizes
that each SIMD path is byte-identical to scalar for all dimensions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: kalwalt

crates/core/Cargo.toml

@@ -154,6 +154,10 @@ name = "feature_map_bench"
 harness = false
 required-features = ["log-helpers"]
 
+[[bench]]
+name = "pyramid_bench"
+harness = false
+
 [[bench]]
 name = "gaussian_pyramid_bench"
 harness = false

crates/core/benches/pyramid_bench.rs

@@ -0,0 +1,131 @@
+/*
+ *  pyramid_bench.rs
+ *  WebARKitLib-rs
+ *
+ *  This file is part of WebARKitLib-rs - WebARKit.
+ *
+ *  WebARKitLib-rs is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  WebARKitLib-rs is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with WebARKitLib-rs.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ *  As a special exception, the copyright holders of this library give you
+ *  permission to link this library with independent modules to produce an
+ *  executable, regardless of the license terms of these independent modules, and to
+ *  copy and distribute the resulting executable under terms of your choice,
+ *  provided that you also meet, for each linked independent module, the terms and
+ *  conditions of the license of that module. An independent module is a module
+ *  which is neither derived from nor based on this library. If you modify this
+ *  library, you may extend this exception to your version of the library, but you
+ *  are not obligated to do so. If you do not wish to do so, delete this exception
+ *  statement from your version.
+ *
+ *  Copyright 2026 WebARKit.
+ *
+ *  Author(s): Walter Perdan @kalwalt https://github.com/kalwalt
+ *
+ */
+
+//! Criterion baseline for `kpm::freak::pyramid` downsampling (#131).
+//!
+//! Establishes the scalar baseline so the SIMD path (#132) and any
+//! chunked-layout work (#133) can prove their speedup against stable
+//! numbers. Two groups are measured at typical AR input resolutions
+//! (640×480, 1280×720, 1920×1080):
+//!
+//! - `downsample`: one 2×2 box-filter decimation step (the hot inner loop).
+//! - `pyramid_build`: end-to-end `Pyramid::build` with `num_levels = 4`.
+//!
+//! Inputs are filled deterministically with a fixed-seed PRNG so runs are
+//! comparable across machines and across PRs in the trilogy.
+
+use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
+use purecv::core::Matrix;
+use rand::rngs::StdRng;
+use rand::{Rng, SeedableRng};
+use std::hint::black_box;
+use webarkitlib_rs::kpm::freak::pyramid::{downsample_scalar, Pyramid};
+
+#[cfg(all(target_arch = "x86_64", feature = "simd-x86-sse41"))]
+use webarkitlib_rs::kpm::freak::pyramid::downsample_sse41;
+
+#[cfg(all(target_arch = "x86_64", feature = "simd-x86-avx2"))]
+use webarkitlib_rs::kpm::freak::pyramid::downsample_avx2;
+
+/// Typical AR camera input resolutions as `(width, height)`.
+const SIZES: &[(usize, usize)] = &[(640, 480), (1280, 720), (1920, 1080)];
+
+/// Build a deterministic grayscale `Matrix<u8>` of `rows × cols` using a
+/// fixed-seed PRNG, so every benchmark run sees identical pixel data.
+fn random_gray(rows: usize, cols: usize) -> Matrix<u8> {
+    let mut rng = StdRng::seed_from_u64(0xA12B_C3D4);
+    let data: Vec<u8> = (0..rows * cols).map(|_| rng.random::<u8>()).collect();
+    Matrix::<u8>::from_vec(rows, cols, 1, data)
+}
+
+fn bench_downsample(c: &mut Criterion) {
+    let mut group = c.benchmark_group("downsample");
+    for &(w, h) in SIZES {
+        let src = random_gray(h, w);
+        // One output pixel per 2×2 source block; throughput is measured in
+        // source pixels touched.
+        group.throughput(Throughput::Elements((w * h) as u64));
+        group.bench_with_input(
+            BenchmarkId::new("scalar", format!("{w}x{h}")),
+            &src,
+            |bencher, src| bencher.iter(|| downsample_scalar(black_box(src))),
+        );
+
+        #[cfg(all(target_arch = "x86_64", feature = "simd-x86-sse41"))]
+        if is_x86_feature_detected!("sse4.1") {
+            group.bench_with_input(
+                BenchmarkId::new("sse41", format!("{w}x{h}")),
+                &src,
+                // SAFETY: sse4.1 confirmed available by the runtime check above.
+                |bencher, src| bencher.iter(|| unsafe { downsample_sse41(black_box(src)) }),
+            );
+        }
+
+        #[cfg(all(target_arch = "x86_64", feature = "simd-x86-avx2"))]
+        if is_x86_feature_detected!("avx2") {
+            group.bench_with_input(
+                BenchmarkId::new("avx2", format!("{w}x{h}")),
+                &src,
+                // SAFETY: avx2 confirmed available by the runtime check above.
+                |bencher, src| bencher.iter(|| unsafe { downsample_avx2(black_box(src)) }),
+            );
+        }
+    }
+    group.finish();
+}
+
+fn bench_pyramid_build(c: &mut Criterion) {
+    let mut group = c.benchmark_group("pyramid_build");
+    for &(w, h) in SIZES {
+        let src = random_gray(h, w);
+        group.throughput(Throughput::Elements((w * h) as u64));
+        group.bench_with_input(
+            BenchmarkId::new("levels4", format!("{w}x{h}")),
+            &src,
+            |bencher, src| {
+                bencher.iter(|| {
+                    let mut p = Pyramid::new(4, 2.0);
+                    p.build(black_box(src)).expect("build should succeed");
+                    p
+                })
+            },
+        );
+    }
+    group.finish();
+}
+
+criterion_group!(benches, bench_downsample, bench_pyramid_build);
+criterion_main!(benches);