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 diff --git a/docs/source/conf.py b/docs/source/conf.py index ada71d6e..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 @@ -121,6 +122,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), @@ -139,6 +141,29 @@ ("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_"), + # 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\..*"), + ("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)\..*"), +] # maybe issues with cv2 https://stackoverflow.com/questions/30939867/how-to-properly-write-cross-references-to-external-documentation-with-intersphin @@ -369,7 +394,54 @@ 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.", + "machinevisiontoolbox.PointCloud.", + ): + ref = py.resolve_xref( + env, + node.get("refdoc", ""), + app.builder, + node["reftype"], + prefix + target, + 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 + + 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/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/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/Camera.py b/src/machinevisiontoolbox/Camera.py index 4a0920ce..b25e32c5 100644 --- a/src/machinevisiontoolbox/Camera.py +++ b/src/machinevisiontoolbox/Camera.py @@ -733,7 +733,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 @@ -858,10 +858,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. @@ -1177,11 +1177,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/ImageConstants.py b/src/machinevisiontoolbox/ImageConstants.py index 10bc5b8d..5993e9c9 100644 --- a/src/machinevisiontoolbox/ImageConstants.py +++ b/src/machinevisiontoolbox/ImageConstants.py @@ -152,6 +152,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 @@ -211,6 +212,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 @@ -417,6 +419,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 @@ -576,6 +579,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 @@ -670,6 +674,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 @@ -764,6 +769,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 @@ -862,6 +868,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 @@ -944,6 +951,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 @@ -1037,6 +1045,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/ImagePointFeatures.py b/src/machinevisiontoolbox/ImagePointFeatures.py index 41fe1dfb..1fca13da 100644 --- a/src/machinevisiontoolbox/ImagePointFeatures.py +++ b/src/machinevisiontoolbox/ImagePointFeatures.py @@ -240,7 +240,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("#"), @@ -1123,7 +1123,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 @@ -1196,7 +1196,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 diff --git a/src/machinevisiontoolbox/ImageSpatial.py b/src/machinevisiontoolbox/ImageSpatial.py index a51ca179..6d910ab6 100644 --- a/src/machinevisiontoolbox/ImageSpatial.py +++ b/src/machinevisiontoolbox/ImageSpatial.py @@ -192,7 +192,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' @@ -258,7 +258,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 `_ @@ -348,7 +348,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' @@ -371,7 +371,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/Kernel.py b/src/machinevisiontoolbox/Kernel.py index bec1c735..89693c73 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: diff --git a/src/machinevisiontoolbox/base/graphics.py b/src/machinevisiontoolbox/base/graphics.py index ef17c201..87203cd2 100644 --- a/src/machinevisiontoolbox/base/graphics.py +++ b/src/machinevisiontoolbox/base/graphics.py @@ -1016,7 +1016,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 c323819d..523c96eb 100644 --- a/src/machinevisiontoolbox/base/imageio.py +++ b/src/machinevisiontoolbox/base/imageio.py @@ -1430,8 +1430,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::