Merge pull request #44 from ethz-asl/feature/srd_demo

Docs and scripts to reproduce the RSS wavemap demo
ethz-asl · Nov 20, 2023 · 5e827cd · 5e827cd
2 parents 6d4b5c1 + 4f129f5
commit 5e827cd
Show file tree

Hide file tree

Showing 37 changed files with 804 additions and 39 deletions.
diff --git a/docs/pages/demos.rst b/docs/pages/demos.rst
@@ -51,3 +51,36 @@ We usually use depth measurements from depth cameras or 3D LiDARs, but any sourc
 
 To help you get started quickly, we provide various example :gh_file:`config <ros/wavemap_ros/config>` and ROS :gh_file:`launch <ros/wavemap_ros/launch>` files.
 For a brief introduction on how to edit wavemap configs and an overview of all the available settings, see the :doc:`configuration page <configuration>`.
+
+Multi-sensor live demo
+**********************
+This section provides instructions to reproduce the interactive multi-sensor, multi-resolution mapping demo we performed at several events, including `RSS 2023 <https://roboticsconference.org/program/papers/065/>`__ and the `Swiss Robotics Day 2023 <https://swissroboticsday.ch/>`__. In this demo, wavemap fuses measurements from a depth camera up to a resolution of 1cm and a LiDAR up to a range of 15m in real-time on a laptop. The odometry is obtained by running FastLIO2 using the LiDAR's pointclouds and built-in IMU.
+
+Hardware
+========
+Wavemap can be :doc:`configured <configuration>` to work with almost any depth input. In case you want to replicate our exact setup, we used a Livox MID-360 LiDAR at RSS and an Ouster OS0-128 at the Swiss Robotics Day. We chose the PMD Pico Monstar depth camera for both demos, but the Azure Kinect also works well. Although any recent laptop will suffice, we recommend using a laptop with a discrete GPU as it will help Rviz run much smoother.
+
+Docker
+======
+For convenience, the entire demo can be run in Docker using :gh_file:`this Docker image <tooling/docker/live_demo.Dockerfile>`, which includes the sensor drivers, FastLIO and wavemap. You can build it by running::
+
+    docker build --tag=wavemap_demo --pull - <<< $(curl -s https://raw.githubusercontent.com/ethz-asl/wavemap/main/tooling/docker/live_demo.Dockerfile)
+
+We provide a convenience script that you can use to run the Docker image. To download it, run::
+
+    curl -o demo_in_docker.sh https://raw.githubusercontent.com/ethz-asl/wavemap/main/tooling/packages/wavemap_utils/scripts/demo_in_docker.sh
+    sudo chmod +x demo_in_docker.sh
+
+Configure
+=========
+Start by configuring the laptop's network interface to receive the LiDAR data. By default, the Livox we used required the laptop's IP to be set to ``192.168.1.50``, while the Ouster required the laptop's IP to be set to ``192.168.10.50``. In case you're using another LiDAR, the expected receiver IP is usually mentioned in the LiDARs manual or driver documentation.
+
+Next, update the sensor calibrations to match your sensor setup. If you're using the exact sensors we used, you mainly need to update the extrinsics. These are defined through static TFs, at the bottom of the launch file for your sensor setup (e.g. :gh_file:`here <ros/wavemap_ros/launch/online/livox_mid360_pico_monstar.launch#L76>` or :gh_file:`here <ros/wavemap_ros/launch/online/ouster_os0_pico_monstar.launch#L78>`). If you're using different sensors, you will also need to update the wavemap, FastLIO and sensor driver config files. To help you get started quickly, we provide examples for many different sensor setups for :gh_file:`wavemap <ros/wavemap_ros/config>` and :gh_file:`FastLIO <ros/wavemap_ros/config/other_packages/fast_lio>`. In case we do not yet have an example FastLIO config for your LiDAR, you might find one in the `official the FastLIO repository <https://github.com/hku-mars/FAST_LIO>`__.
+
+Note that the ``demo_in_docker.sh`` script saves and restores the `ros/wavemap_ros` folder across runs (explained :gh_file:`here <tooling/packages/wavemap_utils/scripts/demo_in_docker.sh#L9>`), so you can configure wavemap by simply running ``demo_in_docker.sh`` and editing the launch and config files through the resulting interactive shell.
+
+Run
+===
+Once the configured, you can directly run the demo by calling the ``demo_in_docker.sh`` script followed by the launch command. For example::
+
+    demo_in_docker.sh roslaunch wavemap_ros ouster_os0_pico_monstar.launch
diff --git a/docs/pages/intro.rst b/docs/pages/intro.rst
@@ -18,9 +18,13 @@ Abstract:
 
 Please cite it when using wavemap for research:
 
+.. code-block:: text
+
     Reijgwart, V., Cadena, C., Siegwart, R., & Ott, L. (2023). Efficient volumetric mapping of multi-scale environments using wavelet-based compression. Proceedings of Robotics: Science and System XIX.
 
-BibTeX::
+BibTeX:
+
+.. code-block:: text
 
     @INPROCEEDINGS{reijgwart2023wavemap,
         author = {Reijgwart, Victor and Cadena, Cesar and Siegwart, Roland and Ott, Lionel},

diff --git a/examples/CHANGELOG.rst b/examples/CHANGELOG.rst
@@ -2,6 +2,9 @@
 Changelog for package wavemap_examples
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+1.6.1 (2023-11-20)
+------------------
+
 1.6.0 (2023-10-17)
 ------------------
 * Add initial usage examples

diff --git a/examples/package.xml b/examples/package.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <package format="2">
   <name>wavemap_examples</name>
-  <version>1.6.0</version>
+  <version>1.6.1</version>
   <description>Usages examples for wavemap.</description>
 
   <maintainer email="[email protected]">Victor Reijgwart</maintainer>

diff --git a/libraries/wavemap/CHANGELOG.rst b/libraries/wavemap/CHANGELOG.rst
@@ -2,6 +2,9 @@
 Changelog for package wavemap
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+1.6.1 (2023-11-20)
+------------------
+
 1.6.0 (2023-10-17)
 ------------------
 * New features

diff --git a/libraries/wavemap/package.xml b/libraries/wavemap/package.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <package format="2">
   <name>wavemap</name>
-  <version>1.6.0</version>
+  <version>1.6.1</version>
   <description>Base library for wavemap.</description>
 
   <maintainer email="[email protected]">Victor Reijgwart</maintainer>

diff --git a/libraries/wavemap_io/CHANGELOG.rst b/libraries/wavemap_io/CHANGELOG.rst
@@ -2,6 +2,9 @@
 Changelog for package wavemap_io
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+1.6.1 (2023-11-20)
+------------------
+
 1.6.0 (2023-10-17)
 ------------------
 * Refactor wavemap utils

diff --git a/libraries/wavemap_io/package.xml b/libraries/wavemap_io/package.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <package format="2">
   <name>wavemap_io</name>
-  <version>1.6.0</version>
+  <version>1.6.1</version>
   <description>(De)serialization of wavemap types to files.</description>
 
   <maintainer email="[email protected]">Victor Reijgwart</maintainer>

diff --git a/ros/wavemap_msgs/CHANGELOG.rst b/ros/wavemap_msgs/CHANGELOG.rst
@@ -2,6 +2,9 @@
 Changelog for package wavemap_msgs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+1.6.1 (2023-11-20)
+------------------
+
 1.6.0 (2023-10-17)
 ------------------
 * Update incremental transmission and Rviz to remove deleted blocks

diff --git a/ros/wavemap_msgs/package.xml b/ros/wavemap_msgs/package.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <package format="2">
   <name>wavemap_msgs</name>
-  <version>1.6.0</version>
+  <version>1.6.1</version>
   <description>Message definitions for wavemap's ROS interfaces.</description>
 
   <maintainer email="[email protected]">Victor Reijgwart</maintainer>

diff --git a/ros/wavemap_ros/CHANGELOG.rst b/ros/wavemap_ros/CHANGELOG.rst
@@ -2,6 +2,14 @@
 Changelog for package wavemap_ros
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+1.6.1 (2023-11-20)
+------------------
+* Add config for Ouster OS0 + Pico Monstar
+* Improve demo settings and tune FastLIO
+* Make depth camera startup more reliable
+* Document how to replicate the live demo
+* Contributors: Victor Reijgwart
+
 1.6.0 (2023-10-17)
 ------------------
 * New features

diff --git a/ros/wavemap_ros/config/wavemap_server.rviz → ros/wavemap_ros/config/rviz/default.rviz b/ros/wavemap_ros/config/wavemap_server.rviz → ros/wavemap_ros/config/rviz/default.rviz