[GSoC 2020] Extending PCL for use with Python: Bindings generation using Pybind11

.github/workflows/black.yml

@@ -0,0 +1,52 @@
+name: Black Formatting
+
+on: [push]
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  Black:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v2
+
+      # Setup python version
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.8"
+
+      # Install pip and packages
+      - name: Install pip
+        run: python -m pip install --upgrade pip
+
+      - name: Install black
+        run: pip install black
+
+      # Format with black
+      - name: Format with black
+        run: |
+          cd bindings/python
+          black .
+
+      # Diff check
+      - name: Check git diff
+        # Output the diff in ${GITHUB_WORKSPACE}
+        run: git diff > black_formatting_diff.patch
+
+      # Exit if diff
+      - name: Set job exit status
+        run: "[ ! -s black_formatting_diff.patch ]"
+
+      # Artifacts
+      - name: Upload formatting diff
+        uses: actions/upload-artifact@v2
+        with:
+          # We are in ${GITHUB_WORKSPACE}
+          # ${GITHUB_SHA} won't work: use ${{ github.sha }}
+          name: black_formatting_diff-${{ github.sha }}
+          path: black_formatting_diff.patch
+        # Use always() to always run this step to publish test results when there are test failures
+        if: ${{ always() }}

.github/workflows/pytest.yml

@@ -0,0 +1,65 @@
+name: Pytest
+
+on: [push]
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  Pytest:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.6, 3.7, 3.8]
+
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v2
+
+      # Setup python version
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version  }}
+      - name: Display python version
+        run: python -c "import sys; print(sys.version)"
+
+      # Install pip and packages
+      - name: Install pip
+        run: python -m pip install --upgrade pip
+
+      - name: Install pytest
+        run: pip install pytest
+
+      # Install clang and it's python inteface via apt
+      - name: Add llvm keys
+        run: |
+          wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
+          echo 'deb http://apt.llvm.org/bionic/ llvm-toolchain-bionic-11 main' | sudo tee -a /etc/apt/sources.list
+          echo 'deb-src http://apt.llvm.org/bionic/ llvm-toolchain-bionic-11 main' | sudo tee -a /etc/apt/sources.list
+      - name: Install libclang and its python bindings
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libclang-11-dev python3-clang-11
+
+      # Add dist-package to path to enable apt installed python3-clang import
+      - name: Add dist-packages to PYTHONPATH
+        run: echo "::set-env name=PYTHONPATH::${PYTHON_PATH}:/usr/lib/python3/dist-packages"
+      - name: Display PYTHONPATH
+        run: python -c "import sys; print('\n'.join(sys.path))"
+
+      # Test with pytest
+      - name: Test with pytest
+        run: cd ${_PYTHON_BINDINGS_PATH} && pytest --junitxml=${GITHUB_WORKSPACE}/result_${{ matrix.python-version }}.xml
+        env:
+          _PYTHON_BINDINGS_PATH: bindings/python
+
+      # Artifacts
+      - name: Upload pytest test results
+        uses: actions/upload-artifact@v2
+        with:
+          # We are in ${GITHUB_WORKSPACE}
+          # ${GITHUB_SHA} won't work: use ${{ github.sha }}
+          name: pytest_py${{ matrix.python-version }}-${{ github.sha }}
+          path: result_${{ matrix.python-version }}.xml
+        # Use always() to always run this step to publish test results when there are test failures
+        if: ${{ always() }}

bindings/discussion.md

@@ -0,0 +1,158 @@
+## Python bindings
+
+### Shared pointer usage
+#### [05-06-2020]
+- > When we want `cloud = pcl.PointCloud[pcl.PointXYZ]()` to be a shared_ptr by default, we set the holder class as shared_ptr. This is needed in some cases because the interface otherwise would be non-idomatic:
+  > ```py
+  > import pcl
+  > 
+  > filter = pcl.filters.PassThrough[pcl.PointXYZ]()
+  > filter.setInput(cloud)
+  > ```
+  > 
+  > Here, cloud needs to be a shared_ptr. That can be done in 2 ways
+  > 1. `cloud = pcl.PointCloud[pcl.PointXYZ]()` and the holder class as shared_ptr
+  > 2. `cloud = pcl.make_shared[pcl.PointXYZ]()` and holder class as void
+  > 
+  > The issue is the ease-of-use and expected semantics
+  > ```py
+  > cloud2 = cloud1 # Python user will assume this is a shallow copy
+  > ```
+  > 
+  > This will only be true for a variable held in a shared_ptr. This is the semantics in Python.
+  > 
+  > However, wrapping everything in shared_ptr has downsides for C++ wrapper:
+  > ```py
+  > import pcl
+  > 
+  > point = pcl.PointXYZ()
+  > cloud[100] = point
+  > ```
+  > 
+  > If PointXYZ is held in a shared_ptr... things go south. If not, things go south
+
+### Handling unions
+#### [04-06-2020]
+- > given `assert(&(union.r) == &(union.rgb));` does the following hold:
+  > `assert id(union_wrapper.r) == id(union_wrapper.rgb) ?`
+  Yes. Tested.
+- Working example:
+  ```cpp
+  #include <pybind11/pybind11.h>
+  namespace py = pybind11;
+
+  union RGB {
+    int rgb;
+    struct {
+      int r;
+      int g;
+      int b;
+    };
+  };
+
+  PYBIND11_MODULE(pcl, m)
+  {
+    py::class_<RGB>(m, "RGB")
+        .def(py::init<>())
+        .def_property(
+            "rgb",
+            [](RGB& self) -> int { return self.rgb; },
+            [](RGB& self, int value) { self.rgb = value; })
+        .def_property(
+            "r",
+            [](RGB& self) -> int { return self.r; },
+            [](RGB& self, int value) { self.r = value; })
+        .def_property(
+            "g",
+            [](RGB& self) -> int { return self.g; },
+            [](RGB& self, int value) { self.g = value; })
+        .def_property(
+            "b",
+            [](RGB& self) -> int { return self.b; },
+            [](RGB& self, int value) { self.b = value; });
+  }
+  ```
+
+### General
+#### [05-06-2020]
+- MetaCPP relies on Clang's LibTooling to generate all the metadata: https://github.com/mlomb/MetaCPP
+
+#### [04-06-2020]
+- > Was reading this yesterday: https://peerj.com/articles/cs-149.pdf
+  > 
+  > Summary: 
+  > - They too, automatically generate Python bindings for C++ code using Boost::Python.
+  > - The whole process is python based.
+  > - Same design as to what we have in mind i.e., parse, process, and generate.
+  > - Their data structure of choice for the whole process is Abstract Semantic Graph: https://github.com/StatisKit/AutoWIG/blob/master/src/py/autowig/asg.py
+  > - The architecture is plugin-based, and somebody added a pybind plugin some months back: https://github.com/StatisKit/AutoWIG/blob/master/src/py/autowig/pybind11_generator.py
+  > - They use libclang for frontend parsing(python API). The project was done some time back so they wrote their own py-libclang code: https://github.com/StatisKit/AutoWIG/blob/master/src/py/autowig/libclang_parser.py
+  > - Repo: https://github.com/StatisKit/AutoWIG
+  > 
+  > I think it can act as a good reference for the project. Have a look at the pdf and the source if you wish.
+  > The libclang python part can be explored from their repo as of now (as python-libclang has no documentation whatsoever and the 1-2 example articles are outdated)
+- Problems:
+  > Templates:
+  > * suffixing doesn't work well. Unless you're a fan of the pseudo-Hungarian notation espoused by older devs (and by MS). It's ok for 1 (or maybe 2) arguments.
+  > * Templates in Python represent an instantiation of C++ template. It should be easy to add/remove an instantiation without affecting needless code. It should also be visually easy to switch the template type without having to lookup the notation or count underscores
+  > * Python has a strong syntax for this: index lookup via __getitem__ and __setitem__
+  > * Using strings as keys is bad because the editor can't help if spelling is wrong. Pandas MultiKey failed here.
+- Use of a templating engine for pybind11 code gen (jinja2>mako)
+
+#### [03-06-2020]
+- Ambiguity in the phrase: "full control over clang's AST"
+
+#### [02-06-2020]
+- Use of python bindings of libclang, for faster prototyping: https://github.com/llvm/llvm-project/blob/master/clang/bindings/python/clang/cindex.py 
+- > protyping and exploring python bindings in which everything is runtime and can be done interactively would usually be my first approach
+
+#### [28-05-2020]
+- > While reading lsst's documentation, came to find out they use a __str__ method:
+  > ```py
+  > cls.def("__str__", [](Class const& self) {
+  >     std::ostringstream os;
+  >     os << self;
+  >     return os.str();
+  > });
+  > ```
+- > the << operator with ostreams is the most common way in C++ of extracting a string representation of a given object (I have no idea why there's no practice of implementing the cast to string method),
+That being said I believe you can use << with std::stringstreams, effectively allowing you to fetch a string representation of PCL objects which have operator<< (std::ostream, ....) implemented.
+
+#### [15-05-2020]
+- > You can create docstring from \brief part and copy the function signature via libtooling.
+
+#### [09-05-2020]
+- Start with binding PointTypes.
+- AST parsing helps in cases of convoluted code.
+- > We can keep 2 approaches in parallel:
+  > 1. header parser on a limited number of files
+  > 2. libtooling to replace it
+  > 1st will allow the pipeline to be developed
+  > 2nd will replace that
+- > We can make a prototype which works on manually provided API points
+- > From my understanding:
+  > 1. Code -> AST -> JSON: use some tool for it first, then replace with libtooling
+  > 2. JSON -> cpp: Python tool, language dependent
+  > 3. CMake + compile_database.json: rest of toolchain
+  > 4. organize properly so usage in LANG is nice
+
+#### [05-05-2020]
+- > I'd put PyPi integration immediately after we get 1 module working. That'd allow us to keep shipping improved bindings after GSoC (in case the timeline gets delayed)
+The order in which modules are tackled should be the dependency order (because we don't have the popularity data from our users)
+
+***
+
+## Javascript Bindings
+#### [05-05-2020]
+- Webassembly as an option: https://en.wikipedia.org/wiki/WebAssembly
+- Emscripten as an option: https://emscripten.org/
+- > *  Getting clang to compile to WebAsm will be the best "performance".
+  > * Using Emscripten on the other hand is a well-travelled road, but the performance will be similar to hand written JS (or worse).
+  > Both approaches need clang so that's a milestone we need to conquer first.
+
+***
+
+## Jupyter Visualisation
+#### [05-05-2020]
+- > WebGL view straddles JS bindings and Python bindings. It should come before JS bindings in terms of priority keeping in mind the popularity of Python as a second language for the kind of C++ users PCL attracts (academia)
+- > https://jupyter.org/widgets has pythreejs which is embedding js in python. .... That's 1 step above webgl, involves using JS in Py, but is faster to get up and running.... We can tackle this based on time when we reach some stage

bindings/python/CMakeLists.txt

@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 3.5)
+project(bindings)
+
+# find_package(PCL REQUIRED)
+find_package(PCL COMPONENTS common REQUIRED)
+
+# We can replace `find_package` with `add_subdirectory`, depending on usage.
+# https://pybind11.readthedocs.io/en/stable/compiling.html#find-package-vs-add-subdirectory 
+find_package(pybind11)
+
+pybind11_add_module(pcl ${CMAKE_CURRENT_SOURCE_DIR}/pybind11-gen/common/include/pcl/impl/point_types.cpp)
+
+target_link_libraries(pcl PRIVATE ${PCL_LIBRARIES})
+# add_dependencies(pcl_demo some_other_target)

bindings/python/README.md

@@ -0,0 +1,32 @@
+## Python bindings for PCL
+
+### common-archive
+- `point_types.json`: contains JSON based meta of `point_types.h` and `point_types.hpp`.
+- `py_point_types.cpp`: file generated by `generate_bindings.py` taking meta info from `point_types.json`.
+- `union_test.cpp`: testing file for handling of unions.
+
+### generate_bindings.py
+- Converts JSON data to pybind11 C++ code.
+- Run:
+  ```py
+	python3 generate_bindings.py <path/to/json>
+	```
+
+### CMakeLists.txt
+- Finding PCL and pybind11, then adding the python module(s) via `pybind11_add_module` (which is a wrapper over `add_library`).
+
+### setup.py
+- For using setuptools. Uses `CMakeLists.txt`.
+
+### libclang.py
+- Using python libclang to parse C++ code, for generation of metadata by static analysis.
+- Run:
+  ```py
+	python3 libclang.py <path/to/file>
+	```
+
+### json/*
+- JSON output generated by `libclang.py`
+
+### pybind11/* 
+- pybind11 C++ outupt generated by `generate_bindings.py`

bindings/python/scripts/context.py

@@ -0,0 +1,6 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+import scripts