Ubuntu下Pangolin安装配置全攻略：解决视觉SLAM可视化开发痛点

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运行和编译的基石，通常通过系统的包管理器安装。

1. CMake (>= 3.10)：这是现代C++项目的标准构建工具。Pangolin使用CMake来管理编译流程。Ubuntu 20.04及以上版本自带的CMake版本通常已满足要求。你可以通过cmake --version来检查。
2. GCC/G++：C++编译器。推荐使用GCC 7及以上版本以支持更好的C++11/14特性。Ubuntu 18.04默认是GCC 7.5，足够使用。
3. Git：用于从GitHub克隆源代码。sudo apt-get install git
4. pkg-config：一个帮助查找库文件和头文件的工具，在配置阶段会被调用。sudo apt-get install pkg-config

2.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-dev

• Python3 & pybind11 (可选但推荐)：Pangolin支持通过Python绑定进行调用，这对于快速原型开发和脚本化可视化非常有用。即使你主要用C++，安装此依赖也能确保库的完整性。

  • 确保已安装Python3开发包：sudo apt-get install python3-dev
  • pybind11会在编译时自动下载，但有时网络问题会导致失败，也可以手动安装：sudo apt-get install pybind11-dev

• Wayland/ 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-dev
• libjpeg, libpng, libtiff, libopenexr：用于图像加载和保存。如果你需要显示或保存截图，这些库是必要的。sudo apt-get install libjpeg-dev libpng-dev libtiff-dev libopenexr-dev
• FFMPEG：用于录制视频。如果你需要将可视化过程录制成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-dev

3. 从源码编译安装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_TYPE=Release：指定编译为发布模式。这会开启编译器优化（如-O3），使生成的库更小、运行更快。如果是调试，可改为Debug。
• -DCMAKE_INSTALL_PREFIX=/usr/local：指定安装路径。默认是/usr/local，库和头文件将分别安装到/usr/local/lib和/usr/local/include。你也可以安装到用户目录，如$HOME/.local，以避免需要sudo权限。

执行CMake配置命令：

cmake .. -DCMAKE_BUILD_TYPE=Release

CMake会运行一段时间，检测系统上的所有依赖库。请仔细查看终端的输出信息。你会看到类似如下的检测结果：

-- 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开发包)

关键检查点：确保你关心的功能（如Python，OpenGL）显示为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包里。

解决方案：

1. 根据错误信息，安装对应的-dev包。例如，找不到OpenGL就安装libgl1-mesa-dev。
2. 一个更彻底的方法是，在Pangolin源码目录下查看CMakeLists.txt或scripts文件夹中的安装脚本（如install_prerequisites.sh），里面列出了所有依赖。你可以手动执行脚本或参照安装。
3. 如果确认已安装但CMake仍找不到，可能是路径问题。可以尝试用apt-get install --reinstall重新安装。

4.2 编译错误：undefined reference to ‘glewInit‘

问题描述：make编译时，链接阶段报错，提示glewInit等函数未定义。

原因分析：这是典型的链接错误。可能的原因有：

• 系统中安装了多个版本的GLEW（如libglew2.1和libglew2.2），CMake找到了错误版本的头文件，但链接了错误版本的库。
• Pangolin的CMake脚本在查找GLEW时，链接库的名称设置不正确。

解决方案：

1. 统一依赖：明确指定使用freeglut而不是glew。在CMake配置时，强制关闭GLEW，使用GLUT。重新配置：

   cd build rm -rf * # 清除之前的配置缓存 cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_PANGOLIN_VIDEO=OFF -DBUILD_PANGOLIN_GUI=ON -DBUILD_PANGOLIN_APP=ON -DBUILD_PANGOLIN_PYTHON=ON -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-dev：sudo apt-get remove libglew-dev。
2. 手动链接：如果问题依旧，可以尝试修改Pangolin源码CMakeLists.txt中关于GLEW的查找逻辑，但这比较繁琐。对于大多数用户，方案1已足够。

4.3 运行时错误：X11‘ related error或窗口无法创建

问题描述：程序编译成功，但运行时崩溃，错误信息涉及X11或GLX，或者窗口一闪而过。

原因分析：

1. 显示环境问题：在纯终端（无图形界面）的服务器上运行，或者通过SSH连接但没有设置正确的DISPLAY环境变量。
2. Wayland兼容性问题：Ubuntu新版默认使用Wayland显示协议，一些旧的OpenGL应用程序兼容性不佳。
3. 显卡驱动问题：NVIDIA/AMD显卡驱动未正确安装，或者使用的是开源驱动nouveau，其OpenGL支持可能不完整。

解决方案：

1. 检查DISPLAY：在终端输入echo $DISPLAY，正常情况下应输出:0或:1。如果为空，说明当前会话没有连接到显示服务器。确保你在图形桌面环境下运行程序。
2. 切换至X11：如果使用Wayland，尝试在登录界面选择“Ubuntu on Xorg”会话再登录。
3. 安装专有显卡驱动：对于NVIDIA显卡，使用ubuntu-drivers devices查看推荐驱动，然后通过“软件和更新”->“附加驱动”安装，或使用sudo apt install nvidia-driver-xxx。安装后重启。
4. 使用虚拟缓冲（无头渲染）：如果必须在无显示器的服务器上运行，可以安装xvfb（X 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时失败。

原因分析：

1. Python绑定未编译：CMake配置时，BUILD_PANGOLIN_PYTHON选项可能被意外关闭或检测Python失败。
2. 安装路径不在Python搜索路径中：pypangolin模块被安装到了非标准路径（如/usr/local/lib/python3.8/site-packages），而你的Python环境（尤其是虚拟环境）找不到它。
3. Python版本不匹配：编译时针对的是Python 3.8，但运行时使用的是Python 3.10。

解决方案：

1. 重新编译并确保Python选项开启：清除build目录，重新运行CMake，并观察输出中BUILD_PANGOLIN_PYTHON是否为ON。可以显式指定Python解释器路径：cmake .. -DPython3_EXECUTABLE=/usr/bin/python3.8。
2. 检查安装路径：编译安装后，在/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

3. 使用pip安装（如果可用）：某些Pangolin的分支或版本提供了pip安装方式，这能更好地处理路径问题。但官方主分支通常只支持源码编译。

5. 在SLAM项目（以ORB-SLAM3为例）中集成与使用Pangolin

安装好Pangolin后，我们来看如何在一个真实的SLAM项目中使用它。这里以ORB-SLAM3为例，因为它清晰地展示了Pangolin在可视化方面的典型用法。

5.1 在CMake项目中链接Pangolin

ORB-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/local"

5.2 Pangolin在SLAM中的核心可视化模式

在ORB-SLAM3中，Pangolin主要承担两个可视化任务：

1. 地图查看器（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为了简洁使用了立即模式。

2. 帧查看器（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::vector<Eigen::Matrix4f> poses = getCameraPosesFromSLAM(); std::vector<Eigen::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.block<3,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类就扮演了这个“数据获取与绘制”的角色。