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

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

machinevisiontoolbox/ImageCore.py

@@ -20,6 +20,7 @@ from spatialmath.base import islistof, isscalar
 
 # from numpy.lib.arraysetops import isin
 from machinevisiontoolbox.base import (
+    DTYPE_ALIASES,
     draw_box,
     draw_circle,
     draw_labelbox,
@@ -98,8 +99,13 @@ class Image(
         :type copy: bool, optional
         :param size: new size for the image, defaults to None
         :type size: tuple, optional
-        :param dtype: data type for image, defaults to same type as ``image``
-        :type dtype: str or NumPy dtype, optional
+        :param dtype: data type for image; ``None`` [default] auto-detects (any
+            floating input becomes ``float32``; integer input becomes the
+            smallest unsigned/signed integer type that holds all its values);
+            ``True`` keeps ``image``'s own dtype as-is; ``False`` raises
+            ``ValueError``; otherwise a NumPy dtype string (``"uint8"``,
+            ``"float32"``, ...) or NumPy type. |dtype_aliases|
+        :type dtype: str, NumPy dtype, bool, or None, optional
         :param name: name of image, defaults to None
         :type name: str, optional
         :param id: numeric id of image, typically a sequence number, defaults to None
@@ -301,13 +307,22 @@ class Image(
             )
 
         # if dtype is not given, determine the appropriate type for the data
+        dtype_given = dtype is not None
         dtype = self._infer_dtype(image, dtype)
 
         if binary:
             image = image > 0
 
-        # change type of array to the determined dtype
-        if dtype is not None:
+        # Change type of array to the determined dtype -- unless the caller
+        # also passed convert()-only options (eg. maxintval) alongside an
+        # explicit dtype=, in which case defer the cast to convert() below.
+        # convert()'s int_image()/float_image() know how to *scale* a value
+        # using maxintval; a bare .astype() here would instead silently
+        # truncate (eg. uint16 0..4095 -> uint8 keeps only the low byte,
+        # producing a corrupted "bottom byte" image instead of the intended
+        # rescaled 0..255).
+        defer_dtype_to_convert = dtype_given and bool(kwargs)
+        if dtype is not None and not defer_dtype_to_convert:
             image = image.astype(dtype, copy=False)
 
         self.name = name
@@ -324,7 +339,7 @@ class Image(
             image = image[:, :, 0]  # squeeze out singleton plane
 
         if kwargs:
-            image = convert(image, **kwargs)
+            image = convert(image, dtype=dtype if defer_dtype_to_convert else None, **kwargs)
 
         # assign the image to the object, copying if requested
         if copy:
@@ -381,6 +396,8 @@ class Image(
             raise ValueError("bad dtype argument passed to Image constructor")
         else:
             # dtype is given, convert to a NumPy dtype
+            if isinstance(dtype, str):
+                dtype = DTYPE_ALIASES.get(dtype, dtype)
             try:
                 dtype = np.dtype(dtype)
             except TypeError:
@@ -475,6 +492,37 @@ class Image(
         """Iterate over image planes."""
         return self.planes()
 
+    def __array__(self, dtype: Dtype | None = None, copy: bool | None = None) -> np.ndarray:
+        """
+        Convert to a plain NumPy array
+
+        :param dtype: dtype of the returned array, defaults to the image's own dtype
+        :type dtype: numpy dtype, optional
+        :param copy: force a copy of the underlying data, defaults to None
+        :type copy: bool, optional
+        :return: image pixel data
+        :rtype: ndarray(H,W) or ndarray(H,W,3)
+
+        Implements the NumPy array protocol, used by ``np.asarray(img)`` and by
+        any NumPy/SciPy/Matplotlib function that isn't ufunc- or array-function-
+        aware (those instead go through :meth:`__array_ufunc__` /
+        :meth:`__array_function__`) and calls ``np.asarray()`` internally on
+        whatever it's given. Without this, such a call would silently coerce an
+        :class:`Image` into a useless 0-d object array instead of its pixel data.
+
+        Returns the same read-only view as the :attr:`array` property unless a
+        dtype conversion or an explicit copy is requested, either of which
+        produces a new, independent (writeable) array.
+
+        :seealso: :attr:`array`
+        """
+        arr = self.array
+        if dtype is not None:
+            arr = arr.astype(dtype)
+        if copy:
+            arr = arr.copy()
+        return arr
+
     def __array_ufunc__(self, ufunc, method: str, *inputs, **kwargs):
         """
         Support NumPy ufunc calls on image data.
@@ -1927,6 +1975,9 @@ class Image(
 
         :param dtype: Numpy data type
         :type dtype: str or NumPy dtype
+
+        |dtype_aliases|
+
         :return: image
         :rtype: :class:`Image`
 
@@ -1949,8 +2000,9 @@ class Image(
         :seealso: :meth:`astype` :meth:`to_int` :meth:`to_float`
         """
         # convert image to different type, does rescaling
-        # as just changes type
-        dtype = np.dtype(dtype)  # convert to dtype if it's a string
+        # as just changes type. array_as() and the constructor both
+        # resolve dtype (including the short-name aliases) themselves,
+        # so just pass it through unchanged rather than resolving twice.
         return self.__class__(self.array_as(dtype), dtype=dtype)
 
     def astype(self, dtype: Dtype) -> "Image":
@@ -1959,6 +2011,9 @@ class Image(
 
         :param dtype: Numpy data type
         :type dtype: str or NumPy dtype
+
+        |dtype_aliases|
+
         :return: image
         :rtype: :class:`Image`
 
@@ -1979,6 +2034,8 @@ class Image(
 
         :seealso: :meth:`to`
         """
+        if isinstance(dtype, str):
+            dtype = DTYPE_ALIASES.get(dtype, dtype)
         return self.__class__(self._A.astype(dtype), dtype=dtype)
 
     # ---- NumPy array access ---- #
@@ -2254,7 +2311,9 @@ class Image(
         Convert Image to NumPy array of specified type
 
         :param dtype: data type of the output array
-        :type dtype: str or np.dtype
+        :type dtype: str or np.dtype, optional
+
+        |dtype_aliases|
         :return: NumPy array with specified type
         :rtype: ndarray(H,W) or ndarray(H,W,P)
 
@@ -2296,6 +2355,8 @@ class Image(
         if dtype is None:
             return self._A
         else:
+            if isinstance(dtype, str):
+                dtype = DTYPE_ALIASES.get(dtype, dtype)
             dtype = np.dtype(dtype)  # convert to dtype if it's a string
             if np.issubdtype(dtype, np.integer) or np.issubdtype(dtype, np.bool_):
                 return int_image(self._A, dtype)

machinevisiontoolbox/ImageFiducials.py

@@ -429,14 +429,22 @@ class FiducialCollection:
         # -------------------------------------------------------------------
         ids = ids.reshape(-1) if ids is not None else ids
 
-        # filter tags by ID
-        cornerss = [
-            corners.T.squeeze()
-            for corners, id in zip(cornerss, ids)
-            if id in self._ids
-        ]
-        ids = [id for corners, id in zip(cornerss, ids) if id in self._ids]
-        # ids = np.reshape(ids, (-1, 1))
+        # filter tags by ID, keeping each marker's corners and id together in
+        # a single pass so the two lists cannot get out of step (detectMarkers
+        # returns ids=None when it finds nothing)
+        matches = (
+            []
+            if ids is None
+            else [
+                (corners.T.squeeze(), id)
+                for corners, id in zip(cornerss, ids)
+                if id in self._ids
+            ]
+        )
+        if not matches:
+            raise ValueError("no markers belonging to this board were detected")
+        cornerss = [corners for corners, _ in matches]
+        ids = [id for _, id in matches]
 
         # match the markers to the board
         # print(f"{len(ids)} markers found")

machinevisiontoolbox/ImageIO.py

@@ -267,6 +267,14 @@ class ImageIOMixin(_ImageBase if TYPE_CHECKING else object):
                 # map tag number to tag name
                 exif[TAGS[tag]] = value
 
+        # Camera-specific tags (FocalLength, ExposureTime, FNumber,
+        # ISOSpeedRatings, LensModel, ...) live in a separate "Exif" sub-IFD
+        # that Image.getexif() does not flatten into the top-level dict --
+        # 0x8769 is the fixed EXIF-spec tag id for the pointer to it.
+        for tag, value in meta.get_ifd(0x8769).items():
+            if tag in TAGS:
+                exif[TAGS[tag]] = value
+
         if key is None:
             return exif
         else:

machinevisiontoolbox/ImagePointFeatures.py

@@ -669,7 +669,7 @@ class BaseFeature2D:
         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 @@ class BaseFeature2D:
         :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 @@ class BaseFeature2D:
         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 @@ class BaseFeature2D:
         # 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,

machinevisiontoolbox/ImageWholeFeatures.py

@@ -285,7 +285,7 @@ class ImageWholeFeaturesMixin(_ImageBase if TYPE_CHECKING else object):
         :seealso: :meth:`stats`
         """
 
-        stats = self._stats
+        stats = self.stats
         if self.iscolor and self.colororder is not None:
             colororder = self.colororder
             for k in sorted(stats.keys(), key=lambda x: colororder[x]):
@@ -1210,7 +1210,9 @@ class Histogram:
 
     def plot(
         self,
-        type: str = "frequency",
+        type: Literal[
+            "frequency", "pdf", "probability", "cf", "cumulative", "cdf", "normalized", "ncdf"
+        ] = "frequency",
         block: bool = False,
         filled: bool | None = None,
         stats: bool = True,
@@ -1227,8 +1229,9 @@ class Histogram:
         """
         Plot histogram
 
-        :param type: histogram type, one of: 'frequency' [default], 'cdf', 'ncdf'
-        :type type: str, optional
+        :param type: histogram type, one of: 'frequency' [default], 'pdf'/'probability',
+            'cf'/'cumulative', 'cdf'/'normalized'; 'ncdf' is accepted as a deprecated
+            alias for 'cdf'
         :param block: hold plot, defaults to False
         :type block: bool, optional
         :param filled: use a filled stairs plot, defaults to True for frequency plot, False for
@@ -1258,7 +1261,9 @@ class Histogram:
 
         Plots the histogram using Matplotlib.  For a color image, the histograms of each
         plane are plotted separately.  The ``type`` option selects the type of histogram
-        to plot: ``frequency``, ``cdf`` or ``ncdf`` (normalized cumulative in the range 0 to 1).
+        to plot: ``frequency``, ``pdf``/``probability``, ``cf``/``cumulative``, or
+        ``cdf``/``normalized`` (normalized cumulative, range 0 to 1).  ``ncdf`` is
+        accepted as a deprecated alias for ``cdf``.
 
         The ``style`` option selects the style for plotting multiple planes:
 
@@ -1342,6 +1347,14 @@ class Histogram:
             if filled is None:
                 filled = bar
 
+        if type == "ncdf":
+            warnings.warn(
+                "Deprecated in 2.0.0: use type='cdf' instead of type='ncdf'.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            type = "cdf"
+
         if type not in ("frequency", "pdf"):
             stats = False  # only show stats for frequency and pdf plot