Merge PR moveit#99: Python API

... based on pybind11

.github/workflows/ci.yaml

@@ -51,6 +51,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
+        with:
+          submodules: recursive
 
       - name: Cache ccache
         uses: rhaschke/cache@main
@@ -85,7 +87,7 @@ jobs:
         uses: actions/upload-artifact@v3
         if: failure() && (steps.ici.outputs.run_target_test || steps.ici.outputs.target_test_results)
         with:
-          name: test-results-${{ matrix.env.IMAGE }}
+          name: test-results-${{ matrix.env.IMAGE }}${{ matrix.env.NAME && '-' || ''}}${{ matrix.env.NAME }}
           path: ${{ env.BASEDIR }}/target_ws/**/test_results/**/*.xml
 
       - name: Generate codecov report

.github/workflows/format.yaml

@@ -14,6 +14,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
+        with:
+          submodules: recursive
       - name: Install clang-format-10
         run: sudo apt-get install clang-format-10
       - uses: rhaschke/install-catkin_lint-action@v1.0

.gitignore

@@ -1 +1,5 @@
 *.swp
+*.pyc
+__pycache__/
+*/doc/html/
+*/doc/manifest.yaml

.gitmodules

@@ -0,0 +1,5 @@
+[submodule "core/python/pybind11"]
+	path = core/python/pybind11
+	url = https://github.com/rhaschke/pybind11
+	branch = smart_holder
+	shallow = true

.pre-commit-config.yaml

@@ -32,6 +32,7 @@ repos:
     rev: 22.3.0
     hooks:
       - id: black
+        args: ["--line-length", "100"]
 
   - repo: local
     hooks:
@@ -41,11 +42,20 @@ repos:
         entry: clang-format-10
         language: system
         files: \.(c|cc|cxx|cpp|frag|glsl|h|hpp|hxx|ih|ispc|ipp|java|js|m|proto|vert)$
-        args: ['-fallback-style=none', '-i']
+        args: ["-fallback-style=none", "-i"]
       - id: catkin_lint
         name: catkin_lint
         description: Check package.xml and cmake files
         entry: catkin_lint .
         language: system
         always_run: true
         pass_filenames: false
+
+  - repo: local
+    hooks:
+      - id: misspelled-moveit
+        name: misspelled-moveit
+        description: MoveIt should be spelled exactly as MoveIt
+        language: pygrep
+        entry: Moveit|MoveIt!
+        exclude: .pre-commit-config.yaml|README.md

core/CMakeLists.txt

@@ -3,6 +3,7 @@ project(moveit_task_constructor_core)
 
 find_package(Boost REQUIRED)
 find_package(catkin REQUIRED COMPONENTS
+	roslint
 	tf2_eigen
 	geometry_msgs
 	moveit_core
@@ -17,11 +18,14 @@ find_package(catkin REQUIRED COMPONENTS
 option(MOVEIT_CI_WARNINGS "Enable all warnings used by CI" OFF) # We use our own set of warnings
 moveit_build_options()
 
+catkin_python_setup()
+
 catkin_package(
 	LIBRARIES
 		${PROJECT_NAME}
 		${PROJECT_NAME}_stages
 		${PROJECT_NAME}_stage_plugins
+		moveit_python_tools
 	INCLUDE_DIRS
 		include
 	CATKIN_DEPENDS
@@ -30,13 +34,15 @@ catkin_package(
 		moveit_task_constructor_msgs
 		rviz_marker_tools
 		visualization_msgs
+	CFG_EXTRAS pybind11.cmake
 )
 
 add_compile_options(-fvisibility-inlines-hidden)
 
 set(PROJECT_INCLUDE ${CMAKE_CURRENT_SOURCE_DIR}/include/moveit/task_constructor)
 
 add_subdirectory(src)
+add_subdirectory(python)
 add_subdirectory(test)
 
 install(DIRECTORY include/ DESTINATION ${CATKIN_GLOBAL_INCLUDE_DESTINATION}

core/cmake/pybind11.cmake.in

@@ -0,0 +1,9 @@
+# pybind11 must use the ROS python version
+set(PYBIND11_PYTHON_VERSION ${PYTHON_VERSION_STRING})
+
+if(@INSTALLSPACE@)
+	include(${CMAKE_CURRENT_LIST_DIR}/pybind11Config.cmake)
+else()
+	# in build space, directly include pybind11 directory
+	add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/../pybind11 ${CMAKE_CURRENT_BINARY_DIR}/pybind11)
+endif()

core/doc/_templates/custom-class-template.rst

@@ -0,0 +1,34 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+   :special-members: __len__, __getitem__, __iter__, __call__, __add__, __mul__
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in methods %}
+      {%- if not item.startswith('_') %}
+      ~{{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

core/doc/_templates/custom-module-template.rst

@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+      :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

core/doc/api.rst

@@ -0,0 +1,14 @@
+.. _sec-api:
+
+API reference
+-------------
+
+.. autosummary::
+   :toctree: _autosummary
+   :caption: API
+   :recursive:
+   :template: custom-module-template.rst
+
+   moveit.task_constructor
+   pymoveit_mtc.core
+   pymoveit_mtc.stages

core/doc/basics.rst

@@ -0,0 +1,30 @@
+Basic Concepts
+==============
+
+The fundamental idea of MTC is that complex motion planning problems can be composed into a set of simpler subproblems. The top-level planning problem is specified as a Task while all subproblems are specified by Stages. Stages can be arranged in any arbitrary order and hierarchy only limited by the individual stages types. The order in which stages can be arranged is restricted by the direction in which results are passed. There are three possible stages relating to the result flow: generator, propagator, and connector stages:
+
+.. glossary::
+
+	Generators
+		compute their results independently of their neighbor stages and pass them in both directions, backwards and forwards. An example is an IK sampler for geometric poses where approaching and departing motions (neighbor stages) depend on the solution.
+
+	Propagators
+		receive the result of one neighbor stage, solve a subproblem and then propagate their result to the neighbor on the opposite site. Depending on the implementation, propagating stages can pass solutions forward, backward or in both directions separately. An example is a stage that computes a Cartesian path based on either a start or a goal state.
+
+	Connectors
+		do not propagate any results, but rather attempt to bridge the gap between the resulting states of both neighbors. An example is the computation of a free-motion plan from one given state to another.
+
+Additional to the order types, there are different hierarchy types allowing to encapsulate subordinate stages. Stages without subordinate stages are called primitive stages, higher-level stages are called container stages. There are three container types:
+
+.. glossary::
+
+	Wrappers
+		encapsulate a single subordinate stage and modify or filter the results. For example, a filter stage that only accepts solutions of its child stage that satisfy a certain constraint can be realized as a wrapper. Another standard use of this type includes the IK wrapper stage, which generates inverse kinematics solutions based on planning scenes annotated with a pose target property.
+
+	Serial Containers
+		hold a sequence of subordinate stages and only consider end-to-end solutions as results. An example is a picking motion that consists of a sequence of coherent steps.
+
+	Parallel Containers
+		combine set of subordinate stages and can be used for passing the best of alternative results, running fallback solvers or for merging multiple independent solutions. Examples are running alternative planners for a free-motion plan, picking objects with the right hand or with the left hand as a fallback, or moving the arm and opening the gripper at the same time.
+
+Stages not only support solving motion planning problems. They can also be used for all kinds of state transitions, as for instance modifying the planning scene. Combined with the possibility of using class inheritance it is possible to construct very complex behavior while only relying on a well-structured set of primitive stages.

core/doc/concepts.rst

@@ -0,0 +1,9 @@
+.. _sec-concepts:
+
+Concepts
+------------
+
+.. toctree::
+    :maxdepth: 2
+
+    basics