bump version 0.5.0

kalwalt · kalwalt · commit 4764f701fe48 · 2026-05-13T16:02:17.000+02:00
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -34,9 +34,12 @@ The unified core library containing all AR functionality:
     -   `kpm::matching` — per-frame matching and ICP-based pose estimation.
     -   `kpm::ref_data_set` — `.fset3` reference data I/O and compression modes.
     -   `kpm::types` — KPM data structures and constants.
-    -   `kpm::freak` — FREAK descriptor math and homography utilities:
+    -   `kpm::freak` — FREAK descriptor math, homography, and matching utilities (pure Rust port of `WebARKitLib/lib/SRC/KPM/FreakMatcher`):
         -   `freak::math` — linear algebra (matrix operations, linear solvers) and Padé matrix exponential.
         -   `freak::homography` — homography estimation and refinement pipeline.
+        -   `freak::hough` — Hough similarity voting (4D bin discretization over translation × angle × scale) for filtering matches by transformation consistency.
+        -   `freak::clustering` — K-Medoids partitioning + Binary Hierarchical Clustering (BHC) vocabulary tree for fast approximate-NN search on 96-byte FREAK descriptors. Hamming distance via 24×32-bit bit-magic. Includes a byte-identical port of C++ `vision::FastRandom` / `vision::ArrayShuffle` so the BHC tree topology matches the C++ baseline given the same seed.
+        -   `freak::matcher` — `FeatureStore` (points + flat descriptor buffer) and `FeatureMatcher` with three match variants: brute force, BHC-indexed (fast path), and homography-guided (spatial filter via 3×3 inverse + `tr` radius). All three apply the C++ ratio test (default 0.7) and filter by `FeaturePoint::maxima`.
 -   **Types** (`types`): core data structures (`ARHandle`, `ARParam`, etc.).
 
 ### `crates/wasm` — `webarkitlib-wasm`
@@ -53,7 +56,7 @@ Depends only on `webarkitlib-rs` (the core crate).
 | `simd-x86-sse41` | x86 SSE4.1 intrinsics |
 | `log-helpers`  | Enable logging infrastructure (installs `env_logger` for desktop/tests, `console_log` for WASM) |
 | `ffi-backend`  | Compile the C++ FreakMatcher library and generate FFI bindings |
-| `dual-mode`    | Reserved for future dual Rust/C++ backend support |
+| `dual-mode`    | Enables FFI-based parity tests that validate pure-Rust ports against the live C++ baseline (M6 math/solvers/homography, M7 BHC/matcher, PRNG). Transitively enables `ffi-backend`. Run in CI on Linux/macOS/Windows. |
 
 ## SIMD Strategy
 
@@ -85,6 +88,17 @@ cargo build --features ffi-backend
 cargo test --workspace --features ffi-backend
 ```
 
+### Dual-mode parity tests (Rust ↔ C++)
+
+Validates the pure-Rust ports against the live C++ baseline via FFI shims.
+Requires the C++ submodule to be initialized:
+
+```bash
+cargo test -p webarkitlib-rs --lib --features dual-mode
+```
+
+CI runs this step on Linux, macOS, and Windows on every push.
+
 ### WASM
 ```bash
 cd crates/wasm
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,47 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.0] - 2026-05-13
+
+### Milestone 7 — Hough voting & feature matching in pure Rust
+
+### 🚀 Features
+
+- *(kpm)* Implement Hough similarity voting algorithm (M7)
+- *(kpm)* Implement binary hierarchical clustering and k-medoids for FREAK descriptors
+- *(kpm)* Port FeatureStore and FeatureMatcher with three match variants
+- *(kpm)* Port ArrayShuffle for BHC parity with C++ baseline
+
+### 🐛 Bug Fixes
+
+- *(kpm)* Fix arlog macro imports and unused variable warnings (#109)
+- *(kpm)* Apply clippy and fmt fixes to hough.rs for M7
+- *(kpm)* Resolve clippy warnings in clustering module
+- *(kpm)* Resolve remaining clippy warnings in clustering
+- *(kpm)* Include <limits> in kpm_c_api.cpp for GCC build
+- *(kpm)* Move <limits> include before matcher headers for GCC build
+- *(build)* Use platform-appropriate C++ stdlib (libc++ on macOS, libstdc++ on Linux)
+- *(kpm)* Use combined absolute+relative tolerance in M6-2 dual-mode tests
+- *(kpm)* Widen relative tolerance to 1e-5 for M6-2 dual-mode tests
+
+### 🧪 Testing
+
+- *(kpm)* Add dual-mode FFI tests for FeatureMatcher (M7-3)
+- *(kpm)* Strengthen dual-mode FeatureMatcher tests with pair equality and global-best invariants
+
+### 📚 Documentation
+
+- Add pre-commit verification workflow and arlog import pattern to CLAUDE.md
+
+### 🎨 Styling
+
+- Fix formatting from cargo fmt
+
+### ⚙️ Miscellaneous Tasks
+
+- Run dual-mode tests in CI to enforce C++ parity
+- Scope dual-mode tests to --lib to avoid pre-existing integration test failures
+
 ## [0.4.1] - 2026-05-09
 
 ### Patch release — Matrix code GlobalID, paramGL ports, and quality fixes
diff --git a/Cargo.toml b/Cargo.toml
@@ -9,7 +9,7 @@ exclude = [
 resolver = "2"
 
 [workspace.package]
-version = "0.4.1"
+version = "0.5.0"
 authors = ["kalwalt <github@kalwaltart.it>"]
 edition = "2021"
 description = "A high-performance, memory-safe Rust port of WebARKitLib (ARToolKit) for native and WASM."
diff --git a/README.md b/README.md
@@ -38,14 +38,14 @@ Add `webarkitlib-rs` to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-webarkitlib-rs = "0.4"
+webarkitlib-rs = "0.5"
 ```
 
 To enable the C++ FFI backend for KPM (Natural Feature Tracking):
 
 ```toml
 [dependencies]
-webarkitlib-rs = { version = "0.4", features = ["ffi-backend"] }
+webarkitlib-rs = { version = "0.5", features = ["ffi-backend"] }
 ```
 
 > When installing from crates.io, no extra setup is required — the C++
@@ -204,7 +204,7 @@ Enable the `log-helpers` feature and call the bundled initializer once in your b
 
 ```toml
 [dependencies]
-webarkitlib-rs = { version = "0.4", features = ["log-helpers"] }
+webarkitlib-rs = { version = "0.5", features = ["log-helpers"] }
 ```
 
 ```rust
@@ -310,6 +310,10 @@ The workspace contains two crates:
 - **`crates/core`** (`webarkitlib-rs`): The unified core AR engine (pure Rust), including:
   - `ar2` module: NFT marker generation pipeline — image pyramid (`ar2_gen_image_set`), feature map (`ar2_gen_feature_map`), JPEG-compressed `.iset` save, `.fset` / `.fset3` I/O.
   - `kpm` module: Keypoint Matching with pluggable backends (Rust + C++ FFI), FREAK descriptor extraction.
+    - `kpm::freak::math` / `kpm::freak::homography`: pure-Rust math & homography pipeline (M6).
+    - `kpm::freak::hough`: Hough similarity voting — 4D-binned voting scheme for finding the consistent similarity transformation across matched feature pairs (M7).
+    - `kpm::freak::clustering`: K-Medoids + Binary Hierarchical Clustering (BHC) vocabulary tree for fast approximate-NN search on 96-byte FREAK descriptors. Byte-identical PRNG (`FastRandom` / `ArrayShuffle`) for C++ parity (M7).
+    - `kpm::freak::matcher`: `FeatureStore` + `FeatureMatcher` with three match variants (brute, BHC-indexed, homography-guided), each gated by C++-faithful ratio test and `maxima` filtering (M7).
   - Core modules: image processing, pattern matching, labeling, ICP, pose estimation.
 - **`crates/wasm`** (`webarkitlib-wasm`): WASM bindings, dual-build scripts, and diagnostic web demo.
 - `benchmarks`: C vs Rust performance comparison suite.
@@ -329,6 +333,11 @@ The workspace contains two crates:
   - Detailed step-by-step logging with timestamps and per-level statistics
 - **M5 -- NFT Pipeline Performance**: Rayon parallelism for pyramid generation and Stage-3 feature scoring, plus optional SSE4.1/AVX2+FMA SIMD vectorization of the `get_similarity` correlation kernel. ~1.7× total speedup on x86_64.
 - **M6 -- Math & homography in pure Rust**: Ported all free mathematical functions from FreakMatcher into `crates/core/src/kpm/freak/math.rs` and `freak/homography.rs` (~1476 lines across 5 C++ headers). Eliminates the only remaining Eigen dependency: the 3×3 matrix exponential in `IncrementalHomographyFromLieWeights`.
+- **M7 -- Hough voting & feature matching in pure Rust**: Ported the full FreakMatcher matching pipeline into `crates/core/src/kpm/freak/{hough,clustering,matcher}.rs` (~2790 LOC total):
+  - Hough similarity voting (4D bin discretization) — 734 LOC
+  - K-Medoids clustering + Binary Hierarchical Clustering vocabulary tree, including a byte-identical `FastRandom` / `ArrayShuffle` PRNG port — 889 LOC
+  - `FeatureStore` + `FeatureMatcher` with three match variants (brute, BHC-indexed, homography-guided), C++-faithful ratio test (default 0.7), and `maxima` filtering — 1167 LOC
+  - **Dual-mode FFI tests run in CI on Linux / macOS / Windows** with sorted-pair equality vs the C++ baseline for brute/indexed/guided matchers (the M7 milestone validation gate). Surfaced and fixed three latent cross-platform issues: macOS `libc++` linking, GCC `<limits>` include order, and ARM64 FMA tolerance in M6-2 solvers.
 
 ### 🎯 Short-term Goals (toward v1.0.0)
 - **Complete KPM in idiomatic Rust**: Port the remaining KPM feature extraction and matching logic to pure Rust, removing the C++ FFI dependency, and ship a working end-to-end NFT example.
diff --git a/crates/wasm/pkg/README.md b/crates/wasm/pkg/README.md
@@ -38,14 +38,14 @@ Add `webarkitlib-rs` to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-webarkitlib-rs = "0.3"
+webarkitlib-rs = "0.5"
 ```
 
 To enable the C++ FFI backend for KPM (Natural Feature Tracking):
 
 ```toml
 [dependencies]
-webarkitlib-rs = { version = "0.3", features = ["ffi-backend"] }
+webarkitlib-rs = { version = "0.5", features = ["ffi-backend"] }
 ```
 
 > When installing from crates.io, no extra setup is required — the C++
@@ -204,7 +204,7 @@ Enable the `log-helpers` feature and call the bundled initializer once in your b
 
 ```toml
 [dependencies]
-webarkitlib-rs = { version = "0.3", features = ["log-helpers"] }
+webarkitlib-rs = { version = "0.5", features = ["log-helpers"] }
 ```
 
 ```rust
@@ -310,6 +310,10 @@ The workspace contains two crates:
 - **`crates/core`** (`webarkitlib-rs`): The unified core AR engine (pure Rust), including:
   - `ar2` module: NFT marker generation pipeline — image pyramid (`ar2_gen_image_set`), feature map (`ar2_gen_feature_map`), JPEG-compressed `.iset` save, `.fset` / `.fset3` I/O.
   - `kpm` module: Keypoint Matching with pluggable backends (Rust + C++ FFI), FREAK descriptor extraction.
+    - `kpm::freak::math` / `kpm::freak::homography`: pure-Rust math & homography pipeline (M6).
+    - `kpm::freak::hough`: Hough similarity voting — 4D-binned voting scheme for finding the consistent similarity transformation across matched feature pairs (M7).
+    - `kpm::freak::clustering`: K-Medoids + Binary Hierarchical Clustering (BHC) vocabulary tree for fast approximate-NN search on 96-byte FREAK descriptors. Byte-identical PRNG (`FastRandom` / `ArrayShuffle`) for C++ parity (M7).
+    - `kpm::freak::matcher`: `FeatureStore` + `FeatureMatcher` with three match variants (brute, BHC-indexed, homography-guided), each gated by C++-faithful ratio test and `maxima` filtering (M7).
   - Core modules: image processing, pattern matching, labeling, ICP, pose estimation.
 - **`crates/wasm`** (`webarkitlib-wasm`): WASM bindings, dual-build scripts, and diagnostic web demo.
 - `benchmarks`: C vs Rust performance comparison suite.
@@ -328,6 +332,12 @@ The workspace contains two crates:
   - FREAK descriptor extraction via `kpm_extract_features` C API (7000+ features per marker)
   - Detailed step-by-step logging with timestamps and per-level statistics
 - **M5 -- NFT Pipeline Performance**: Rayon parallelism for pyramid generation and Stage-3 feature scoring, plus optional SSE4.1/AVX2+FMA SIMD vectorization of the `get_similarity` correlation kernel. ~1.7× total speedup on x86_64.
+- **M6 -- Math & homography in pure Rust**: Ported all free mathematical functions from FreakMatcher into `crates/core/src/kpm/freak/math.rs` and `freak/homography.rs` (~1476 lines across 5 C++ headers). Eliminates the only remaining Eigen dependency: the 3×3 matrix exponential in `IncrementalHomographyFromLieWeights`.
+- **M7 -- Hough voting & feature matching in pure Rust**: Ported the full FreakMatcher matching pipeline into `crates/core/src/kpm/freak/{hough,clustering,matcher}.rs` (~2790 LOC total):
+  - Hough similarity voting (4D bin discretization) — 734 LOC
+  - K-Medoids clustering + Binary Hierarchical Clustering vocabulary tree, including a byte-identical `FastRandom` / `ArrayShuffle` PRNG port — 889 LOC
+  - `FeatureStore` + `FeatureMatcher` with three match variants (brute, BHC-indexed, homography-guided), C++-faithful ratio test (default 0.7), and `maxima` filtering — 1167 LOC
+  - **Dual-mode FFI tests run in CI on Linux / macOS / Windows** with sorted-pair equality vs the C++ baseline for brute/indexed/guided matchers (the M7 milestone validation gate). Surfaced and fixed three latent cross-platform issues: macOS `libc++` linking, GCC `<limits>` include order, and ARM64 FMA tolerance in M6-2 solvers.
 
 ### 🎯 Short-term Goals (toward v1.0.0)
 - **Complete KPM in idiomatic Rust**: Port the remaining KPM feature extraction and matching logic to pure Rust, removing the C++ FFI dependency, and ship a working end-to-end NFT example.
diff --git a/crates/wasm/pkg/package.json b/crates/wasm/pkg/package.json
@@ -5,7 +5,7 @@
                           "kalwalt \u003cgithub@kalwaltart.it\u003e"
                       ],
     "description":  "A high-performance, memory-safe Rust port of WebARKitLib (ARToolKit) for native and WASM.",
-    "version":  "0.4.1",
+    "version":  "0.5.0",
     "license":  "LGPL-3.0-or-later",
     "repository":  {
                        "type":  "git",
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "webarkitlib-rs",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Port of WebARKitLib (ARToolKit) to Rust and WASM",
   "private": true,
   "scripts": {

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "webarkitlib-rs",`
`3`		`- "version": "0.4.1",`
	`3`	`+ "version": "0.5.0",`
`4`	`4`	`"description": "Port of WebARKitLib (ARToolKit) to Rust and WASM",`
`5`	`5`	`"private": true,`
`6`	`6`	`"scripts": {`