sphinx doco cleanup

Author: petercorke

docs/source/_templates/autosummary/class.rst

@@ -17,7 +17,7 @@
 
    {% block attributes %}
    {% if attributes %}
-   .. rubric:: {{ _('Attributes') }}
+   .. rubric:: {{ _('Properties') }}
 
    .. autosummary::
    {% for item in attributes | sort(case_sensitive=False) %}

docs/source/conf.py

@@ -12,6 +12,8 @@
 #
 import os
 import sys
+import inspect
+import importlib
 from pathlib import Path
 from importlib.metadata import version as _pkg_version
 
@@ -44,6 +46,7 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
+    "sphinx.ext.linkcode",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "sphinx.ext.mathjax",
@@ -61,7 +64,7 @@
     "blockname",
 ]
 
-# autoclass_content = 'both' # use __init__ or class docstring
+autoclass_content = "both"  # use __init__ or class docstring
 add_function_parentheses = False
 
 # -- sphinx-autorun setup ----------------------------------------------------
@@ -132,6 +135,60 @@
 }
 html_show_sourcelink = True
 
+
+# -- Source code links -------------------------------------------------------
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+def linkcode_resolve(domain, info):
+    """Return GitHub source links for Python API objects."""
+    if domain != "py":
+        return None
+
+    module_name = info.get("module")
+    fullname = info.get("fullname")
+    if not module_name or not fullname:
+        return None
+
+    try:
+        module = importlib.import_module(module_name)
+    except Exception:
+        return None
+
+    obj = module
+    for part in fullname.split("."):
+        try:
+            obj = getattr(obj, part)
+        except Exception:
+            return None
+
+    # Use underlying function for decorated descriptors.
+    if isinstance(obj, property):
+        obj = obj.fget
+
+    try:
+        obj = inspect.unwrap(obj)
+    except Exception:
+        pass
+
+    try:
+        source_file = Path(inspect.getsourcefile(obj)).resolve()
+        source_lines, start_line = inspect.getsourcelines(obj)
+    except Exception:
+        return None
+
+    try:
+        rel_path = source_file.relative_to(_REPO_ROOT).as_posix()
+    except ValueError:
+        return None
+
+    end_line = start_line + len(source_lines) - 1
+    return (
+        "https://github.com/petercorke/machinevision-toolbox-python/"
+        f"blob/main/{rel_path}#L{start_line}-L{end_line}"
+    )
+
+
 # -- sphinx-copybutton setup -------------------------------------------------
 # Strip interactive prompts (Python and shell) when users copy code snippets.
 copybutton_prompt_text = r">>> |\.\.\. |\$ "

docs/source/image_class.rst

@@ -45,6 +45,7 @@ Describe the attributes of an :class:`~machinevisiontoolbox.ImageCore.Image`.
    ~npixels
    ~size
    ~width
+   ~nplanes
 
 Predicates
 ^^^^^^^^^^
@@ -61,6 +62,30 @@ Test attributes of an ``Image``.
    ~isint
    ~isrgb
 
+Color planes and channels
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Return information about the color planes of an ``Image`` instance.
+
+.. autosummary::
+   :nosignatures:
+   :show-private:
+
+   ~nplanes
+   ~iscolor
+   ~__mod__
+   ~Pstack
+   ~blue
+   ~green
+   ~plane
+   ~red
+   ~colordict
+   ~colordict2list
+   ~colordict2str
+   ~colororder
+   ~colororder2dict
+   ~colororder_str
+
 Image coordinates
 ^^^^^^^^^^^^^^^^^
 
@@ -94,7 +119,7 @@ Return ``Image`` pixel data as a NumPy array.
    ~to_int
    ~view1d
 
-Getting and setting pixels
+Getting pixels
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Access individual pixels or groups of pixels.
@@ -145,22 +170,6 @@ Extract sub-images or planes from an ``Image`` instance.
    ~red
    ~roi
 
-Color info
-^^^^^^^^^^
-
-Return information about the color planes of an ``Image`` instance.
-
-.. autosummary::
-   :nosignatures:
-
-   ~colordict
-   ~colordict2list
-   ~colordict2str
-   ~colororder
-   ~colororder2dict
-   ~colororder_str
-   ~nplanes
-
 Color space and gamma
 ^^^^^^^^^^^^^^^^^^^^^
 

docs/source/index.rst

@@ -6,15 +6,16 @@
 Machine Vision Toolbox for Python
 =================================
 
-An object-oriented wrapper for `OpenCV <https://opencv.org>`_ and `Open3D <https://open3d.org>`_ that supports a suite of useful image
-processing operations from reading and display through to blob and point feature
-extraction.
+A unified, object-oriented Python API that bridges the gap between raw pixels and
+high-level spatial reasoning by harmonizing a 'best-of-breed' foundation of NumPy,
+OpenCV, and Open3D.
 
 .. toctree::
    :maxdepth: 2
 
    intro
    package
+   installation
    cmdline-tools
    jupyter-notebooks
    ros

docs/source/intro.rst

@@ -5,20 +5,18 @@ Introduction
 Rationale
 =========
 
-The goal of this package is to simplify the expression of computer vision algorithms in
-Python.  Images can be represented as 2D or 3D arrays which are the domain of `NumPy
-<https://numpy.org>`_ but many powerful image and point cloud specific operations are
-provided by other popular packages such as `OpenCV <https://opencv.org>`_, `Pillow <https://pillow.readthedocs.io/en/stable/>`_,
-`SciPy <https://scipy.org>`_, `scikit-image <https://scikit-image.org>`_, and `Open3D <open3d.org>`_.
-OpenCV does an adequate job of displaying images but is nowhere nearly as powerful
-`matplotlib <https://matplotlib.org>`_ which can display a wide range of 2D graphics,
-but for 3D graphics Open3D is the go-to.
-
-In practice, using these various packages together, to exploit their individual strengths,
-is complex -- each have their own way of working, similar options are accessed
-differently and some function require image pixels to have particular types. None of
-them consider the image as an object with a set of useful image and vision processing
-methods and operators.  
+The Machine Vision Toolbox (MVTB) brings professional-grade vision algorithms to your
+fingertips with a Pythonic API. Built on a "best-of-breed" foundation—NumPy, SciPy,
+OpenCV, and Open3D —- it bridges the gap between raw pixel manipulation and high-level
+spatial reasoning.
+
+While the Python ecosystem offers powerful individual tools, using them in concert is
+often complex. Libraries like OpenCV, scikit-image and Open3D provide excellent algorithms, but
+they frequently differ in API style, coordinate conventions, and expected data types.
+MVTB unifies these capabilities into a consistent, object-oriented framework. By
+treating images and cameras as first-class objects rather than just raw arrays, the
+Toolbox allows you to focus on the geometry and logic of your vision system rather than
+the boilerplate of library integration.
 
 For example, to read an image using OpenCV, smooth it, and display it is::
 
@@ -271,7 +269,7 @@ belongs to
 .. code-block:: python
 
 	out = f.labelImage(im)
-	out.stats()
+	out.stats
 	out.disp(block=True, colormap="jet", cbar=True, vrange=[0,len(f)-1])
 
 and request the blob label image which we then display

src/machinevisiontoolbox/ImageBlobs.py

@@ -128,51 +128,90 @@ def __init__(
         The list can be indexed, sliced or used as an iterator in a for loop
         or comprehension, for example:
 
-            .. code-block:: python
+        .. code-block:: python
 
-                for blob in blobs:
-                  # do a thing
-                areas = [blob.area for blob in blobs]
+            for blob in blobs:
+                # do a thing
+
+            areas = [blob.area for blob in blobs]
 
 
         However the last line can also be written as:
 
-            .. code-block:: python
+        .. code-block:: python
 
-                areas = blobs.area
+            areas = blobs.area
 
 
         since all methods return a scalar if applied to a single blob:
 
-            .. code-block:: python
+        .. code-block:: python
 
-                blobs[1].area
+            blobs[1].area
 
 
         or a list if applied to multiple blobs:
 
-            .. code-block:: python
+        .. code-block:: python
 
-                blobs.area
+            blobs.area
 
 
         A blob has many attributes:
 
+        Geometric attributes
+
         .. list-table::
            :header-rows: 1
+           :widths: 30 70
 
-           * - Attribute
+           * - Property
              - Description
            * - :meth:`area`
              - The area of the blob.
-           * - :meth:`u`, :meth:`v`
-             - The centroid (center of mass) of the blob.
            * - :meth:`bbox`
              - The bounding box of the blob.
-           * - :meth:`color`
-             - The value of pixels within the blob.
+           * - :meth:`umin`, :meth:`umax`
+             - The horizontal extent of the bounding box.
+           * - :meth:`vmin`, :meth:`vmax`
+             - The vertical extent of the bounding box.
            * - :meth:`touch`
-             - True if the blob touches the border.
+             - True if the blob touches the border of the image.
+           * - :meth:`fillfactor`
+             - Ratio of blob area to bounding box area.
+           * - :meth:`bboxarea`
+             - Area of the bounding box.
+
+
+        Moment attributes
+
+        .. list-table::
+           :header-rows: 1
+           :widths: 30 70
+
+           * - Property
+             - Description
+           * - :meth:`u`, :meth:`v`
+             - The centroid (center of mass) of the blob.
+           * - :meth:`orientation`
+             - Orientation of the equivalent ellipse.
+           * - :meth:`a, b`
+             - The equivalent ellipse radii.
+           * - :meth:`aligned_box`
+             - A rotated bounding box with sides parallel to the axes of the equivalent ellipse.
+           * - :meth:`moments`
+             - The moments of the blob including central and normalised values up to 3rd order.
+           * - :meth:`humoments`
+             - Seven Hu moment invariants (invariant to position, orientation and scale).
+
+        Boundary and shape attributes
+
+        .. list-table::
+           :header-rows: 1
+           :widths: 30 70
+
+           * - Property
+             - Description
            * - :meth:`contour_point`
              - A point on the contour of the blob.
            * - :meth:`perimeter`
@@ -181,18 +220,34 @@ def __init__(
              - The perimeter length of the blob.
            * - :meth:`circularity`
              - The circularity of the blob.
-           * - :meth:`moments`
-             - The moments of the blob including central, normalized upto 3rd order.
-           * - :meth:`orientation`
-             - Orientation of the equivalent ellipse.
-           * - :meth:`a, b`
-             - The equivalent ellipse radii.
+           * - :meth:`perimeter_approx`
+             - A polygonal approximation to the perimeter.
+           * - :meth:`perimeter_hull`
+             - The convex hull of the perimeter.
+           * - :meth:`MEC`
+             - The minimum enclosing circle.
+           * - :meth:`MER`
+             - The minimum enclosing rectangle.
+
+
+        Hierarchy and region attributes
+
+        .. list-table::
+           :header-rows: 1
+           :widths: 30 70
+
+           * - Property
+             - Description
+           * - :meth:`color`
+             - The value of pixels within the blob.
            * - :meth:`children`
              - A list of references to child :class:`Blob` instances.
            * - :meth:`parent`
              - A reference to the parent :class:`Blob` instance, or None if no parent.
            * - :meth:`level`
              - The depth of the blob in the region tree.
+           * - :meth:`dotfile`
+             - Write a GraphViz dot file representing the blob hierarchy.
 
         .. note:: ``findContours`` can give surprising results for small images:
 
@@ -2319,6 +2374,8 @@ def blobs(self, **kwargs) -> Blobs:
 
         :references:
             - |RVC3|, Section 12.1.2.1.
+
+        :seealso: :class:`Blobs` :class:`Blob`
         """
 
         # TODO do the feature extraction here