1. 项目概述与核心价值在机器人、自动驾驶和增强现实这些前沿领域让机器“看见”并理解周围环境是第一步也是最关键的一步。这背后依赖的核心技术就是SLAM即时定位与地图构建。而ORB-SLAM3作为这个领域公认的标杆以其出色的精度、鲁棒性和对多地图的支持成为了众多研究者和开发者的首选。但说实话从零开始把它在Ubuntu 20.04和ROS环境下跑起来对新手甚至是有一定经验的开发者来说都可能是个不小的挑战。依赖冲突、编译错误、参数配置不对随便一个坑都能让你折腾半天。我最近因为一个室内移动机器人项目又重新完整地走了一遍在Ubuntu 20.04 LTS下基于ROS Noetic配置和运行ORB-SLAM3的流程。这次我不仅成功跑通了单目、双目和RGB-D各个版本还把过程中遇到的所有“坑”和优化技巧都系统地记录了下来。这篇文章的目的就是给你一份可以直接“抄作业”的详细指南。无论你是正在做毕业设计的学生还是从事机器人算法开发的工程师都能跟着步骤避开我踩过的雷高效地在自己的系统上部署好这套强大的视觉SLAM系统。我们会从最基础的环境准备开始一步步走到用你自己的摄像头或数据集成功运行建图与定位。2. 环境准备与系统基础配置在开始编译ORB-SLAM3之前一个干净、配置正确的系统环境是成功的一半。Ubuntu 20.04 LTS是一个长期支持版本系统稳定社区支持完善非常适合作为开发平台。我们选择ROS Noetic Ninjemys作为机器人操作系统框架它是ROS 1的最后一个版本与Ubuntu 20.04是官方钦定的搭配。2.1 系统更新与基础工具安装首先打开终端确保你的系统是最新的。这一步能避免很多因软件包版本过旧导致的依赖问题。sudo apt update sudo apt upgrade -y更新完成后安装一些后续编译必不可少的开发工具比如CMake、Git、编译器等。sudo apt install -y cmake git gcc g build-essential2.2 ROS Noetic 完整安装接下来安装ROS。这里我强烈推荐使用官方源进行安装虽然“鱼香ROS”的一键安装脚本在国内网络环境下有时更方便但为了环境的纯净和可追溯性尤其是对于SLAM这种对库版本敏感的应用手动走官方流程更稳妥。设置软件源。将ROS的官方仓库添加到你的源列表。sudo sh -c echo deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main /etc/apt/sources.list.d/ros-latest.list设置密钥。sudo apt install curl curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -安装ROS桌面完整版。这个版本包含了ROS、rqt、rviz、机器人通用库等是我们需要的。sudo apt update sudo apt install -y ros-noetic-desktop-full环境设置。每次打开新终端都需要source一下setup.bash才能使用ROS命令为了方便我们将其写入bashrc。echo source /opt/ros/noetic/setup.bash ~/.bashrc source ~/.bashrc安装构建ROS包所需的依赖。sudo apt install -y python3-rosdep python3-rosinstall python3-rosinstall-generator python3-wstool build-essential sudo rosdep init rosdep update注意sudo rosdep init和rosdep update这两条命令由于网络原因在国内很可能失败。如果遇到ERROR: cannot download default sources list from...之类的错误不必慌张。你可以尝试多次执行或者寻找国内的镜像源进行配置。一个常见的解决方案是修改/etc/hosts文件添加raw.githubusercontent.com的可用IP地址。这个步骤需要一些耐心但它是成功安装ROS的关键。2.3 关键依赖库的安装ORB-SLAM3依赖于几个重量级的开源库必须提前装好。Pangolin用于可视化和用户界面。我们将从源码编译安装。# 安装Pangolin的依赖 sudo apt install -y libglew-dev libpython3.8-dev pkg-config libegl1-mesa-dev libwayland-dev libxkbcommon-dev wayland-protocols # 下载并编译Pangolin cd ~ git clone https://github.com/stevenlovegrove/Pangolin.git cd Pangolin mkdir build cd build cmake .. cmake --build . sudo make installOpenCV计算机视觉的基础库。Ubuntu 20.04的默认软件源提供了OpenCV 4.2.0这个版本与ORB-SLAM3兼容直接安装即可省去自己编译的麻烦。sudo apt install -y libopencv-dev python3-opencv安装后可以通过pkg-config --modversion opencv4命令验证版本是否为4.2.x。Eigen3一个高层次的C模板库用于线性代数运算。SLAM中大量的矩阵运算都依赖它。sudo apt install -y libeigen3-dev3. ORB-SLAM3源码获取与编译当所有依赖就绪后我们就可以开始处理主角了。ORB-SLAM3的源码托管在GitHub上它同时包含了ORB-SLAM2的代码。3.1 克隆源码与准备建议在你的工作空间例如~/catkin_ws/src或一个独立的目录下进行操作。cd ~ mkdir -p orbslam3_ws/src cd orbslam3_ws/src git clone https://github.com/UZ-SLAMLab/ORB_SLAM3.git克隆完成后进入ORB_SLAM3目录你会发现里面已经包含了Thirdparty子目录里面有DBoW2和g2o两个关键的第三方库。3.2 编译第三方依赖库ORB-SLAM3使用DBoW2进行词袋模型的位置识别使用g2o进行图优化。我们需要先编译它们。编译DBoW2:cd ORB_SLAM3/Thirdparty/DBoW2 mkdir build cd build cmake .. make -j4 # 使用4个线程并行编译速度更快-j4参数表示使用4个CPU核心进行编译你可以根据自己电脑的CPU核心数调整通常是物理核心数的1-2倍。编译成功后会在lib目录下生成libDBoW2.so库文件。编译g2o:cd ../../g2o # 回到Thirdparty进入g2o目录 mkdir build cd build cmake .. make -j4同样编译后会在lib目录下生成libg2o.so库文件。3.3 编译ORB-SLAM3主体现在来编译ORB-SLAM3库本身以及它的ROS接口。修改CMakeLists.txt关键步骤这是最容易出错的地方。打开ORB_SLAM3/CMakeLists.txt文件我们需要确保它找到了正确版本的Eigen3和OpenCV。找到find_package(Eigen3 REQUIRED)这一行。确保它存在。Ubuntu 20.04的Eigen3路径通常是/usr/include/eigen3CMake一般能自动找到。重点找到set(CMAKE_CXX_STANDARD 11)这一行。ORB-SLAM3默认使用C11标准但某些新版本的依赖库可能需要更高的标准。如果后续编译出现关于std::map::at或类似C14/17特性的错误可以将这一行改为set(CMAKE_CXX_STANDARD 14)。我实测在Ubuntu 20.04完整安装上述依赖后使用C11是可行的。执行编译cd ~/orbslam3_ws/src/ORB_SLAM3 # 回到ORB_SLAM3主目录 chmod x build.sh # 给编译脚本执行权限 ./build.shbuild.sh脚本会自动创建build目录并执行编译。这个过程会持续几分钟。如果一切顺利你会在build目录下看到libORB_SLAM3.so这个核心库文件。编译ROS接口ORB-SLAM3提供了ROS的封装节点让我们可以方便地订阅ROS话题如/camera/image_raw,/camera/camera_info来运行SLAM。chmod x build_ros.sh ./build_ros.sh这个脚本会编译Examples/ROS/ORB_SLAM3下的ROS节点。编译成功后你需要将生成的ROS节点路径添加到ROS环境变量中这样rosrun命令才能找到它。echo export ROS_PACKAGE_PATH\${ROS_PACKAGE_PATH}:~/orbslam3_ws/src/ORB_SLAM3/Examples/ROS ~/.bashrc source ~/.bashrc实操心得编译过程最常遇到的错误是“找不到 Pangolin”、“找不到 Eigen3”或“OpenCV版本不对”。99%的原因都是依赖库没有正确安装或者CMakeLists.txt中的查找路径不对。请务必严格按照顺序安装依赖并确认sudo make install成功执行。如果遇到Pangolin问题可以尝试在CMakeLists.txt中手动指定其路径find_package(Pangolin REQUIRED PATHS /usr/local)。4. 运行测试与数据集验证编译通过只是第一步能真正跑起来并输出正确结果才是胜利。我们先用公开数据集进行测试这能排除传感器驱动等外部干扰验证算法本身是否工作正常。4.1 下载公开数据集ORB-SLAM3论文和官网推荐使用EuRoC MAV数据集或TUM RGB-D数据集。这里以更常见的TUM RGB-D数据集为例。你可以从 TUM官网 下载。例如下载fr1/desk这个序列。cd ~ wget https://vision.in.tum.de/rgbd/dataset/freiburg1/rgbd_dataset_freiburg1_desk.tgz tar -xzvf rgbd_dataset_freiburg1_desk.tgz解压后会得到一个包含rgb/,depth/,accelerometer.txt等文件的文件夹。4.2 运行RGB-D示例ORB-SLAM3的示例程序需要两个参数词汇表文件路径和配置文件路径。词汇表文件在源码的Vocabulary/目录下配置文件在Examples/对应传感器类型的目录下。准备词汇表和配置文件确保你位于ORB_SLAM3的build目录下。cd ~/orbslam3_ws/src/ORB_SLAM3/build运行RGB-D模式使用以下命令启动RGB-D版本的ORB-SLAM3。这里假设你的数据集解压在~/rgbd_dataset_freiburg1_desk。./Examples/RGB-D/rgbd_tum Vocabulary/ORBvoc.txt Examples/RGB-D/TUM1.yaml ~/rgbd_dataset_freiburg1_desk Associations/TUM1.txt命令分解./Examples/RGB-D/rgbd_tum: 编译好的RGB-D示例可执行文件。Vocabulary/ORBvoc.txt: 预训练好的ORB特征词汇表用于回环检测。Examples/RGB-D/TUM1.yaml: 针对TUM数据集fr1序列的相机参数配置文件。~/rgbd_dataset_freiburg1_desk: 数据集路径。Associations/TUM1.txt: 一个“关联文件”它精确地列出了每一帧RGB图像和深度图像的对应关系及时间戳。这个文件在源码的Examples/RGB-D/associations/目录下已经提供。如果一切配置正确你会看到两个窗口弹出一个显示当前相机跟踪的画面和提取的ORB特征点另一个是Pangolin的可视化窗口显示三维地图点、关键帧和相机轨迹。终端里会持续输出跟踪状态TRACKING、LOST等和帧率信息。4.3 结果分析与评估程序运行结束后或者你按ESC键退出它会在当前目录下生成两个关键文件CameraTrajectory.txt: 估计的相机运动轨迹位姿。KeyFrameTrajectory.txt: 关键帧的位姿。你可以使用ORB-SLAM3提供的脚本将估计的轨迹与数据集中提供的真实轨迹groundtruth进行比较计算绝对轨迹误差ATE。这步操作能定量评估SLAM系统的精度。cd ~/orbslam3_ws/src/ORB_SLAM3 python3 evaluation/evaluate_ate.py evaluation/GroundTruth/your_groundtruth.txt CameraTrajectory.txt --plot plot.png你需要将your_groundtruth.txt替换为数据集中真实的轨迹文件。执行后脚本会输出RMSE均方根误差等误差指标并生成一个轨迹对比图plot.png。对于TUM fr1/desk序列一个运行良好的ORB-SLAM3应该能达到厘米级的精度。注意事项第一次运行可能会因为词汇表文件较大ORBvoc.txt约50MB加载需要几十秒请耐心等待。如果程序启动后立即崩溃最常见的错误是配置文件.yaml中的路径不对或者数据集关联文件.txt中的图片路径与你的实际存放路径不匹配。务必仔细检查这些路径。5. 集成ROS与实时摄像头运行通过数据集验证了算法正确性后下一步就是连接真实的摄像头在ROS框架下进行实时SLAM。这才是机器人项目的常态。5.1 创建ROS工作空间与功能包虽然ORB-SLAM3的ROS节点已经编译好但为了管理方便我们通常在一个独立的ROS工作空间中运行它并创建一个启动文件。source /opt/ros/noetic/setup.bash mkdir -p ~/catkin_ws/src cd ~/catkin_ws/src catkin_init_workspace cd .. catkin_make source devel/setup.bash接下来我们创建一个简单的功能包来存放启动文件和配置文件。cd ~/catkin_ws/src catkin_create_pkg orbslam3_demo rospy std_msgs sensor_msgs cd ~/catkin_ws catkin_make5.2 配置相机驱动与话题ORB-SLAM3的ROS节点订阅特定的ROS话题来获取图像和相机信息。你需要确保你的摄像头能发布这些话题。对于USB摄像头可以使用usb_cam包。sudo apt install ros-noetic-usb-cam运行驱动节点roslaunch usb_cam usb_cam-test.launch运行后使用rostopic list命令查看你应该能看到/usb_cam/image_raw和/usb_cam/camera_info等话题。对于RGB-D相机如Intel Realsense D435i使用realsense2_camera包。sudo apt install ros-noetic-realsense2-camera运行驱动节点roslaunch realsense2_camera rs_camera.launch它会发布/camera/color/image_raw,/camera/aligned_depth_to_color/image_raw和/camera/color/camera_info等话题。5.3 编写ORB-SLAM3 ROS启动文件在~/catkin_ws/src/orbslam3_demo下创建launch和config文件夹。mkdir -p ~/catkin_ws/src/orbslam3_demo/launch mkdir -p ~/catkin_ws/src/orbslam3_demo/config将ORB-SLAM3中的配置文件复制过来并根据你的相机参数进行修改。以RGB-D相机为例cp ~/orbslam3_ws/src/ORB_SLAM3/Examples/ROS/ORB_SLAM3/Asus.yaml ~/catkin_ws/src/orbslam3_demo/config/my_rgbd.yaml你需要用文本编辑器如nano或gedit打开my_rgbd.yaml修改以下关键参数Camera.fx,Camera.fy,Camera.cx,Camera.cy: 相机的内参焦距和主点。你需要通过相机标定获取这些值。对于Realsense驱动发布的/camera/color/camera_info话题中就包含这些信息。Camera.k1,Camera.k2,Camera.p1,Camera.p2,Camera.k3: 相机的畸变系数。Camera.width,Camera.height: 图像分辨率。Camera.fps: 帧率。ORBextractor.nFeatures: 每帧提取的ORB特征点数影响精度和速度默认1000是个不错的起点。ORBextractor.scaleFactor: 图像金字塔的尺度因子影响特征尺度不变性。接下来创建启动文件~/catkin_ws/src/orbslam3_demo/launch/orbslam3_rgbd.launchlaunch !-- ORB-SLAM3 RGB-D 节点 -- node pkgORB_SLAM3 typeRGBD nameORB_SLAM3 args/home/你的用户名/orbslam3_ws/src/ORB_SLAM3/Vocabulary/ORBvoc.txt /home/你的用户名/catkin_ws/src/orbslam3_demo/config/my_rgbd.yaml outputscreen /node !-- 你的相机驱动节点例如 realsense -- !-- include file$(find realsense2_camera)/launch/rs_camera.launch / -- /launch注意你需要将args中的两个路径替换成你电脑上的实际路径。上面的include行是注释掉的因为你可能已经在另一个终端启动了相机驱动。5.4 运行实时RGB-D SLAM现在我们可以启动整个系统了。请打开三个终端分别执行以下命令终端1启动ROS核心。roscore终端2启动你的相机驱动。例如对于Realsenseroslaunch realsense2_camera rs_camera.launch align_depth:truealign_depth:true参数确保深度图与彩色图对齐这对RGB-D SLAM至关重要。终端3启动ORB-SLAM3节点。首先确保环境变量已设置然后运行启动文件。source ~/catkin_ws/devel/setup.bash source ~/.bashrc # 确保ROS_PACKAGE_PATH包含ORB_SLAM3路径 roslaunch orbslam3_demo orbslam3_rgbd.launch如果一切顺利你将再次看到Pangolin的可视化窗口。拿着相机在房间内缓慢移动应该能看到三维点云地图被实时构建出来并且相机的位姿位置和姿态被持续估计。实操心得实时运行的技巧与调参光照与纹理ORB特征依赖图像纹理。在光线均匀、纹理丰富的环境中如办公室、有装饰的家居跟踪效果最好。白墙、纯色桌面是SLAM的“杀手”容易导致跟踪丢失。可以贴一些二维码或高对比度图案来增加特征。运动速度移动相机一定要“慢而稳”。快速旋转或剧烈晃动极易导致特征匹配失败从而丢失跟踪。参数调整如果发现跟踪不稳定频繁LOST可以尝试在my_rgbd.yaml中调高ORBextractor.nFeatures例如到2000但这会增加计算量。也可以微调ORBextractor.scaleFactor默认1.2和ORBextractor.nLevels图像金字塔层数默认8。查看ROS话题使用rqt_graph可以查看节点和话题的连接图确认图像数据是否正确流向了ORB_SLAM3节点。使用rostopic hz /camera/color/image_raw可以查看相机实际发布帧率。6. 常见问题排查与深度优化指南即使按照步骤操作也难免会遇到各种问题。下面我整理了一份从编译到运行最常见的“坑”及其解决方案。6.1 编译阶段错误排查错误fatal error: Eigen/Core: No such file or directory原因CMake找不到Eigen3头文件。解决首先确认已安装libeigen3-dev。然后在ORB_SLAM3的CMakeLists.txt中在find_package(Eigen3 REQUIRED)后面添加一行include_directories(${EIGEN3_INCLUDE_DIR})。如果还不行可以手动指定路径include_directories(/usr/include/eigen3)。错误Pangolin could not be found原因Pangolin没有正确安装或CMake找不到。解决确保你执行了sudo make install。然后在CMakeLists.txt中尝试显式指定查找路径find_package(Pangolin REQUIRED PATHS /usr/local/lib/cmake/Pangolin)。错误OpenCV 4.x requires enabled C11 support或类似C标准问题原因不同库要求的C标准不一致。解决统一标准。在ORB_SLAM3的CMakeLists.txt中将set(CMAKE_CXX_STANDARD 11)改为set(CMAKE_CXX_STANDARD 14)。同时在Thirdparty/DBoW2和Thirdparty/g2o的CMakeLists.txt中也进行同样的修改如果它们有的话。错误undefined reference to ‘omp_‘等OpenMP错误原因编译器找不到OpenMP库这是一个用于并行计算的库。解决安装OpenMPsudo apt install libomp-dev。然后在CMakeLists.txt的find_package(OpenMP REQUIRED)部分确保链接了OpenMP库target_link_libraries(${PROJECT_NAME} OpenMP::OpenMP_CXX)。6.2 运行阶段错误排查问题运行示例程序或ROS节点时提示Segmentation fault (core dumped)原因这是最令人头疼的错误之一原因多样。常见原因有词汇表文件路径错误、配置文件(.yaml)格式错误或路径不对、相机参数与配置文件不匹配、依赖库版本冲突。排查步骤 a.检查路径用pwd和ls命令双重确认所有文件路径都是绝对路径且正确无误。在ROS启动文件的args中尤其要注意。 b.检查YAML文件YAML文件对缩进非常敏感。确保没有Tab键全部用空格。检查相机内参、畸变系数是否填写正确。一个快速验证的方法是先用一个绝对简单的配置文件比如只改图像尺寸和内参试试。 c.使用GDB调试在可执行命令前加上gdb --args例如gdb --args ./rgbd_tum ...。在GDB中运行run程序崩溃后输入bt查看调用栈可以精确定位到崩溃的代码行。 d.检查相机数据对于ROS节点先用rostopic echo /camera/color/image_raw --noarr和rostopic echo /camera/color/camera_info查看话题是否有数据发布以及数据是否正常。问题相机跟踪状态频繁在TRACKING和LOST之间切换原因环境特征不足、相机运动过快、相机参数不准确。解决改善环境增加视觉特征。如前所述避免在特征贫乏的区域运行。降低速度缓慢、平稳地移动相机。重新标定相机使用ROS的camera_calibration包对相机进行精确标定获取准确的内参和畸变系数更新到YAML配置文件中。不准确的相机模型是导致跟踪失败的一大元凶。调整算法参数适当增加nFeatures或减小scaleFactor如从1.2调到1.1让特征提取更密集或尺度变化更平滑。问题Pangolin窗口黑屏或地图点不更新原因通常是图像数据没有正确传入ORB-SLAM3或者跟踪线程已经彻底丢失并无法重定位。解决首先确认图像话题是否成功订阅。在ORB-SLAM3启动时终端会打印Subscribed to: /camera/color/image_raw等信息。如果没有检查ROS节点名和话题名是否匹配。ORB-SLAM3的默认订阅话题在Examples/ROS/ORB_SLAM3/src/ros_rgbd.cc等源文件中定义你可以根据你的相机发布的话题名进行修改并重新编译。6.3 性能优化与进阶配置当系统能稳定运行后你可以考虑以下优化以提升精度或速度。词汇表优化默认的ORBvoc.txt是通用的但较大。你可以为特定场景如室内、走廊训练一个更小的、针对性的词汇表以加速回环检测和重定位。这需要使用DBoW2库提供的工具过程较为复杂但能显著提升在特定环境下的效率。使用IMU数据对于VIOORB-SLAM3最大的亮点之一是支持视觉惯性里程计VIO。如果你有带IMU的相机如Realsense D435i可以运行Stereo-Inertial或RGBD-Inertial模式。这需要在配置文件中启用IMU参数。确保相机驱动同时发布图像话题和IMU话题/imu/data。对相机和IMU进行时空联合标定获取两者之间的外参和延时。VIO模式在快速运动或纹理缺失时能提供比纯视觉更稳定、更准确的位姿估计。保存与加载地图ORB-SLAM3支持将构建好的地图保存为二进制文件下次启动时可以直接加载实现“长期定位”。这在机器人应用中非常实用。你需要修改ROS节点的代码在接收到特定服务调用或键盘指令时调用SaveMap()和LoadMap()函数。系统集成将ORB-SLAM3作为一个提供tf变换和nav_msgs/Odometry消息的ROS节点与你的机器人导航栈如move_base集成。这意味着你需要修改ROS包装器使其不仅发布位姿还持续发布从“地图”坐标系到“相机”坐标系的tf变换以及作为Odometry消息。这样其他节点如路径规划器就能直接使用SLAM提供的定位信息。从系统配置、编译、调试到最终与ROS集成并实时运行这个过程本身就是对现代视觉SLAM技术栈的一次深度实践。每一个错误的解决每一次参数的调整都让你对“机器如何感知世界”这个问题的理解加深一分。我自己的体会是耐心和系统性排查是成功的关键。不要害怕终端里滚动的红色错误信息把它们看作解决问题的线索。当你第一次看到自己摄像头实时构建出的三维点云地图在屏幕上延展开时那种成就感是对所有努力最好的回报。希望这份超详细的指南能帮你顺利跨过门槛进入视觉SLAM的精彩世界。