Skip to content

fix: visual-odometry robustness -- match() metric, points2F(), BundleAdjust - #96

Merged
petercorke merged 2 commits into
mainfrom
fix/visodom-robustness
Aug 16, 2026
Merged

petercorke merged 2 commits into
mainfrom
fix/visodom-robustness

Conversation

@petercorke

Copy link
Copy Markdown
Owner

Summary

Three related fixes found while porting RVC3-python's visodom.py example (real bridge-dataset stereo/temporal ORB tracking) end to end -- grouped together since they were all found via the same investigation, even though they touch unrelated functions.

match() metric default -- defaulted to metric="L2", which is close to meaningless for binary descriptors (ORB, BRISK, AKAZE -- uint8 arrays). This silently returned far fewer matches than the correct metric rather than raising an error: 5-12 matches out of 400x400 ORB features on real stereo pairs instead of 25-56 with the correct metric. Now auto-selects "hamming" for uint8 descriptors and "L2" otherwise (still overridable via metric=).

points2F() crash on estimation failure -- crashed with AttributeError: 'NoneType' object has no attribute 'ravel' whenever cv2.findFundamentalMat couldn't estimate F (too few or too degenerate correspondences) -- a real, reachable case on sparse real-world data. Now raises a clear ValueError, distinguishing "too few points" (checked before ever calling cv2, since the minimum per method is known: 7 for '7p', 8 otherwise) from "enough points but geometrically degenerate" (cv2 itself fails). Docstring also now documents residual, seed, and the actual **kwargs forwarded to cv2.findFundamentalMat (ransacReprojThreshold, confidence, maxIters) -- verified identical between OpenCV 4.10 and 5.0 by installing both into throwaway venvs and diffing the bound signature.

BundleAdjust.optimize() silent NaN -- computed err = sqrt(enew / self.g.ne) with self.g.ne == 0 when no landmark projections had been added (e.g. every candidate landmark got discarded upstream by the caller), producing a misleading "solved" result with a NaN RMS instead of any indication something was wrong. Now raises a clear ValueError up front.

Test plan

  • tests/test_image_point_features.py::test_match_orb_auto_metric (new) -- auto-detected metric agrees with explicit hamming for ORB, L2 for SIFT
  • tests/test_camera.py::test_points2F_too_few_points_raises, test_points2F_degenerate_points_raises (new) -- both distinct failure paths
  • tests/test_bundleadjust.py (new file -- there was no real BundleAdjust test coverage anywhere; tests/test_bundle_adjust.py turns out to test PBVS/IBVS, unrelated, likely a copy-paste mixup, flagged separately not fixed here) -- covers a normal two-view convergence case and the empty-graph ValueError
  • Full test suite: 945 passed, 71 skipped, no regressions
  • Manually verified end-to-end against RVC3-python's RVC3/examples/visodom.py (the full worked example) -- previously crashed on frame 1 of 251, now runs to completion (194 frames fully bundle-adjusted, 53 gracefully skipped via the new error handling, 3 stereo-frame skips)

🤖 Generated with Claude Code

…Adjust

Three related fixes found while porting RVC3-python's visodom.py
example (real bridge-dataset stereo/temporal ORB tracking) end to end:

- match() defaulted to metric="L2", which is close to meaningless for
  binary descriptors (ORB, BRISK, AKAZE -- uint8 arrays). This silently
  returned far fewer matches than the correct metric rather than
  raising an error, e.g. 5-12 matches out of 400x400 ORB features on
  real stereo pairs instead of 25-56 with the correct metric. Now
  auto-selects "hamming" for uint8 descriptors and "L2" otherwise
  (still overridable via metric=).

- points2F() crashed with AttributeError: 'NoneType' object has no
  attribute 'ravel' whenever cv2.findFundamentalMat couldn't estimate
  F (too few or too degenerate correspondences) -- a real, reachable
  case on sparse real-world data, not just a hypothetical. Now raises
  a clear ValueError, distinguishing "too few points" (checked before
  ever calling cv2, since the minimum per method is known) from
  "enough points but geometrically degenerate" (cv2 itself fails).
  Docstring also now documents residual, seed, and the actual kwargs
  forwarded to cv2.findFundamentalMat (ransacReprojThreshold,
  confidence, maxIters) -- verified identical between OpenCV 4.10 and
  5.0 by installing both into throwaway venvs and diffing the bound
  signature.

- BundleAdjust.optimize() silently computed err = sqrt(enew / self.g.ne)
  with self.g.ne == 0 when no landmark projections had been added
  (e.g. every candidate landmark got discarded upstream), producing a
  misleading "solved" result with a NaN RMS instead of any indication
  something was wrong. Now raises a clear ValueError up front.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@codacy-production

Copy link
Copy Markdown

Not up to standards ⛔

🔴 Issues 1 high

Alerts:
⚠ 1 issue (≤ 0 issues of at least minor severity)

Results:
1 new issue

Category Results
ErrorProne 1 high

View in Codacy

🟢 Metrics 0 complexity · 0 duplication

Metric Results
Complexity 0
Duplication 0

View in Codacy

NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.

Follow-up to the previous commit's first pass at documenting the
cv2.findFundamentalMat kwargs. Empirically verified (not just going by
the C++ doc's wording) that:

- ransacReprojThreshold is RANSAC-only -- LMedS produces an identical
  inlier mask regardless of its value.
- confidence and maxIters apply to either method='ransac' or
  method='lmeds' (confirmed confidence= changes LMedS's own result).
  The previous "'ransac'/'lmeds'" docstring shorthand read ambiguously,
  as if both had to be selected together, which method's own type
  (a single str) makes impossible -- reworded to be explicit that
  it's either one, individually.
- A combined "ransac+lmeds" method isn't a real OpenCV feature worth
  exposing: OR-ing FM_RANSAC|FM_LMEDS together doesn't error, but
  silently reduces to plain LMedS's result -- an artifact of internal
  bit-flag check ordering, not a documented hybrid mode. Noted in the
  docstring so nobody adds this to method= later thinking it's real.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@petercorke
petercorke merged commit 406bbcf into main Aug 16, 2026
29 of 30 checks passed
@petercorke
petercorke deleted the fix/visodom-robustness branch October 3, 2026 14:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant