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

machinevisiontoolbox/ImageWholeFeatures.py

@@ -11,6 +11,7 @@ import cv2
 import matplotlib.pyplot as plt
 import numpy as np
 import scipy as sp
+from matplotlib.axes import Axes
 from matplotlib.patches import Polygon
 from matplotlib.ticker import ScalarFormatter
 from spatialmath import SE3, base
@@ -519,6 +520,11 @@ class ImageWholeFeaturesMixin(_ImageBase if TYPE_CHECKING else object):
         .. deprecated:: 2.0.0
             Use ``hist().cdf`` instead.
         """
+        warnings.warn(
+            "Deprecated in 2.0.0: use hist().cdf instead of ncdf.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         hist = self._default_hist()
         return hist.cdf
 
@@ -1193,26 +1199,31 @@ class Histogram:
         :rtype: ndarray(N) or ndarray(N,P)
 
         .. deprecated:: 2.0.0
-            Use ``hist().cdf`` instead.
+            Use ``cdf`` instead.
         """
+        warnings.warn(
+            "Deprecated in 2.0.0: use .cdf instead of .ncdf.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return self.cdf
 
     def plot(
         self,
-        type="frequency",
-        block=False,
-        filled=None,
-        stats=True,
-        style="stack",
-        cursor=False,
-        alpha=0.5,
-        title=None,
-        log=False,
-        samescale=False,
-        ax=None,
-        bar=None,
-        **kwargs,
-    ):
+        type: str = "frequency",
+        block: bool = False,
+        filled: bool | None = None,
+        stats: bool = True,
+        style: str = "stack",
+        cursor: bool = False,
+        alpha: float = 0.5,
+        title: str | None = None,
+        log: bool = False,
+        samescale: bool = False,
+        ax: Axes | None = None,
+        bar: bool | None = None,
+        **kwargs: Any,
+    ) -> None:
         """
         Plot histogram
 
@@ -1343,38 +1354,9 @@ class Histogram:
             samescale = True
 
         # figure vertical axis labels and scaling based on histogram type
-        if type == "frequency":
-            y = self.h
-            if samescale:
-                maxy = np.max(y)
-            else:
-                maxy = np.max(y, axis=0)
-            ylabel1 = "frequency"
-            ylabel2 = "frequency"
-            if filled is None:
-                filled = True
-        elif type in ("pdf", "probability"):
-            y = self.pdf
-            if samescale:
-                maxy = np.max(y)
-            else:
-                maxy = np.max(y, axis=0)
-            ylabel1 = "PDF"
-            ylabel2 = "probability density"
-        elif type in ("cf", "cumulative"):
-            y = self.cf
-            maxy = y[
-                -1, 0
-            ]  # last row values are all the same, total number of pixels in plane
-            ylabel1 = "cumulative frequency"
-            ylabel2 = "cumulative frequency"
-        elif type in ("cdf", "normalized"):
-            y = self.cdf
-            maxy = 1
-            ylabel1 = "CDF"
-            ylabel2 = "normalized cumulative frequency"
-        else:
-            raise ValueError("unknown type")
+        y, maxy, ylabel1, ylabel2 = self._compute_plot_series(type, samescale)
+        if type == "frequency" and filled is None:
+            filled = True
 
         if self.nplanes == 1:
             y = y[..., np.newaxis]
@@ -1391,17 +1373,6 @@ class Histogram:
         if self.nplanes == 1:
             hist_counts = hist_counts[..., np.newaxis]
 
-        def plane_stats(counts: np.ndarray) -> tuple[float | None, float | None]:
-            total = float(np.sum(counts))
-            if total <= 0:
-                return None, None
-
-            mean = float(np.sum(self.x * counts) / total)
-            cdf = np.cumsum(counts)
-            median_idx = int(np.searchsorted(cdf, 0.5 * total, side="left"))
-            median = float(self.x[min(median_idx, len(self.x) - 1)])
-            return mean, median
-
         if self._sorted:
             xrange = (self.x[0], self.x[-1])
             xlabel = "bin rank"
@@ -1448,7 +1419,7 @@ class Histogram:
                     ScalarFormatter(useOffset=False, useMathText=True)
                 )
                 if stats:
-                    mean, median = plane_stats(hist_counts[:, i])
+                    mean, median = self._histogram_plane_stats(hist_counts[:, i])
                     if mean is not None and median is not None:
                         ax.axvline(
                             mean,
@@ -1549,18 +1520,7 @@ class Histogram:
             x = np.r_[xrange[0], x, xrange[1]]
             _, ax = plt.subplots(1, 1)
 
-            patchcolor = []
-            goodcolors = [c for c in "rgbykcm"]
-            if self.colordict is None:
-                self.colordict = {c: i for i, c in enumerate(goodcolors[:n])}
-                colors = list(self.colordict.keys())
-                patchcolor = [c.lower() for c in colors]
-            else:
-                for color, i in self.colordict.items():
-                    if color.lower() in "rgbykcm":
-                        patchcolor.append(color.lower())
-                    else:
-                        patchcolor.append(goodcolors.pop(0))
+            colors, patchcolor = self._resolve_overlay_colors(n, colors)
 
             if filled:
                 for i in range(n):
@@ -1580,7 +1540,7 @@ class Histogram:
                     ax.plot(x, np.r_[0, y[:, i], 0], color=patchcolor[i], **kwargs)
 
             if stats:
-                mean, median = plane_stats(np.sum(hist_counts, axis=1))
+                mean, median = self._histogram_plane_stats(np.sum(hist_counts, axis=1))
                 if mean is not None and median is not None:
                     ax.axvline(
                         mean,
@@ -1617,6 +1577,87 @@ class Histogram:
             set_window_title(title)
         safe_plt_show(block=block)
 
+    def _compute_plot_series(
+        self, type: str, samescale: bool
+    ) -> tuple[np.ndarray, np.ndarray | float, str, str]:
+        """Compute plot()'s y-values, y-axis max, and y-axis labels for a
+        given ``type``. Pure computation over self.h/self.pdf/self.cf/
+        self.cdf -- no mutation."""
+        if type == "frequency":
+            y = self.h
+            if samescale:
+                maxy = np.max(y)
+            else:
+                maxy = np.max(y, axis=0)
+            ylabel1 = "frequency"
+            ylabel2 = "frequency"
+        elif type in ("pdf", "probability"):
+            y = self.pdf
+            if samescale:
+                maxy = np.max(y)
+            else:
+                maxy = np.max(y, axis=0)
+            ylabel1 = "PDF"
+            ylabel2 = "probability density"
+        elif type in ("cf", "cumulative"):
+            y = self.cf
+            maxy = y[
+                -1, 0
+            ]  # last row values are all the same, total number of pixels in plane
+            ylabel1 = "cumulative frequency"
+            ylabel2 = "cumulative frequency"
+        elif type in ("cdf", "normalized"):
+            y = self.cdf
+            maxy = 1
+            ylabel1 = "CDF"
+            ylabel2 = "normalized cumulative frequency"
+        else:
+            raise ValueError("unknown type")
+
+        return y, maxy, ylabel1, ylabel2
+
+    def _histogram_plane_stats(
+        self, counts: np.ndarray
+    ) -> tuple[float | None, float | None]:
+        """Mean and median of a single plane's histogram counts, or
+        (None, None) if the plane is empty. Used by both plot()'s stack
+        and overlay styles."""
+        total = float(np.sum(counts))
+        if total <= 0:
+            return None, None
+
+        mean = float(np.sum(self.x * counts) / total)
+        cdf = np.cumsum(counts)
+        median_idx = int(np.searchsorted(cdf, 0.5 * total, side="left"))
+        median = float(self.x[min(median_idx, len(self.x) - 1)])
+        return mean, median
+
+    def _resolve_overlay_colors(
+        self, n: int, colors: list[str]
+    ) -> tuple[list[str], list[str]]:
+        """Resolve per-plane display colors for plot()'s style="overlay".
+
+        If self.colordict is unset, assigns a default one as a side effect
+        (preserved intentionally -- this is existing behavior, not
+        introduced by extracting this into its own method) and returns the
+        colors derived from it; otherwise maps the existing colordict's
+        color names onto a fallback palette for any non-standard names.
+        """
+        patchcolor = []
+        goodcolors = [c for c in "rgbykcm"]
+        if self.colordict is None:
+            self.colordict = {c: i for i, c in enumerate(goodcolors[:n])}
+            colors = list(self.colordict.keys())
+            patchcolor = [c.lower() for c in colors]
+        else:
+            for color, i in self.colordict.items():
+                if color.lower() in "rgbykcm":
+                    patchcolor.append(color.lower())
+                else:
+                    patchcolor.append(goodcolors.pop(0))
+
+        return colors, patchcolor
+
     def peaks(self, **kwargs: Any) -> np.ndarray | list[np.ndarray]:
         r"""
         Histogram peaks

machinevisiontoolbox/Sources.py

@@ -3113,7 +3113,7 @@ class ROSBag(ImageSource):
             reader.close()
             self.reader = None
 
-    def _open_reader(self):
+    def _open_reader(self) -> Any:
         if self.reader is not None:
             return self.reader
 

machinevisiontoolbox/__init__.py

@@ -188,5 +188,5 @@ try:
     import importlib.metadata
 
     __version__ = importlib.metadata.version("machinevision-toolbox-python")
-except:
+except importlib.metadata.PackageNotFoundError:
     pass

machinevisiontoolbox/base/imageio.py

@@ -707,13 +707,14 @@ def idisp(
 
         # display the image
         if len(im.shape) == 3:
-            # reverse the color planes if it's color
-            if colororder not in ("RGB", "BGR"):
-                raise ValueError("unknown colororder ", colororder)
-            if colororder == "BGR":
-                im = im[:, :, ::-1]
-            h = ax.imshow(im, norm=norm, cmap=cmap, **options)
+            # color image, display in RGB or RGBA order; imshow handles alpha
+            # natively for both uint8 (0-255) and float (0.0-1.0) arrays
+            target = "RGBA" if "A" in colororder else "RGB"
+            idx = [colororder.find(c) for c in target if colororder.find(c) >= 0]
+            im_rgb = im[:, :, idx]  # reorder planes → RGB or RGBA
+            h = ax.imshow(im_rgb, norm=norm, cmap=cmap, **options)
         else:
+            # monochrome image, display in indexed mode, where pixel value is mapped through the colormap
             if norm is None:
                 # exclude NaN values
                 if vrange is None:
@@ -889,7 +890,19 @@ def idisp(
         # At this point title is guaranteed to be a string
         assert title is not None
         cv2.namedWindow(title, cv2.WINDOW_AUTOSIZE)
-        cv2.imshow(title, im)  # make sure BGR format image
+
+        if im.ndim == 3:
+            # color image, display in BGR order, but allow user to specify color order of input image
+            idx = []
+            for c in "BGR":
+                j = colororder.find(c)
+                if j >= 0:
+                    idx.append(j)
+            cv2.imshow(title, im[:, :, idx])  # convert → BGR order and display
+        else:
+            # monochrome image, display in indexed mode, where pixel value is mapped through the colormap
+            cv2.imshow(title, im)  # make sure BGR format image
+
         cv2.waitKey(1)
 
         if fps is not None:
@@ -1028,7 +1041,7 @@ def iread(
             headers={"User-Agent": "machinevisiontoolbox-python/1.0"},
         )
         try:
-            with urllib.request.urlopen(req, context=ctx) as resp:
+            with urllib.request.urlopen(req, context=ctx, timeout=10) as resp:
                 if resp.status != 200:
                     raise ValueError(f"HTTP {resp.status} fetching {filename}")
                 array = np.asarray(bytearray(resp.read()), dtype="uint8")
@@ -1126,7 +1139,9 @@ def iread_iter(
 
         # read a single file
         path = Path(mvtb_path_to_datafile("images", path))
-        image = cv2.imread(path.as_posix(), cv2.IMREAD_UNCHANGED)
+        image = cv2.imread(
+            path.as_posix(), cv2.IMREAD_UNCHANGED
+        )  # read BGR or BGRA image, or greyscale if that's what the file contains
         if image is None:
             raise ValueError(f"Could not read {filename}")
         yield (convert(image, **kwargs), str(path))
@@ -1153,7 +1168,7 @@ def convert(
     """
     Convert image
 
-    :param image: input image
+    :param image: input image in BGR or BGRA order, as read by OpenCV
     :type image: ndarray(H,W), ndarray(H,W,P)
     :param mono: convert to grey scale, synonym for ``grey``
     :type mono: bool, optional
@@ -1207,20 +1222,29 @@ def convert(
         )
     image_original = image
 
+    # handle color plane order and alpha channel
+    # note that Torch doesn't like views of arrays with non-standard strides, so we use fancy indexing which implicitly makes a copy
+
     if image.ndim == 3 and image.shape[2] in (3, 4):
-        # is color image RGB, RGBA, BGR, BGRA
-        if not alpha:
-            # optionally remove the alpha plane
-            image = image[:, :, :3]
+        # color image, convert to RGB order if requested, otherwise leave in BGR order
         if rgb:
-            # optionally invert the color planes
-            image = np.copy(image[:, :, ::-1])  # reverse the planes
-            # np.copy() is required to make torchvision happy
-            colororder = "RGB"
+            # RGB order is more common in Python, but OpenCV reads in BGR order, so convert to RGB
+            if alpha and image.shape[2] == 4:
+                # BGRA→RGBA
+                image = image[:, :, [2, 1, 0, 3]]  # BGRA → RGBA
+                colororder = "RGBA"
+            else:
+                # BGR→RGB
+                image = image[:, :, [2, 1, 0]]
+                colororder = "RGB"
         else:
-            colororder = "BGR"
-        if alpha:
-            colororder += "A"
+            # leave in BGR order, which is more efficient for OpenCV processing, but less common in Python
+            if alpha and image.shape[2] == 4:
+                colororder = "BGRA"
+            else:
+                # BGRA→BGR
+                image = image[:, :, :3]  # BGRA → BGR
+                colororder = "BGR"
 
     mono = mono or gray or grey
     if mono and len(image.shape) == 3:
@@ -1284,32 +1308,43 @@ def iwrite(
     :return: successful write
     :rtype: bool
 
-    Writes the image ``im`` to ``filename`` using cv2.imwrite(), passing any
-    keyword arguments as options.  The file type is taken from the extension in
-    ``filename``.
+    Writes the image ``im`` to ``filename`` using cv2.imwrite(), passing any keyword
+    arguments as options.  The file type is taken from the extension in ``filename``.
 
     Example:
 
         .. code-block:: python
 
-            from machinevisiontoolbox import iwrite
-            import numpy as np
-            image = np.zeros((20,20))  # 20x20 black image
-            iwrite(image, "black.png")
+            from machinevisiontoolbox import iwrite import numpy as np image =
+            np.zeros((20,20))  # 20x20 black image iwrite(image, "black.png")
 
 
     .. note::
         - supports 8-bit greyscale and color images
         - supports uint16 for PNG, JPEG 2000, and TIFF formats
         - supports float32
-        - image must be in BGR or RGB format
+        - supports alpha channel for PNG and TIFF formats
+        - color image planes, with planes specified by ``colororder``, are reordered to
+          OpenCV order: BGR or BGRA. For example, if ``colororder`` is "GRBA", the planes
+          are reordered to "BGRA" for writing.  If ``colororder`` is "BGR" or "BGRA", no reordering is done.
 
-    :seealso: :func:`iread` `cv2.imwrite <https://docs.opencv.org/4.x/d4/da8/group__imgcodecs.html#gabbc7ef1aa2edfaa87772f1202d67e0ce>`_
+    :seealso: :func:`iread` `cv2.imwrite
+        <https://docs.opencv.org/4.x/d4/da8/group__imgcodecs.html#gabbc7ef1aa2edfaa87772f1202d67e0ce>`_
     """
-    if im.ndim > 2 and colororder == "RGB":
-        # put image into OpenCV BGR order for writing
-        return cv2.imwrite(filename, im[:, :, ::-1], **kwargs)
+    if im.ndim > 2:
+        # color image, convert to OpenCV BGR order for writing
+        if im.shape[2] not in (3, 4):
+            raise ValueError("color image must have 3 or 4 planes")
+        if colororder is not None:
+            idx = []
+            for c in "BGRA":
+                j = colororder.find(c)
+                if j >= 0:
+                    idx.append(j)
+            im_bgra = im[:, :, idx]  # reorder color planes → BGRA
+        return cv2.imwrite(filename, im_bgra, **kwargs)
     else:
+        # monochrome image
         return cv2.imwrite(filename, im, **kwargs)