From 8eaf375ba1804219837db2dcfcfe2a840f4c9330 Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Wed, 18 Nov 2026 08:58:26 +1000 Subject: [PATCH 1/5] docs: stop BundleAdjust scene-graph classes being documented twice bundle-adjust.rst re-documented ViewPoint, Landmark and Observation, which the support-classes autosummary already generates, giving 75 duplicate object description warnings. Mark the manual copies no-index. Co-Authored-By: Claude Sonnet 5.5 --- docs/source/bundle-adjust.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/bundle-adjust.rst b/docs/source/bundle-adjust.rst index 4a7a1c49..b6cccc61 100644 --- a/docs/source/bundle-adjust.rst +++ b/docs/source/bundle-adjust.rst @@ -11,13 +11,16 @@ Scene graph classes ------------------- .. autoclass:: machinevisiontoolbox.BundleAdjust.ViewPoint + :no-index: :members: :inherited-members: .. autoclass:: machinevisiontoolbox.BundleAdjust.Landmark + :no-index: :members: :inherited-members: .. autoclass:: machinevisiontoolbox.BundleAdjust.Observation + :no-index: :members: :inherited-members: \ No newline at end of file From f1a5d998e824d82c01b886e438140dfe9c40cb9c Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Wed, 18 Nov 2026 08:58:26 +1000 Subject: [PATCH 2/5] docs: fix docstring markup that Sphinx warns about - ImageConstants: blank line after |dtype_aliases| so the following :param field is not a block-quote error (9 docstrings) - ImageSpatial: point Kernel references at machinevisiontoolbox.Kernel.Kernel, removing an ambiguous cross-reference - iwrite: the example had collapsed onto two lines; restore it - mpl_styling: pseudo-code block is not valid Python, mark it text - intro.rst: separate the camera example code from its printed output Co-Authored-By: Claude Sonnet 5.5 --- docs/source/intro.rst | 5 +++++ src/machinevisiontoolbox/ImageConstants.py | 9 +++++++++ src/machinevisiontoolbox/ImageSpatial.py | 8 ++++---- src/machinevisiontoolbox/base/graphics.py | 2 +- src/machinevisiontoolbox/base/imageio.py | 6 ++++-- 5 files changed, 23 insertions(+), 7 deletions(-) diff --git a/docs/source/intro.rst b/docs/source/intro.rst index 4775d1e8..ce65ac82 100644 --- a/docs/source/intro.rst +++ b/docs/source/intro.rst @@ -264,6 +264,11 @@ We can model a standard central-perspective camera using its known parameters: camera = mvtb.CentralCamera(f=0.015, rho=10e-6, imagesize=[1280, 1024], pp=[640, 512], name="mycamera") print(camera) + +which displays + +.. code-block:: text + Name: mycamera [CentralCamera] focal length: (array([0.015]), array([0.015])) pixel size: 1e-05 x 1e-05 diff --git a/src/machinevisiontoolbox/ImageConstants.py b/src/machinevisiontoolbox/ImageConstants.py index b3b1b20c..6d68664e 100644 --- a/src/machinevisiontoolbox/ImageConstants.py +++ b/src/machinevisiontoolbox/ImageConstants.py @@ -150,6 +150,7 @@ def Zeros( :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 @@ -209,6 +210,7 @@ def Constant( :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 @@ -415,6 +417,7 @@ def Random( :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 @@ -573,6 +576,7 @@ def Squares( :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 @@ -667,6 +671,7 @@ def Circles( :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 @@ -761,6 +766,7 @@ def Ramp( :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 @@ -859,6 +865,7 @@ def Sin( :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 @@ -941,6 +948,7 @@ def Chequerboard( :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 @@ -1033,6 +1041,7 @@ def Polygons( :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 diff --git a/src/machinevisiontoolbox/ImageSpatial.py b/src/machinevisiontoolbox/ImageSpatial.py index a7190093..99f15d1b 100644 --- a/src/machinevisiontoolbox/ImageSpatial.py +++ b/src/machinevisiontoolbox/ImageSpatial.py @@ -224,7 +224,7 @@ def convolve( Image convolution :param K: convolution kernel - :type K: :class:`~.Kernel` or ndarray, optional + :type K: :class:`~machinevisiontoolbox.Kernel.Kernel` or ndarray, optional :param mode: option for convolution, defaults to 'same' :type mode: str, optional :param border: option for boundary handling, defaults to 'reflect' @@ -290,7 +290,7 @@ def convolve( .. important:: Uses OpenCV functions ``cv2.filter2D`` and ``cv2.copyMakeBorder`` which accept multiple-channel, CV_8U, CV_16U, CV_16S, CV_32F or CV_64F images. :seealso: - :class:`~.Kernel` + :class:`~machinevisiontoolbox.Kernel.Kernel` :meth:`~smooth` `cv2.filter2D `_ `cv2.copyMakeBorder `_ @@ -376,7 +376,7 @@ def gradients( Compute horizontal and vertical gradients :param K: derivative kernel, defaults to Sobel - :type K: :class:`~machinevisiontoolbox.ImageSpatial.Kernel` or ndarray, optional + :type K: :class:`~machinevisiontoolbox.Kernel.Kernel` or ndarray, optional :param mode: option for convolution, see :meth:`convolve`, defaults to 'same' :type mode: str, optional :param border: option for boundary handling, see :meth:`convolve`, defaults to 'reflect' @@ -399,7 +399,7 @@ def gradients( :references: - |RVC3|, Section 11.5.1.3. - :seealso: :class:`~machinevisiontoolbox.ImageSpatial.Kernel` + :seealso: :class:`~machinevisiontoolbox.Kernel.Kernel` """ if K is None: K = Kernel.Sobel() diff --git a/src/machinevisiontoolbox/base/graphics.py b/src/machinevisiontoolbox/base/graphics.py index 9e08bf53..3779ed04 100644 --- a/src/machinevisiontoolbox/base/graphics.py +++ b/src/machinevisiontoolbox/base/graphics.py @@ -1013,7 +1013,7 @@ def mpl_styling( to specify styling in a compact format string, while still allowing for more detailed styling through keyword arguments with decent defaults. - .. code-block:: python + .. code-block:: text def function(*fmt, ..., **kwargs): options = mpl_styling(fmt, defaults={color='red', marker='o'}, kwargs=kwargs) diff --git a/src/machinevisiontoolbox/base/imageio.py b/src/machinevisiontoolbox/base/imageio.py index 4e45e154..551106ad 100644 --- a/src/machinevisiontoolbox/base/imageio.py +++ b/src/machinevisiontoolbox/base/imageio.py @@ -1428,8 +1428,10 @@ def iwrite( .. 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:: From b5ccf99b3c0181388349f7c6d768991fcb64df9e Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Wed, 18 Nov 2026 09:02:04 +1000 Subject: [PATCH 3/5] docs: ignore shape annotations and prose types in nitpicky mode Types such as ndarray(N,2), "2-tuple" or "Vertex subclass" are split into words and treated as class names. Ignore these pseudo-types by pattern, cutting nitpicky warnings from 2079 to 712 and leaving the genuinely unresolved references visible. Co-Authored-By: Claude Sonnet 5.5 --- docs/source/conf.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index ada71d6e..4077a5a6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -139,6 +139,19 @@ ("py:class", "H"), ("py:class", "numpy._typing.DTypeLike"), ] +# Shape annotations such as ``ndarray(N,2)`` and prose types such as "2-tuple" or +# "Vertex subclass" are split into words by Sphinx and treated as class names. +nitpick_ignore_regex = [ + ("py:class", r"ndarray"), + ("py:class", r"\d+"), # dimensions: 2, 3, 4, ... + ("py:class", r"[A-Z]\d?"), # symbolic dimensions: N, M, N1, N2, ... + ("py:class", r"n"), + ("py:class", r"N elements"), + ("py:class", r"\d+-tuple"), + ("py:class", r"N-tuple"), + ("py:class", r".* subclass"), + ("py:class", r"scalar|string|callable|axes|_type_"), +] # maybe issues with cv2 https://stackoverflow.com/questions/30939867/how-to-properly-write-cross-references-to-external-documentation-with-intersphin From 6e249e6c8cc3309b45163b4c0ac60be5653f860a Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Wed, 18 Nov 2026 09:34:26 +1000 Subject: [PATCH 4/5] docs: resolve toolbox, stdlib and matplotlib references in nitpicky mode - conf.py: resolve bare toolbox names (Image, PointCloud, ...) under machinevisiontoolbox; add the Python intersphinx inventory; ignore pgraph-relative names, OpenCV names and NumPy private typing aliases - Camera, ImagePointFeatures: correct matplotlib references (patches.Circle, axes.Axes, lines.Line2D, Axes3D) Nitpicky warnings: 712 to 357. Co-Authored-By: Claude Sonnet 5.5 --- docs/source/conf.py | 36 +++++++++++++++++++ src/machinevisiontoolbox/Camera.py | 10 +++--- .../ImagePointFeatures.py | 4 +-- 3 files changed, 43 insertions(+), 7 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 4077a5a6..c4550739 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -121,6 +121,7 @@ # -- Cross-project links ----------------------------------------------------- intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), "numpy": ("https://numpy.org/doc/stable/", None), "scipy": ("https://docs.scipy.org/doc/scipy/", None), "matplotlib": ("https://matplotlib.org/stable/", None), @@ -151,6 +152,12 @@ ("py:class", r"N-tuple"), ("py:class", r".* subclass"), ("py:class", r"scalar|string|callable|axes|_type_"), + # pgraph's inherited docstrings use names relative to the pgraph package + ("py:(class|meth|attr)", r"(Graph|UGraph|DGraph|PGraph|Edge|Vertex)(\..+)?"), + # NumPy private typing aliases leak into signatures + ("py:class", r"numpy\._typing\..*"), + # OpenCV publishes no Sphinx inventory + ("py:(class|obj|func|meth)", r"(opencv|cv2)\..*"), ] # maybe issues with cv2 https://stackoverflow.com/questions/30939867/how-to-properly-write-cross-references-to-external-documentation-with-intersphin @@ -382,7 +389,36 @@ def _sort_members_ci(self, documenters, order): # -- Sphinx application hooks ------------------------------------------------ +def _resolve_toolbox_names(app, env, node, contnode): + """Resolve a bare name such as ``Image`` or ``CameraBase`` to this package. + + Docstrings refer to toolbox classes without their full path. When Sphinx + cannot find the name as written, try it under ``machinevisiontoolbox``. + """ + if node.get("refdomain") != "py": + return None + target = node.get("reftarget", "") + if target.startswith("machinevisiontoolbox."): + return None + py = env.get_domain("py") + for prefix in ("machinevisiontoolbox.", "machinevisiontoolbox.Image."): + ref = py.resolve_xref( + env, + node.get("refdoc", ""), + app.builder, + node["reftype"], + prefix + target, + node, + contnode, + ) + if ref is not None: + return ref + return None + + def setup(app): + app.connect("missing-reference", _resolve_toolbox_names) + # Custom stylesheet for docs/site-level overrides. app.add_css_file("custom.css") diff --git a/src/machinevisiontoolbox/Camera.py b/src/machinevisiontoolbox/Camera.py index b5645b8f..147b52b9 100644 --- a/src/machinevisiontoolbox/Camera.py +++ b/src/machinevisiontoolbox/Camera.py @@ -729,7 +729,7 @@ def _new_imageplane( :param fig: Matplotlib figure number, defaults to ``None`` :type fig: int, optional :param ax: Matplotlob axes, defaults to ``None`` - :type ax: :class:`matplotlib.axes`, optional + :type ax: :class:`~matplotlib.axes.Axes`, optional :return: whether virtual image plane exists :rtype: bool @@ -854,10 +854,10 @@ def plot_point( :param pose: pose of the camera, defaults to ``None`` :type pose: :class:`~spatialmath.pose3d.SE3`, optional :param ax: axes to plot into - :type ax: :class:`matplotlib.axes` + :type ax: :class:`~matplotlib.axes.Axes` :param kwargs: additional arguments passed to :obj:`~matplotlib.pyplot.plot` :return: Matplotlib line objects - :rtype: list of :class:`~matplotlib.lines.Line2d` + :rtype: list of :class:`~matplotlib.lines.Line2D` 3D world points are first projected to the image plane and then plotted on the camera's virtual image plane. @@ -1173,11 +1173,11 @@ def plot( :param projection: projection model for new axes, defaults to 'ortho' :type projection: str, optional :param ax: axes to draw in, defaults to current 3D axes - :type ax: :class:`~matplotlib.Axes3D`, optional + :type ax: :class:`~mpl_toolkits.mplot3d.axes3d.Axes3D`, optional :raises ValueError: called unbound (eg. ``CentralCamera.plot(...)``) without a ``pose`` :return: axes drawn into - :rtype: :class:`~matplotlib.Axes3D` + :rtype: :class:`~mpl_toolkits.mplot3d.axes3d.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 diff --git a/src/machinevisiontoolbox/ImagePointFeatures.py b/src/machinevisiontoolbox/ImagePointFeatures.py index b46750e3..56695aa8 100644 --- a/src/machinevisiontoolbox/ImagePointFeatures.py +++ b/src/machinevisiontoolbox/ImagePointFeatures.py @@ -1120,7 +1120,7 @@ def plot( :type handthickness: int, optional :param handalpha: transparency of clock hand, defaults to 1 :type handalpha: int, optional - :param kwargs: options passed to :obj:`matplotlib.Circle` such as color, + :param kwargs: options passed to :class:`matplotlib.patches.Circle` such as color, alpha, edgecolor, etc. :type kwargs: dict @@ -1193,7 +1193,7 @@ def draw( :type handthickness: int, optional :param handalpha: transparency of clock hand, defaults to 1 :type handalpha: int, optional - :param kwargs: options passed to :obj:`matplotlib.Circle` such as color, + :param kwargs: options passed to :class:`matplotlib.patches.Circle` such as color, alpha, edgecolor, etc. :type kwargs: dict From ee3ad73fc0f3810fe01854f7cf2089ba1a059855 Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Wed, 18 Nov 2026 09:48:07 +1000 Subject: [PATCH 5/5] docs: resolve spatialmath and PointCloud references, fix stray Image links - conf.py: resolve bare spatialmath names (SE3, Polygon2, ...) through the smtb inventory and PointCloud names under machinevisiontoolbox.PointCloud; ignore the undocumented CameraBase, the Dtype alias and shape names like 2N - sources.rst, Kernel.py: link Image as machinevisiontoolbox.Image, and remove a stray line of repeated Image links from the Kernel docstring - BaseFeature2D.table: plain ``str`` instead of a broken :meth: reference Nitpicky warnings: 357 to 265. Co-Authored-By: Claude Sonnet 5.5 --- docs/source/conf.py | 25 ++++++++++++++++++- docs/source/sources.rst | 4 +-- .../ImagePointFeatures.py | 2 +- src/machinevisiontoolbox/Kernel.py | 2 -- 4 files changed, 27 insertions(+), 6 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index c4550739..03b23e57 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -14,6 +14,7 @@ import os import sys import inspect +from sphinx.ext import intersphinx import importlib from pathlib import Path from importlib.metadata import version as _pkg_version @@ -156,6 +157,10 @@ ("py:(class|meth|attr)", r"(Graph|UGraph|DGraph|PGraph|Edge|Vertex)(\..+)?"), # NumPy private typing aliases leak into signatures ("py:class", r"numpy\._typing\..*"), + ("py:class", r"Dtype"), # type alias used in signatures + ("py:class", r"(machinevisiontoolbox\.Camera\.)?CameraBase"), # undocumented base + ("py:class", r"\d+[A-Z]"), # shape such as 2N + ("py:(class|meth|func|attr)", r"pgraph\..*"), # OpenCV publishes no Sphinx inventory ("py:(class|obj|func|meth)", r"(opencv|cv2)\..*"), ] @@ -401,7 +406,11 @@ def _resolve_toolbox_names(app, env, node, contnode): if target.startswith("machinevisiontoolbox."): return None py = env.get_domain("py") - for prefix in ("machinevisiontoolbox.", "machinevisiontoolbox.Image."): + for prefix in ( + "machinevisiontoolbox.", + "machinevisiontoolbox.Image.", + "machinevisiontoolbox.PointCloud.", + ): ref = py.resolve_xref( env, node.get("refdoc", ""), @@ -413,6 +422,20 @@ def _resolve_toolbox_names(app, env, node, contnode): ) if ref is not None: return ref + # spatialmath names (SE3, Polygon2, plot_line, ...), via its inventory + for prefix in ( + "spatialmath.", + "spatialmath.pose3d.", + "spatialmath.pose2d.", + "spatialmath.geom2d.", + "spatialmath.base.", + "spatialmath.base.graphics.", + ): + newnode = node.copy() + newnode["reftarget"] = prefix + target + ref = intersphinx.resolve_reference_in_inventory(env, "smtb", newnode, contnode) + if ref is not None: + return ref return None diff --git a/docs/source/sources.rst b/docs/source/sources.rst index 23d94058..0248da4b 100644 --- a/docs/source/sources.rst +++ b/docs/source/sources.rst @@ -7,7 +7,7 @@ The toolbox provides a variety of sources for these objects. They can be obtained from files, from cameras, from ROS topics and bag files, from the web, and from other sources. The toolbox provides a convenient interface to these sources, and the objects -they produce are instances of the :class:`~machinevisiontoolbox.ImageCore.Image` and +they produce are instances of the :class:`~machinevisiontoolbox.Image` and :class:`~machinevisiontoolbox.PointCloudCore.PointCloud` classes, which have a large number of methods for processing and displaying them. @@ -84,7 +84,7 @@ tensor. For example, to read a video file and display each frame:: Image Sources ------------- -:class:`~machinevisiontoolbox.ImageCore.Image` objects can be conveniently obtained from a variety of sources: +:class:`~machinevisiontoolbox.Image` objects can be conveniently obtained from a variety of sources: .. autosummary:: :toctree: stubs diff --git a/src/machinevisiontoolbox/ImagePointFeatures.py b/src/machinevisiontoolbox/ImagePointFeatures.py index 56695aa8..37c085cb 100644 --- a/src/machinevisiontoolbox/ImagePointFeatures.py +++ b/src/machinevisiontoolbox/ImagePointFeatures.py @@ -238,7 +238,7 @@ def table(self) -> None: Each row is in the table includes: the index in the feature vector, centroid coordinate, feature strength, feature scale and image id. - :seealso: :meth:`str` + :seealso: ``str`` """ columns = [ Column("#"), diff --git a/src/machinevisiontoolbox/Kernel.py b/src/machinevisiontoolbox/Kernel.py index 82a5cd71..3e01805b 100644 --- a/src/machinevisiontoolbox/Kernel.py +++ b/src/machinevisiontoolbox/Kernel.py @@ -25,8 +25,6 @@ def __init__(self, K: np.ndarray, name: str | None = None) -> None: processing operations. They are created by a number of class methods that generate common kernels such as Gaussian, Laplacian, etc. - :class:`ImageCore.Image` :class:`machinevisiontoolbox.ImageCore.Image` :class:`machinevisiontoolbox.Image` - :seealso: :meth:`Gauss` :meth:`Laplace` :meth:`Sobel` :meth:`DoG` :meth:`LoG` :meth:`DGauss` :meth:`Circle` :meth:`Box` """ if not isinstance(K, np.ndarray) and K.ndim != 2: