1. 项目概述为什么Pangolin是视觉SLAM开发者的必备工具在视觉SLAM、三维重建或者机器人感知的开发过程中我们经常需要实时地查看相机轨迹、点云地图或者对算法中间结果进行可视化调试。如果你还在用cv::imshow一张张地看图片或者把数据导出到MATLAB里再画图那效率就太低了。一个强大、轻量且跨平台的可视化工具能极大提升开发效率而Pangolin正是为此而生。Pangolin不是一个像OpenCV那样的通用计算机视觉库它的定位非常精准为视觉几何计算提供快速、简单的可视化与交互界面。你可以把它理解为一个“画图板”和“控制器”的结合体。它封装了OpenGL的渲染细节提供了简洁的C API让你能用几行代码就创建一个窗口并在其中绘制相机位姿通常用坐标系表示、三维点云、图像甚至构建一个简单的GUI来调节算法参数。在ORB-SLAM、VINS-Mono等众多知名开源SLAM系统中Pangolin都是默认的可视化后端用于展示稀疏地图点和相机运动轨迹。这次在Ubuntu上配置Pangolin几乎是每一个踏入视觉SLAM领域的研究者和工程师的“新手村”任务。过程看似简单但其中涉及的依赖管理、编译选项、与不同版本系统或硬件的兼容性问题常常会让初学者耗费大量时间。本文将基于我多次在Ubuntu 18.04, 20.04, 22.04等不同版本上的实战经验详细拆解Pangolin的安装、配置全过程并汇总那些官方文档不会明说但大概率会踩到的“坑”及其解决方案。2. 核心依赖解析与系统环境准备Pangolin的轻量化是相对的它为了跨平台和提供丰富的功能自身也依赖一系列基础库。在动手编译之前理清这些依赖的关系和作用能在出问题时快速定位。2.1 必须的系统级依赖这些是Pangolin运行和编译的基石通常通过系统的包管理器安装。CMake ( 3.10)这是现代C项目的标准构建工具。Pangolin使用CMake来管理编译流程。Ubuntu 20.04及以上版本自带的CMake版本通常已满足要求。你可以通过cmake --version来检查。GCC/GC编译器。推荐使用GCC 7及以上版本以支持更好的C11/14特性。Ubuntu 18.04默认是GCC 7.5足够使用。Git用于从GitHub克隆源代码。sudo apt-get install gitpkg-config一个帮助查找库文件和头文件的工具在配置阶段会被调用。sudo apt-get install pkg-config2.2 核心功能依赖库这些库赋予了Pangolin具体的可视化能力。Pangolin的CMake脚本能自动检测它们如果找不到相关功能会被禁用。OpenGL GLUT/GLEW这是Pangolin的渲染核心。libgl1-mesa-dev和libglu1-mesa-dev提供了OpenGL的实现Mesa和GLU工具库。freeglut3-dev或libglew-dev提供了窗口管理和OpenGL扩展功能。Pangolin两者都支持通常安装freeglut3-dev即可。安装命令sudo apt-get install libgl1-mesa-dev libglu1-mesa-dev freeglut3-devPython3 pybind11 (可选但推荐)Pangolin支持通过Python绑定进行调用这对于快速原型开发和脚本化可视化非常有用。即使你主要用C安装此依赖也能确保库的完整性。确保已安装Python3开发包sudo apt-get install python3-devpybind11会在编译时自动下载但有时网络问题会导致失败也可以手动安装sudo apt-get install pybind11-devWayland/ X11窗口系统。Ubuntu 22.04开始默认使用Wayland但许多图形应用包括Pangolin的某些功能在X11下更稳定。如果你在Wayland下遇到窗口创建问题可以尝试切换到X11会话。注意在服务器无图形界面环境下安装时需要安装“虚拟”的OpenGL实现如libgl1-mesa-dev和xorg-dev并可能使用虚拟帧缓冲区Xvfb来运行。但这属于高级用法本文主要针对桌面环境。2.3 可选但常用的增强依赖Eigen3 (3.3)一个高性能的线性代数库。虽然Pangolin不强制依赖Eigen但几乎所有的SLAM/几何计算项目都使用Eigen。Pangolin能很好地与Eigen类型如Eigen::Vector3d,Eigen::Matrix4f集成方便直接传入数据。安装sudo apt-get install libeigen3-devlibjpeg, libpng, libtiff, libopenexr用于图像加载和保存。如果你需要显示或保存截图这些库是必要的。sudo apt-get install libjpeg-dev libpng-dev libtiff-dev libopenexr-devFFMPEG用于录制视频。如果你需要将可视化过程录制成mp4等格式需要此库。sudo apt-get install libavcodec-dev libavformat-dev libavutil-dev libswscale-dev实操心得我建议一次性安装上述所有“核心功能依赖”和“增强依赖”。这能确保Pangolin以最全的功能进行编译避免日后因缺少某个功能而重新编译。使用以下组合命令sudo apt-get update sudo apt-get install -y cmake g git pkg-config libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev python3-dev libeigen3-dev libjpeg-dev libpng-dev libtiff-dev libopenexr-dev3. 从源码编译安装Pangolin的完整流程官方推荐从源码编译安装这样可以灵活控制编译选项并确保获得最新版本或特定版本。3.1 获取源代码打开终端选择一个你存放代码的目录例如~/workspace。cd ~/workspace git clone https://github.com/stevenlovegrove/Pangolin.git cd Pangolin克隆完成后建议检查一下标签选择一个稳定版本进行编译而不是直接使用可能不稳定的master分支。例如使用v0.8版本git checkout v0.8使用稳定版本可以避免遇到最新开发分支中可能存在的未知问题。3.2 配置与生成构建系统在Pangolin源码目录下创建一个独立的构建目录并进入这是一个良好的实践可以保持源码树的清洁。mkdir build cd build接下来使用CMake进行配置。这里有几个关键参数需要理解-DCMAKE_BUILD_TYPERelease指定编译为发布模式。这会开启编译器优化如-O3使生成的库更小、运行更快。如果是调试可改为Debug。-DCMAKE_INSTALL_PREFIX/usr/local指定安装路径。默认是/usr/local库和头文件将分别安装到/usr/local/lib和/usr/local/include。你也可以安装到用户目录如$HOME/.local以避免需要sudo权限。执行CMake配置命令cmake .. -DCMAKE_BUILD_TYPEReleaseCMake会运行一段时间检测系统上的所有依赖库。请仔细查看终端的输出信息。你会看到类似如下的检测结果-- Found OpenGL: /usr/lib/x86_64-linux-gnu/libOpenGL.so -- Found GLEW: /usr/include -- Found Python3: /usr/bin/python3.8 (found version 3.8.10) found components: Development Interpreter -- Found Eigen3: /usr/include/eigen3 (found version 3.3.7) -- BUILD_PANGOLIN_PYTHON: ON -- BUILD_PANGOLIN_FFMPEG: OFF (因为没装FFMPEG开发包)关键检查点确保你关心的功能如PythonOpenGL显示为FOUND或ON。如果某个必须的依赖如OpenGL未找到配置将失败你需要返回上一步安装对应的-dev包。3.3 编译与安装配置成功后开始编译。-j参数指定并行编译的线程数通常设置为CPU核心数可以显著加快编译速度。你可以用nproc命令查看核心数。make -j$(nproc)编译过程大约需要1-3分钟。如果遇到编译错误最常见的原因是依赖缺失或版本冲突错误信息通常会指向具体的头文件或函数。编译成功后将库和头文件安装到系统目录。这一步需要sudo权限因为要写入/usr/local。sudo make install安装完成后Pangolin的头文件会在/usr/local/include/pangolin库文件如libpangolin.so会在/usr/local/lib。3.4 验证安装创建一个简单的测试程序来验证安装是否成功。在任意位置新建一个文件test_pangolin.cpp#include pangolin/pangolin.h #include iostream int main() { // 创建窗口 pangolin::CreateWindowAndBind(Pangolin Test, 640, 480); // 启用深度测试 glEnable(GL_DEPTH_TEST); // 定义投影和模型视图矩阵 pangolin::OpenGlRenderState s_cam( pangolin::ProjectionMatrix(640, 480, 420, 420, 320, 240, 0.1, 1000), pangolin::ModelViewLookAt(-2, 2, -2, 0, 0, 0, pangolin::AxisY) ); // 创建交互视图 pangolin::Handler3D handler(s_cam); pangolin::View d_cam pangolin::CreateDisplay() .SetBounds(0.0, 1.0, 0.0, 1.0, -640.0f/480.0f) .SetHandler(handler); while(!pangolin::ShouldQuit()) { // 清空颜色和深度缓冲区 glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); d_cam.Activate(s_cam); // 在这里绘制一个简单的彩色立方体 pangolin::glDrawColouredCube(); // 交换帧缓冲区显示内容 pangolin::FinishFrame(); } std::cout Pangolin test passed! Installation is successful. std::endl; return 0; }编写一个简单的CMakeLists.txt来编译它cmake_minimum_required(VERSION 3.10) project(TestPangolin) find_package(Pangolin REQUIRED) add_executable(test_pangolin test_pangolin.cpp) target_link_libraries(test_pangolin PRIVATE pangolin)在终端中编译并运行mkdir test_build cd test_build cmake .. make ./test_pangolin如果弹出一个窗口里面有一个可以鼠标拖拽旋转的彩色立方体并且终端打印出成功信息那么恭喜你Pangolin安装配置成功4. 编译与运行中的典型问题及解决方案即便按照步骤操作也可能会遇到各种问题。下面是我总结的几个最常见的问题场景。4.1 依赖缺失导致的CMake配置失败问题描述执行cmake ..时报错Could NOT find OpenGL或Could NOT find GLEW等。原因分析系统缺少对应的开发包-dev包。apt-get install安装的运行时库和开发库是分开的。编译需要的是头文件.h和链接库.so这些都在-dev包里。解决方案根据错误信息安装对应的-dev包。例如找不到OpenGL就安装libgl1-mesa-dev。一个更彻底的方法是在Pangolin源码目录下查看CMakeLists.txt或scripts文件夹中的安装脚本如install_prerequisites.sh里面列出了所有依赖。你可以手动执行脚本或参照安装。如果确认已安装但CMake仍找不到可能是路径问题。可以尝试用apt-get install --reinstall重新安装。4.2 编译错误undefined reference to ‘glewInit‘问题描述make编译时链接阶段报错提示glewInit等函数未定义。原因分析这是典型的链接错误。可能的原因有系统中安装了多个版本的GLEW如libglew2.1和libglew2.2CMake找到了错误版本的头文件但链接了错误版本的库。Pangolin的CMake脚本在查找GLEW时链接库的名称设置不正确。解决方案统一依赖明确指定使用freeglut而不是glew。在CMake配置时强制关闭GLEW使用GLUT。重新配置cd build rm -rf * # 清除之前的配置缓存 cmake .. -DCMAKE_BUILD_TYPERelease -DBUILD_PANGOLIN_VIDEOOFF -DBUILD_PANGOLIN_GUION -DBUILD_PANGOLIN_APPON -DBUILD_PANGOLIN_PYTHONON -DGLEW_INCLUDE_DIR/usr/include -DGLEW_LIBRARY/usr/lib/x86_64-linux-gnu/libGLEW.so -DGLUT_INCLUDE_DIR/usr/include -DGLUT_glut_LIBRARY/usr/lib/x86_64-linux-gnu/libglut.so更简洁的方法是在CMake配置前确保只安装了freeglut3-dev并卸载可能冲突的libglew-devsudo apt-get remove libglew-dev。手动链接如果问题依旧可以尝试修改Pangolin源码CMakeLists.txt中关于GLEW的查找逻辑但这比较繁琐。对于大多数用户方案1已足够。4.3 运行时错误X11‘ related error或窗口无法创建问题描述程序编译成功但运行时崩溃错误信息涉及X11或GLX或者窗口一闪而过。原因分析显示环境问题在纯终端无图形界面的服务器上运行或者通过SSH连接但没有设置正确的DISPLAY环境变量。Wayland兼容性问题Ubuntu新版默认使用Wayland显示协议一些旧的OpenGL应用程序兼容性不佳。显卡驱动问题NVIDIA/AMD显卡驱动未正确安装或者使用的是开源驱动nouveau其OpenGL支持可能不完整。解决方案检查DISPLAY在终端输入echo $DISPLAY正常情况下应输出:0或:1。如果为空说明当前会话没有连接到显示服务器。确保你在图形桌面环境下运行程序。切换至X11如果使用Wayland尝试在登录界面选择“Ubuntu on Xorg”会话再登录。安装专有显卡驱动对于NVIDIA显卡使用ubuntu-drivers devices查看推荐驱动然后通过“软件和更新”-“附加驱动”安装或使用sudo apt install nvidia-driver-xxx。安装后重启。使用虚拟缓冲无头渲染如果必须在无显示器的服务器上运行可以安装xvfbX Virtual Frame Buffer来创建一个虚拟显示。sudo apt-get install xvfb Xvfb :99 -screen 0 1024x768x24 export DISPLAY:99然后在此终端中运行你的Pangolin程序。程序会正常渲染但你看不到窗口。这常用于自动化测试或生成图像序列。4.4 Python绑定导入失败ModuleNotFoundError: No module named ‘pypangolin‘问题描述C库安装成功但想在Python中import pypangolin时失败。原因分析Python绑定未编译CMake配置时BUILD_PANGOLIN_PYTHON选项可能被意外关闭或检测Python失败。安装路径不在Python搜索路径中pypangolin模块被安装到了非标准路径如/usr/local/lib/python3.8/site-packages而你的Python环境尤其是虚拟环境找不到它。Python版本不匹配编译时针对的是Python 3.8但运行时使用的是Python 3.10。解决方案重新编译并确保Python选项开启清除build目录重新运行CMake并观察输出中BUILD_PANGOLIN_PYTHON是否为ON。可以显式指定Python解释器路径cmake .. -DPython3_EXECUTABLE/usr/bin/python3.8。检查安装路径编译安装后在/usr/local/lib或/usr/lib下搜索pypangolin*.so文件找到其确切位置。然后将该路径添加到Python的sys.path中或者在虚拟环境中创建软链接。# 查找模块 find /usr -name *pypangolin*.so 2/dev/null # 假设找到 /usr/local/lib/python3.8/site-packages/pypangolin.cpython-38-x86_64-linux-gnu.so # 在Python中或设置环境变量 PYTHONPATH export PYTHONPATH/usr/local/lib/python3.8/site-packages:$PYTHONPATH使用pip安装如果可用某些Pangolin的分支或版本提供了pip安装方式这能更好地处理路径问题。但官方主分支通常只支持源码编译。5. 在SLAM项目以ORB-SLAM3为例中集成与使用Pangolin安装好Pangolin后我们来看如何在一个真实的SLAM项目中使用它。这里以ORB-SLAM3为例因为它清晰地展示了Pangolin在可视化方面的典型用法。5.1 在CMake项目中链接PangolinORB-SLAM3的CMakeLists.txt中关于Pangolin的部分是关键。你需要确保你的项目CMake能正确找到Pangolin。在你的项目CMakeLists.txt中添加如下内容# 1. 查找Pangolin包 find_package(Pangolin 0.8 REQUIRED) # 指定版本可选 # 2. 包含其头文件目录 include_directories(${Pangolin_INCLUDE_DIRS}) # 3. 在创建可执行文件或库时链接Pangolin库 target_link_libraries(your_target_name ${Pangolin_LIBRARIES})如果CMake提示找不到Pangolin可能是因为它被安装在了非标准路径。你可以通过设置CMAKE_PREFIX_PATH变量来提示CMake。cd your_project_build cmake .. -DCMAKE_PREFIX_PATH/usr/local5.2 Pangolin在SLAM中的核心可视化模式在ORB-SLAM3中Pangolin主要承担两个可视化任务地图查看器Map Viewer这是一个独立的线程持续渲染整个稀疏地图地图点和所有关键帧的位姿相机。它使用Pangolin的3D交互功能允许用户用鼠标旋转、缩放和平移地图视图。核心代码在Viewer.cc中。创建窗口与视图pangolin::CreateWindowAndBind创建窗口pangolin::CreateDisplay()创建3D显示区域并绑定一个Handler3D来实现鼠标交互。绘制相机使用glPushMatrix,glMultMatrixf将当前关键帧的位姿矩阵Eigen::Matrix4f或cv::Mat应用到OpenGL模型视图矩阵然后调用一个绘制相机模型通常是金字塔形的函数。绘制点云将地图点Eigen::Vector3f存入一个std::vector然后使用glPointSize设置点大小glColor3f设置颜色最后通过glVertex3f在循环中绘制所有点。为了提高效率通常会使用顶点数组Vertex Array或顶点缓冲对象VBO但ORB-SLAM3为了简洁使用了立即模式。帧查看器Frame Viewer显示当前跟踪帧的图像并在图像上叠加绘制特征点如ORB角点、匹配关系、跟踪状态等。这本质上是2D图像绘制。纹理上传使用pangolin::GlTexture类将OpenCV的cv::Mat图像数据上传为OpenGL纹理。2D绘制在Pangolin的2D视图中使用glDrawPixels较老或更现代的方式通过绘制一个覆盖整个视图的四边形并绑定纹理来显示图像。在其上再用glBegin(GL_POINTS)等绘制特征点。5.3 一个简化的Pangolin可视化循环示例下面是一个比第3.4节测试程序更贴近SLAM使用的简化示例展示了如何在一个循环中更新数据并渲染。// 初始化Pangolin pangolin::CreateWindowAndBind(SLAM Viewer, 1024, 768); glEnable(GL_DEPTH_TEST); glEnable(GL_BLEND); glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA); // 定义相机渲染对象视图投影矩阵 pangolin::OpenGlRenderState s_cam( pangolin::ProjectionMatrix(1024, 768, 500, 500, 512, 389, 0.1, 1000), pangolin::ModelViewLookAt(0, -5, -10, 0, 0, 0, pangolin::AxisNegZ) // 调整初始视角 ); // 创建交互视图 pangolin::Handler3D handler(s_cam); pangolin::View d_cam pangolin::CreateDisplay() .SetBounds(0.0, 1.0, 0.0, 1.0, -1024.0f/768.0f) .SetHandler(handler); // 主循环 while(!pangolin::ShouldQuit()) { glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); d_cam.Activate(s_cam); // --- 开始绘制3D内容 --- // 1. 绘制坐标系 glLineWidth(3); glColor3f(1.0, 0.0, 0.0); // X轴红色 pangolin::glDrawLine(0,0,0, 1,0,0); glColor3f(0.0, 1.0, 0.0); // Y轴绿色 pangolin::glDrawLine(0,0,0, 0,1,0); glColor3f(0.0, 0.0, 1.0); // Z轴蓝色 pangolin::glDrawLine(0,0,0, 0,0,1); // 2. 假设我们有一个从SLAM系统获取的相机位姿列表 poses 和地图点列表 points std::vectorEigen::Matrix4f poses getCameraPosesFromSLAM(); std::vectorEigen::Vector3f points getMapPointsFromSLAM(); glPointSize(2); glColor3f(1.0, 1.0, 0.0); // 地图点设为黄色 glBegin(GL_POINTS); for(const auto p : points) { glVertex3f(p.x(), p.y(), p.z()); } glEnd(); glLineWidth(2); glColor3f(0.0, 1.0, 1.0); // 相机轨迹设为青色 glBegin(GL_LINE_STRIP); for(const auto pose : poses) { // 提取位姿矩阵的平移部分 Eigen::Vector3f t pose.block3,1(0,3); glVertex3f(t.x(), t.y(), t.z()); } glEnd(); // 3. 绘制每个相机位姿的小模型 for(const auto pose : poses) { glPushMatrix(); // 将Eigen矩阵转换为OpenGL格式列优先并相乘 glMultMatrixf(pose.data()); // 调用一个绘制简单相机模型的函数 drawCamera(0.1f); // 参数是相机尺寸 glPopMatrix(); } // --- 结束绘制3D内容 --- pangolin::FinishFrame(); // 可以在这里添加一个短暂的休眠控制刷新率 std::this_thread::sleep_for(std::chrono::milliseconds(50)); }这个循环结构是SLAM可视化器的核心。在实际项目中getCameraPosesFromSLAM和getMapPointsFromSLAM函数会被替换为从SLAM系统的共享数据区通常是一个Map类安全地读取数据可能需要使用互斥锁进行保护。实操心得在复杂的多线程SLAM系统中可视化线程Pangolin主循环和SLAM计算线程跟踪、局部建图、闭环是分开的。数据同步是关键。通常的做法是在Map类中存储地图点和关键帧的副本并为这些数据提供带锁的访问接口。可视化线程在每一帧渲染前通过接口获取数据的“快照”然后基于这个快照进行绘制。这样避免了在绘制过程中数据被修改导致的崩溃或显示错乱。ORB-SLAM3中的MapDrawer类就扮演了这个“数据获取与绘制”的角色。