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..9be5c404 100644 --- a/src/machinevisiontoolbox/Camera.py +++ b/src/machinevisiontoolbox/Camera.py @@ -2703,8 +2703,41 @@ 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``. + ``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 + 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 +2771,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 +2785,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)