Merge branch 'main' into fix/metadata-exif-subifd

Author: petercorke

docs/source/conf.py

@@ -108,6 +108,7 @@
 autosectionlabel_prefix_document = True
 rst_epilog = """
 .. |RVC3| replace:: `P. Corke, Robotics, Vision & Control for Python, Springer, 2023 <https://link.springer.com/book/10.1007/978-3-031-06469-2>`__
+.. |dtype_aliases| replace:: The short-name aliases ``'int'``, ``'float'``, ``'double'``, ``'half'`` are also accepted and resolve to the Toolbox's own defaults (``uint8``, ``float32``, ``float64``, ``float16`` respectively) -- this matters because NumPy's own ``np.dtype('float')`` resolves to ``float64``, not ``float32``. See :data:`~machinevisiontoolbox.base.types.DTYPE_ALIASES`.
 """
 
 # tricks to get :class:`Image` links to resolve to the correct place in the RsT docs

src/machinevisiontoolbox/BagOfWords.py

@@ -58,6 +58,13 @@ def __init__(
         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 @@ def __init__(
         # 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 = []
 

src/machinevisiontoolbox/Camera.py

@@ -1152,7 +1152,7 @@ def plot(
         """
         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,15 +1170,28 @@ def plot(
         :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`
 
         Plot a 3D icon representing the pose of a camera into a 3D Matplotlib
         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 +1208,11 @@ def plot(
         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 +1234,27 @@ def _add_collection3d_compat(collection, *args, **kwargs):
         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 +1298,8 @@ def _plot_frustum(self, ax: Axes, pose: SE3, scale: float, alpha: float) -> None
         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,

src/machinevisiontoolbox/ImageConstants.py

@@ -23,7 +23,7 @@
 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 @@ def Zeros(
         :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 @@ def Zeros(
         )
 
         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 @@ def Constant(
         :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 @@ def Constant(
             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 @@ def Random(
         :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 @@ def Random(
             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 @@ def Squares(
         :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 @@ def Circles(
         :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 @@ def Ramp(
         :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 @@ def Sin(
         :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 @@ def Chequerboard(
         :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 @@ def Polygons(
         :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

src/machinevisiontoolbox/ImageCore.py

@@ -20,6 +20,7 @@
 
 # from numpy.lib.arraysetops import isin
 from machinevisiontoolbox.base import (
+    DTYPE_ALIASES,
     draw_box,
     draw_circle,
     draw_labelbox,
@@ -98,8 +99,13 @@ def __init__(
         :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
@@ -381,6 +387,8 @@ def _infer_dtype(image: np.ndarray, dtype: Dtype | bool | None) -> np.dtype | No
             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:
@@ -1958,6 +1966,9 @@ def to(self, dtype: Dtype) -> "Image":
 
         :param dtype: Numpy data type
         :type dtype: str or NumPy dtype
+
+        |dtype_aliases|
+
         :return: image
         :rtype: :class:`Image`
 
@@ -1980,8 +1991,9 @@ def to(self, dtype: Dtype) -> "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":
@@ -1990,6 +2002,9 @@ def astype(self, dtype: Dtype) -> "Image":
 
         :param dtype: Numpy data type
         :type dtype: str or NumPy dtype
+
+        |dtype_aliases|
+
         :return: image
         :rtype: :class:`Image`
 
@@ -2010,6 +2025,8 @@ def astype(self, dtype: Dtype) -> "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 ---- #
@@ -2285,7 +2302,9 @@ def array_as(self, dtype: Dtype | None = None) -> np.ndarray:
         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)
 
@@ -2327,6 +2346,8 @@ def array_as(self, dtype: Dtype | None = None) -> np.ndarray:
         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)

src/machinevisiontoolbox/base/__init__.py

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