diff --git a/crates/core/src/kpm/freak/homography.rs b/crates/core/src/kpm/freak/homography.rs index e55a901..d666aa8 100644 --- a/crates/core/src/kpm/freak/homography.rs +++ b/crates/core/src/kpm/freak/homography.rs @@ -296,6 +296,9 @@ fn homography_3_points_geometrically_consistent( /// `math/geometry.h:71`. Private helper used by RANSAC to filter degenerate /// 4-tuples before solving for the homography. #[inline(always)] +// rationale: numerical homography routine — the flat point/matrix/scalar +// signature mirrors the math and the C++ source; a param struct would +// obscure it. Restructure deferred to a pre-1.0 pass (#83). #[allow(clippy::too_many_arguments)] fn homography_4_points_geometrically_consistent( x1: &[f32; 2], @@ -964,6 +967,9 @@ pub fn update_projective_motion_post_multiply(hp: &mut [f32; 9], h: &[f32; 9], x /// C++ equivalent: `vision::Condition4Points2d` from /// `homography_estimation/homography_solver.h:47`. #[inline(always)] +// rationale: numerical homography routine — the flat point/matrix/scalar +// signature mirrors the math and the C++ source; a param struct would +// obscure it. Restructure deferred to a pre-1.0 pass (#83). #[allow(clippy::too_many_arguments)] fn condition_4_points_2d( xp: &mut [[f32; 2]; 4], @@ -1022,6 +1028,9 @@ fn condition_4_points_2d( /// C++ equivalent: `vision::DenormalizeHomography` from /// `homography_estimation/homography_solver.h:104`. #[inline(always)] +// rationale: numerical homography routine — the flat point/matrix/scalar +// signature mirrors the math and the C++ source; a param struct would +// obscure it. Restructure deferred to a pre-1.0 pass (#83). #[allow(clippy::too_many_arguments)] fn denormalize_homography( hp: &mut [f32; 9], @@ -1104,6 +1113,9 @@ fn add_homography_point_constraint(dst: &mut [f32; 18], x: &[f32; 2], xp: &[f32; /// C++ equivalent: `vision::SolveHomography4PointsInhomogenous` from /// `homography_estimation/homography_solver.h:185`. #[inline(always)] +// rationale: numerical homography routine — the flat point/matrix/scalar +// signature mirrors the math and the C++ source; a param struct would +// obscure it. Restructure deferred to a pre-1.0 pass (#83). #[allow(clippy::too_many_arguments)] fn solve_homography_4_points_inhomogeneous( h: &mut [f32; 9], @@ -1155,6 +1167,9 @@ fn solve_homography_4_points_inhomogeneous( /// `homography_estimation/homography_solver.h:209`. Called from /// [`preemptive_robust_homography`] for each RANSAC trial. #[inline(always)] +// rationale: numerical homography routine — the flat point/matrix/scalar +// signature mirrors the math and the C++ source; a param struct would +// obscure it. Restructure deferred to a pre-1.0 pass (#83). #[allow(clippy::too_many_arguments)] fn solve_homography_4_points( h: &mut [f32; 9], @@ -1396,6 +1411,9 @@ fn fast_median(a: &mut [(f32, i32)]) { /// `vision::PreemptiveRobustHomography` from /// `homography_estimation/robust_homography.h:96`. #[inline(always)] +// rationale: numerical homography routine — the flat point/matrix/scalar +// signature mirrors the math and the C++ source; a param struct would +// obscure it. Restructure deferred to a pre-1.0 pass (#83). #[allow(clippy::too_many_arguments)] pub fn preemptive_robust_homography( h: &mut [f32; 9], @@ -1819,6 +1837,9 @@ fn symmetric_extend_upper_to_lower_8x8(a: &mut [f32; 64]) { /// `vision::ComputeHomographyNormalEquationsPostMultiply` from /// `homography_estimation/robust_homography.h:397`. #[inline(always)] +// rationale: numerical homography routine — the flat point/matrix/scalar +// signature mirrors the math and the C++ source; a param struct would +// obscure it. Restructure deferred to a pre-1.0 pass (#83). #[allow(clippy::too_many_arguments)] fn compute_homography_normal_equations_post_multiply( jt_j: &mut [f32; 64], @@ -1983,6 +2004,9 @@ fn solve_positive_definite_system_8x8(x: &mut [f32; 8], a: &[f32; 64], b: &[f32; /// `homography_estimation/robust_homography.h:500`. Called by /// [`RobustHomography::find`] after the RANSAC step. #[inline(always)] +// rationale: numerical homography routine — the flat point/matrix/scalar +// signature mirrors the math and the C++ source; a param struct would +// obscure it. Restructure deferred to a pre-1.0 pass (#83). #[allow(clippy::too_many_arguments)] pub fn polish_homography( h: &mut [f32; 9], diff --git a/crates/core/src/kpm/freak/hough.rs b/crates/core/src/kpm/freak/hough.rs index 1a3d234..674dece 100644 --- a/crates/core/src/kpm/freak/hough.rs +++ b/crates/core/src/kpm/freak/hough.rs @@ -104,6 +104,8 @@ impl BinParams { /// * `min_y`, `max_y` - Translation y range (min_y < max_y) /// * `min_scale`, `max_scale` - Scale range (min_scale < max_scale) /// * `scale_k` - Log base for scale (typically 2.0 or e) + // rationale: mirrors the C++ HoughSimilarityVoting init parameter list + // (bin + scale configuration); struct-grouping deferred to pre-1.0 (#83). #[allow(clippy::too_many_arguments)] pub fn new( num_x_bins: i32, @@ -213,6 +215,8 @@ impl BinParams { /// 0, 0, num_angle_bins, num_scale_bins)` from /// `hough_similarity_voting.cpp:95-99`, where `numXBins == 0 && /// numYBins == 0` toggles `mAutoAdjustXYNumBins = true`. + // rationale: mirrors the C++ HoughSimilarityVoting init parameter list + // (bin + scale configuration); struct-grouping deferred to pre-1.0 (#83). #[allow(clippy::too_many_arguments)] pub fn new_auto_xy( num_angle_bins: i32, @@ -633,6 +637,8 @@ pub fn find_features( /// # Returns /// The bin index with the most votes (>= MIN_VOTES_THRESHOLD). /// Returns `Err(InvalidInput("insufficient votes for feature matching".into()))` if no bin reaches the threshold. +// rationale: numerical voting routine — flat signature matches the C++ +// source; struct-grouping deferred to a pre-1.0 pass (#83). #[allow(clippy::too_many_arguments)] pub fn find_hough_similarity( voting: &mut HoughSimilarityVoting, diff --git a/crates/core/src/kpm/ref_data_set.rs b/crates/core/src/kpm/ref_data_set.rs index aeb7bf4..59d3db2 100644 --- a/crates/core/src/kpm/ref_data_set.rs +++ b/crates/core/src/kpm/ref_data_set.rs @@ -244,6 +244,8 @@ impl KpmRefDataSet { /// * `page_no` — page number to assign to all features. /// * `image_no` — image number within the page. /// * `matcher` — backend that will extract FREAK features. + // rationale: public generator mirroring the C++ kpmGenRefDataSet parameter + // list; struct-grouping deferred to a pre-1.0 pass (#83). #[allow(clippy::too_many_arguments)] pub fn generate( image: &[u8], diff --git a/docs/design/issue-83-too-many-args-audit.md b/docs/design/issue-83-too-many-args-audit.md index 63ad50e..33627e0 100644 --- a/docs/design/issue-83-too-many-args-audit.md +++ b/docs/design/issue-83-too-many-args-audit.md @@ -78,9 +78,17 @@ Defer to a deliberate pass rather than obscure the math. ## Incremental plan -1. **This PR:** refactor `sample_grid`, `make_template`, `select_features`; - add rationale comments to the 13 public/SIMD `ar`/`ar2` allows. -2. **Follow-up:** `kpm/freak` public rationale comments + narrow the - `detector.rs` module-level allow. +1. **Done (PR #228):** refactored `sample_grid`, `make_template`, + `select_features`; added rationale comments to the public/SIMD `ar`/`ar2` + allows. +2. **Done:** `kpm/freak` + `ref_data_set` rationale comments — the + homography numerical routines, the Hough constructors / voting, and + `KpmRefDataSet::generate`. The `webarkit_cpp_*` FFI extern shim and the + `detector.rs` module-level allow are left as-is: both already carry an + explanatory rationale comment, and narrowing the 34-fn detector module + would be churn with no lint benefit. 3. **Pre-1.0 (maybe):** deliberate public-API restructure of the - C-faithful `ar`/`ar2` entry points into param structs (breaking). + C-faithful `ar`/`ar2` entry points into param structs (breaking). This is + the only remaining item; every current allow is now either removed or + carries a `// rationale:` note, so #83 can be closed and this restructure + tracked as its own pre-1.0 API task if desired.