Kudan Visual SLAM#

This tutorial tells you how to run a Kudan Visual SLAM (KdVisual) system using ROS 2 bags as the input containing data of a robot exploring an area.

  • The ROS 2 tool rviz2 is used to visualize how KdVisual interprets the data from the ROS 2 bag.

  • Find more information about Kudan Visual SLAM here.

  • Find more information on Kudan in general here.

Install EI for AMR Including the Optional Kudan Visual SLAM Bundle#

  1. Download the Robot Complete Kit with the optional Kudan Visual SLAM (KdVisual) bundle.

    1. Go to the Product Download page.

    2. Select the Robot Complete Kit.

    3. Select the Custom Configuration.

    4. Click Customize.

    5. On page “Intel Containers”, make sure that AMR Kudan Slam Docker Image is selected.

    6. On page “Reference Implementations”, make sure that AMR Kudan SLAM and AMR Bag Files are selected.

      ../_images/kudan_download_package.png

    7. Click Next until you get to the “Download” page.

    8. Click Download.

    9. During installation, you are prompted to enter your product key, so copy the product key displayed on the download page.

  2. Copy edge_insights_for_amr.zip from the developer workstation to the Home directory on your target system. You can use a USB flash drive to copy the file.

  3. Extract the zip archive according to Step 4 of the Get Started Guide for Robots.

  4. Install the EI for AMR software according to Step 5 of the Get Started Guide for Robots.

Run the Sample Application#

This section describes how to run the Kudan Visual SLAM (KdVisual) system using a video stream from an Intel® RealSense™ camera. The tutorial applies the ROS 2 bag robot_moving_15fps. This ROS 2 bag is part of the AMR Bag Files package, which you have downloaded during the EI for AMR installation according to Section Install EI for AMR Including the Optional Kudan Visual SLAM Bundle.

  1. Check if your installation has the amr-kudan-slam Docker* image.

    docker images |grep amr-kudan-slam
#if you have it installed, the result is:
amr-kudan-slam

    Note

    If the image is not installed, continuing with these steps triggers a build that takes longer than an hour (sometimes, a lot longer depending on the system resources and internet connection). Intel® recommends checking your installation by repeating the steps in Section Install EI for AMR Including the Optional Kudan Visual SLAM Bundle. Further information on installing the Robot Complete Kit can be found in the Get Started Guide for Robots.

  2. Open and read the End User License Agreement for Kudan SLAM. The following command applies the Evince document viewer, but you can use every other application that can display PDF documents.

    evince $CONTAINER_BASE_PATH/'01_docker_sdk_env/artifacts/01_amr/amr_kudan_slam/install/End User License Agreement for Kudan SLAM.pdf'

    Note

    If the file End User License Agreement for Kudan SLAM.pdf does not exist, repeat the steps in Section Install EI for AMR Including the Optional Kudan Visual SLAM Bundle and make sure that AMR Kudan SLAM on page “Reference Implementations” is selected.

    Alternatively, you can extract the document from the amr-kudan-slam Docker* image:

    id=$(docker create amr-kudan-slam:$DOCKER_TAG)
docker cp $id:'/home/eiforamr/ros2_ws/install/End User License Agreement for Kudan SLAM.pdf' - | tar xv
docker rm -v $id
evince 'End User License Agreement for Kudan SLAM.pdf'

    If you agree with the terms of this document, continue with the next steps.

  3. Check that EI for AMR environment is set:

    echo $AMR_TUTORIALS
# should output the path to EI for AMR tutorials
/home/user/edge_insights_for_amr/Edge_Insights_for_Autonomous_Mobile_Robots_2023.1/AMR_containers/01_docker_sdk_env/docker_compose/05_tutorials

    If nothing is output, refer to Get Started Guide for Robots Step 5 for information on how to configure the environment.

  4. Run the Kudan Visual SLAM algorithm using a ROS 2 bag simulating a robot exploring an area:

    docker compose -f $AMR_TUTORIALS/kudan-slam-cpu.tutorial.yml up

    In rviz2, you can see what KdVisual does with the input from the ROS 2 bag.

    ../_images/kudan_slam.png

  5. To close this execution, close the rviz2 window, and press Ctrl-c in the terminal.

  6. Clean up the Docker* images:

    docker compose -f $AMR_tutorials/kudan-slam-cpu.tutorial.yml down --remove-orphans

  7. KdVisual can also offload some processing to the GPU. To demonstrate this, use this example:

    Note

    Offloading to the GPU only works on systems with 12th or 11th Generation Intel® Core™ processors with Intel® Iris® Xe Integrated Graphics or Intel® UHD Graphics.

    docker compose -f $AMR_TUTORIALS/kudan-slam-gpu.tutorial.yml up

  8. On a different terminal, check how much of the GPU is used. To analyze the GPU load you can apply the tool intel-gpu-top, which is part of the package intel-gpu-tools:

    sudo apt-get install intel-gpu-tools
sudo intel_gpu_top
    ../_images/kudan_slam_gpu_top.png

  9. To close this execution, close the rviz2 window, and press Ctrl-c in the terminal.

  10. Cleanup the Docker* images:

    docker compose -f $AMR_TUTORIALS/kudan-slam-gpu.tutorial.yml down --remove-orphans

Run Kudan Visual SLAM Using a Stereo Camera Stream#

The Kudan Visual SLAM (KdVisual) system can also work on video streams from a stereo camera.

To test the Kudan Visual SLAM (KdVisual) system in this mode, you need a video stream with stereo data. ROS bag files with stereo data can be found in the EuRoC MAV Dataset. In the following, we use the ROS bag MH_01_easy.bag.

  1. Navigate to the AMR_containers folder, which you have created during the installation of the Edge Insights for Autonomous Mobile Robots software:

    cd $CONTAINER_BASE_PATH

    Create a folder EuRoC_MAV_Dataset and change to this folder.

    mkdir EuRoC_MAV_Dataset
cd EuRoC_MAV_Dataset

  2. Download the ROS bag MH_01_easy.bag from the “Downloads” Section of the EuRoC MAV Dataset. Save the file MH_01_easy.bag into the EuRoC_MAV_Dataset folder, which you have created. Since this file represents a ROS 1 bag, convert it into a ROS 2 bag by means of these commands:

    pip install rosbags
rosbags-convert MH_01_easy.bag

    If everything went well, your directory tree looks like this:

    AMR_containers/
├── ...
├── EuRoC_MAV_Dataset
│   ├── MH_01_easy
│   │   ├── metadata.yaml
│   │   └── MH_01_easy.db3
│   └── MH_01_easy.bag
├── ...
:

  3. Check that EI for AMR environment is set:

    echo $AMR_TUTORIALS
# should output the path to EI for AMR tutorials
/home/user/edge_insights_for_amr/Edge_Insights_for_Autonomous_Mobile_Robots_2023.1/AMR_containers/01_docker_sdk_env/docker_compose/05_tutorials

    If nothing is output, refer to Get Started Guide for Robots Step 5 for information on how to configure the environment.

  4. Run the Kudan Visual SLAM algorithm using the ROS 2 bag with the stereo stream:

    docker compose -f $AMR_TUTORIALS/kudan-slam-stereo-cpu.tutorial.yml up

    In rviz2, you can see what KdVisual does with the input from the ROS 2 bag.

    ../_images/kudan_slam_stereo.png

  5. To close this execution, close the rviz2 window, and press Ctrl-c in the terminal.

  6. Clean up the Docker* images:

    docker compose -f $AMR_TUTORIALS/kudan-slam-stereo-cpu.tutorial.yml down --remove-orphans

  7. KdVisual can offload some processing to the GPU also in stereo mode. To demonstrate this, use this example:

    docker compose -f $AMR_TUTORIALS/kudan-slam-stereo-gpu.tutorial.yml up

  8. Clean up the Docker* images:

    docker compose -f $AMR_TUTORIALS/kudan-slam-stereo-gpu.tutorial.yml down --remove-orphans

Troubleshooting#

If you encounter this error:

amr-kudan-slam | [kdvisual_ros2_rgbd-1] /workspace/src/gpu/l0_rt_helpers.h:56: L0 error 78000001

The render group might be on a different id then 109 which is placed in the yaml files used in the examples.

To find what id the render group has on your system:

getent group render
cat /etc/group |grep render

If the result is different then: render:x:109 change the yml file:

gedit 01_docker_sdk_env/docker_compose/05_tutorials/kudan-slam-gpu.tutorial.yml
# and/or
gedit 01_docker_sdk_env/docker_compose/05_tutorials/kudan-slam-cpu.tutorial.yml
# Change the at the line 26 from 109, to the number you got above.

If you encounter this error:

[kdvisual_ros2_rgbd]: Failed to load license: Missing or invalid license file! Pass file path to Kd::Visual::Slam or Kd::Visual::MapOptimiser constructor. System clock has been set back (-40)

This message indicates that the license manager has detected an issue with the status of certain system files. To fix the issue, ensure that your file system does not include any files that have a modification date in the future. You can use the Linux* command find to identify such files in your file system. In general, you should refrain from manually changing the date of your system clock.

For general robot issues, go to: Troubleshooting for Robot Tutorials.