machinevision-toolbox-python 2.0.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

machinevisiontoolbox/ImageBlobs.py

@@ -3,13 +3,15 @@ Detection and description of 2D blob (connected region) features in images.
 """
 
 import copy
+import io
+import json
 import subprocess
 import sys
 import tempfile
 import webbrowser
 from collections import UserList, namedtuple
 from dataclasses import dataclass
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
 import cv2
 import matplotlib.pyplot as plt
@@ -22,6 +24,9 @@ import spatialmath.base as smb
 from machinevisiontoolbox.base import plot_labelbox, mpl_styling
 from machinevisiontoolbox.decorators import array_result, scalar_result
 
+if TYPE_CHECKING:
+    from machinevisiontoolbox._image_typing import _ImageBase
+
 """
 NOTES
 
@@ -456,7 +461,10 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
 
                 ## Equivalent ellipse
                 J = np.array([[M["mu20"], M["mu11"]], [M["mu11"], M["mu02"]]])
-                e, X = np.linalg.eig(J)
+                # J is real-symmetric, so use eigh (not eig): eig can return
+                # complex128 for a symmetric matrix due to floating-point
+                # noise even though the eigenvalues are mathematically real.
+                e, X = np.linalg.eigh(J)
                 blob_params["a"] = 2.0 * np.sqrt(e.max() / M["m00"])
                 blob_params["b"] = 2.0 * np.sqrt(e.min() / M["m00"])
 
@@ -629,7 +637,7 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
             return self[:]
         m: np.ndarray = np.array(mask).all(axis=0)  # type: ignore[assignment]
 
-        return self[m]
+        return self[m.flatten()]
 
     def sort(self, by: str = "area", reverse: bool = False) -> "Blobs":  # type: ignore[override]
         """
@@ -1194,7 +1202,7 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
             >>> blobs[2].level
             >>> blobs.level
 
-        :seealso: :meth:`color` :meth:`parent` :meth:`children` :meth:`dotfile`
+        :seealso: :meth:`color` :meth:`parent` :meth:`children` :meth:`dotfile` :meth:`graph`
         """
         return [b.level for b in self.data]
 
@@ -1247,7 +1255,7 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
 
         A parent of -1 is the image background.
 
-        :seealso: :meth:`id` :meth:`children` :meth:`level` :meth:`dotfile`
+        :seealso: :meth:`id` :meth:`children` :meth:`level` :meth:`dotfile` :meth:`graph`
         """
         return [b.parent.id if b.parent is not None else -1 for b in self.data]
 
@@ -1272,7 +1280,7 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
             >>> blobs[6].id
 
 
-        :seealso: :meth:`parent` :meth:`children` :meth:`level` :meth:`dotfile`
+        :seealso: :meth:`parent` :meth:`children` :meth:`level` :meth:`dotfile` :meth:`graph`
         """
         return [b.id for b in self.data]
 
@@ -1293,7 +1301,7 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
             >>> blobs = im.blobs()
             >>> blobs[5].children
 
-        :seealso: :meth:`parent` :meth:`level` :meth:`dotfile`
+        :seealso: :meth:`parent` :meth:`level` :meth:`dotfile` :meth:`graph`
         """
         return [[c.id for c in b.children] for b in self.data]
 
@@ -2380,6 +2388,180 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
 
         return image.__class__(labels)
 
+    def graph(
+        self,
+        format: str = "dot",
+        filename: str | io.TextIOBase | None = None,
+        direction: str | None = None,
+    ) -> str:
+        """
+        Render blob hierarchy graph text.
+
+        :param format: graph output format: ``"dot"``, ``"mermaid"``,
+            ``"mermaid_fenced"``, ``"graphml"`` or ``"elk"``
+        :type format: str, optional
+        :param filename: destination path or open text stream, defaults to None
+        :type filename: str | file handle | None, optional
+        :param direction: graph direction for DOT output, defaults to None
+        :type direction: str, optional
+        :return: rendered graph text
+        :rtype: str
+
+        Creates graph text representing the blob hierarchy. If ``filename`` is
+        provided, the rendered text is also written to it.
+
+                Mermaid outputs:
+
+                - ``"mermaid"`` returns plain Mermaid text.
+                - ``"mermaid_fenced"`` returns Markdown fenced text suitable for
+                    direct display via ``IPython.display.Markdown``.
+
+        The blob hierarchy is represented as a directed graph where each node is
+        a blob id and each edge points from parent blob to child blob.
+
+        :seealso: :meth:`dotfile` :meth:`parent` :meth:`children` :meth:`level`
+        """
+
+        graph_format = format.lower().replace("-", "_")
+
+        def _parent_id(blob: Any) -> int:
+            parent = blob.parent
+            if parent is None:
+                return -1
+            if isinstance(parent, int):
+                return parent
+            return parent.id
+
+        hierarchy_edges = [(_parent_id(blob), blob.id) for blob in self]
+        node_ids_set = {blob.id for blob in self}
+        if any(parent_id == -1 for parent_id, _ in hierarchy_edges):
+            node_ids_set.add(-1)
+
+        if graph_format == "dot":
+            lines = ["digraph {"]
+            if direction is not None:
+                lines.append(f"rankdir = {direction}")
+
+            for node_id in sorted(node_ids_set):
+                lines.append(f'  "{node_id}"')
+
+            for parent_id, child_id in hierarchy_edges:
+                lines.append(f'  "{parent_id}" -> "{child_id}"')
+
+            lines.append("}")
+            text = "\n".join(lines) + "\n"
+
+        elif graph_format in ("mermaid", "mermaid_fenced"):
+            lines = ["flowchart TB"]
+            node_ids: dict[Any, str] = {}
+            sorted_nodes = sorted(node_ids_set)
+
+            for i, node in enumerate(sorted_nodes):
+                node_alias = f"b{i}"
+                node_ids[node] = node_alias
+                lines.append(f'    {node_alias}["{node}"]')
+
+            for parent_id, child_id in hierarchy_edges:
+                lines.append(f"    {node_ids[parent_id]} --> {node_ids[child_id]}")
+
+            mermaid_text = "\n".join(lines) + "\n"
+            if graph_format == "mermaid_fenced":
+                text = f"```mermaid\n{mermaid_text}```\n"
+            else:
+                text = mermaid_text
+
+        elif graph_format == "graphml":
+
+            def _xml_escape(value: str) -> str:
+                return (
+                    value.replace("&", "&")
+                    .replace("<", "&lt;")
+                    .replace(">", "&gt;")
+                    .replace('"', "&quot;")
+                    .replace("'", "&apos;")
+                )
+
+            lines = [
+                '<?xml version="1.0" encoding="UTF-8"?>',
+                '<graphml xmlns="http://graphml.graphdrawing.org/xmlns"',
+                '         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"',
+                '         xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns',
+                '         http://graphml.graphdrawing.org/xmlns/1.0/graphml.xsd">',
+                '  <key id="node_label" for="node" attr.name="label" attr.type="string"/>',
+                '  <graph id="G" edgedefault="directed">',
+            ]
+
+            for node in sorted(node_ids_set):
+                node_id = f"n{node}"
+                lines.extend(
+                    [
+                        f'    <node id="{node_id}">',
+                        f'      <data key="node_label">{_xml_escape(str(node))}</data>',
+                        "    </node>",
+                    ]
+                )
+
+            edge_id = 0
+            for parent_id, child_id in hierarchy_edges:
+                lines.append(
+                    f'    <edge id="e{edge_id}" source="n{parent_id}" target="n{child_id}"/>'
+                )
+                edge_id += 1
+
+            lines.extend(["  </graph>", "</graphml>"])
+            text = "\n".join(lines) + "\n"
+
+        elif graph_format == "elk":
+            children = []
+            edges = []
+
+            for node in sorted(node_ids_set):
+                children.append(
+                    {
+                        "id": f"n{node}",
+                        "labels": [{"text": str(node)}],
+                        "width": 60,
+                        "height": 40,
+                    }
+                )
+
+            edge_id = 0
+            for parent_id, child_id in hierarchy_edges:
+                edges.append(
+                    {
+                        "id": f"e{edge_id}",
+                        "sources": [f"n{parent_id}"],
+                        "targets": [f"n{child_id}"],
+                    }
+                )
+                edge_id += 1
+
+            elk_graph = {
+                "id": "root",
+                "layoutOptions": {
+                    "org.eclipse.elk.algorithm": "layered",
+                    "org.eclipse.elk.direction": "DOWN",
+                },
+                "children": children,
+                "edges": edges,
+            }
+            text = json.dumps(elk_graph, indent=2) + "\n"
+
+        else:
+            raise ValueError(
+                "unsupported graph format "
+                f"'{format}', expected 'dot', 'mermaid', 'mermaid_fenced', 'graphml' or 'elk'"
+            )
+
+        if filename is not None:
+            if isinstance(filename, str):
+                with open(filename, "w") as file:
+                    file.write(text)
+            else:
+                filename.write(text)
+
+        return text
+
     def dotfile(
         self, filename: Any = None, direction: str | None = None, show: bool = False
     ) -> None:
@@ -2400,53 +2582,51 @@ class Blobs(UserList):  # lgtm[py/missing-equals]
         .. note:: If ``filename`` is a file object then the file will *not*
             be closed after the GraphViz model is written.
 
-        :seealso: :meth:`child` :meth:`parent` :meth:`level`
+        :seealso: :meth:`graph` :meth:`child` :meth:`parent` :meth:`level`
         """
 
         if show:
             # create the temporary dotfile
             filename = tempfile.TemporaryFile(mode="w")
+        dot_text = self.graph(format="dot", direction=direction)
+
         if filename is None:
             f = sys.stdout
+            f.write(dot_text)
         elif isinstance(filename, str):
-            f = open(filename, "w")
+            with open(filename, "w") as f:
+                f.write(dot_text)
         else:
             f = filename
-
-        print("digraph {", file=f)
-
-        if direction is not None:
-            print(f"rankdir = {direction}", file=f)
-
-        # add the nodes including name and position
-        for id, blob in enumerate(self):
-            print('  "{:d}"'.format(id), file=f)
-            print(
-                '  "{:d}" -> "{:d}"'.format(blob.parent if blob.parent else -1, id),
-                file=f,
-            )
-
-        print("}", file=f)
+            f.write(dot_text)
 
         if show:
             # rewind the dot file, create PDF file in the filesystem, run dot
-            f.seek(0)
+            if filename is None:
+                dot_stream = tempfile.TemporaryFile(mode="w+")
+                dot_stream.write(dot_text)
+                dot_stream.seek(0)
+            elif isinstance(filename, str):
+                dot_stream = open(filename, "r")
+            else:
+                f.seek(0)
+                dot_stream = f
+
             pdffile = tempfile.NamedTemporaryFile(suffix=".pdf", delete=False)
             subprocess.run(
                 ["dot", "-Tpdf"],
-                stdin=cast(Any, f),
+                stdin=cast(Any, dot_stream),
                 stdout=pdffile,
                 check=True,
             )
 
             # open the PDF file in browser (hopefully portable), then cleanup
             webbrowser.open(f"file://{pdffile.name}")
-        else:
             if filename is None or isinstance(filename, str):
-                f.close()  # noqa
+                dot_stream.close()
 
 
-class ImageBlobsMixin:
+class ImageBlobsMixin(_ImageBase if TYPE_CHECKING else object):
     def blobs(self, **kwargs) -> Blobs:
         """
         Find and describe blobs in image

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]