feat(calib3d): implement camera undistortion, perspective warping, and fundamental matrix estimation (#76)

[kalwalt]

Pull Request: Implement Camera Undistortion and Perspective Warping (#76)

1. PR Summary

This PR implements camera undistortion maps, generic image remapping, perspective warping, and fundamental matrix estimation in pure Rust (purecv), utilizing Rayon-based parallelism and pulp SIMD dispatching.

• Impact: 10 files changed (1831 insertions, 2 deletions)
• Risk Level: 🟡 Medium (New math modules and optimizations, fully covered by tests)
• Estimated Review Time: ~15 minutes

---

2. Detailed Description

Key Features Implemented:

1. SIMD-Accelerated Remapping (src/core/simd.rs):

   • Added simd_remap_bilinear_row and simd_remap_nearest_row to the SimdElement trait.
   • Optimized row remapping loops for f32, f64, and u8 using pulp::Arch::new().dispatch(...) auto-vectorization when the simd feature is active.

2. Geometric Transformations (src/imgproc/geometric.rs):

   • Implemented remap using Rayon-based row parallelism (par_chunks_exact_mut), falling back to scalar loops when SIMD routines are not available. It correctly interpolates borders using border_interpolate.
   • Implemented warp_perspective with its own backward homography mapping to perform perspective transformations directly without intermediate map allocation.

3. Camera Undistortion (src/calib3d/undistort.rs):

   • Implemented init_undistort_rectify_map to compute undistortion and rectification maps (equivalent to OpenCV's initUndistortRectifyMap).
   • Supports radial lens distortion coefficients up to $k_6$, tangential coefficients ($p_1, p_2$), rectification rotation matrix $R$, and arbitrary camera matrices.

4. Epipolar Geometry (src/calib3d/fundamental.rs):

   • Implemented find_fundamental_mat supporting two estimation methods:
     • FundamentalMatMethod::FM_8POINT: Normalized 8-Point algorithm solving the linear system $Af = 0$ via SVD, enforcing the rank-2 constraint ($\sigma_3 = 0$), and de-normalizing.
     • FundamentalMatMethod::FM_RANSAC: Robust estimator selecting random samples of 8 correspondences, evaluating inliers using Sampson distance, and refitting the model using all found inliers.

5. Example Application (examples/rectification.rs):

   • A complete example program showing how to load butterfly.jpg, compute undistortion mapping, remap, warp perspective, and save the results.

---

3. Review Checklist

General

• Code follows project style guidelines (cargo fmt).
• Self-review completed.
• Comments added for complex mathematical logic.
• No debugging code left.

Code Quality & Parity

• Functions are focused and small where possible.
• Error handling is comprehensive and propagates via PureCvError.
• No unsafe blocks used.
• SIMD loops include a fallback scalar implementation.

Testing

• Added tests cover edge cases (e.g. invalid dimensions, empty points).
• All unit tests pass (cargo test).

---

4. Risk Assessment

Factor	Score	Details	Mitigation
Size	6/10	1831 lines added	Most additions are self-contained math submodules (fundamental.rs, undistort.rs, geometric.rs) accompanied by tests.
Complexity	7/10	SVD, Sampson distance, distortion projections	Verified using math-invariance tests (e.g., verifying epipolar constraint $x'^T F x = 0$ on RANSAC output).
Dependencies	1/10	No new external dependencies	Uses Rayon and pulp already present in purecv.
Security	1/10	Zero unsafe code	No memory safety risks.

---

5. Test Coverage

• Before: 260 unit tests, 30 doc-tests.
• After: 288 unit tests, 30 doc-tests.
• Coverage Change: +28 new unit tests covering:
  • Translation/identity warping in warp_perspective.
  • Nearest/bilinear interpolation correctness in remap.
  • Radial and tangential lens distortion mapping.
  • Robust RANSAC-based fundamental matrix estimation on noisy synthetic point correspondences.

---

6. Visual Aids

Coordinate Transformation Pipeline:

graph TD
    A[Undistorted Pixels u, v] --> B[Normalized Space x, y]
    B --> C[Apply Rotation R]
    C --> D[Radial Distortion k1-k6]
    C --> E[Tangential Distortion p1-p2]
    D & E --> F[Distorted Space x_dist, y_dist]
    F --> G[Project using Camera Matrix fx, fy, cx, cy]
    G --> H[Final Map Coordinates map1, map2]
    H --> I[Remap Source Image]

Loading

---

7. Size Recommendations

Although the PR is large (~1800 lines), it consists almost entirely of new, self-contained submodules (geometric.rs, undistort.rs, fundamental.rs) and their corresponding tests. We recommend merging this PR in its entirety since these modules are closely coupled for camera calibration/rectification.

---

8. Review Automation

• cargo fmt: Checked and formatted clean.
• cargo clippy: Run clean on all targets (warning-free).
• cargo test: Passed.