docs: update LIO-SAM and vector map documentation (#465)

* init LIO-SAM Signed-off-by: ismetatabay <[email protected]> * init UTM to MGRS converter Signed-off-by: ismetatabay <[email protected]> * init downsampling Signed-off-by: ismetatabay <[email protected]> * init Vector map Signed-off-by: ismetatabay <[email protected]> * add lanelet page Signed-off-by: ismetatabay <[email protected]> * docs: update lio-sam (#2) Signed-off-by: ismetatabay <[email protected]> * init crosswalk Signed-off-by: ismetatabay <[email protected]> * init stop line Signed-off-by: ismetatabay <[email protected]> * init traffic light Signed-off-by: ismetatabay <[email protected]> * init speed bump Signed-off-by: ismetatabay <[email protected]> * init detection area Signed-off-by: ismetatabay <[email protected]> * fix some sentences and typos Signed-off-by: ismetatabay <[email protected]> * add LIO-SAM link to lanelet2 documentation Signed-off-by: ismetatabay <[email protected]> --------- Signed-off-by: ismetatabay <[email protected]>
autowarefoundation · Nov 2, 2023 · 23b81e6 · 23b81e6
1 parent ffa8491
commit 23b81e6
Show file tree

Hide file tree

Showing 33 changed files with 949 additions and 31 deletions.
diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/.pages
@@ -1,3 +1,6 @@
 nav:
   - index.md
   - Open-source SLAM algorithms: open-source-slam
+  - Converting UTM map to MGRS map: converting-utm-to-mgrs-map
+  - Pointcloud map downsampling: pointcloud-map-downsampling
+  - Creating a vector map: creating-vector-map
diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/converting-utm-to-mgrs-map/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/converting-utm-to-mgrs-map/.pages
@@ -0,0 +1,2 @@
+nav:
+  - index.md
diff --git a/...o-guides/integrating-autoware/creating-maps/converting-utm-to-mgrs-map/index.md b/...o-guides/integrating-autoware/creating-maps/converting-utm-to-mgrs-map/index.md
@@ -0,0 +1,110 @@
+# Converting UTM maps to MGRS map format
+
+## Overview
+
+If you want to use MGRS (Military Grid Reference System) format in Autoware,
+you need to convert UTM (Universal Transverse Mercator) map to MGRS format.
+In order to do that, we will use [UTM to MGRS pointcloud converter](https://github.com/leo-drive/pc_utm_to_mgrs_converter) ROS 2 package provided by Leo Drive.
+
+## Installation
+
+### Dependencies
+
+- ROS 2
+- PCL-conversions
+- [GeographicLib](https://geographiclib.sourceforge.io/C++/doc/install.html)
+
+To install dependencies:
+
+```bash
+sudo apt install ros-humble-pcl-conversions \
+       geographiclib-tools
+```
+
+### Building
+
+```bash
+    cd <PATH-TO-YOUR-ROS-2-WORKSPACE>/src
+    git clone https://github.com/leo-drive/pc_utm_to_mgrs_converter.git
+    cd ..
+    colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
+```
+
+### Usage
+
+After the installation of converter tool,
+we need to define northing,
+easting and ellipsoid height of local UTM map origin in `pc_utm_to_mgrs_converter.param.yaml`.
+For example, you can use latitude,
+longitude and altitude values in the navsatfix message from your GNSS/INS sensor.
+
+??? note "Sample ROS 2 topic echo from navsatfix message"
+
+    ```sh
+    header:
+    stamp:
+    sec: 1694612439
+    nanosec: 400000000
+    frame_id: GNSS_INS/gnss_ins_link
+    status:
+    status: 0
+    service: 1
+    latitude: 41.0216110801253
+    longitude: 28.887096461148346
+    altitude: 74.28264078891529
+    position_covariance:
+    - 0.0014575386885553598
+    - 0.0
+    - 0.0
+    - 0.0
+    - 0.004014162812381983
+    - 0.0
+    - 0.0
+    - 0.0
+    - 0.0039727711118757725
+    position_covariance_type: 2
+    ```
+
+After that, you need to convert latitude and longitude values to northing and easting values.
+You can use any converter on the internet for converting latitude longitude values to UTM.
+(i.e., [UTMconverter](https://www.latlong.net/lat-long-utm.html))
+
+Now, we are ready to update `pc_utm_to_mgrs_converter.param.yaml`,
+example for our navsatfix message:
+
+```diff
+/**:
+  ros__parameters:
+      # Northing of local origin
+-     Northing: 4520550.0
++     Northing: 4542871.33
+
+      # Easting of local origin
+-     Easting: 698891.0
++     Easting: 658659.84
+
+      # Elipsoid Height of local origin
+-     ElipsoidHeight: 47.62
++     ElipsoidHeight: 74.28
+```
+
+Lastly, we will update input and pointcloud the map path in `pc_utm_to_mgrs_converter.launch.xml`:
+
+```diff
+...
+- <arg name="input_file_path" default="/home/melike/projects/autoware_data/gebze_pospac_map/pointcloud_map.pcd"/>
++ <arg name="input_file_path" default="<PATH-TO-YOUR-INPUT-PCD-MAP>"/>
+- <arg name="output_file_path" default="/home/melike/projects/autoware_data/gebze_pospac_map/pointcloud_map_mgrs_orto.pcd"/>
++ <arg name="output_file_path" default="<PATH-TO-YOUR-OUTPUT-PCD-MAP>"/>
+...
+```
+
+After the setting of the package, we will launch pc_utm_to_mgrs_converter:
+
+```bash
+ros2 launch pc_utm_to_mgrs_converter pc_utm_to_mgrs_converter.launch.xml
+```
+
+The conversion process will be started,
+you should see `Saved <YOUR-MAP-POINTS-SIZE> data points saved to <YOUR-OUTPUT-MAP-PATH>` message on your terminal.
+MGRS format pointcloud map should be saved on your output map directory.
diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/creating-vector-map/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/creating-vector-map/.pages
@@ -0,0 +1,8 @@
+nav:
+  - index.md
+  - Lanelet2: lanelet2
+  - Crosswalk: crosswalk
+  - Stop line: stop-line
+  - Traffic light: traffic-light
+  - Speed bump: speed-bump
+  - Detection area: detection-area
diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/creating-vector-map/crosswalk/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/creating-vector-map/crosswalk/.pages
@@ -0,0 +1,2 @@
+nav:
+  - index.md
diff --git a/...-autoware/creating-maps/creating-vector-map/crosswalk/images/crosswalk-test.png b/...-autoware/creating-maps/creating-vector-map/crosswalk/images/crosswalk-test.png
diff --git a/...uides/integrating-autoware/creating-maps/creating-vector-map/crosswalk/index.md b/...uides/integrating-autoware/creating-maps/creating-vector-map/crosswalk/index.md
@@ -0,0 +1,74 @@
+# Crosswalk attribute
+
+Behavior velocity planner's [crosswalk module](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_crosswalk_module/) plans velocity
+to stop or decelerate for pedestrians approaching or walking on a crosswalk.
+In order to operate that, we will add crosswalk attribute to our lanelet2 map.
+
+## Creating a crosswalk attribute
+
+In order to create a crosswalk on your map, please follow these steps:
+
+1. Click `Abstraction` button on top panel.
+2. Select `Crosswalk` from the panel.
+3. Click and draw crosswalk on your pointcloud map.
+
+You can see these steps in the crosswalk creating demonstration video:
+
+![type:video](https://youtube.com/embed/J6WrL8dkFhI)
+
+### Testing created crosswalk with planning simulator
+
+After the completing of creating the map, we need to save it.
+To that please click `File` --> `Export Lanelet2Maps` then download.
+
+After the download is finished,
+we need to put lanelet2 map and pointcloud map on the same location.
+The directory structure should be like this:
+
+```diff
++ <YOUR-MAP-DIRECTORY>/
++  ├─ pointcloud_map.pcd
++  └─ lanelet2_map.osm
+```
+
+If your .osm or .pcd map file's name is different from these names,
+you need to update autoware.launch.xml:
+
+```diff
+  <!-- Map -->
+-  <arg name="lanelet2_map_file" default="lanelet2_map.osm" description="lanelet2 map file name"/>
++  <arg name="lanelet2_map_file" default="<YOUR-LANELET-MAP-NAME>.osm" description="lanelet2 map file name"/>
+-  <arg name="pointcloud_map_file" default="pointcloud_map.pcd" description="pointcloud map file name"/>
++  <arg name="pointcloud_map_file" default="<YOUR-POINTCLOUD-MAP-NAME>.pcd" description="pointcloud map file name"/>
+```
+
+Now we are ready to launch the planning simulator:
+
+```bash
+ros2 launch autoware_launch planning_simulator.launch.xml map_path:=<YOUR-MAP-FOLDER-DIR> vehicle_model:=<YOUR-VEHICLE-MODEL> sensor_model:=<YOUR-SENSOR-KIT>
+```
+
+Example for tutorial_vehicle:
+
+```bash
+ros2 launch autoware_launch planning_simulator.launch.xml map_path:=$HOME/Files/autoware_map/tutorial_map/ vehicle_model:=tutorial_vehicle sensor_model:=tutorial_vehicle_sensor_kit vehicle_id:=tutorial_vehicle
+```
+
+1. Click `2D Pose Estimate` button on rviz or press `P` and give a pose for initialization.
+2. Click `2D Goal Pose` button on rviz or press `G` and give a pose for goal point.
+3. We need to add pedestrians to crosswalk, so activate interactive pedestrians from `Tool Properties` panel on rviz.
+4. After that, please press `Shift`, then click right click button for inserting pedestrians.
+5. You can control inserted pedestrian via dragging right click.
+
+Crosswalk markers on rviz:
+
+<figure markdown>
+  ![crosswalk-test](images/crosswalk-test.png){ align=center }
+  <figcaption>
+    Crosswalk test on the created map.
+  </figcaption>
+</figure>
+
+You can check your crosswalk elements in the planning simulator as this demonstration video:
+
+![type:video](https://youtube.com/embed/hhwBku_1qmA)
diff --git a/...ow-to-guides/integrating-autoware/creating-maps/creating-vector-map/detection-area/.pages b/...ow-to-guides/integrating-autoware/creating-maps/creating-vector-map/detection-area/.pages
@@ -0,0 +1,2 @@
+nav:
+  - index.md
diff --git a/...creating-maps/creating-vector-map/detection-area/images/detection-area-test.png b/...creating-maps/creating-vector-map/detection-area/images/detection-area-test.png
diff --git a/.../integrating-autoware/creating-maps/creating-vector-map/detection-area/index.md b/.../integrating-autoware/creating-maps/creating-vector-map/detection-area/index.md
@@ -0,0 +1,76 @@
+# Detection area element
+
+Behavior velocity planner's [detection area](https://autowarefoundation.github.io/autoware.universe/main/planning/behavior_velocity_detection_area_module/) plans velocity
+when if pointcloud is detected in a detection area defined on a map, the stop planning will be executed at the predetermined point.
+In order to operate that, we will add a detection area element to our lanelet2 map.
+
+## Creating a detection area element
+
+In order to create a detection area on your map, please follow these steps:
+
+1. Click `Lanelet2Maps` button on top panel.
+2. Select `Detection Area` from the panel.
+3. Please select lanelet which stop line to be added.
+4. Click and insert `Detection Area` on your pointcloud map.
+5. You can change the dimensions of the detection area with clicking points on the corners of the detection area. For more information, you can check the demonstration video.
+
+You can see these steps in the detection area creating demonstration video:
+
+![type:video](https://youtube.com/embed/RUJvXok-ncQ)
+
+### Testing created detection area with planning simulator
+
+After the completing of creating the map, we need to save it.
+To that please click `File` --> `Export Lanelet2Maps` then download.
+
+After the download is finished,
+we need to put lanelet2 map and pointcloud map on the same location.
+The directory structure should be like this:
+
+```diff
++ <YOUR-MAP-DIRECTORY>/
++  ├─ pointcloud_map.pcd
++  └─ lanelet2_map.osm
+```
+
+If your .osm or .pcd map file's name is different from these names,
+you need to update autoware.launch.xml:
+
+```diff
+  <!-- Map -->
+-  <arg name="lanelet2_map_file" default="lanelet2_map.osm" description="lanelet2 map file name"/>
++  <arg name="lanelet2_map_file" default="<YOUR-LANELET-MAP-NAME>.osm" description="lanelet2 map file name"/>
+-  <arg name="pointcloud_map_file" default="pointcloud_map.pcd" description="pointcloud map file name"/>
++  <arg name="pointcloud_map_file" default="<YOUR-POINTCLOUD-MAP-NAME>.pcd" description="pointcloud map file name"/>
+```
+
+Now we are ready to launch the planning simulator:
+
+```bash
+ros2 launch autoware_launch planning_simulator.launch.xml map_path:=<YOUR-MAP-FOLDER-DIR> vehicle_model:=<YOUR-VEHICLE-MODEL> sensor_model:=<YOUR-SENSOR-KIT>
+```
+
+Example for tutorial_vehicle:
+
+```bash
+ros2 launch autoware_launch planning_simulator.launch.xml map_path:=$HOME/Files/autoware_map/tutorial_map/ vehicle_model:=tutorial_vehicle sensor_model:=tutorial_vehicle_sensor_kit vehicle_id:=tutorial_vehicle
+```
+
+1. Click `2D Pose Estimate` button on rviz or press `P` and give a pose for initialization.
+2. Click `2D Goal Pose` button on rviz or press `G` and give a pose for goal point.
+3. We need to add pedestrians to detection area, so activate interactive pedestrians from `Tool Properties` panel on rviz.
+4. After that, please press `Shift`, then click right click button for inserting pedestrians.
+5. You can control inserted pedestrian via dragging right click. So, you should put pedestrian on the detection area for testing.
+
+Stop detection area on rviz:
+
+<figure markdown>
+  ![detection-area-test](images/detection-area-test.png){ align=center }
+  <figcaption>
+    Detection area test on the created map.
+  </figcaption>
+</figure>
+
+You can check your detection area elements in the planning simulator as this demonstration video:
+
+![type:video](https://youtube.com/embed/zjfPnRIz8Xk)
diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/creating-vector-map/index.md b/docs/how-to-guides/integrating-autoware/creating-maps/creating-vector-map/index.md
@@ -0,0 +1,29 @@
+# Creating a vector map
+
+## Overview
+
+In this section, we will explain how to create Lanelet2 maps with TIER IV's [Vector Map Builder tool](https://tools.tier4.jp/feature/vector_map_builder_ll2/).
+
+There are alternative tools such as
+Unity-based app [MapToolbox](https://github.com/autocore-ai/MapToolbox) and
+Java-based app [JOSM](https://josm.openstreetmap.de/) that you may use for creating a Lanelet2 map.
+We will be using TIER IV's Vector Map Builder in the tutorial
+since it works on a browser without installation of extra dependency applications.
+
+## Vector Map Builder
+
+You need a TIER IV account for using Vector Map Builder tool.
+If it is the first time to use the tool,
+[create a TIER IV account](https://docs.web.auto/en/user-manuals/tier-iv-account/quick-start)
+in order to use [Vector Map Builder tool](https://tools.tier4.jp/feature/vector_map_builder_ll2/).
+For more information about this tool,
+please check the [official guide](https://docs.web.auto/en/user-manuals/vector-map-builder/introduction).
+
+You can follow these pages for creating a Lanelet2 map and understanding its regulatory elements.
+
+- [Lanelet2](./lanelet2)
+- [Crosswalk](./crosswalk)
+- [Stop Line](./stop-line)
+- [Traffic Light](./traffic-light)
+- [Speed Bump](./speed-bump)
+- [Detection Area](./detection-area)
diff --git a/docs/how-to-guides/integrating-autoware/creating-maps/creating-vector-map/lanelet2/.pages b/docs/how-to-guides/integrating-autoware/creating-maps/creating-vector-map/lanelet2/.pages
@@ -0,0 +1,2 @@
+nav:
+  - index.md
diff --git a/...eating-maps/creating-vector-map/lanelet2/images/planning-simulator-map-test.png b/...eating-maps/creating-vector-map/lanelet2/images/planning-simulator-map-test.png
diff --git a/...g-autoware/creating-maps/creating-vector-map/lanelet2/images/pointcloud-map.png b/...g-autoware/creating-maps/creating-vector-map/lanelet2/images/pointcloud-map.png