---
285
---

# ORB-SLAM3 for ROS2 on Ubuntu 24.04

##### tags: `ORB-SLAM3`, `ROS2`, `SLAM`, `Ubuntu 24`, `Jazzy`

## 本文目的

目前網路上大部分的 ORB-SLAM3 安裝都是基於 Ubuntu 22 及更先前的版本教學文。然而對於已經升級成 Ubuntu 24.04 (Nobel Numbat) 的使用者而言，是否能夠使用 ORB-SLAM3 呢?

答案是肯定的，不過需要進行小部分的修改，本文的主旨是盡可能基於 Ubuntu 24.04 的預設工具鍊，幫助使用者在 Ubuntu 24.04 測試及使用 ORB-SLAM3，以及讓 ROS2 能夠使用 ORB-SLAM3，接下來就讓我們開始吧!

:::info
本文假設使用者具備基礎 Linux 知識, e.g.,
- vim/nano
- ~/.bashrc
:::

## Prerequisite

**Required**

- [Ubuntu 24.04](https://ubuntu.com/blog/tag/ubuntu-24-04-lts) (虛擬機/原生安裝皆可)

**Optional**
- Editor (VSCode, vim, nano, ...)
- [ROS2 Jazzy(推薦安裝)](https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debs.html)
- ==確保 Jazzy 對於每個 terminal 都是可見的==

    # in ~/.bashrc

    ## use ros2 jazzy in every terminal 
    source /opt/ros/jazzy/setup.bash

## Toolchain Installation

- C/C++ Compiler related

    sudo apt install build-essential    

應確保以下的編譯工具存在且版本一致:

| Tool Name | Command | Version |
|:---------:|:-----------------:|:-------:|
| gcc | `gcc --version` | 13.3.0 |
| g++ | `g++ --version` | 13.3.0 |
| cmake | `cmake --version` | 3.28.3 |

- [python virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/)
- 根據 PEP 668, Ubuntu 現不允許直接透過 `pip` 全局安裝，因此建議使用虛擬環境，如何安裝配置參考[此處](https://medium.com/@minecola/python3-%E6%8B%AF%E6%95%91%E9%AA%AF%E9%AB%92%E7%92%B0%E5%A2%83%E5%A4%A7%E4%BD%9C%E6%88%B0-with-virtualenv-4b398142463d)
:::warning
如果要強制全局安裝，可用下列參數

    pip install <package-name> --break-system-packages

:::
- 安裝及添加 python 虛擬環境 (預設是 python 3.12)

    # install virtualenvwrapper requirement
    sudo apt install python3-pip python3-virtualenv python3-virtualenvwrapper -y
    
    # 透過記事本或編輯器將下面這行添加到 ~/.bashrc 中
    source /usr/share/virtualenvwrapper/virtualenvwrapper.sh
    
    # 更新當前的 terminal
    source ~/.bashrc
    
    # 建立一個虛擬環境
    mkvirtualenv orb-slam3
    
    # 啟動虛擬環境
    workon orb-slam3
    
    # 結束虛擬環境
    deactivate

- [Eigen3](https://eigen.tuxfamily.org/index.php?title=Main_Page)
- ORB-SLAM3 的依賴項，截至 2025/02/15 最新版本是 ==3.4.0==
- 透過 `sudo apt install libeigen3-dev` 安裝

- [OpenCV](https://opencv.org/)
- ORB-SLAM3 的依賴項，Ubuntu 24 預設安裝 ==4.6.0==
- 版本 4.6.0 和 `ros-jazzy-cv-bridge`(4.1.0) 是已經搭配好的，請盡可能使用該版本避免在 ROS2 出現錯誤
- 透過 `sudo apt install libopencv-dev` 安裝
- ==應確保當前並沒有其他 opencv 版本產生衝突==

## Installation and Compilation Walkthrough

- **Preparation**

    # 確保你已經完成 Prerequisite

    # 更新 apt 資訊
    sudo apt update && sudo apt upgrade -y

    # 確保啟動 python 虛擬環境 
    workon orb-slam3

    # 安裝必要工具鍊
    sudo apt install -y \
        build-essential \  
        libeigen3-dev \     
        libopencv-dev \     
        libepoxy-dev  \ # Pangolin 依賴項
        

    # 前往 HOME directory
    cd ~

    # 建立 src code directory 並進入
    mkdir orb-slam3-root && cd orb-slam3-root
    
    # 將 ORB-SLAM3 的 root 路徑定義在 ~/.bashrc
    vim ~/.bashrc
    
    # 添加變數在最後方
    export ORB_SLAM3_ROOT_PATH=~/orb-slam3-root
    
    # 更新當前 terminal
    source ~/.bashrc

- **Compile Pangolin**

    # 使用上一個 terminal 或者確保你的路徑在 ~/orb-slam3-root
    cd $ORB_SLAM3_ROOT_PATH
    
    # 編譯
    git clone https://github.com/stevenlovegrove/Pangolin
    cd ./Pangolin
    git checkout v0.9.2 # 當前最新版本，經過測試可行
    mkdir build
    cd build
    cmake ..
    make

- **Test Pangolin**

測試可以用下方指令:

    $ORB_SLAM3_ROOT_PATH/Pangolin/build/examples/HelloPangolin/HelloPangolin

應會出現:

- **Compile ORB-SLAM3**

    cd $ORB_SLAM3_ROOT_PATH
    git clone https://github.com/zang09/ORB-SLAM3-STEREO-FIXED.git ORB-SLAM3

修改以下文件:

- `$ORB_SLAM3_ROOT_PATH/ORB-SLAM3/CMakeLists.txt`

        # 修改 33 行版本號變成 4.6
        find_package(OpenCV 4.6)
        
        # ...
        
        # 刪除 41 行的 Eigen3 版本號
        # find_package(Eigen3 3.1.0 REQUIRED)
        find_package(Eigen3 REQUIRED)

- `$ORB_SLAM3_ROOT_PATH/ORB-SLAM3/build.sh`
- opt: 使用虛擬機且 CPU 核心數 < 4才要更改
- 要將 make -j\<n> 的 n 改成你設定的 CPU 核心數

- `$ORB_SLAM3_ROOT_PATH/ORB-SLAM3/ThirdParty/DBoW2/CMakeLists.txt`

        # 修改第 32 行 opencv 到版本 4.6
        find_package(OpenCV 4.6 QUIET)

- `$ORB_SLAM3_ROOT_PATH/ORB-SLAM3/ThirdParty/Sophus/CMakeLists.txt`

        # 因為用 gcc 所以修改要針對 GNU
        # 第 23 行參數加入 `-Wno-error=array-bounds`
        SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Werror -Wextra -std=c++11 -Wno-error=array-bounds -Wno-deprecated-declarations -ftemplate-backtrace-limit=0")
        #                                                                         ^^^^^^^^^^^^^^^^^^^^^^
        
        # 第 35 行把版本號去掉
        find_package(Eigen3 REQUIRED)

- `$ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Examples/Monocular/mono_euroc.cc`

        /* 將第 83 行 false -> true */

        // ...

        cout << endl << "-------" << endl;
        cout.precision(17);


        int fps = 20;
        float dT = 1.f/fps;
        // Create SLAM system. It initializes all system threads and gets ready to process frames.
        ORB_SLAM3::System SLAM(argv[1],argv[2],ORB_SLAM3::System::MONOCULAR, true);
        //                                                                   ^^^^^
        float imageScale = SLAM.GetImageScale();

修改完之後:

    cd $ORB_SLAM3_ROOT_PATH/ORB-SLAM3
    chmod +x build.sh
    
    # 開始編譯
    ./build.sh
    
    # 編譯**完成**後要全局安裝 Sophus 否則後續 ROS2 部分會報找不到頭文件的錯誤
    cd $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/ThirdParty/Sophus/build
    sudo make install

:::info
未來如果要刪除 Sophus 可以執行:

    sudo rm -rf /usr/local/include/sophus
    sudo rm -rf /usr/local/share/sophus

:::

- **Test ORB-SLAM3**
- 使用 `MH_01_easy.zip` 進行測試

    cd $ORB_SLAM3_ROOT_PATH/ORB-SLAM3
    mkdir datasets && cd datasets
    
    # 獲取測試資料
    wget http://robotics.ethz.ch/~asl-datasets/ijrr_euroc_mav_dataset/machine_hall/MH_01_easy/MH_01_easy.zip
    
    # 解壓縮
    unzip MH_01_easy.zip
    mkdir MH01
    mv mav0 MH01/mav0
    
    cd ..
    
    # 運行測試
    ./Examples/Monocular/mono_euroc ./Vocabulary/ORBvoc.txt ./Examples/Monocular/EuRoC.yaml ./datasets/MH01 ./Examples/Monocular/EuRoC_TimeStamps/MH01.txt dataset-MH01_mono


## 與 ROS2 整合

當前面的步驟執行完後，ORB-SLAM3 已經可以運行以及客製化了，但是要讓 ORB-SLAM3 能以 ROS2 package 的形式呼叫還需要額外的動作。

### 編譯 ORB-SLAM3 ROS2 package

# install required packages
sudo apt install ros-${ROS_DISTRO}-cv-bridge ros-${ROS_DISTRO}-message-filters

# ros-${ROS_DISTRO}-message-filters: 4.11.3
# ros-${ROS_DISTRO}-cv-bridge: 4.1.0

cd $ORB_SLAM3_ROOT_PATH

git clone https://github.com/zang09/ORB_SLAM3_ROS2 orbslam3_ros2
mkdir ROS2_ORB_SLAM3 && cd ROS2_ORB_SLAM3 && mkdir src && cd ..
mv orbslam3_ros2 ROS2_ORB_SLAM3/src/orbslam3_ros2

修改以下文件:

- `$ORB_SLAM3_ROOT_PATH/ROS2_ORB_SLAM3/src/orbslam3_ros2/CMakeLists.txt`

    # 將 CMakeLists.txt 第 5 行 python path 更新
    set(ENV{PYTHONPATH} "/opt/ros/jazzy/lib/python3.12/site-packages/")
    
    # 第 26 行加上 OpenCV dependency
    find_package(OpenCV 4.6 REQUIRED)

    # 在 stereo 和 stereo-inertial 的 ament_target_dependencies 中的最後加上 OpenCV (大約是 54 和 61 行)
    
    ament_target_dependencies(stereo rclcpp sensor_msgs cv_bridge message_filters RB_SLAM3 Pangolin OpenCV)
    #                                                                                               ^^^^^^^
    
    ament_target_dependencies(stereo-inertial rclcpp sensor_msgs cv_bridge ORB_SLAM3 Pangolin OpenCV)
    #                                                                                         ^^^^^^^

- `$ORB_SLAM3_ROOT_PATH/ROS2_ORB_SLAM3/src/orbslam3_ros2/CMakeModules/FindORB_SLAM3.cmake`

    # 修改第 8 行, 後面是先前你 git clone 的 ORB-SLAM3 位置
    set(ORB_SLAM3_ROOT_DIR "${ENV{ORB_SLAM3_ROOT_PATH}}/ORB-SLAM3")

- 將 `$ORB_SLAM3_ROOT_PATH/ROS2_ORB_SLAM3` 內所有文件含 `#include <cv_bridge/cv_bridge.h>` 都換成 `#include <cv_bridge/cv_bridge.hpp>`，應該有==四處==，可以善用 VSCode replace all 功能

修改完後:

workon orb-slam3
pip install catkin_pkg
cd $ORB_SLAM3_ROOT_PATH/ROS2_ORB_SLAM3
colcon build

# register orb-slam3 related path
vim ~/.bashrc

# 加載 ROS2_ORB_SLAM3 的環境變數
if [ -f "$ORB_SLAM3_ROOT_PATH/ROS2_ORB_SLAM3/install/setup.bash" ]; then
    source "$ORB_SLAM3_ROOT_PATH/ROS2_ORB_SLAM3/install/setup.bash"
fi

# 設置 ORB-SLAM3 和 Pangolin 的動態庫路徑
export LD_LIBRARY_PATH="$ORB_SLAM3_ROOT_PATH/ORB-SLAM3/lib:$LD_LIBRARY_PATH"
export LD_LIBRARY_PATH="$ORB_SLAM3_ROOT_PATH/Pangolin/build:$LD_LIBRARY_PATH"

# store and quit ~/.bashrc

至此 ROS2 ORB-SLAM3 package(orbslam3) 應該已經可以使用:

ros2 run orbslam3 mono $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Vocabulary/ORBvoc.txt $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Examples/Monocular/TUM1.yaml

### 測試

測試可以分成[實體相機測試](https://blog.csdn.net/liiiuzy/article/details/136272727)和 ros2 bag 模擬測試兩部分，擁有 webcam 的使用者可以參考前者，使用虛擬機可以參考後者。

---

**實體 webcam 測試**

:::warning
注意!
- 預設 orbslam3 package 訂閱的 topic 是 `/camera`
- 進入 `/camera` 的圖片應該是**未經壓縮的**! 應是 YUYV422 等格式
- 用實體相機測試應避免畫面過於單一或光線過暗
- 如果一直是黑畫面，嘗試轉動鏡頭
:::

1. 測試相機發布是否正常

    sudo apt install ros-${ROS_DISTRO}-v4l2-camera
    sudo apt install ros-${ROS_DISTRO}-rqt-image-view

    # Terminal-1
    # 需要進行 topic remap to /camera
    ros2 run v4l2_camera v4l2_camera_node --ros-args -r /image_raw:=/camera

    # Terminal-2
    ros2 run rqt_image_view rqt_image_view
    
    # 調整到 topic /camera 應該可以看到畫面

2. 測試 `orbslam3 mono`

    # Terminal-1
    # 可以續用上方的 Terminal-1
    
    # Terminal-2
    ros2 run orbslam3 mono $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Vocabulary/ORBvoc.txt $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Examples/Monocular/TUM1.yaml

---

**ROS2 bag 測試**

作者曾嘗試在 VirtualBox 上面執行 webcam 測試，但是使用 `vboxmanage` [掛載 webcam](https://docs.oracle.com/en/virtualization/virtualbox/6.0/admin/webcam-passthrough.html) 時只能使用預設 MJPEG 格式，在[不更改原始程式](https://blog.csdn.net/Functioe/article/details/131848026)的前提下，OpenCV 會出現格式錯誤的 Exception。

因此，作者使用自己的 webcam 錄製了一段 ros2 bag 供使用者進行簡易測試:

cd $ORB_SLAM3_ROOT_PATH

# download test bag
# 1. use URL
https://drive.google.com/drive/folders/1NY4KEW2qpfKlzR-674E-DFNkUEfDkJsC?usp=sharing

unzip my_camera_bag.zip

# 2. use gdown
workon orb-slam3
pip install gdown
gdown --folder https://drive.google.com/drive/folders/1NY4KEW2qpfKlzR-674E-DFNkUEfDkJsC

# Terminal-1
ros2 run orbslam3 mono $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Vocabulary/ORBvoc.txt $ORB_SLAM3_ROOT_PATH/ORB-SLAM3/Examples/Monocular/TUM1.yaml
# Terminal-2
cd $ORB_SLAM3_ROOT_PATH
ros2 bag play my_camera_bag


## Future Works

- 將資源整合進一個 GitHub repo
- 使用 turtle4 camera
- 撰寫自動化程式
- 整理 Reference

## Reference

- [Error at Installation of PX4 development environment(Ubuntu24.04)](https://discuss.px4.io/t/error-at-installation-of-px4-development-environment/41885)
- [How to install opencv 4.10 on Ubuntu 24.04](https://gist.github.com/raulqf/f42c718a658cddc16f9df07ecc627be7)
- [Pangolin - Can anyone compile this](https://github.com/uoip/pangolin/issues/33)
- [ORB_SLAM3的安装与测试](https://blog.csdn.net/miracle_world/article/details/124424598)
- [ORB-SLAM2和ORB-SLAM3环境配置及运行(必看)](https://blog.csdn.net/meng_152634/article/details/127570220)
- [ros2安装与orb-slam3](https://blog.csdn.net/weixin_43468458/article/details/133985107)
- [CAM driver 問題](https://blog.csdn.net/Functioe/article/details/131848026)
- [ROS2 基于USB单目相机(格式MJPEG)运行ORB_SLAM3及一些问题解决](https://blog.csdn.net/Functioe/article/details/131848026)