machinevision-toolbox-python 2.0.1__py3-none-any.whl → 2.2.0__py3-none-any.whl

machinevisiontoolbox/ImageCore.py

@@ -301,6 +301,57 @@ class Image(
             )
 
         # if dtype is not given, determine the appropriate type for the data
+        dtype = self._infer_dtype(image, dtype)
+
+        if binary:
+            image = image > 0
+
+        # change type of array to the determined dtype
+        if dtype is not None:
+            image = image.astype(dtype, copy=False)
+
+        self.name = name
+
+        color_dict = Image.colororder2dict(colororder)
+
+        image = self._reshape_to_size(image, size)
+
+        if image.ndim not in (2, 3):
+            raise ValueError(
+                "bad ndarray passed to Image constructor: must be 2D or 3D array"
+            )
+        if image.ndim == 3 and image.shape[2] == 1:
+            image = image[:, :, 0]  # squeeze out singleton plane
+
+        if kwargs:
+            image = convert(image, **kwargs)
+
+        # assign the image to the object, copying if requested
+        if copy:
+            self._A = image.copy()
+        else:
+            self._A = image
+
+        # final check that colororder length matches number of planes
+        if colororder is not None:
+            if len(color_dict) != self.nplanes:
+                raise ValueError("colororder length does not match number of planes")
+
+        if colororder is None:
+            if self.nplanes == 3:
+                self.colororder = "RGB"
+                # warnings.warn("defaulting color to RGB")
+        else:
+            self.colororder = color_dict
+
+        self._stats = None
+
+        self.name = name
+
+    @staticmethod
+    def _infer_dtype(image: np.ndarray, dtype: Dtype | bool | None) -> np.dtype | None:
+        """Determine the pixel dtype for the constructor when ``dtype`` isn't
+        given explicitly, or resolve/validate it when it is."""
         if dtype is None:
             # no type given, automatically choose it
             if np.issubdtype(image.dtype, np.floating):
@@ -335,17 +386,12 @@ class Image(
             except TypeError:
                 raise ValueError("bad dtype argument passed to Image constructor")
 
-        if binary:
-            image = image > 0
-
-        # change type of array to the determined dtype
-        if dtype is not None:
-            image = image.astype(dtype, copy=False)
-
-        self.name = name
-
-        color_dict = Image.colororder2dict(colororder)
+        return dtype
 
+    def _reshape_to_size(
+        self, image: np.ndarray, size: tuple | list | None
+    ) -> np.ndarray:
+        """Reshape 1D/2D pixel data per the constructor's ``size=`` argument."""
         if isinstance(size, self.__class__):
             # size is an Image instance, ignore the size/shape and use the image's shape
             size = size.size
@@ -354,16 +400,7 @@ class Image(
         if size is not None:
             newsize = [size[1], size[0]]
 
-            if self.colororder is not None:
-                nplanes = len(color_dict)
-
-                if len(size) == 3:
-                    if nplanes != size[2]:
-                        raise ValueError(
-                            "colororder length does not match number of planes in size"
-                        )
-                newsize.append(nplanes)
-            elif len(size) == 3:
+            if len(size) == 3:
                 newsize.append(size[2])
 
             if image.ndim == 1:
@@ -420,37 +457,7 @@ class Image(
 
                     image = image.reshape(*newsize)
 
-        if image.ndim not in (2, 3):
-            raise ValueError(
-                "bad ndarray passed to Image constructor: must be 2D or 3D array"
-            )
-        if image.ndim == 3 and image.shape[2] == 1:
-            image = image[:, :, 0]  # squeeze out singleton plane
-
-        if kwargs:
-            image = convert(image, **kwargs)
-
-        # assign the image to the object, copying if requested
-        if copy:
-            self._A = image.copy()
-        else:
-            self._A = image
-
-        # final check that colororder length matches number of planes
-        if colororder is not None:
-            if len(color_dict) != self.nplanes:
-                raise ValueError("colororder length does not match number of planes")
-
-        if colororder is None:
-            if self.nplanes == 3:
-                self.colororder = "RGB"
-                # warnings.warn("defaulting color to RGB")
-        else:
-            self.colororder = color_dict
-
-        self._stats = None
-
-        self.name = name
+        return image
 
     @staticmethod
     def _plane_stats(plane: np.ndarray) -> dict[str, float | int]:
@@ -2711,50 +2718,6 @@ class Image(
         :seealso: :meth:`red` :meth:`green` :meth:`blue` :meth:`plane` :meth:`roi` :meth:`pixel`
         """
 
-        def fixdims(
-            out: np.ndarray, shape: tuple[int, ...], keys: tuple[Any, ...]
-        ) -> np.ndarray:
-            # deal with the fact that some of the keys may have reduced the
-            # dimensionality of the array, eg. a slice of span 0 or 1, or an integer
-            # key.
-
-            # shape: (nrows, ncols, nplanes)  in NumPy order
-            # key: (rowspec, colspec, planespec) in NumPy order
-
-            def lenkey(key: int | slice, max: int) -> int:
-                # compute the span of a particular key
-                if isinstance(key, int):
-                    # int key has a span on 1
-                    return 1
-                elif isinstance(key, slice):
-                    # slice key has a span depending on the slice and the corresponding
-                    # array dimension. we have to essentially replicate the logic of
-                    # slice() here.
-                    start = key.start if key.start is not None else 0
-                    stop = key.stop if key.stop is not None else max
-                    step = key.step if key.step is not None else 1
-                    n = stop - start
-                    if n < step:
-                        return 1
-                    else:
-                        return n // step
-
-            dims = list(shape)
-
-            if len(shape) == 2:
-                dims = [lenkey(keys[0], shape[0]), lenkey(keys[1], shape[1])]
-            elif len(shape) == 3:
-                dims = [
-                    lenkey(keys[0], shape[0]),
-                    lenkey(keys[1], shape[1]),
-                    lenkey(keys[2], shape[2]),
-                ]
-                # ignore loss of color dimension
-                if dims[2] == 1:
-                    dims = dims[:2]
-
-            return out.reshape(tuple(dims))
-
         if (
             isinstance(keys, tuple)
             and len(keys) == 2
@@ -2791,7 +2754,7 @@ class Image(
                 out = self._A[keys]
 
                 if out.ndim < 3:
-                    out = fixdims(out, self._A.shape, keys)
+                    out = self._fixdims(out, self._A.shape, keys)
 
             else:
                 # greyscale image
@@ -2804,7 +2767,7 @@ class Image(
                 out = self._A[keys]
 
                 if out.ndim < 2:
-                    out = fixdims(out, self._A.shape, keys)
+                    out = self._fixdims(out, self._A.shape, keys)
 
             # a singleton plane dimensions is a grey scale image
             if out.ndim == 3 and out.shape[2] == 1:
@@ -2825,6 +2788,51 @@ class Image(
         else:
             raise ValueError("invalid slice")
 
+    @staticmethod
+    def _lenkey(key: int | slice, max: int) -> int:
+        """Span of a single ``__getitem__`` key component (int or slice)."""
+        if isinstance(key, int):
+            # int key has a span on 1
+            return 1
+        elif isinstance(key, slice):
+            # slice key has a span depending on the slice and the corresponding
+            # array dimension. we have to essentially replicate the logic of
+            # slice() here.
+            start = key.start if key.start is not None else 0
+            stop = key.stop if key.stop is not None else max
+            step = key.step if key.step is not None else 1
+            n = stop - start
+            if n < step:
+                return 1
+            else:
+                return n // step
+
+    @classmethod
+    def _fixdims(
+        cls, out: np.ndarray, shape: tuple[int, ...], keys: tuple[Any, ...]
+    ) -> np.ndarray:
+        """Restore dimensionality lost by ``__getitem__`` keys that collapse
+        an axis (eg. a slice of span 0 or 1, or an integer key).
+
+        ``shape``: (nrows, ncols, nplanes) in NumPy order.
+        ``keys``: (rowspec, colspec, planespec) in NumPy order.
+        """
+        dims = list(shape)
+
+        if len(shape) == 2:
+            dims = [cls._lenkey(keys[0], shape[0]), cls._lenkey(keys[1], shape[1])]
+        elif len(shape) == 3:
+            dims = [
+                cls._lenkey(keys[0], shape[0]),
+                cls._lenkey(keys[1], shape[1]),
+                cls._lenkey(keys[2], shape[2]),
+            ]
+            # ignore loss of color dimension
+            if dims[2] == 1:
+                dims = dims[:2]
+
+        return out.reshape(tuple(dims))
+
     def pixel(self, u: int, v: int) -> int | float | np.ndarray:
         """
         Return pixel value

machinevisiontoolbox/ImageFiducials.py

@@ -133,20 +133,53 @@ class ImageFiducialsMixin(_ImageBase if TYPE_CHECKING else object):
         # corners is a list of marker corners, one element per tag
         #  each element is 1x4x2 matrix holding corner coordinates
         #
-        # ids is ndarray of shape (N,1) holding the tag ids
+        # --- OpenCV 4/5 compat -------------------------------------------
+        # ids is (N,1) on OpenCV 4 but a flat (N,) on OpenCV 5 (verified
+        # empirically 2026-08-03). Flatten so each `id` below is always a
+        # plain scalar -- on OpenCV 5, id[0] on an already-0-d element
+        # raises IndexError: invalid index to scalar variable.
+        # -------------------------------------------------------------------
 
         fiducials = []
         if ids is None or len(ids) == 0:
             return fiducials  # no markers found
+        ids = ids.reshape(-1)
         if K is not None and side is not None:
-            rvecs, tvecs, p3d = cv2.aruco.estimatePoseSingleMarkers(
-                corners=cornerss, markerLength=side, cameraMatrix=K, distCoeffs=None
+            # --- OpenCV 4/5 compat ---------------------------------------
+            # cv2.aruco.estimatePoseSingleMarkers was removed entirely in
+            # OpenCV 5 -- not moved/renamed, hasattr(cv2.aruco,
+            # "estimatePoseSingleMarkers") is False in a real 5.0.0
+            # install. Replaced with the per-marker cv2.solvePnP +
+            # SOLVEPNP_IPPE_SQUARE call that OpenCV's own migration notes
+            # recommend for planar square markers. The object points use
+            # the same convention (clockwise from top-left, Z out of the
+            # marker) the old function used internally, so this works
+            # unchanged on OpenCV 4 too -- no version branching needed.
+            # Verified empirically 2026-08-03.
+            # -----------------------------------------------------------------
+            half = side / 2
+            obj_pts = np.array(
+                [
+                    [-half, half, 0],
+                    [half, half, 0],
+                    [half, -half, 0],
+                    [-half, -half, 0],
+                ],
+                dtype=np.float32,
             )
-            for id, rvec, tvec, corners in zip(ids, rvecs, tvecs, cornerss):
-                fiducials.append(Fiducial(id[0], corners[0].T, K, rvec, tvec, p3d))
+            p3d = obj_pts.reshape(4, 1, 3)
+            for id, corners in zip(ids, cornerss):
+                _, rvec, tvec = cv2.solvePnP(
+                    obj_pts, corners[0], K, None, flags=cv2.SOLVEPNP_IPPE_SQUARE
+                )
+                fiducials.append(
+                    Fiducial(
+                        id, corners[0].T, K, rvec.reshape(1, 3), tvec.reshape(1, 3), p3d
+                    )
+                )
         else:
             for id, corners in zip(ids, cornerss):
-                fiducials.append(Fiducial(id[0], corners[0].T))
+                fiducials.append(Fiducial(id, corners[0].T))
 
         return fiducials
 
@@ -386,16 +419,23 @@ class FiducialCollection:
         cornerss, ids, rejected = detector.detectMarkers(image=image.mono()._A)
 
         # corners is a list of ndarray(1,4,2) of marker corners
-        # ids is ndarray of shape (N,1) holding the tag ids
         # rejected is a list of rejected corners from tags whose inner code is incorrectly coded
+        #
+        # --- OpenCV 4/5 compat -------------------------------------------
+        # ids is (N,1) on OpenCV 4 but a flat (N,) on OpenCV 5 (verified
+        # empirically 2026-08-03). Flatten so each `id` below is always a
+        # plain scalar -- on OpenCV 5, id[0] on an already-0-d element
+        # raises IndexError: invalid index to scalar variable.
+        # -------------------------------------------------------------------
+        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[0] in self._ids
+            if id in self._ids
         ]
-        ids = [id[0] for corners, id in zip(cornerss, ids) if id[0] in self._ids]
+        ids = [id for corners, id in zip(cornerss, ids) if id in self._ids]
         # ids = np.reshape(ids, (-1, 1))
 
         # match the markers to the board
@@ -587,9 +627,21 @@ class ArUcoBoard(FiducialCollection):
         :return: 3D object points and 2D image points
         :rtype: ndarray(M,1,3), ndarray(M,1,2), where M is the number of corners found (multiple of 4)
         """
-        return self._board.matchImagePoints(
+        objPoints, imgPoints = self._board.matchImagePoints(
             [corners.T.reshape(1, 4, 2) for corners in cornerss], np.c_[ids]
         )
+        # --- OpenCV 4/5 compat -------------------------------------------
+        # cv2.aruco.Board.matchImagePoints returns (M,1,3)/(M,1,2) on
+        # OpenCV 4 but a true (M,3)/(M,2) on OpenCV 5 (verified
+        # empirically 2026-08-03). Normalize back to the documented
+        # (M,1,3)/(M,1,2) shape so this method's return contract is
+        # stable regardless of the installed OpenCV version.
+        # -------------------------------------------------------------------
+        if objPoints.ndim == 2:
+            objPoints = objPoints[:, np.newaxis, :]
+        if imgPoints.ndim == 2:
+            imgPoints = imgPoints[:, np.newaxis, :]
+        return objPoints, imgPoints
 
     def chart(self, filename: str | None = None, dpi: int = 100) -> Image | None:
         """Write ArUco chart to a file

machinevisiontoolbox/ImageIO.py

@@ -178,10 +178,14 @@ class ImageIOMixin(_ImageBase if TYPE_CHECKING else object):
                 self.domain[1][0],
             ]
 
+        if self.colororder_str is not None:
+            colororder = self.colororder_str.replace(":", "")
+        else:
+            colororder = None
         return idisp(
             self._A,
             title=display_title,
-            colororder="RGB" if self.isrgb else "BGR",
+            colororder=colororder,
             **kwargs,
         )
 

machinevisiontoolbox/ImageLineFeatures.py

@@ -156,8 +156,16 @@ class HoughFeature:
         )
         if lines is None:
             return np.zeros((0, 4))
-        else:
+        # --- OpenCV 4/5 compat -----------------------------------------
+        # OpenCV 5's HoughLinesP returns a true (N,4) array; OpenCV 4
+        # returns (N,1,4) (the old std::vector<T>-wrapping convention).
+        # Verified empirically 2026-08-03 (opencv-contrib-python 5.0.0.93
+        # vs 4.13.0.92). Drop the singleton middle dim only if present.
+        # -----------------------------------------------------------------
+        elif lines.ndim == 3 and lines.shape[1] == 1:
             return lines[:, 0, :]
+        else:
+            return lines
 
     def plot_lines(self, lines: np.ndarray, *args: Any, **kwargs: Any) -> None:
         r"""

machinevisiontoolbox/ImagePointFeatures.py

@@ -3,7 +3,7 @@ Detection and matching of keypoint and descriptor features (SIFT, ORB, etc.) in
 """
 
 import math
-from typing import Any, Iterator
+from typing import TYPE_CHECKING, Any, Iterator
 
 import cv2
 import matplotlib.lines as mlines
@@ -21,13 +21,15 @@ from machinevisiontoolbox.base import (
     name2color,
     safe_plt_show,
 )
-from machinevisiontoolbox._image_typing import _ImageBase
 from machinevisiontoolbox.decorators import (
     array_result,
     array_result2,
     scalar_result,
 )
 
+if TYPE_CHECKING:
+    from machinevisiontoolbox._image_typing import _ImageBase
+
 # TODO, either subclass SIFTFeature(BaseFeature2D) or just use BaseFeature2D
 # directly
 
@@ -280,7 +282,7 @@ class BaseFeature2D:
 
         try:  # Sort features into grid
             nw, nh = nbins
-        except:
+        except (TypeError, ValueError):
             nw = nbins
             nh = nbins
 
@@ -294,8 +296,8 @@ class BaseFeature2D:
         bins = np.zeros((nh, nw), dtype="int")
 
         for f in self:
-            ix = f.p[0] // binwidth
-            iy = f.p[1] // binheight
+            ix = int(f.p[0].item() // binwidth)
+            iy = int(f.p[1].item() // binheight)
 
             if bins[iy, ix] < nfeat:
                 keep.append(f)
@@ -2012,7 +2014,26 @@ class LUCIDFeature(BaseFeature2D):
     pass
 
 
-class ImagePointFeaturesMixin(_ImageBase):
+# --- OpenCV 4/5 compat -------------------------------------------------
+# OpenCV 5 dropped BRISK/AKAZE/KAZE from the main cv2 namespace; they now
+# live under cv2.xfeatures2d (verified empirically 2026-08-02, opencv-
+# contrib-python 5.0.0.93 vs 4.13.0.92 -- no OPENCV_ENABLE_NONFREE build
+# flag needed for these, unlike SURF). SIFT/ORB are unaffected, stay in
+# main cv2 in both versions. Resolve by attribute existence, not a
+# version-string check, so this keeps working if a future OpenCV release
+# moves things back or a build has both.
+def _resolve_feature_create(name: str) -> Any:
+    if hasattr(cv2, f"{name}_create"):
+        return getattr(cv2, f"{name}_create")
+    if hasattr(cv2, "xfeatures2d") and hasattr(cv2.xfeatures2d, f"{name}_create"):
+        return getattr(cv2.xfeatures2d, f"{name}_create")
+    raise AttributeError(f"{name}_create not found in cv2 or cv2.xfeatures2d")
+
+
+# -------------------------------------------------------------------------
+
+
+class ImagePointFeaturesMixin(_ImageBase if TYPE_CHECKING else object):
     def _image2feature(
         self,
         cls,
@@ -2028,8 +2049,8 @@ class ImagePointFeaturesMixin(_ImageBase):
             "SIFT": getattr(cv2, "SIFT_create"),
             "ORB": getattr(cv2, "ORB_create"),
             "Harris": _Harris_create,
-            "BRISK": getattr(cv2, "BRISK_create"),
-            "AKAZE": getattr(cv2, "AKAZE_create"),
+            "BRISK": _resolve_feature_create("BRISK"),
+            "AKAZE": _resolve_feature_create("AKAZE"),
             # 'FREAK': (cv2.FREAK_create, FREAKFeature),
             # 'DAISY': (cv2.DAISY_create, DAISYFeature),
         }

machinevisiontoolbox/ImageProcessing.py

@@ -1146,7 +1146,7 @@ class ImageProcessingMixin(_ImageBase if TYPE_CHECKING else object):
                 else:
                     try:
                         color = argcheck.getvector(image2, 3)
-                    except:
+                    except Exception:
                         raise ValueError("expecting a scalar, string or 3-vector")
                 if self.isbgr:
                     color = color[::-1]

machinevisiontoolbox/ImageRegionFeatures.py

@@ -9,7 +9,7 @@ import matplotlib.pyplot as plt
 import numpy as np
 from ansitable import ANSITable, Column
 from spatialmath import SE3
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from machinevisiontoolbox.decorators import array_result
 from machinevisiontoolbox.base import plot_labelbox
@@ -22,8 +22,11 @@ except ImportError:
     _pytesseract = None
     _pytesseract_available = False
 
+if TYPE_CHECKING:
+    from machinevisiontoolbox._image_typing import _ImageBase
 
-class ImageRegionFeaturesMixin:
+
+class ImageRegionFeaturesMixin(_ImageBase if TYPE_CHECKING else object):
     def MSER(self, **kwargs: Any) -> "MSERFeature":
         """
         Find MSER features in image
@@ -170,6 +173,22 @@ class MSERFeature:
             self._points = [
                 mser.T for mser in msers
             ]  # transpose point arrays to be Nx2
+            # --- OpenCV 4/5 compat ---------------------------------------
+            # When no regions are found, OpenCV 5's detectRegions() returns
+            # an empty tuple () for bboxes instead of an empty ndarray(0,4)
+            # -- bboxes[:, 2:] then raises TypeError: tuple indices must be
+            # integers or slices, not tuple. Normalize first.
+            #
+            # Separately (not a shape issue, not fixable here): verified
+            # empirically 2026-08-03 that with identical default parameters
+            # and identical grayscale input, OpenCV 5's MSER finds fewer or
+            # zero regions compared to OpenCV 4 on real photos -- an
+            # upstream algorithm behavior change, not an API surface
+            # change. Logged as its own issue (#54), not something this
+            # compat fix can address.
+            # -----------------------------------------------------------------
+            if len(bboxes) == 0:
+                bboxes = np.zeros((0, 4), dtype=int)
             bboxes[:, 2:] = bboxes[:, 0:2] + bboxes[:, 2:]  # convert to lrtb
             self._bboxes = bboxes
 
@@ -239,7 +258,7 @@ class MSERFeature:
 
         return new
 
-    def __str__(self):
+    def __str__(self) -> str:
         """
         String representation of MSER
 
@@ -262,7 +281,7 @@ class MSERFeature:
             s = f"MSER feature: u: {self._bboxes[0,0]} - {self._bboxes[0,2]}, v: {self._bboxes[0,1]} - {self._bboxes[0,3]}"
             return s
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         """
         Representation of MSER
 
@@ -370,7 +389,7 @@ class OCRWord:
         for key in ocr.keys():
             self.dict[key] = ocr[key][i]
 
-    def __str__(self):
+    def __str__(self) -> str:
         """
         String representation of MSER
 
@@ -379,7 +398,7 @@ class OCRWord:
         """
         return f"{self.dict['text']} ({self.dict['conf']}%)"
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return str(self)
 
     @property