Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions src/machinevisiontoolbox/BundleAdjust.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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
Expand Down
53 changes: 51 additions & 2 deletions src/machinevisiontoolbox/Camera.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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)
Expand All @@ -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
Expand Down
15 changes: 13 additions & 2 deletions src/machinevisiontoolbox/ImagePointFeatures.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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,
Expand Down
52 changes: 52 additions & 0 deletions tests/test_bundleadjust.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
#!/usr/bin/env python

import unittest

import numpy as np

Check warning on line 5 in tests/test_bundleadjust.py

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

tests/test_bundleadjust.py#L5

'numpy as np' imported but unused (F401)
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()
25 changes: 25 additions & 0 deletions tests/test_camera.py
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
26 changes: 26 additions & 0 deletions tests/test_image_point_features.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down