machinevision-toolbox-python 2.0.1__py3-none-any.whl → 2.1.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/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/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,7 @@ class LUCIDFeature(BaseFeature2D):
     pass
 
 
-class ImagePointFeaturesMixin(_ImageBase):
+class ImagePointFeaturesMixin(_ImageBase if TYPE_CHECKING else object):
     def _image2feature(
         self,
         cls,

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
@@ -239,7 +242,7 @@ class MSERFeature:
 
         return new
 
-    def __str__(self):
+    def __str__(self) -> str:
         """
         String representation of MSER
 
@@ -262,7 +265,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 +373,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 +382,7 @@ class OCRWord:
         """
         return f"{self.dict['text']} ({self.dict['conf']}%)"
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return str(self)
 
     @property

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