diff --git a/modules/python/doc/CMakeLists.txt b/modules/python/doc/CMakeLists.txt index 0a5a3e3430..66be5e73de 100644 --- a/modules/python/doc/CMakeLists.txt +++ b/modules/python/doc/CMakeLists.txt @@ -66,7 +66,7 @@ configure_file( ) add_custom_target(visp_python_bindings_doc - COMMAND ${PYTHON3_EXECUTABLE} -m pip install -r "${CMAKE_CURRENT_SOURCE_DIR}/requirements.txt" + COMMAND ${PYTHON3_EXECUTABLE} -m pip install -q -r "${CMAKE_CURRENT_SOURCE_DIR}/requirements.txt" COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_CURRENT_SOURCE_DIR}/_static" "${BINARY_BUILD_DIR}/_static" COMMAND ${PYTHON3_EXECUTABLE} -m sphinx -b html diff --git a/modules/python/doc/api.rst.in b/modules/python/doc/api.rst.in index 2d24c2efdb..004e63bc57 100644 --- a/modules/python/doc/api.rst.in +++ b/modules/python/doc/api.rst.in @@ -1,6 +1,14 @@ +.. _API reference: + API reference ============== +This API documentation is automatically generated by parsing the C++ documentation. + +.. warning:: + + Some documentation may be missing, and there may incorrect/missing links. If you are having issues, see the C++ documentation. + .. autosummary:: :toctree: _autosummary diff --git a/modules/python/doc/conf.py.in b/modules/python/doc/conf.py.in index 46cfa401e6..cd46bf0496 100644 --- a/modules/python/doc/conf.py.in +++ b/modules/python/doc/conf.py.in @@ -16,12 +16,8 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. import sys import os -from sphinx.util.logging import * - -sys.path.insert(0, os.path.abspath('../build')) - # If your documentation needs a minimal Sphinx version, state it here. # needs_sphinx = '1.0' @@ -35,7 +31,7 @@ extensions = [ "sphinx.ext.autosummary", "sphinx.ext.doctest", "sphinx_immaterial", - # "sphinx_immaterial.apidoc.python.apigen" + "sphinx_design" ] # python_apigen_modules = { @@ -159,6 +155,7 @@ html_theme_options = { "toc.sticky", "navigation.instant" ], + "globaltoc_collapse": False, "palette": [ { "media": "(prefers-color-scheme: light)", @@ -282,7 +279,11 @@ latex_elements = { # Latex figure (float) alignment #'figure_align': 'htbp', } - +rst_prolog = """ +.. role:: python(code) + :language: python + :class: highlight +""" html_logo = '_static/visp_icon_white.png' html_favicon = '_static/visp_icon.png' @@ -364,7 +365,7 @@ texinfo_documents = [ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {"python": ("https://docs.python.org/", None)} -from sphinx.util.logging import WarningLogRecordTranslator +from sphinx.util.logging import WarningLogRecordTranslator, WarningStreamHandler # Filter warning about Parameter names not matching function signature # This is somethiing that is due to pybind overloads, so we cannot do anything about it diff --git a/modules/python/doc/index.rst b/modules/python/doc/index.rst index 110acd9d28..e227c22780 100644 --- a/modules/python/doc/index.rst +++ b/modules/python/doc/index.rst @@ -1,16 +1,82 @@ ViSP Python Documentation ============================ -Welcome to the ViSP Python binding documentation! - - - .. currentmodule:: visp .. toctree:: - :glob: :maxdepth: 2 + :hidden: rst/coming_from_cpp.rst - rst/python_api.rst + rst/python_api/python_api.rst + rst/tutorials/tutorials.rst + rst/dev/dev.rst + api.rst rst/known_issues.rst + + +Welcome to the ViSP Python binding documentation! + + ViSP is a modular C++ library that allows fast development of visual servoing applications. + ViSP is developed and maintained by the `Inria Rainbow (former Lagadic) team located `_ at Inria Rennes. + + + +Introduction +---------------------------- + +This documentation is specifically aimed at developers choosing to use ViSP in Python. + +Other, more general resources, are available: + +* If you are using C++, please see `the dedicated documentation `_ + +* The ViSP wiki can be found `here `_ + +* The ViSP source code available on `GitHub `_ + +* Results and demonstrations can be seen on the `ViSP YouTube channel `_ + + +Disclaimer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This documentation does not cover the full capabilities of ViSP. Please see the C++ documentation, which contains: + +* `Tutorials `_ on: + + * The core concepts: linear algebra, image processing, etc. + * Visual servoing with 3D, 2D or photometric features + * Object pose estimation and tracking + + * With the model-based tracker (MBT) :py:class:`visp.mbt.MbGenericTracker` + * With MegaPose, a deep learning approach to pose estimation :py:class:`visp.dnn_tracker.Megapose` + +* `Examples `_ + + * Demonstrating basic feature usage + * Servoing on specific robotics platforms + * Tracking + + +There are still issues with these generated bindings: see :ref:`Known issues` + + +Getting started +^^^^^^^^^^^^^^^^^^^^^^^ + +If you are transitioning from C++, please have a look at the :ref:`CPP guide` to understand the differences between the Python and C++ versions. + + +For general ViSP + Python guidance, see the :ref:`Python API guide`. + + +For tutorials on specific features: see :ref:`Tutorials`. + +Finally, if you wish to browse the full ViSP class documentation, go to the :ref:`API reference`. + + +Customizing, extending and contributing to the bindings +-------------------------------------------------------- + +If you wish to contribute, extend or modify the bindings for your own needs, please read the :ref:`Development guide` diff --git a/modules/python/doc/requirements.txt b/modules/python/doc/requirements.txt index 1e8f099944..fdb58ef4a2 100644 --- a/modules/python/doc/requirements.txt +++ b/modules/python/doc/requirements.txt @@ -1,3 +1,4 @@ sphinx sphinx-immaterial sphinxcontrib-jsmath +sphinx-design diff --git a/modules/python/doc/rst/coming_from_cpp.rst b/modules/python/doc/rst/coming_from_cpp.rst index 18b4191a6b..b358014430 100644 --- a/modules/python/doc/rst/coming_from_cpp.rst +++ b/modules/python/doc/rst/coming_from_cpp.rst @@ -1,2 +1,157 @@ -Differences with the C++ +.. _CPP guide: + +Differences with C++ ViSP ============================== + +In this section, we highlight the differences with writing ViSP code in C++. + +Module structure +----------------------------- + +The overall module structure remains the same. +What was, in C++, referred as :code:`visp3/core/*` can now be accessed as :python:`visp.core.*` in Python. +Note that before this works in Python, you need to :python:`import visp` + + +Naming convention +----------------------------- + +In C++, each class has the prefix `vp`. In Python, this prefix has been dropped as imports can be aliased and full names can be used. + +.. testcode:: + + import visp.core + from visp.core import Matrix as vpMatrix # if the name clashes with another lib + + m = vpMatrix() + vec = visp.core.ColVector(10) # Use the full name, explicit visp use + + + +Importing a class +---------------------------- + +The syntax to import a ViSP class into the current scope is different. + +In C++, including a header file pulls everything in it (functions and classes). + + +In the ViSP Python API, no distinction is made between the different headers: everything is at the same level in the package hierarchy. +In Python, you can import a single symbol. + +Thus, if a single header contains two symbols in ViSP, you will need to import both on the Python side. + +Below, the difference in syntax between C++ and Python on imports is illustrated: + +.. tab-set:: + + .. tab-item:: C++ + :sync: cpp + + .. code-block:: cpp + + #include + #include + #include + + + .. tab-item:: Python + :sync: python + + .. testcode:: + + from visp.core import ImageConvert + from visp.core import ColVector, Matrix # Grouping relevant imports + + +You can also import everything from a single submodule: + +.. tab-set:: + + .. tab-item:: C++ + :sync: cpp + + .. code-block:: cpp + + #include + + + .. tab-item:: Python + :sync: python + + .. testcode:: + + from visp.core import * + + +Changes in function parameters +-------------------------------------- + +For some functions, the Python API differs from the C++ one, mainly in the input arguments and return type. + +Due to python considering basic types as immutable, it is no longer possible to modify them passing their reference to a function call. + +Thus, we have made the choice to modify the functions such that these immutable types, if they are modified, are returned along with the original type. + +This encompasses other types, such as lists (std::vector), and dictionaries (maps) + + +Naively translating the use of :code:`convertPoint` from C++: + +.. testcode:: error_args + + from visp.core import PixelMeterConversion, CameraParameters + cam = CameraParameters(600, 600, 320, 240) + u, v = 240, 320 + x, y = 0, 0 + PixelMeterConversion.convertPoint(cam, u, v, x, y) # WRONG: C++-like version, using references to modify x and y + +Would lead to an error such as: + +.. testoutput:: error_args + :options: -ELLIPSIS, +NORMALIZE_WHITESPACE, +IGNORE_EXCEPTION_DETAIL + + Traceback (most recent call last): + File "", line 1, in + TypeError: convertPoint(): incompatible function arguments. The following argument types are supported: + 1. (cam: _visp.core.CameraParameters, u: float, v: float) -> Tuple[float, float] + 2. (cam: _visp.core.CameraParameters, iP: _visp.core.ImagePoint) -> Tuple[float, float] + + Invoked with: Camera parameters for perspective projection without distortion: + px = 600 py = 600 + u0 = 320 v0 = 240 + , 240, 320, 0, 0 + +Because this function has been modified to return a tuple of :code:`Tuple[float, float]` (the x and y values). +The x and y arguments are no longer accepted, as they are output only. + +Thus, the correct function call is: + +.. testcode:: error_args + + from visp.core import PixelMeterConversion, CameraParameters + cam = CameraParameters(600, 600, 320, 240) + u, v = 240, 320 + x, y = PixelMeterConversion.convertPoint(cam, u, v) + + +If you have such errors, it is recommended that you look at the Python :ref:`API reference` for the function and look at its signature. + + + +.. tab-set:: + + .. tab-item:: C++ + :sync: cpp + + .. code-block:: cpp + + #include + + + .. tab-item:: Python + :sync: python + + .. testcode:: + + from visp.core import * diff --git a/modules/python/doc/rst/dev/config.rst b/modules/python/doc/rst/dev/config.rst new file mode 100644 index 0000000000..e0775eebc1 --- /dev/null +++ b/modules/python/doc/rst/dev/config.rst @@ -0,0 +1,2 @@ +Configuration files +==================== diff --git a/modules/python/doc/rst/dev/custom_bindings.rst b/modules/python/doc/rst/dev/custom_bindings.rst new file mode 100644 index 0000000000..ec34cb9062 --- /dev/null +++ b/modules/python/doc/rst/dev/custom_bindings.rst @@ -0,0 +1,2 @@ +Adding a custom function binding +================================= diff --git a/modules/python/doc/rst/dev/dev.rst b/modules/python/doc/rst/dev/dev.rst new file mode 100644 index 0000000000..2ee80f093f --- /dev/null +++ b/modules/python/doc/rst/dev/dev.rst @@ -0,0 +1,13 @@ +.. _Development guide: + +Modifying and contributing to the bindings +==================== + +.. toctree:: + :glob: + :maxdepth: 2 + + how.rst + config.rst + custom_bindings.rst + python_side.rst diff --git a/modules/python/doc/rst/dev/how.rst b/modules/python/doc/rst/dev/how.rst new file mode 100644 index 0000000000..31bb1d3823 --- /dev/null +++ b/modules/python/doc/rst/dev/how.rst @@ -0,0 +1,2 @@ +How bindings are generated +=========================== diff --git a/modules/python/doc/rst/dev/python_side.rst b/modules/python/doc/rst/dev/python_side.rst new file mode 100644 index 0000000000..0122871cf6 --- /dev/null +++ b/modules/python/doc/rst/dev/python_side.rst @@ -0,0 +1,2 @@ +Adding a Python side improvement +================================= diff --git a/modules/python/doc/rst/known_issues.rst b/modules/python/doc/rst/known_issues.rst index cd33877295..d991af0d1e 100644 --- a/modules/python/doc/rst/known_issues.rst +++ b/modules/python/doc/rst/known_issues.rst @@ -1,7 +1,24 @@ -List of todos +.. _Known issues: + +Known issues ====================== -What remains to be done +We are aware of some issues remaining + + +No implicit conversion from ViSP types to Numpy +------------------------------------------------- + + +ViSP 3rd party types (such as cv::Mat) cannot be used from Python +------------------------------------------------- + +Cannot inherit from ViSP +------------------------------------------------ + + + + Changes to ViSP ------------------ diff --git a/modules/python/doc/rst/python_api/conversions.rst b/modules/python/doc/rst/python_api/conversions.rst index 43e386f1e0..d66db575d5 100644 --- a/modules/python/doc/rst/python_api/conversions.rst +++ b/modules/python/doc/rst/python_api/conversions.rst @@ -99,7 +99,7 @@ Thus, this code will not work: ValueError: assignment destination is read-only >>> T = HomogeneousMatrix() - >>> R.numpy()[0, 1] = 1.0 + >>> T.numpy()[0, 1] = 1.0 Traceback (most recent call last): File "", line 1, in ValueError: assignment destination is read-only diff --git a/modules/python/doc/rst/python_api/python_api.rst b/modules/python/doc/rst/python_api/python_api.rst new file mode 100644 index 0000000000..3e803a1885 --- /dev/null +++ b/modules/python/doc/rst/python_api/python_api.rst @@ -0,0 +1,10 @@ +.. _Python API guide: + +General ViSP + Python help +==================== + +.. toctree:: + :glob: + :maxdepth: 2 + + conversions.rst diff --git a/modules/python/doc/rst/tutorials/ibvs.rst b/modules/python/doc/rst/tutorials/ibvs.rst new file mode 100644 index 0000000000..9fe61b2ffe --- /dev/null +++ b/modules/python/doc/rst/tutorials/ibvs.rst @@ -0,0 +1,2 @@ +Simulated Image-Based visual servoing +=================================== diff --git a/modules/python/doc/rst/tutorials/pbvs.rst b/modules/python/doc/rst/tutorials/pbvs.rst new file mode 100644 index 0000000000..50e04a169a --- /dev/null +++ b/modules/python/doc/rst/tutorials/pbvs.rst @@ -0,0 +1,2 @@ +Simulated Pose-Based visual servoing +=================================== diff --git a/modules/python/doc/rst/python_api.rst b/modules/python/doc/rst/tutorials/tutorials.rst similarity index 55% rename from modules/python/doc/rst/python_api.rst rename to modules/python/doc/rst/tutorials/tutorials.rst index a49cb65a90..f26ab19243 100644 --- a/modules/python/doc/rst/python_api.rst +++ b/modules/python/doc/rst/tutorials/tutorials.rst @@ -1,8 +1,11 @@ -Python tips +.. _Tutorials: + +Tutorials ==================== .. toctree:: :glob: :maxdepth: 2 - python_api/conversions.rst + ibvs.rst + pbvs.rst