feat(kpm): implement Hough similarity voting algorithm (M7)

[kalwalt]

Summary

Port Hough voting for similarity transformation matching from WebARKitLib C++.

Resolves #109 (M7 sub-issue)
Parent #108 (Hough voting & feature matching milestone)

What Changed

Core Implementation

• BinParams struct: Encapsulates 4D bin discretization (tx, ty, scale, angle)

  • Validates bin counts and transformation ranges at construction
  • Provides bin calculation utilities: map_to_bin(), bin_index(), bins_from_index()
  • Precomputes strides for efficient linear indexing

• HoughSimilarityVoting struct: Accumulates votes in discretized 4D space

  • vote(): Casts 16 votes via bilinear interpolation for a single match
  • get_maximum_votes(): Finds the bin with the most votes
  • get_similarity_from_index(): Maps bin index back to transformation (x, y, angle, scale)
  • reset(): Clears vote map for fresh voting round (reusable pattern)

• Free functions:

  • find_hough_similarity(): Main voting loop; returns max bin index or error if insufficient votes
  • find_hough_matches(): Filters matches to those within bin_delta of winning bin
  • compute_similarity(): Helper to compute transformation from feature correspondence

Stub Types (M8 Placeholders)

• FeaturePoint: Position, angle, scale
• Match: Query/reference correspondence
• DoGScaleInvariantDetector, GaussianScaleSpacePyramid, Keyframe: M8 stubs
• find_features(): Stub function for M8

Testing

• 10 unit tests covering:
  • BinParams creation, validation (bin counts, ranges, scale_k)
  • Bin indexing round-trips (forward & inverse)
  • Vote accumulation (single vote, out-of-bounds handling)
  • Vote map reset
  • Maximum vote detection
  • Match filtering by bin delta
• All 218 existing tests pass ✓

Design Decisions

Decision	Rationale
Functionally equivalent bin discretization (not bitwise)	Practical for cross-language ports; normal floating-point rounding acceptable
Result-based error handling	Aligns with CLAUDE.md; forces explicit error handling in callers
Reusable struct with reset()	Efficient for frame-by-frame processing; matches C++ pattern
Single new() constructor	Idiomatic Rust; combines C++ default + init() into one call
Encapsulated BinParams	Clear separation of concerns; testable in isolation; reusable by M8
Stub types in M7	M7 self-contained; minimal blocking on M8; stubs will be overridden later

Code Quality

• ✅ cargo fmt -- --check passes
• ✅ cargo clippy clean (no hough-related warnings)
• ✅ cargo test --lib passes (218 tests)
• ✅ LGPL-3.0 license header on all new files
• ✅ Idiomatic Rust: no unwrap(), panic!(), or println!() in library code
• ✅ Logging via arlog_*!() macros (debug & error levels as appropriate)
• ✅ Comprehensive error messages for validation failures

Testing

# Run all tests
cargo test --lib

# Run only hough tests
cargo test --lib hough

# Check code quality
cargo fmt -- --check
cargo clippy --all-targets

Files Changed

• crates/core/src/kpm/freak/hough.rs — New file (700 lines): Main implementation
• crates/core/src/kpm/freak/mod.rs — Updated: Added pub mod hough and re-exports

Next Steps

• Review & merge to feat/milestone7-hough-voting-feature-match
• feat(kpm): M7 — Hough voting & feature matching in pure Rust #108 closes only when all sub-issues (feat(kpm): M7-1 — port hough_similarity_voting.h to freak/hough.rs #109, ...) are merged

---

🤖 Generated with Claude Code