From 8691847df58cc3cf003838436f7d94c59d5ae609 Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Sun, 16 Aug 2026 10:42:41 +1000 Subject: [PATCH 1/2] fix: visual-odometry robustness -- match() metric, points2F(), BundleAdjust 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 --- src/machinevisiontoolbox/BundleAdjust.py | 9 ++++ src/machinevisiontoolbox/Camera.py | 36 ++++++++++++- .../ImagePointFeatures.py | 15 +++++- tests/test_bundleadjust.py | 52 +++++++++++++++++++ tests/test_camera.py | 25 +++++++++ tests/test_image_point_features.py | 26 ++++++++++ 6 files changed, 159 insertions(+), 4 deletions(-) create mode 100644 tests/test_bundleadjust.py diff --git a/src/machinevisiontoolbox/BundleAdjust.py b/src/machinevisiontoolbox/BundleAdjust.py index d822dcae..67b41f28 100644 --- a/src/machinevisiontoolbox/BundleAdjust.py +++ b/src/machinevisiontoolbox/BundleAdjust.py @@ -562,6 +562,8 @@ def optimize( :type iterations: int, optional :param verbose: show Levenberg-Marquadt status, defaults to False :type verbose: bool, optional + :raises ValueError: no landmark projections have been added to + the graph :return: optimized state vector :rtype: ndarray(N) @@ -578,6 +580,13 @@ def optimize( self.update_index() + if self.g.ne == 0: + raise ValueError( + "no landmark projections in the graph -- nothing to " + "optimize (add_projection() was never called, or every " + "candidate landmark was discarded)" + ) + if x is None: x = self.getstate() x0 = x diff --git a/src/machinevisiontoolbox/Camera.py b/src/machinevisiontoolbox/Camera.py index 9b6007ad..f5273e23 100644 --- a/src/machinevisiontoolbox/Camera.py +++ b/src/machinevisiontoolbox/Camera.py @@ -2703,8 +2703,24 @@ def points2F( :type p2: ndarray(2,N) :param method: algorithm '7p', '8p' [default], 'ransac', 'lmeds' :type method: str, optional - :param kwargs: optional arguments as required for ransac', 'lmeds' - methods + :param residual: also return the reprojection residual, defaults to True + :type residual: bool, optional + :param seed: seed the RNG used by 'ransac'/'lmeds' for repeatable + results, defaults to None (not seeded) + :type seed: int, optional + :param kwargs: passed through to ``cv2.findFundamentalMat`` -- for + 'ransac': ``ransacReprojThreshold`` (float, max distance in + pixels from a point to its epipolar line for the point to + count as an inlier) and ``maxIters`` (int, max robust-method + iterations); for 'ransac'/'lmeds': ``confidence`` (float in + (0,1), desired probability the estimate is correct). Same + parameter set on OpenCV 4 and 5, verified empirically + 2026-08-16. + :type kwargs: dict, optional + :raises ValueError: fewer than the minimum number of point + correspondences for ``method`` (7 for '7p', 8 otherwise), or + the points are too degenerate (eg. coplanar, collinear) for + ``cv2.findFundamentalMat`` to estimate F from :return: fundamental matrix and residual :rtype: ndarray(3,3), float @@ -2738,6 +2754,12 @@ def points2F( "ransac": cv2.FM_RANSAC, "lmeds": cv2.FM_LMEDS, } + min_points = 7 if method == "7p" else 8 + if p1.shape[1] < min_points: + raise ValueError( + f"points2F() needs at least {min_points} point correspondences " + f"for method={method!r}, got {p1.shape[1]}" + ) if seed is not None: cv2.setRNGSeed(seed) @@ -2746,6 +2768,16 @@ def points2F( points1=p1.T, points2=p2.T, method=points2F_dict[method], **kwargs ) + if F is None or mask is None: + # already know p1.shape[1] >= min_points (checked above), so a + # failure here means the points themselves are degenerate (eg. + # coplanar, collinear), not a raw-count problem + raise ValueError( + f"cv2.findFundamentalMat could not estimate F from " + f"{p1.shape[1]} point correspondences using method={method!r} " + "-- points are likely too degenerate (eg. coplanar, collinear)" + ) + mask = mask.ravel().astype(bool) # add various return values diff --git a/src/machinevisiontoolbox/ImagePointFeatures.py b/src/machinevisiontoolbox/ImagePointFeatures.py index fd98eb0b..5579b7e1 100644 --- a/src/machinevisiontoolbox/ImagePointFeatures.py +++ b/src/machinevisiontoolbox/ImagePointFeatures.py @@ -669,7 +669,7 @@ def match( other: "BaseFeature2D", ratio: float = 0.75, crosscheck: bool = False, - metric: str = "L2", + metric: str | None = None, sort: bool = True, top: int | None = None, thresh: float | None = None, @@ -683,7 +683,9 @@ def match( :type ratio: float, optional :param crosscheck: perform left-right cross check, defaults to False :type crosscheck: bool, optional - :param metric: distance metric, one of: 'L1', 'L2' [default], 'hamming', 'hamming2' + :param metric: distance metric, one of: 'L1', 'L2', 'hamming', 'hamming2'. + Defaults to ``None``, which auto-selects 'hamming' for binary + descriptors (eg. ORB, BRISK, AKAZE) and 'L2' otherwise (eg. SIFT). :type metric: str, optional :param sort: sort features by strength, defaults to True :type sort: bool, optional @@ -694,6 +696,12 @@ def match( Return a match object that contains pairs of putative corresponding points. If ``crosscheck`` is True the ratio test is disabled + .. note:: Binary descriptors (eg. ORB, BRISK, AKAZE) are ``uint8`` + arrays, for which 'L2' distance is close to meaningless -- it + will silently return very few matches rather than raising an + error, which is why this is auto-selected rather than left for + the caller to always remember. + Example: .. runblock:: pycon @@ -720,6 +728,9 @@ def match( # sorting # return + if metric is None: + metric = "hamming" if self.descriptor.dtype == np.uint8 else "L2" + metricdict = { "L1": cv2.NORM_L1, "L2": cv2.NORM_L2, diff --git a/tests/test_bundleadjust.py b/tests/test_bundleadjust.py new file mode 100644 index 00000000..6506ae39 --- /dev/null +++ b/tests/test_bundleadjust.py @@ -0,0 +1,52 @@ +#!/usr/bin/env python + +import unittest + +import numpy as np +from spatialmath import SE3 + +from machinevisiontoolbox import BundleAdjust, CentralCamera, mkcube + + +class TestBundleAdjust(unittest.TestCase): + def test_optimize(self): + """A two-view problem with a deliberately wrong initial pose guess + for the second view must converge back towards the true pose.""" + cam = CentralCamera.Default() + P = mkcube(0.2, pose=SE3.Tz(1.0)) + + pose0 = SE3() + pose1_true = SE3.Tx(0.1) + + p0 = cam.project_point(P, pose=pose0) + p1 = cam.project_point(P, pose=pose1_true) + + ba = BundleAdjust(cam) + v0 = ba.add_view(pose0, fixed=True) + v1 = ba.add_view(SE3()) # wrong initial guess, true pose is Tx(0.1) + + for k in range(P.shape[1]): + landmark = ba.add_landmark(P[:, k]) + ba.add_projection(v0, landmark, p0[:, k]) + ba.add_projection(v1, landmark, p1[:, k]) + + x_new, err = ba.optimize(iterations=20) + self.assertLess(err, 1.0) + + def test_optimize_empty_graph_raises(self): + """optimize() on a graph with no landmark projections must raise a + clear error rather than silently reporting err=nan (previously + err = sqrt(enew / self.g.ne) divided by zero with no landmarks + added, eg. every candidate landmark got discarded upstream).""" + cam = CentralCamera.Default() + ba = BundleAdjust(cam) + ba.add_view(SE3(), fixed=True) + ba.add_view(SE3()) + + with self.assertRaises(ValueError): + ba.optimize(iterations=5) + + +# ----------------------------------------------------------------------- # +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_camera.py b/tests/test_camera.py index 14495766..9d51693c 100644 --- a/tests/test_camera.py +++ b/tests/test_camera.py @@ -290,6 +290,31 @@ def test_plucker(self): line = c.ray(p) self.assertTrue(line.contains(P)) + def test_points2F_too_few_points_raises(self): + """Fewer than the minimum required correspondences must raise a + clear ValueError before ever calling cv2.findFundamentalMat -- + regression test for a bare AttributeError: + 'NoneType' object has no attribute 'ravel' when cv2 silently + returned (None, None)""" + p1 = np.array([[10, 20, 30], [10, 20, 30]], dtype=float) + p2 = np.array([[11, 21, 31], [11, 21, 31]], dtype=float) + + with self.assertRaises(ValueError) as cm: + CentralCamera.points2F(p1, p2, method="ransac") + self.assertIn("at least 8", str(cm.exception)) + + def test_points2F_degenerate_points_raises(self): + """Enough points (>= 8), but collinear -- cv2.findFundamentalMat + itself fails (returns None), which must raise a clear ValueError + distinct from the too-few-points case above""" + t = np.linspace(0, 1, 10) + p1 = np.vstack([10 + 5 * t, 10 + 5 * t]) + p2 = np.vstack([11 + 5 * t, 11 + 5 * t]) + + with self.assertRaises(ValueError) as cm: + CentralCamera.points2F(p1, p2, method="ransac") + self.assertIn("degenerate", str(cm.exception)) + def test_camera_attributes_access(self): """Test accessing various camera attributes""" c = CentralCamera(f=0.015, rho=10e-6, imagesize=[1280, 1024], pp=(640, 512)) diff --git a/tests/test_image_point_features.py b/tests/test_image_point_features.py index a572874d..25711095 100644 --- a/tests/test_image_point_features.py +++ b/tests/test_image_point_features.py @@ -161,6 +161,32 @@ def test_orb(self): except: pass + def test_match_orb_auto_metric(self): + """match() must auto-select hamming distance for binary (ORB) + descriptors -- regression test for the L2 default giving + near-meaningless distances for binary descriptors, which silently + yields far fewer matches than the correct metric rather than + raising an error""" + img1 = Image.Read("eiffel-1.png", mono=True) + img2 = Image.Read("eiffel-2.png", mono=True) + orb1 = img1.ORB(nfeatures=200) + orb2 = img2.ORB(nfeatures=200) + + m_auto = orb1.match(orb2) + m_hamming = orb1.match(orb2, metric="hamming") + m_l2 = orb1.match(orb2, metric="L2") + + # auto-detected metric must agree with explicit hamming, not L2 + self.assertEqual(len(m_auto), len(m_hamming)) + self.assertGreater(len(m_auto), len(m_l2)) + + # float descriptors (SIFT) must still default to L2 + sift1 = img1.SIFT() + sift2 = img2.SIFT() + m_sift_auto = sift1.match(sift2) + m_sift_l2 = sift1.match(sift2, metric="L2") + self.assertEqual(len(m_sift_auto), len(m_sift_l2)) + def test_corners(self): """Test corner detection""" img = Image.Read("monalisa.png", mono=True) From 6b10d6401925564163568a09e1e504c99eec99fa Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Sun, 16 Aug 2026 10:55:49 +1000 Subject: [PATCH 2/2] docs: points2F() kwargs -- correct which params apply to which method 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 --- src/machinevisiontoolbox/Camera.py | 33 ++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/src/machinevisiontoolbox/Camera.py b/src/machinevisiontoolbox/Camera.py index f5273e23..9be5c404 100644 --- a/src/machinevisiontoolbox/Camera.py +++ b/src/machinevisiontoolbox/Camera.py @@ -2708,14 +2708,31 @@ def points2F( :param seed: seed the RNG used by 'ransac'/'lmeds' for repeatable results, defaults to None (not seeded) :type seed: int, optional - :param kwargs: passed through to ``cv2.findFundamentalMat`` -- for - 'ransac': ``ransacReprojThreshold`` (float, max distance in - pixels from a point to its epipolar line for the point to - count as an inlier) and ``maxIters`` (int, max robust-method - iterations); for 'ransac'/'lmeds': ``confidence`` (float in - (0,1), desired probability the estimate is correct). Same - parameter set on OpenCV 4 and 5, verified empirically - 2026-08-16. + :param kwargs: passed through to ``cv2.findFundamentalMat``. + ``ransacReprojThreshold`` (float, defaults to 3.0) applies only + when ``method='ransac'`` -- max distance in pixels from a point + to its epipolar line for the point to still count as an inlier; + ``method='lmeds'`` ignores it entirely (verified empirically -- + identical result regardless of value). ``confidence`` (float in + (0,1), defaults to 0.99) and ``maxIters`` (int, defaults to + 1000) apply to either ``method='ransac'`` or ``method='lmeds'`` + -- ``method`` only ever selects one algorithm at a time (a + combined "ransac+lmeds" method isn't a real OpenCV feature; + verified empirically that OR-ing the two method flags together + doesn't error, but silently reduces to plain LMedS -- an + implementation accident, not a documented hybrid mode). + Defaults verified empirically 2026-08-16 (identical inlier + masks with/without them explicit, same RNG seed) -- not + otherwise documented by the ``cv2`` Python bindings. Same + parameter set and defaults on OpenCV 4.10 and 5.0. + + .. warning:: ``maxIters`` only works when ``ransacReprojThreshold`` + and ``confidence`` are *also* given explicitly -- passing + only ``maxIters=`` hits a ``cv2.findFundamentalMat`` + overload-resolution failure (a confusing low-level OpenCV + error, not a clear Python one), since the 3-argument + overload this method otherwise uses has no ``maxIters`` + parameter at all. :type kwargs: dict, optional :raises ValueError: fewer than the minimum number of point correspondences for ``method`` (7 for '7p', 8 otherwise), or