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

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/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
 

machinevisiontoolbox/Kernel.py

@@ -115,6 +115,35 @@ class Kernel:
     def shape(self) -> tuple[int, int]:
         return self.K.shape
 
+    @property
+    def ndim(self) -> int:
+        return 2
+
+    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 kernel'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: kernel weighting matrix
+        :rtype: ndarray(N,M)
+
+        Implements the NumPy array protocol, used by ``np.asarray(K)`` and by
+        any NumPy/SciPy/Matplotlib function that calls ``np.asarray()``
+        internally on whatever it's given (e.g. ``scipy.signal.convolve2d``,
+        ``Axes3D.plot_surface``, ``np.linalg.svd``). Without this, such a call
+        would silently coerce a :class:`Kernel` into a useless 0-d object
+        array instead of its weighting matrix.
+        """
+        arr = self.K
+        if dtype is not None:
+            arr = arr.astype(dtype)
+        if copy:
+            arr = arr.copy()
+        return arr
+
     def print(
         self, fmt: str | None = None, separator: str = " ", precision: int = 2
     ) -> None:

machinevisiontoolbox/PointCloud.py

@@ -2,6 +2,7 @@
 Thin wrapper around Open3D point-cloud objects with MVTB look and feel.
 """
 
+from pathlib import Path
 from warnings import warn
 from typing import Any, Callable
 
@@ -26,7 +27,7 @@ class PointCloud:
         :type arg: :obj:`o3d.geometry.PointCloud`, :obj:`~machinevisiontoolbox.PointCloud`, ndarray(3,N)
         :param depth_scale: depth scale factor, defaults to 1.0
         :type depth_scale: float, optional
-        :raises RuntimeError: PointCloud class requires Open3D to be installed: pip install open3d-python or pip install machinevision-toolbox-python[open3d]
+        :raises RuntimeError: PointCloud class requires Open3D to be installed: pip install open3d or pip install machinevision-toolbox-python[open3d]
         :raises ValueError: bad arguments
 
         This object wraps an Open3D :obj:`open3d.geometry.PointCloud` object.  It can be
@@ -50,7 +51,7 @@ class PointCloud:
         if not _open3d:
             raise RuntimeError(
                 "PointCloud class requires Open3D to be installed: "
-                "pip install open3d-python or "
+                "pip install open3d or "
                 "pip install machinevision-toolbox-python[open3d]\n"
                 " ** Note that Open3d typically does not run on the latest Python version(s)"
             )
@@ -60,7 +61,7 @@ class PointCloud:
         if not _open3d:
             raise RuntimeError(
                 "PointCloud class requires Open3D to be installed: "
-                "pip install open3d-python or "
+                "pip install open3d or "
                 "pip install machinevision-toolbox-python[open3d]"
             )
 
@@ -244,10 +245,22 @@ class PointCloud:
         the ``data`` folder of the
         `mvtb_data package <https://github.com/petercorke/machinevision-toolbox-python/tree/master/packages/mvtb-data>`_.
 
+        .. note:: ``filename`` may be given as a bare name (``'bunny.ply'``)
+            or with a redundant leading ``data/`` (``'data/bunny.ply'``, the
+            older convention some book examples still use) -- both resolve
+            to the same file.
+
         """
 
         from machinevisiontoolbox import mvtb_path_to_datafile
 
+        # accept a caller-supplied redundant "data/" prefix (older
+        # convention) without double-joining it against the "data" this
+        # method already prepends
+        parts = Path(filename).parts
+        if parts and parts[0] == "data":
+            filename = str(Path(*parts[1:])) if len(parts) > 1 else ""
+
         filename = mvtb_path_to_datafile("data", filename, string=True)
         pcd = o3d.io.read_point_cloud(filename, *args, **kwargs)
         return cls(pcd)
@@ -273,7 +286,7 @@ class PointCloud:
         :type rgb: :class:`~machinevisiontoolbox.Image`, optional
         :param depth_scale: depth scale factor, defaults to 1.0
         :type depth_scale: float, optional
-        :raises RuntimeError: PointCloud class requires Open3D to be installed: pip install open3d-python or pip install machinevision-toolbox-python[open3d]
+        :raises RuntimeError: PointCloud class requires Open3D to be installed: pip install open3d or pip install machinevision-toolbox-python[open3d]
         :raises ValueError: input images has wrong number of planes
 
         The depth image is converted to a point cloud using the Open3D, and the pixel

machinevisiontoolbox/Sources.py

@@ -25,7 +25,6 @@ import warnings
 import zipfile
 from collections import Counter, deque
 from collections.abc import Iterator
-from numpy.char import array
 from tqdm import tqdm
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING, IO, Any, Literal, cast
@@ -2346,10 +2345,10 @@ class ROSTopic(ImageSource):
         if not _open3d_available:
             raise ImportError(
                 "open3d is required for PointCloud publish support. "
-                "Install it with: pip install open3d-python "
+                "Install it with: pip install open3d "
                 "or pip install machinevision-toolbox-python[open3d]"
             )
-            assert o3d is not None
+        assert o3d is not None
 
         points = np.asarray(pc._pcd.points)
         if points.ndim != 2 or points.shape[1] != 3:
@@ -3573,7 +3572,7 @@ class ROSBag(ImageSource):
                     if not _open3d_available:
                         raise ImportError(
                             "open3d is required to read PointCloud2 messages. "
-                            "Install it with: pip install open3d-python "
+                            "Install it with: pip install open3d "
                             "or pip install machinevision-toolbox-python[open3d]"
                         )
                     assert o3d is not None
@@ -3770,7 +3769,7 @@ class PointCloudSequence:
         if not _open3d_available:
             raise ImportError(
                 "open3d is required for point cloud display. "
-                "Install it with: pip install open3d-python "
+                "Install it with: pip install open3d "
                 "or pip install machinevision-toolbox-python[open3d]"
             )
         assert o3d is not None

machinevisiontoolbox/base/__init__.py

@@ -56,6 +56,7 @@ __all__ = [
     # types
     "int_image",
     "float_image",
+    "DTYPE_ALIASES",
     # data
     "mvtb_path_to_datafile",
     "mvtb_load_data",

machinevisiontoolbox/base/color.py

@@ -17,6 +17,7 @@ import matplotlib.path as mpath
 import matplotlib.pyplot as plt
 import numpy as np
 import spatialmath.base as smb
+from spatialmath import Polygon2
 from scipy import interpolate
 
 # import io as io
@@ -814,8 +815,10 @@ def name2color(
                 color = (color * np.iinfo(dtype).max).astype(dtype)
             if colororder is not None:
                 # reorder the elements of the color if colororder is given
-                # colororder is a dict mapping plane name to index
-                color = [color[colororder[c]] for c in colorspace]
+                # colororder is a dict mapping plane name to index -- fancy
+                # index rather than a list comprehension, to keep the
+                # ndarray return type promised by this function's contract
+                color = color[[colororder[c] for c in colorspace]]
             return color
         except ValueError:
             return None
@@ -1777,8 +1780,8 @@ def shadow_invariant(
     return gs
 
 
-def esttheta(im: Any, sharpen: np.ndarray | None = None) -> None:
-    """
+def esttheta(im: Any, sharpen: np.ndarray | None = None) -> float:
+    r"""
     Estimate theta for shadow invariance
 
     :param im: input image
@@ -1790,24 +1793,27 @@ def esttheta(im: Any, sharpen: np.ndarray | None = None) -> None:
 
     This is an interactive procedure where the image is displayed and the user
     selects a region of homogeneous material (eg. grass or road) that includes
-    areas that are directly lit by the sun and in shadow.
+    areas that are directly lit by the sun and in shadow.  The invariant angle
+    θ is found by sweeping candidate angles and choosing the one that
+    minimizes the variance of the resulting invariant image over the selected
+    region -- at the true invariant angle, lit and shadowed pixels of the same
+    material map to (nearly) the same greyscale value.
 
     .. note:: The user selects boundary points by clicking the mouse. After the
         last point, hit the Enter key and the region will be closed.
+
+    :seealso: :func:`shadow_invariant`
     """
 
     def pickregion(im: Any) -> np.ndarray:
-        im.disp()
+        h = im.disp()
 
-        clicks = plt.ginput(n=-1)
+        clicks = h.figure.ginput(n=-1)
 
         xy = np.array(clicks)
-        print(xy)
 
-        smb.plot_poly(xy.T, "g", close=True)
-
-        polygon = smb.Polygon2(xy.T)
-        polygon.plot("g")
+        polygon = Polygon2(xy.T)
+        polygon.plot(color="g")
 
         X, Y = im.meshgrid()
         inside = polygon.contains(np.c_[X.ravel(), Y.ravel()].T)
@@ -1816,13 +1822,33 @@ def esttheta(im: Any, sharpen: np.ndarray | None = None) -> None:
 
     k_region = pickregion(im)
 
-    imcol = im.column()
-
+    imcol = im.view1d()
     z = imcol[k_region, :]
-    print(z.shape)
-    # k = find(in);
+    print(f"{z.shape[0]} pixels selected in the region")
+
+    theta_v = np.arange(0, np.pi, 0.02)
+    sim = np.empty_like(theta_v)
+    for i, θ in enumerate(theta_v):
+        gs = shadow_invariant(z.reshape(-1, 1, 3), θ, sharpen=sharpen).ravel()
+        bad = np.isinf(gs) | np.isnan(gs)
+        sim[i] = np.std(gs[~bad])
+
+    k = np.argmin(sim)
+    theta = theta_v[k]
+
+    plt.figure()
+    plt.plot(theta_v, sim)
+    plt.plot(theta, sim[k], "o")
+    plt.xlabel("invariant line angle (rad)")
+    plt.ylabel("invariance image variance")
+    plt.grid(True)
+
+    print(f"best angle = {theta:.4f} rad")
+
     _safe_show(block=True)
 
+    return theta
+
 
 if __name__ == "__main__":  # pragma: no cover
     import os.path