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

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
@@ -603,7 +602,8 @@ class VideoCamera(ImageSource):
         attached video camera.  On a Mac running 13.0 (Ventura) or later and
         an iPhone with iOS 16 or later, the Continuity Camera feature allows
         the phone camera to be used as a local video camera, and it will
-        appear as a separate camera with its own ID.
+        appear as a separate camera with its own ID.  Other phones, and cameras
+        on the network, can be used through :class:`WebCam`.
 
         OpenCV does not expose a portable API for mapping integer ``id``
         values to human-readable camera names.  Use :meth:`list` to
@@ -613,7 +613,7 @@ class VideoCamera(ImageSource):
     :references:
         - |RVC3|, Section 11.1.3.
 
-    :seealso: :meth:`list` :func:`~machinevisiontoolbox.base.imageio.convert`
+    :seealso: :meth:`list` :class:`WebCam` :func:`~machinevisiontoolbox.base.imageio.convert`
         `cv2.VideoCapture <https://docs.opencv.org/4.x/d8/dfe/classcv_1_1VideoCapture.html#a57c0e81e83e60f36c83027dc2a188e80>`_
     """
 
@@ -1730,15 +1730,24 @@ class WebCam(ImageSource):
                     pass
 
 
-    .. note:: Manu webcameras accept a query string in the URL to specify
+    .. note:: Many webcameras accept a query string in the URL to specify
         image resolution, image format, codec and other parameters. There
         is no common standard for this, see the manufacturer's datasheet
         for details.
 
+    .. note:: The ``url`` is passed to ``cv2.VideoCapture``, so it can be
+        anything that OpenCV can open, for example a still-image URL, a
+        live HTTP (MJPEG) stream or an RTSP stream.  A phone can be used as a
+        networked camera in this way: many IP-camera apps for iOS and Android
+        publish a live stream at a URL.  Which stream types and URL formats are
+        supported depends on the app and on how your OpenCV was built.  On a Mac
+        with an iPhone, Continuity Camera makes the phone appear as a local
+        camera instead, see :class:`VideoCamera`.
+
     :references:
         - |RVC3|, Section 11.1.5.
 
-    :seealso: :func:`~machinevisiontoolbox.base.imageio.convert`
+    :seealso: :class:`VideoCamera` :func:`~machinevisiontoolbox.base.imageio.convert`
         `cv2.VideoCapture <https://docs.opencv.org/4.x/d8/dfe/classcv_1_1VideoCapture.html#a57c0e81e83e60f36c83027dc2a188e80>`_
     """
 
@@ -2346,10 +2355,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 +3582,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 +3779,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