machinevision-toolbox-python 2.3.0__py3-none-any.whl → 2.4.0__py3-none-any.whl

{machinevision_toolbox_python-2.3.0.dist-info → machinevision_toolbox_python-2.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: machinevision-toolbox-python
-Version: 2.3.0
+Version: 2.4.0
 Summary: Object-oriented machine vision for Python.
 Project-URL: Homepage, https://github.com/petercorke/machinevision-toolbox-python
 Project-URL: Bug Tracker, https://github.com/pypa/sampleproject/issues
@@ -23,8 +23,8 @@ Requires-Dist: ansitable
 Requires-Dist: matplotlib
 Requires-Dist: mvtb-data
 Requires-Dist: numpy
-Requires-Dist: opencv-contrib-python<5.0.0
-Requires-Dist: opencv-python<5.0.0
+Requires-Dist: opencv-contrib-python<6.0.0,>=4.5
+Requires-Dist: opencv-python<6.0.0,>=4.5
 Requires-Dist: pgraph-python
 Requires-Dist: pillow
 Requires-Dist: requests
@@ -35,7 +35,7 @@ Provides-Extra: all
 Requires-Dist: ipympl; extra == 'all'
 Requires-Dist: ipython; extra == 'all'
 Requires-Dist: ipywidgets; extra == 'all'
-Requires-Dist: open3d-python; extra == 'all'
+Requires-Dist: open3d; (python_version < '3.13') and extra == 'all'
 Requires-Dist: pygments; extra == 'all'
 Requires-Dist: pytesseract; extra == 'all'
 Requires-Dist: rosbags; extra == 'all'
@@ -64,7 +64,7 @@ Requires-Dist: ipywidgets; extra == 'jupyter'
 Provides-Extra: ocr
 Requires-Dist: pytesseract; extra == 'ocr'
 Provides-Extra: open3d
-Requires-Dist: open3d-python; extra == 'open3d'
+Requires-Dist: open3d; (python_version < '3.13') and extra == 'open3d'
 Provides-Extra: ros
 Requires-Dist: rosbags; extra == 'ros'
 Requires-Dist: roslibpy; extra == 'ros'

{machinevision_toolbox_python-2.3.0.dist-info → machinevision_toolbox_python-2.4.0.dist-info}/RECORD

@@ -1,25 +1,25 @@
-machinevisiontoolbox/BagOfWords.py,sha256=CYNvYkVhE_aDijV7v3gIxXHkN60QD3MNu9-Xh97q5Y4,19036
-machinevisiontoolbox/BundleAdjust.py,sha256=Fjp1eWe78DwZfvu9tuiuMYlCGmv8fqwF2kMFT1_GW4w,37076
-machinevisiontoolbox/Camera.py,sha256=YRG5s6rvlI9vJX2C3X2mawcTBofknjU8MiRc7atJv3o,139142
+machinevisiontoolbox/BagOfWords.py,sha256=dfl-9v_CJmXyf2LUQnGUQBw7QWiQSw1qe8jN3fjE_30,19808
+machinevisiontoolbox/BundleAdjust.py,sha256=07i0dxuKiLHthUWsLw0DU6hxvRXpMTZMSbipP9YVsYc,37498
+machinevisiontoolbox/Camera.py,sha256=fHqCIyyF_QchRv-luZaz5nocxkcL_7c-n4rQSAh4qOk,143841
 machinevisiontoolbox/ImageBlobs.py,sha256=TsXaJpqUN1WrPg0zHRmLQvP3wUBxcHHUBt9qDggjVnE,89447
 machinevisiontoolbox/ImageColor.py,sha256=fueFYDNlvqSJPgcKsG5v2wBxaW7mYNa6OA-_rK-UJK0,17577
-machinevisiontoolbox/ImageConstants.py,sha256=R0sc9z8sbraruI6qkixLso6fTgxUAC5cQMSw4ms9m2k,38774
-machinevisiontoolbox/ImageCore.py,sha256=ufDI7ynOGRwM8TSSDEdM4LMQxBhclc0ve976tsprBW8,140594
+machinevisiontoolbox/ImageConstants.py,sha256=TGzo62YR2_CFozena3ReZdTnuRHY_spQlgsMJoDa8RE,39154
+machinevisiontoolbox/ImageCore.py,sha256=pQSJ3x-hmsTWvar0FpkGn4ZHi6fncy9d4We4fOr_ktA,143486
 machinevisiontoolbox/ImageFiducials.py,sha256=wrCevhrkgdHzBMMRoDqADZE9OOD7L6nQCd3UDA_e3rU,26903
-machinevisiontoolbox/ImageIO.py,sha256=MFUwjxdQ8oGttGMgzon9xOom-IGsVUFkiEWDrVEEgMs,27019
+machinevisiontoolbox/ImageIO.py,sha256=BA-szxEJy6LSeq4DdBF845wmy3Nq2s_YjRko_dteWXA,27434
 machinevisiontoolbox/ImageLineFeatures.py,sha256=Kq0rCzPER2eB9MhEBNn6hAHpGY-G_WPZd657RmuRryA,10855
 machinevisiontoolbox/ImageMorph.py,sha256=WioUD2Jr9Ejnk7Let4Vf3iTFz5DhMkZ7l_ZBCbvgl4U,30237
 machinevisiontoolbox/ImageMultiview.py,sha256=swzNsxX39dijPdPa-a4LFOl7T7liTcQeP7NJf5ODGQU,15605
-machinevisiontoolbox/ImagePointFeatures.py,sha256=HYgBUs931OOYsM9kx4p_zFU5vAc9dOJsNPuUyTKxoY4,78209
+machinevisiontoolbox/ImagePointFeatures.py,sha256=mf1GN37ZOvZRMhX25WAP9Twrymgk8yn1e7XXHkoq5-k,78807
 machinevisiontoolbox/ImageProcessing.py,sha256=HBR6cbTlgfAdOiqXU8DPSFKZQXWTBIVufCyRaifky7g,51669
 machinevisiontoolbox/ImageRegionFeatures.py,sha256=nZAdKFSpxmMZKwlbF13MOxBIUwXvPvDtIxNJUyp7pvg,16092
 machinevisiontoolbox/ImageReshape.py,sha256=F8eNrJ1to6d5jrIJeT1D2RqX-7EnARrQ03UGUCvljXg,50204
 machinevisiontoolbox/ImageSpatial.py,sha256=nzgScDprv7UQXhKcOps80gKjx4Ve6y498lCRm21sEtw,55622
 machinevisiontoolbox/ImageTensor.py,sha256=ohNbThdsQid2AQbDIHaCoxj00tpRggFWv0TTpIHAJQk,9006
-machinevisiontoolbox/ImageWholeFeatures.py,sha256=wpD03wsGu314Ff-nkDqrbCVGgPGobuQItnCZ04Xkwfo,62901
-machinevisiontoolbox/Kernel.py,sha256=VWobkVDlgMvQDo1eoC0fSLxAn2SGu2pQG13QaUIrRNE,21501
-machinevisiontoolbox/PointCloud.py,sha256=FJP-gFmd16ePFfBQ2Y-Tdu6SSw_HyEhtDjNeLyknJFY,25239
-machinevisiontoolbox/Sources.py,sha256=ZWH4o4ffT-qaJuRJOYT7YFLQV4WmzwzuH5J7ZWwzHvQ,152710
+machinevisiontoolbox/ImageWholeFeatures.py,sha256=eLOZdG2OTyHUjkk6W2Wmp9mYOwqEFvfxQcFmGZgwX1s,63457
+machinevisiontoolbox/Kernel.py,sha256=erTDpPsB38bNHvtBfijjf-9zIW57YM-Bg2ltlFCu6Mg,22607
+machinevisiontoolbox/PointCloud.py,sha256=uwa-Y6aIV3_c6iIrfR60VkiCfPst6cSZntEXPhe2z2s,25819
+machinevisiontoolbox/Sources.py,sha256=Odr3ome26j306JNYdak86RcutWT46chQwnSPsHNTScU,152656
 machinevisiontoolbox/VisualServo.py,sha256=2q_szKZo51McduLUMnN8-O6foLyLAR-o0h10-UDWKPY,60947
 machinevisiontoolbox/__init__.py,sha256=ocn82vw6o7pvUKSfebBwPKyKTiK-jMR8FK3SEtpDFVM,3871
 machinevisiontoolbox/_image_typing.py,sha256=FjdzZpuxEH9nBrj8gb-tkwUZDjpCNH92sQS3meemCVE,7286
@@ -27,21 +27,21 @@ machinevisiontoolbox/camera_derivatives.py,sha256=ysaP8PvgeBpFf8e37AmYQTW28SiFBK
 machinevisiontoolbox/decorators.py,sha256=6wEoLFozK2RFcGb9QrLy2bAw4sjkbm_2q3PpnIS9Rtk,2623
 machinevisiontoolbox/fiducial.py,sha256=syC7iIz95nYBTr_njo4ZzLXOyAdAIqoAZq_wRVhyUHQ,1374
 machinevisiontoolbox/mvtb_types.py,sha256=YD2P9mDXhz75GgC7Cyeer8luBpSHckkrLZ0GDVvGOnE,728
-machinevisiontoolbox/base/__init__.py,sha256=DxtRJJF6vnY2S1n33xJmXTBf504RCkctmoyKwBW4pc4,1645
-machinevisiontoolbox/base/color.py,sha256=F1eBcjyQPFV1uiTkeOe6UtBf_2V4s5wkQH-0egh7Ru0,58432
+machinevisiontoolbox/base/__init__.py,sha256=RvRL9e_FMqBordxwHDqX44YGN38AD4m4fHfkEXslNK4,1666
+machinevisiontoolbox/base/color.py,sha256=-8bjXwkgfRamNs-jZnFsbqpGKR_dN4rCrLqxrsUYjN8,59492
 machinevisiontoolbox/base/data.py,sha256=PF1HyrYQ-EDR-0heHMG1oDxs63AtQshNWbUvN8GOKsY,6130
 machinevisiontoolbox/base/findpeaks.py,sha256=Ag0UIw2CPVioB356Pvj-_k_wjxMODGpsW7qdkt6UvEs,11251
 machinevisiontoolbox/base/graphics.py,sha256=R8hbf_jK3mvq_dEoATxkjcbxUJvoSMovNbrk3W4BQe8,36974
-machinevisiontoolbox/base/imageio.py,sha256=QwiYa0XS2E1ZyOIPqGU72RFaPZQZAzKO47w_FBouKV8,54053
+machinevisiontoolbox/base/imageio.py,sha256=uQceV4CDDhXrWMKgB4hhu3DxeJjEOKE2QJ8fatd4-MA,55592
 machinevisiontoolbox/base/meshgrid.py,sha256=Bo2GIlk0tRT2CV5sP5I9i-mZy-6c3BPozLOuOiEVHT0,3162
 machinevisiontoolbox/base/shapes.py,sha256=d-DmB_9iEsHyC6AT6lv2LMHvb-PMqHTXtehqMKk3aRQ,11430
-machinevisiontoolbox/base/types.py,sha256=AEiyEsmX5ljifC_PldaOcJnZRDyUSF3kwRbAihNDslQ,5055
+machinevisiontoolbox/base/types.py,sha256=AkeDiJOh1nUmfhcfE-ZS_cISIPYIcSEJxzzWKkvkgTw,5687
 machinevisiontoolbox/base/version.py,sha256=uSKKfk9fOu5XF_21Kzfh3N111U-39mobNwiRyelOqcU,976
 machinevisiontoolbox/bin/_bintools.py,sha256=WwzyOqXEv4T-TB2GMBym4pGU2NACM5ACDCg7exGRl0I,1918
 machinevisiontoolbox/bin/_iminteractive.py,sha256=9fh2QcuO9RFfO9uGA05MePbe6cUtlh-F19z2zbG4pLA,17063
 machinevisiontoolbox/bin/bagtool.py,sha256=b-Ap2AynpXe0FtcydyfkXIgHDaumAkGBJgDZ6lgdZBU,12359
 machinevisiontoolbox/bin/imtool.py,sha256=la9m9LuMnthJzXxjMRWqGY_l7rJUZS5wiVgZsw84SO4,7897
-machinevisiontoolbox/bin/mvtbtool.py,sha256=NuVm2lLCJSUT4_RvlSplqeuUb0duDxAoupL1UIrjjuQ,13785
+machinevisiontoolbox/bin/mvtbtool.py,sha256=7-fhz11-TIUCTPeDlpCxnpM7rONWcHRBTi80b537-nY,13871
 machinevisiontoolbox/bin/ocrtool.py,sha256=HtkbLnjij40oy83nBtZlbJSFJ2pn7lcQAmOifvCLw0I,4719
 machinevisiontoolbox/bin/tagtool.py,sha256=io-NCIMdMc5zIFYMa6U2ITTv2T-Q8Y0bwh_pB1qZ4IQ,8523
 machinevisiontoolbox/blocks/__init__.py,sha256=EsdfK2WxYLSo0SA5HSmlgsivLT1kDnoH9v-RTBDnWwc,142
@@ -51,8 +51,8 @@ machinevisiontoolbox/blocks/Icons/camera.png,sha256=CGcTB_llMoucN-rfnP6ZP_7AfE_9
 machinevisiontoolbox/blocks/Icons/estpose_p.png,sha256=1XrwL4OkotGWMwKmhnar3tt8cQWUdZiO7PxXD354T-E,4320
 machinevisiontoolbox/blocks/Icons/imageplane.png,sha256=34FYQMzkq6foxvRU8pn0KkcHxpHRvsJRJSYKfNu13Eg,3902
 machinevisiontoolbox/blocks/Icons/visjac_p.png,sha256=8X023l-C9Y5DfAN8wCdWYjSjq6wp1vRzuZ85sUbwxv8,3819
-machinevision_toolbox_python-2.3.0.dist-info/METADATA,sha256=GIbwk-9OjmGJcOWpGeEDlp1tuH0qTk-9YUtHFLdc9Nw,21733
-machinevision_toolbox_python-2.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-machinevision_toolbox_python-2.3.0.dist-info/entry_points.txt,sha256=R0sRa7JufKCG1VPkgo5KcL7j7pW4-E0Ch2Og4AqmXg4,310
-machinevision_toolbox_python-2.3.0.dist-info/licenses/LICENSE,sha256=niCzY_CzbIMKuUZlUkGimjrKp0vkLAtcwFmoSuSKrdw,1068
-machinevision_toolbox_python-2.3.0.dist-info/RECORD,,
+machinevision_toolbox_python-2.4.0.dist-info/METADATA,sha256=LQ2UVCMI5WioCEYdVK_NQnCgjhjI-4JBSChJ2e6cZDE,21791
+machinevision_toolbox_python-2.4.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+machinevision_toolbox_python-2.4.0.dist-info/entry_points.txt,sha256=R0sRa7JufKCG1VPkgo5KcL7j7pW4-E0Ch2Og4AqmXg4,310
+machinevision_toolbox_python-2.4.0.dist-info/licenses/LICENSE,sha256=niCzY_CzbIMKuUZlUkGimjrKp0vkLAtcwFmoSuSKrdw,1068
+machinevision_toolbox_python-2.4.0.dist-info/RECORD,,

machinevisiontoolbox/BagOfWords.py

@@ -58,6 +58,13 @@ class BagOfWords:
         of image features is assigned labels from the ``.centroids`` any with a
         label greater that ``.nstopwords`` is a stop word and can be discarded.
 
+        .. note:: Removing stop words can leave a remaining word that never
+            occurs in any image, giving it an inverse document frequency (idf)
+            of ``inf`` (``log(N / 0)``). This is harmless -- every place idf is
+            used to compute a word-frequency vector, the corresponding word
+            count is also always zero there, so the ``0 * inf`` result is
+            ``nan`` and gets replaced with 0 before the vector is returned.
+
         :reference:
             - Video Google: a text retrieval approach to object matching in videos
               J.Sivic and A.Zisserman,
@@ -139,7 +146,12 @@ class BagOfWords:
         # total number of occurrences of word i
         # multiple occurrences in the one image count only as one
         ni = (W > 0).sum(axis=1)
-        idf = np.log(N / ni)
+        # a word that never occurs in any image (ni=0, possible after
+        # stopword removal) gives idf=inf here; harmless since nid is
+        # always 0 at that same position below, so 0*inf->nan, already
+        # suppressed by the invalid="ignore" there.
+        with np.errstate(divide="ignore"):
+            idf = np.log(N / ni)
 
         M = []
 

machinevisiontoolbox/BundleAdjust.py

@@ -405,7 +405,8 @@ if pgraph_installed:
 
             :seealso: :meth:`add_view` :meth:`add_landmark`
             """
-            assert len(uv) == 2, "uv must be a 2-vector"
+            if len(uv) != 2:
+                raise ValueError("uv must be a 2-vector")
 
             edge = Observation(viewpoint, landmark, uv.flatten())  # create edge object
             e = viewpoint.connect(landmark, edge=edge)  # connect nodes with it
@@ -562,6 +563,8 @@ if pgraph_installed:
             :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 +581,13 @@ if pgraph_installed:
 
             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

machinevisiontoolbox/Camera.py

@@ -350,7 +350,8 @@ class CameraBase(ABC):
 
         :seealso: :meth:`nv` :meth:`width` :meth:`imagesize`
         """
-        assert self._imagesize is not None, "imagesize not set"
+        if self._imagesize is None:
+            raise ValueError("imagesize not set")
         return self._imagesize[0]
 
     @property
@@ -370,7 +371,8 @@ class CameraBase(ABC):
 
         :seealso: :meth:`nu` :meth:`height`  :meth:`imagesize`
         """
-        assert self._imagesize is not None, "imagesize not set"
+        if self._imagesize is None:
+            raise ValueError("imagesize not set")
         return self._imagesize[1]
 
     @property
@@ -390,7 +392,8 @@ class CameraBase(ABC):
 
         :seealso: :meth:`nu` :meth:`height`
         """
-        assert self._imagesize is not None, "imagesize not set"
+        if self._imagesize is None:
+            raise ValueError("imagesize not set")
         return self._imagesize[0]
 
     @property
@@ -410,7 +413,8 @@ class CameraBase(ABC):
 
         :seealso: :meth:`nv` :meth:`width`
         """
-        assert self._imagesize is not None, "imagesize not set"
+        if self._imagesize is None:
+            raise ValueError("imagesize not set")
         return self._imagesize[1]
 
     @property
@@ -1152,7 +1156,7 @@ class CameraBase(ABC):
         """
         Plot 3D camera icon in world view (base method)
 
-        :param pose: camera pose
+        :param pose: camera pose, required when called unbound (see below)
         :type pose: :class:`~spatialmath.pose3d.SE3`
         :param scale: scale factor, defaults to 1
         :type scale: float
@@ -1170,6 +1174,8 @@ class CameraBase(ABC):
         :type projection: str, optional
         :param ax: axes to draw in, defaults to current 3D axes
         :type ax: :class:`~matplotlib.Axes3D`, optional
+        :raises ValueError: called unbound (eg. ``CentralCamera.plot(...)``)
+            without a ``pose``
         :return: axes drawn into
         :rtype: :class:`~matplotlib.Axes3D`
 
@@ -1177,8 +1183,19 @@ class CameraBase(ABC):
         plot.  Two icons are supported: the traditional frustum, and a
         simplistic camera comprising a box and cylinder.
 
-        .. note:: If ``pose`` is not given it defaults to the pose of the
-            instance.
+        This method can be called two ways:
+
+        - **Bound**, ``camera.plot(...)`` -- draws an icon for ``camera``.
+          ``pose`` defaults to the instance's own pose if not given.
+        - **Unbound**, ``CentralCamera.plot(pose=..., ...)`` -- called on
+          the class itself, with no camera instance involved (``self`` is
+          ``None``). Useful for drawing icons at a set of poses that don't
+          correspond to any single camera instance -- e.g. plotting the
+          calibration frames returned by :meth:`images2C`. ``pose`` is
+          required in this form.
+
+        .. note:: If ``pose`` is not given, it defaults to the pose of
+            ``self`` -- this only applies to the bound form.
         """
 
         # if (fig is None) and (ax is None):
@@ -1195,6 +1212,11 @@ class CameraBase(ABC):
         ax = smb.axes_logic(ax, 3, projection=projection)
 
         if pose is None:
+            if self is None:
+                raise ValueError(
+                    "pose is required when plot() is called unbound, eg. "
+                    "CentralCamera.plot(pose=...)"
+                )
             pose = self.pose
 
         # Matplotlib >=3.10 can raise while autoscaling ragged 3D line
@@ -1216,26 +1238,27 @@ class CameraBase(ABC):
         try:
             # draw camera-like object:
             if shape == "frustum":
-                self._plot_frustum(ax, pose, scale, alpha)
+                CameraBase._plot_frustum(ax, pose, scale, alpha)
 
             elif shape == "camera":
-                self._plot_camera_icon(ax, pose, scale, solid, color, alpha, label)
+                CameraBase._plot_camera_icon(ax, pose, scale, solid, color, alpha, label)
 
             if frame is True:
-                self.pose.plot(
+                pose.plot(
                     length=scale * 1.5,
                     style="line",
                     color=color,
                     flo=(0.07, 0, -0.01),
                 )
             elif frame is not False:
-                self.pose.plot(**frame)
+                pose.plot(**frame)
         finally:
             ax.add_collection3d = _orig_add_collection3d
 
         return ax
 
-    def _plot_frustum(self, ax: Axes, pose: SE3, scale: float, alpha: float) -> None:
+    @staticmethod
+    def _plot_frustum(ax: Axes, pose: SE3, scale: float, alpha: float) -> None:
         """Draw the ``shape="frustum"`` camera icon into ``ax``."""
         # TODO make this kwargs or optional inputs
         # side colors:
@@ -1279,8 +1302,8 @@ class CameraBase(ABC):
         poly = Poly3DCollection(points, facecolors=["r", "g", "r", "y"], alpha=alpha)
         ax.add_collection3d(poly)
 
+    @staticmethod
     def _plot_camera_icon(
-        self,
         ax: Axes,
         pose: SE3,
         scale: float,
@@ -2684,8 +2707,41 @@ class CentralCamera(CameraBase):
         :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
 
@@ -2719,13 +2775,40 @@ class CentralCamera(CameraBase):
             "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)
 
-        F, mask = cv2.findFundamentalMat(
-            points1=p1.T, points2=p2.T, method=points2F_dict[method], **kwargs
-        )
+        try:
+            F, mask = cv2.findFundamentalMat(
+                points1=p1.T, points2=p2.T, method=points2F_dict[method], **kwargs
+            )
+        except cv2.error as e:
+            # on some degenerate point configurations cv2.findFundamentalMat
+            # raises a raw C++ assertion (eg. a Mat rowRange error) instead
+            # of returning None -- same underlying cause as the F is None
+            # case below, just surfaced differently by OpenCV
+            raise ValueError(
+                f"cv2.findFundamentalMat could not estimate F from "
+                f"{p1.shape[1]} point correspondences using method={method!r} "
+                f"-- points are likely too degenerate (eg. coplanar, collinear): {e}"
+            ) from e
+
+        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)
 

machinevisiontoolbox/ImageConstants.py

@@ -23,7 +23,7 @@ from spatialmath import base as smb
 from spatialmath.base import islistof, isscalar
 
 # from numpy.lib.arraysetops import isin
-from machinevisiontoolbox.base import float_image, int_image, name2color
+from machinevisiontoolbox.base import DTYPE_ALIASES, float_image, int_image, name2color
 from machinevisiontoolbox.base.imageio import convert, idisp, iread, iwrite
 from machinevisiontoolbox.Kernel import Kernel
 from machinevisiontoolbox.mvtb_types import Dtype
@@ -110,6 +110,9 @@ def _resolve_pattern_options(
         else:
             dtype = default_dtype
 
+    if isinstance(dtype, str):
+        dtype = DTYPE_ALIASES.get(dtype, dtype)
+
     if colororder is None and like is not None and like.iscolor:
         colororder = like.colororder_str.replace(":", "")
 
@@ -121,7 +124,7 @@ def _pattern_image(cls, image: np.ndarray, colororder: str | None):
         image = np.repeat(
             image[..., np.newaxis], len(cls.colordict(colororder)), axis=2
         )
-    return cls(image, colororder=colororder)
+    return cls(image, colororder=colororder, dtype=True)
 
 
 class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
@@ -145,6 +148,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type colororder: str
         :param dtype: NumPy datatype, defaults to 'uint8'
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param like: template image supplying default ``size`` and ``colororder``
             when those are not given explicitly
         :type like: :class:`Image` or None, optional
@@ -179,7 +184,7 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         )
 
         shape = _getshape(cls, None, None, colororder, size)
-        return cls(np.zeros(shape, dtype=dtype), colororder=colororder)
+        return cls(np.zeros(shape, dtype=dtype), colororder=colororder, dtype=True)
 
     @classmethod
     def Constant(
@@ -202,6 +207,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type colororder: str
         :param dtype: NumPy datatype, defaults to 'uint8'
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param like: template image supplying default ``size``, ``dtype`` and
             ``colororder`` when those are not given explicitly
         :type like: :class:`Image` or None, optional
@@ -258,11 +265,11 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
             planes = []
             for bg in value:
                 planes.append(np.full(shape[:2], bg, dtype=dtype))
-            return cls(np.stack(planes, axis=2), colororder=colororder)
+            return cls(np.stack(planes, axis=2), colororder=colororder, dtype=True)
 
         else:
             # scalar
-            return cls(np.full(shape, value, dtype=dtype))
+            return cls(np.full(shape, value, dtype=dtype), dtype=True)
 
     @classmethod
     def String(
@@ -406,6 +413,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type colororder: str
         :param dtype: NumPy datatype, defaults to 'uint8'
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param maxval: maximum value for random values, defaults to None
         :type maxval: same as ``dtype``, optional
         :param pdf: probability density function for pixel values, defaults to None
@@ -535,7 +544,7 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
             else:
                 raise ValueError("pdf must be a 1D or 2D array")
 
-        return cls(im, colororder=colororder)
+        return cls(im, colororder=colororder, dtype=True)
 
     @classmethod
     def Squares(
@@ -562,6 +571,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type bg: int, optional
         :param dtype: NumPy datatype, defaults to 'uint8'
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param colororder: color plane names for the output image, defaults to None
         :type colororder: str or None, optional
         :param like: template image supplying default ``size``, ``dtype`` and
@@ -654,6 +665,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type bg: int, optional
         :param dtype: NumPy datatype, defaults to 'uint8'
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param colororder: color plane names for the output image, defaults to None
         :type colororder: str or None, optional
         :param like: template image supplying default ``size``, ``dtype`` and
@@ -746,6 +759,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type cycles: int, optional
         :param dtype: NumPy datatype, defaults to 'float32'
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param colororder: color plane names for the output image, defaults to None
         :type colororder: str or None, optional
         :param like: template image supplying default ``size``, ``dtype`` and
@@ -842,6 +857,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type cycles: int, optional
         :param dtype: NumPy datatype, defaults to 'float32'
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param colororder: color plane names for the output image, defaults to None
         :type colororder: str or None, optional
         :param like: template image supplying default ``size``, ``dtype`` and
@@ -922,6 +939,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type square: int, optional
         :param dtype: image data type, defaults to "uint8"
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param colororder: color plane names for the output image, defaults to None
         :type colororder: str or None, optional
         :param like: template image supplying default ``size``, ``dtype`` and
@@ -1012,6 +1031,8 @@ class ImageConstantsMixin(_ImageBase if TYPE_CHECKING else object):
         :type shift: int, optional
         :param dtype: image data type, defaults to "uint8"
         :type dtype: str or NumPy dtype, optional
+
+        |dtype_aliases|
         :param colororder: color plane names for the output image, defaults to None
         :type colororder: str or None, optional
         :param like: template image supplying default ``size``, ``dtype`` and