add doc and readme

README.md

@@ -13,6 +13,10 @@ https://build.ros2.org/job/Hdev__lanelet2__ubuntu_jammy_amd64/lastBuild/)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/lanelet2.svg?label=PyPI%20downloads)](
 https://pypi.org/project/lanelet2/)
 
+## New module :rocket: : `lanelet2_ml_converter`
+
+Convert Lanelet2 maps directly to instance labels for map perception and other map-based learning tasks! `lanelet2_ml_converter` provides local instance labels of various abstraction layers and representations accessible as numpy arrays from python. Check out the `lanelet2_ml_converter` module for more information and usage examples.
+
 ## Overview
 
 Lanelet2 is a C++ library for handling map data in the context of automated driving. It is designed to utilize high-definition map data in order to efficiently handle the challenges posed to a vehicle in complex traffic scenarios. Flexibility and extensibility are some of the core principles to handle the upcoming challenges of future maps.
@@ -30,6 +34,7 @@ Features:
 - **Boost Geometry** support for all thinkable kinds of geometry calculations on map primitives
 - Released under the [**BSD 3-Clause license**](LICENSE)
 - Support for **ROS1, ROS2, Docker and Conan** (see instructions below)
+- Converter module to convert Lanelet2 maps into **local instance labels for machine learning tasks**.
 
 ![](lanelet2_core/doc/images/lanelet2_example_image.png)
 
@@ -181,6 +186,7 @@ Examples and common use cases in both C++ and Python can be found [here](lanelet
 * **lanelet2_routing** implements the routing graph for routing or reachable set or queries as well as collision checking
 * **lanelet2_maps** provides example maps and functionality to visualize and modify them easily in JOSM
 * **lanelet2_matching** provides functions to determine in which lanelet an object is/could be currently located
+* **lanelet2_ml_converter** converts Lanelet2 maps into local instance labels for machine learning tasks
 * **lanelet2_python** implements the python interface for lanelet2
 * **lanelet2_validation** provides checks to ensure a valid lanelet2 map
 * **lanelet2_examples** contains tutorials for working with Lanelet2 in C++ and Python

lanelet2_ml_converter/README.md

@@ -1,3 +1,61 @@
 # Lanelet2 ML Converter
 
-Converter module to convert Lanelet2 maps into local label instances for machine learning tasks.
+Converter module to convert Lanelet2 maps into local instance labels for machine learning tasks.
+
+![](doc/summary_flowchart.png)
+
+## Usage Examples
+
+### Python
+
+```python
+import lanelet2
+from lanelet2.core import BasicPoint2d
+from lanelet2.ml_converter import MapDataInterface
+
+pos = BasicPoint2d(10, 10)                              # set your local reference frame origin
+yaw = 0                                                 # set your local reference frame yaw angle (heading)
+mDataIf = MapDataInterface(ll2_map)                     # get the MapDataInterface object and pass the ll2 map
+mDataIf.setCurrPosAndExtractSubmap(pos, yaw)            # extract the local submap 
+lData = mDataIf.laneData(True)                          # get the LaneData local instance labels
+tfData = lData.getTensorFeatureData(True, False)        # get the local instance labels as numpy arrays
+```
+
+### C++
+```c++
+#include "lanelet2_ml_converter/MapData.h"
+#include "lanelet2_ml_converter/MapDataInterface.h"
+#include "lanelet2_ml_converter/MapFeatures.h"
+
+using TensorData = lanelet::ml_converter::LaneData::TensorFeatureData;
+
+lanelet::BasicPoint2d pos(10, 10);                      // set your local reference frame origin
+double yaw = 0;                                         // set your local reference frame yaw angle (heading)
+MapDataInterface mDataIf(laneletMap);                   // get the MapDataInterface object and pass the ll2 map
+mDataIf.setCurrPosAndExtractSubmap(pos, yaw);                    // extract the local submap 
+lanelet::ml_converter::LaneData lData = mDataIf.laneData(True);  // get the LaneData local instance labels
+TensorData tData = lData.getTensorFeatureData(True, False);      // get the local instance labels as Eigen mats
+```
+
+## Components
+
+### `MapDataInterface`
+
+Main interface class that is used to generate `LaneData` objects.
+
+### `LaneData`
+
+`LaneData` objects hold all local instance labels of a local reference frame pose.
+
+### `TensorFeatureData`
+
+Subclass of `LaneData` that holds all local instance label in a convenient numpy array / Eigen matrix form.
+
+### `LaneLineStringFeature` / `CompoundLaneLineStringFeature` / `LaneletFeature` / ...
+
+Each object of these classes holds a single instance label. You can access various information such as the map element ID and the raw or partially processed LineStrings.
+
+## Important to know
+
+- **Road border tagging**: To correctly recognize road borders, they must be tagged as such! It is not possible to automatically recognize untagged road borders, they will be processed as lane dividers.
+- **Python numpy arrays**: To make it possible to convert the underlying Eigen matrices to numpy arrays, they are copied for each access (such as calling `getTensorFeatureData`). This means that if you change a numpy array returned from a function like this, the underlying Eigen matrix or object will not be modified! 

lanelet2_ml_converter/test/test_map_data_interface.cpp

@@ -79,9 +79,7 @@ TEST_F(MLConverterTest, MapDataInterface) {  // NOLINT
     //   y.resize(mat.rows());
     //   Eigen::VectorXd::Map(&x[0], mat.rows()) = mat.col(0);
     //   Eigen::VectorXd::Map(&y[0], mat.rows()) = mat.col(1);
-    //   matplot::plot(x, y, "r")->line_width(3);
-    // }
-    // for (const auto& mat : compoundLaneDividers) {
+    //   matplot::pltrafficRulesuto& mat : compoundLaneDividers) {
     //   std::vector<double> x;
     //   std::vector<double> y;
     //   x.resize(mat.rows());