Pangolin这个库做SLAM和三维视觉的朋友应该都不陌生。ORB-SLAM系列、OpenMVG这些项目都拿它做可视化OpenGL渲染加上一套干净的GUI封装用起来确实顺手。但说到安装在Ubuntu 22.04上折腾它的时候我踩过的坑一点都不少——依赖缺失、编译报错、Python绑定编译不过随便一个都能卡你半天。这篇文章就把我从零开始装Pangolin的完整过程捋一遍包括依赖怎么选、CMake参数怎么定、报错怎么排查照着走基本能一次过。1. 环境准备与依赖安装Pangolin本身是C写的底层依赖OpenGL和一系列图像、窗口库。在Ubuntu 22.04上装它第一步不是拉源码而是把系统的编译环境和依赖库装齐。这一步偷懒后面编译报错会教你做人。1.1 基础编译工具链先确保系统里有完整的编译工具。Ubuntu 22.04默认装的是GCC 11.2.0和CMake 3.22.1这两个版本编译Pangolin完全没问题不需要手动升级。如果你之前没装过build-essential先执行sudo apt update sudo apt install -y build-essential cmake git pkg-config这里有个细节值得说下pkg-config这个包经常被忽略但Pangolin在查找依赖时会用到它。另外如果你打算后续编译其他视觉库建议顺手把g、gcc也确认一下版本gcc --version cmake --version实测下来GCC 11和CMake 3.22这对组合在当前主流的Pangolin v0.9版本下没有任何兼容性问题不需要额外折腾工具链版本。1.2 核心依赖库详解Pangolin的依赖可以分成三组OpenGL相关的图形库、图像编解码库、以及辅助库。我按重要程度排一下第一组图形与窗口依赖sudo apt install -y libgl1-mesa-dev libglew-dev libglfw3-dev libx11-dev libxrandr-dev libxi-dev这里重点说下libglew-dev。GLEW是OpenGL扩展加载库Pangolin用它来管理OpenGL的函数指针。如果你漏装GLEWCMake配置阶段会直接报错说找不到GLEW。libglfw3-dev是GLFW窗口库Pangolin在新版本里默认用GLFW作为窗口后端。Ubuntu 22.04源里的GLFW版本是3.3.6满足Pangolin的要求。第二组图像处理依赖sudo apt install -y libjpeg-dev libpng-dev libtiff-devPangolin支持加载和显示JPEG、PNG、TIFF格式的图片。这三个库是它的图像IO后端。如果没装Pangolin编译时虽然不会报错但LoadImage这类接口会失去对应格式的支持运行时会静默失败。第三组辅助依赖sudo apt install -y libeigen3-dev libpython3-dev python3-piplibeigen3-dev是Eigen矩阵库Pangolin内部用Eigen做数学计算虽然它不是强制依赖但很多依赖Pangolin的项目比如ORB-SLAM3都要用Eigen建议一起装。libpython3-dev和python3-pip是为了编译Python绑定用的如果你只需要C版这两个可以不装但装了也不吃亏。1.3 依赖安装时容易踩的坑依赖安装看似简单但我在Ubuntu 22.04上遇到过一个比较隐蔽的问题。如果你执行sudo apt install时提示某些包无法定位大概率是软件源没更新或者源里没有对应包。这时候先执行sudo apt update如果还不行检查/etc/apt/sources.list确保universe组件是启用的。Ubuntu 22.04的libglfw3-dev在universe源里默认是开启的但个别精简版系统或镜像源可能把它关了。另外提醒一下不要图省事直接apt install libglew2.2这是运行时库不带开发头文件。编译Pangolin必须装libglew-dev这个包名带-dev后缀的才是开发版包含头文件和链接库。很多人第一次装的时候顺手装了运行时库结果CMake提示找不到头文件又折腾半天。2. 源码下载与编译配置依赖装好之后下面就是正戏拉Pangolin源码、配置CMake、编译安装。这个过程有不少细节会直接影响最终结果尤其是CMake参数的选择。2.1 获取Pangolin源码Pangolin的官方仓库在GitHub上推荐直接用git克隆git clone --recursive https://github.com/stevenlovegrove/Pangolin.git cd Pangolin这里有个重点--recursive参数不能省。Pangolin仓库里有几个子模块submodule主要是一个用于构建文档和部分组件的第三方工具库。如果你不加--recursiveCMake配置阶段会报submodule相关的错误或者某些组件编译失败。如果你已经克隆完了但忘了加参数可以在仓库目录里执行git submodule update --init --recursive效果和克隆时加--recursive一样。另外建议直接拉默认分支master目前对应的源码版本是v0.9系列。这个版本在Ubuntu 22.04上表现稳定不建议用老旧的v0.6或更早版本那些版本对新时代的OpenGL和GLFW支持不好。2.2 CMake配置详解Pangolin用CMake构建配置方式比较灵活。先创建构建目录然后运行cmake配置mkdir build cd build cmake ..默认配置会编译C库和Python绑定还会构建测试和示例程序。如果你想精简编译时间或者遇到某个组件编译失败可以用下面的参数灵活控制cmake .. -DCMAKE_BUILD_TYPERelease -DBUILD_EXAMPLESOFF -DBUILD_TESTSOFF -DBUILD_PANGOLIN_PYTHONOFF这几个参数的作用-DCMAKE_BUILD_TYPERelease开启编译优化。Pangolin作为渲染库Release和Debug的性能差距很大。如果你只是做可视化Debug版也能跑但帧率会明显下降。-DBUILD_EXAMPLESOFF不编译示例程序。示例代码对学习有帮助但如果你是急着在项目里用Pangolin可以先关掉缩短编译时间。-DBUILD_TESTSOFF不编译测试。-DBUILD_PANGOLIN_PYTHONOFF关闭Python绑定编译。这里要特别说明一下Python绑定的编译过程比较慢而且对pybind11的版本敏感。如果你不是要在Python里import pangolin建议关掉能省不少时间。我个人的习惯是第一次编译只保留核心库确认无误后再按需开启其他组件。这样排障范围小出了问题更容易定位。2.3 编译与安装CMake配置通过后直接开始编译make -j$(nproc)-j$(nproc)是让make用所有CPU核心并行编译。如果你机器内存不大比如只有8GB建议改成-j4避免编译时内存溢出导致卡死。Pangolin核心库的编译量不小8核16线程的机器大概要三五分钟如果开了Python绑定可能要十分钟以上。编译完成后没有报错就可以安装了sudo make install sudo ldconfigsudo ldconfig这步非常重要。Pangolin安装后会在/usr/local/lib下生成libpango_core.so、libpango_display.so、libpango_opengl.so等一组动态库。ldconfig会更新系统动态链接库缓存让运行时不至于找不到这些so文件。经常有人装完Pangolin编译项目链接失败就是因为忘了执行ldconfig。3. 安装验证与工程应用装好之后不能直接说“完事”得实际验证一下库能不能用。这个环节我每次都会做因为静态检查通过不代表运行时一切正常尤其是涉及图形渲染的程序问题往往在运行时才暴露。3.1 验证安装是否成功最简单的验证方式是检查头文件和动态库是否就位ls /usr/local/include/pangolin ls /usr/local/lib/libpango* 2/dev/null如果头文件存在、动态库列表里能看到libpango_core.so等文件说明安装基本成功。更靠谱的验证是写个最小的测试程序。创建一个test_pangolin.cpp#include pangolin/pangolin.h #include iostream int main() { std::cout Pangolin version: pangolin::Version() std::endl; std::cout Pangolin is ready. std::endl; return 0; }编译运行g -o test_pangolin test_pangolin.cpp -lpangolin ./test_pangolin如果输出版本号且程序正常退出说明链接没问题。这里用-lpangolin是直接链接主库实际项目中通常会通过CMakefind_package(Pangolin)来管理链接。3.2 在CMake工程中集成PangolinPangolin安装时会自动安装CMake配置文件。在项目的CMakeLists.txt里这样引用find_package(Pangolin REQUIRED) add_executable(my_app main.cpp) target_link_libraries(my_app ${Pangolin_LIBRARIES}) target_include_directories(my_app PRIVATE ${Pangolin_INCLUDE_DIRS})这里有个容易踩坑的点不同版本的PangolinCMake变量名不完全一样。v0.6时代的变量是Pangolin_LIBRARIES和Pangolin_INCLUDE_DIRS但新版v0.8有些版本改成了pango_display这种细粒度目标。如果你find_package之后变量没定义可以在CMakeLists里先打印一下message(STATUS Pangolin LIBRARIES${Pangolin_LIBRARIES}) message(STATUS Pangolin INCLUDE_DIRS${Pangolin_INCLUDE_DIRS})根据实际输出再做调整。如果找不到Pangolin包多半是CMake的模块路径没有包含/usr/local/lib/cmake/Pangolin可以在CMakeLists里加一句set(CMAKE_PREFIX_PATH /usr/local/lib/cmake/Pangolin)3.3 一个可跑的Pangolin小程序为了验证完整功能我通常会跑一个带窗口的示例。下面这段代码创建了一个3D视口并显示一个旋转的立方体它能验证OpenGL渲染、窗口创建、鼠标交互这些核心功能是否正常。#include pangolin/pangolin.h #include cmath int main(int argc, char** argv) { pangolin::CreateWindowAndBind(Pangolin Test, 640, 480); glEnable(GL_DEPTH_TEST); pangolin::OpenGlRenderState s_cam( pangolin::ProjectionMatrix(640, 480, 420, 420, 320, 240, 0.2, 100), pangolin::ModelViewLookAt(-2, 2, -2, 0, 0, 0, pangolin::AxisY) ); pangolin::View d_cam pangolin::CreateDisplay() .SetBounds(0.0, 1.0, 0.0, 1.0) .SetHandler(new pangolin::Handler3D(s_cam)); while (!pangolin::ShouldQuit()) { glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); d_cam.Activate(s_cam); glColor3f(0.8f, 0.3f, 0.2f); pangolin::glDrawColouredCube(); pangolin::FinishFrame(); } return 0; }编译命令g -o cube_demo cube_demo.cpp $(pkg-config --cflags --libs pangolin)这个程序值得实际跑一下因为它能暴露大多数运行时问题比如OpenGL版本不兼容、窗口系统初始化失败等。屏幕上出现彩色立方体并且能用鼠标拖拽旋转就说明Pangolin的整个渲染管线工作正常。4. 常见问题与排查技巧实录我在安装和使用Pangolin的过程中踩过不少坑有些问题网上能搜到答案有些则费了不少功夫才找到原因。这里整理几个高频问题按出现概率排序。4.1 常见报错速查表错误现象可能原因解决方案CMake提示找不到GLEW未安装libglew-devsudo apt install libglew-devCMake提示找不到GLFW未安装libglfw3-devsudo apt install libglfw3-dev编译时报错fatal error: pangolin/xxx.h: No such file or directory头文件路径未正确配置检查CMakeLists里的include目录确认指向/usr/local/include链接时报错cannot find -lpangolin动态库未安装或ldconfig未执行确认libpango*.so是否存在执行sudo ldconfig运行时报Segmentation Fault显卡驱动或OpenGL上下文问题检查OpenGL版本更新显卡驱动Python绑定导入失败Python版本不匹配或pybind11版本问题确认编译Python绑定时用的Python版本与运行时一致4.2 编译时缺头文件的典型场景有一次我在新机器上装Pangolin所有依赖都按常规装好了但编译到display/device/display_x11.cpp时报错说找不到X11/Xlib.h。排查下来发现是libx11-dev没装。这个问题看起来很基础但容易漏因为X11开发头文件只影响Pangolin的X11后端如果当时CMake检测到其他窗口后端可用就不会触发。为了避免这种问题我后来在装依赖时习惯把X11相关的一起装掉sudo apt install -y libx11-dev libxrandr-dev libxi-dev4.3 Python绑定编译失败的排查如果你在Ubuntu 22.04上编译Pangolin的Python绑定BUILD_PANGOLIN_PYTHONON可能会遇到pybind11找不到的报错。这是因为Pangolin v0.9的Python绑定依赖pybind11的特定版本系统通过apt装的pybind11可能版本不符。解决办法是给Pangolin指定外部pybind11的路径或者干脆用pip装一个新版pybind11pip3 install pybind11然后在CMake配置时指定路径cmake .. -Dpybind11_DIR$(python3 -m pybind11 --cmakedir)如果这个方案还不行我的建议是直接关掉Python绑定毕竟在SLAM和三维视觉的开发生态里主流项目调用Pangolin都是走C接口。Python绑定更多是实验性质不值得在上面耗太多时间。4.4 运行时报OpenGL版本过低的问题Ubuntu 22.04上如果你的机器显卡驱动没装好Pangolin创建窗口时会报出类似OpenGL 3.0 required的错误。这类问题的根源通常是系统在用默认的llvmpipe软件渲染而不是独立显卡。排查方法glxinfo | grep OpenGL version如果输出里出现llvmpipe说明在用CPU软渲染。解决思路是安装对应显卡的驱动NVIDIA卡装nvidia-driver-XXXAMD卡装mesa相关包。这里不展开讲驱动安装但可以给个通用建议在虚拟机里装Pangolin时如果OpenGL版本报错多半是虚拟机的3D加速没开检查一下虚拟机的显示设置开启3D加速通常能解决。4.5 卸载和重装Pangolin的卸载比较麻烦因为make install不会留下卸载脚本。如果你装出了问题想重装可以手动删除文件或者忽略旧安装直接从源码重新编译覆盖安装。我实际操作中验证过一种相对干净的卸载方式cd Pangolin/build sudo make uninstall新版CMake生成的构建规则里包含uninstall目标可以执行。如果提示没有这个target就手动清理sudo rm -rf /usr/local/include/pangolin sudo rm -f /usr/local/lib/libpango*.so* sudo rm -rf /usr/local/lib/cmake/Pangolin清理完再重新走一遍编译安装流程即可。5. 进阶实践静态编译与交叉编译要点标准流程跑通后有些场景会需要额外配置。我补充两种实际工程中可能遇到的进阶用法静态编译和交叉编译。这两种情况在日常SLAM项目里不多见但在特定场景部署到无图形环境的服务器、嵌入式设备中会用到。5.1 静态编译Pangolin默认情况下Pangolin编译生成的是动态库.so文件方便共享和链接。但如果你需要把程序部署到没有Pangolin运行环境的机器上静态链接是更省心的选择。静态编译的关键是让CMake生成静态库。可以在配置时指定cmake .. -DBUILD_SHARED_LIBSOFF同时要保证依赖库也是静态版。比如GLFW、GLEW都需要有对应的.a文件否则静态链接阶段会报找不到符号。这个方案理论上可行但我实际试下来发现GLFW和GLEW的静态库编译并不总是顺利建议除非确实有必要否则优先用动态库方案。真要在无图形环境的服务器上用Pangolin还有个思路是用虚拟屏幕比如Xvfb或者直接用Pangolin的无头模式。这些方案比静态编译省事得多。5.2 交叉编译的注意事项在ARM开发板如树莓派、Jetson上编译Pangolin需要用到交叉编译环境。这里只提示一个关键点Pangolin的第三方依赖GLFW、GLEW等也需要交叉编译直接使用宿主机上的x86版库是行不通的。如果你在嵌入式平台上用Pangolin我建议直接在目标板子上原生编译而不是交叉编译。Pangolin本身的编译开销在树莓派4上大概十几分钟Jetson系列更快完全可以接受。5.3 与ORB-SLAM系列搭配的配置细节最后补一个实际工程里最常见的场景给ORB-SLAM2或ORB-SLAM3配置Pangolin。这两个项目用Pangolin做轨迹和关键帧可视化安装Pangolin时建议保持默认配置也就是不要关掉示例程序因为ORB-SLAM的CMakeLists里有时候会依赖Pangolin的一些组件。编译ORB-SLAM3时如果链接阶段报Pangolin相关错误先确认是不是同时装过多个版本的Pangolin尤其是用apt install ros-xxx-pangolin之类命令装过的ROS版本Pangolin经常会和源码装的Pangolin冲突。遇到这种情况最干净的办法是卸载ROS版保留源码版或者反过来统一用ROS版。我个人在实际操作中更倾向于源码安装因为版本可控出问题好排查。Pangolin的安装总结起来就是三步装好依赖、编译安装、验证运行。大部分问题都出在依赖缺失和版本冲突上只要耐心排查都能解决。最后分享一个我自己的习惯装Pangolin这类基础库时会在装完之后顺手验证一下动态库依赖是否完整用ldd检查一下关键so文件的依赖ldd /usr/local/lib/libpango_display.so | grep not found如果这个命令没有任何输出说明所有依赖都齐了后续编译项目基本不会遇到链接错误。这个小检查花不了几秒钟但能省掉后面可能遇到的几个小时排障时间算是长期踩坑换来的经验。
Ubuntu 22.04 安装 Pangolin 全攻略：依赖配置、编译避坑与 SLAM 可视化实践
Pangolin这个库做SLAM和三维视觉的朋友应该都不陌生。ORB-SLAM系列、OpenMVG这些项目都拿它做可视化OpenGL渲染加上一套干净的GUI封装用起来确实顺手。但说到安装在Ubuntu 22.04上折腾它的时候我踩过的坑一点都不少——依赖缺失、编译报错、Python绑定编译不过随便一个都能卡你半天。这篇文章就把我从零开始装Pangolin的完整过程捋一遍包括依赖怎么选、CMake参数怎么定、报错怎么排查照着走基本能一次过。1. 环境准备与依赖安装Pangolin本身是C写的底层依赖OpenGL和一系列图像、窗口库。在Ubuntu 22.04上装它第一步不是拉源码而是把系统的编译环境和依赖库装齐。这一步偷懒后面编译报错会教你做人。1.1 基础编译工具链先确保系统里有完整的编译工具。Ubuntu 22.04默认装的是GCC 11.2.0和CMake 3.22.1这两个版本编译Pangolin完全没问题不需要手动升级。如果你之前没装过build-essential先执行sudo apt update sudo apt install -y build-essential cmake git pkg-config这里有个细节值得说下pkg-config这个包经常被忽略但Pangolin在查找依赖时会用到它。另外如果你打算后续编译其他视觉库建议顺手把g、gcc也确认一下版本gcc --version cmake --version实测下来GCC 11和CMake 3.22这对组合在当前主流的Pangolin v0.9版本下没有任何兼容性问题不需要额外折腾工具链版本。1.2 核心依赖库详解Pangolin的依赖可以分成三组OpenGL相关的图形库、图像编解码库、以及辅助库。我按重要程度排一下第一组图形与窗口依赖sudo apt install -y libgl1-mesa-dev libglew-dev libglfw3-dev libx11-dev libxrandr-dev libxi-dev这里重点说下libglew-dev。GLEW是OpenGL扩展加载库Pangolin用它来管理OpenGL的函数指针。如果你漏装GLEWCMake配置阶段会直接报错说找不到GLEW。libglfw3-dev是GLFW窗口库Pangolin在新版本里默认用GLFW作为窗口后端。Ubuntu 22.04源里的GLFW版本是3.3.6满足Pangolin的要求。第二组图像处理依赖sudo apt install -y libjpeg-dev libpng-dev libtiff-devPangolin支持加载和显示JPEG、PNG、TIFF格式的图片。这三个库是它的图像IO后端。如果没装Pangolin编译时虽然不会报错但LoadImage这类接口会失去对应格式的支持运行时会静默失败。第三组辅助依赖sudo apt install -y libeigen3-dev libpython3-dev python3-piplibeigen3-dev是Eigen矩阵库Pangolin内部用Eigen做数学计算虽然它不是强制依赖但很多依赖Pangolin的项目比如ORB-SLAM3都要用Eigen建议一起装。libpython3-dev和python3-pip是为了编译Python绑定用的如果你只需要C版这两个可以不装但装了也不吃亏。1.3 依赖安装时容易踩的坑依赖安装看似简单但我在Ubuntu 22.04上遇到过一个比较隐蔽的问题。如果你执行sudo apt install时提示某些包无法定位大概率是软件源没更新或者源里没有对应包。这时候先执行sudo apt update如果还不行检查/etc/apt/sources.list确保universe组件是启用的。Ubuntu 22.04的libglfw3-dev在universe源里默认是开启的但个别精简版系统或镜像源可能把它关了。另外提醒一下不要图省事直接apt install libglew2.2这是运行时库不带开发头文件。编译Pangolin必须装libglew-dev这个包名带-dev后缀的才是开发版包含头文件和链接库。很多人第一次装的时候顺手装了运行时库结果CMake提示找不到头文件又折腾半天。2. 源码下载与编译配置依赖装好之后下面就是正戏拉Pangolin源码、配置CMake、编译安装。这个过程有不少细节会直接影响最终结果尤其是CMake参数的选择。2.1 获取Pangolin源码Pangolin的官方仓库在GitHub上推荐直接用git克隆git clone --recursive https://github.com/stevenlovegrove/Pangolin.git cd Pangolin这里有个重点--recursive参数不能省。Pangolin仓库里有几个子模块submodule主要是一个用于构建文档和部分组件的第三方工具库。如果你不加--recursiveCMake配置阶段会报submodule相关的错误或者某些组件编译失败。如果你已经克隆完了但忘了加参数可以在仓库目录里执行git submodule update --init --recursive效果和克隆时加--recursive一样。另外建议直接拉默认分支master目前对应的源码版本是v0.9系列。这个版本在Ubuntu 22.04上表现稳定不建议用老旧的v0.6或更早版本那些版本对新时代的OpenGL和GLFW支持不好。2.2 CMake配置详解Pangolin用CMake构建配置方式比较灵活。先创建构建目录然后运行cmake配置mkdir build cd build cmake ..默认配置会编译C库和Python绑定还会构建测试和示例程序。如果你想精简编译时间或者遇到某个组件编译失败可以用下面的参数灵活控制cmake .. -DCMAKE_BUILD_TYPERelease -DBUILD_EXAMPLESOFF -DBUILD_TESTSOFF -DBUILD_PANGOLIN_PYTHONOFF这几个参数的作用-DCMAKE_BUILD_TYPERelease开启编译优化。Pangolin作为渲染库Release和Debug的性能差距很大。如果你只是做可视化Debug版也能跑但帧率会明显下降。-DBUILD_EXAMPLESOFF不编译示例程序。示例代码对学习有帮助但如果你是急着在项目里用Pangolin可以先关掉缩短编译时间。-DBUILD_TESTSOFF不编译测试。-DBUILD_PANGOLIN_PYTHONOFF关闭Python绑定编译。这里要特别说明一下Python绑定的编译过程比较慢而且对pybind11的版本敏感。如果你不是要在Python里import pangolin建议关掉能省不少时间。我个人的习惯是第一次编译只保留核心库确认无误后再按需开启其他组件。这样排障范围小出了问题更容易定位。2.3 编译与安装CMake配置通过后直接开始编译make -j$(nproc)-j$(nproc)是让make用所有CPU核心并行编译。如果你机器内存不大比如只有8GB建议改成-j4避免编译时内存溢出导致卡死。Pangolin核心库的编译量不小8核16线程的机器大概要三五分钟如果开了Python绑定可能要十分钟以上。编译完成后没有报错就可以安装了sudo make install sudo ldconfigsudo ldconfig这步非常重要。Pangolin安装后会在/usr/local/lib下生成libpango_core.so、libpango_display.so、libpango_opengl.so等一组动态库。ldconfig会更新系统动态链接库缓存让运行时不至于找不到这些so文件。经常有人装完Pangolin编译项目链接失败就是因为忘了执行ldconfig。3. 安装验证与工程应用装好之后不能直接说“完事”得实际验证一下库能不能用。这个环节我每次都会做因为静态检查通过不代表运行时一切正常尤其是涉及图形渲染的程序问题往往在运行时才暴露。3.1 验证安装是否成功最简单的验证方式是检查头文件和动态库是否就位ls /usr/local/include/pangolin ls /usr/local/lib/libpango* 2/dev/null如果头文件存在、动态库列表里能看到libpango_core.so等文件说明安装基本成功。更靠谱的验证是写个最小的测试程序。创建一个test_pangolin.cpp#include pangolin/pangolin.h #include iostream int main() { std::cout Pangolin version: pangolin::Version() std::endl; std::cout Pangolin is ready. std::endl; return 0; }编译运行g -o test_pangolin test_pangolin.cpp -lpangolin ./test_pangolin如果输出版本号且程序正常退出说明链接没问题。这里用-lpangolin是直接链接主库实际项目中通常会通过CMakefind_package(Pangolin)来管理链接。3.2 在CMake工程中集成PangolinPangolin安装时会自动安装CMake配置文件。在项目的CMakeLists.txt里这样引用find_package(Pangolin REQUIRED) add_executable(my_app main.cpp) target_link_libraries(my_app ${Pangolin_LIBRARIES}) target_include_directories(my_app PRIVATE ${Pangolin_INCLUDE_DIRS})这里有个容易踩坑的点不同版本的PangolinCMake变量名不完全一样。v0.6时代的变量是Pangolin_LIBRARIES和Pangolin_INCLUDE_DIRS但新版v0.8有些版本改成了pango_display这种细粒度目标。如果你find_package之后变量没定义可以在CMakeLists里先打印一下message(STATUS Pangolin LIBRARIES${Pangolin_LIBRARIES}) message(STATUS Pangolin INCLUDE_DIRS${Pangolin_INCLUDE_DIRS})根据实际输出再做调整。如果找不到Pangolin包多半是CMake的模块路径没有包含/usr/local/lib/cmake/Pangolin可以在CMakeLists里加一句set(CMAKE_PREFIX_PATH /usr/local/lib/cmake/Pangolin)3.3 一个可跑的Pangolin小程序为了验证完整功能我通常会跑一个带窗口的示例。下面这段代码创建了一个3D视口并显示一个旋转的立方体它能验证OpenGL渲染、窗口创建、鼠标交互这些核心功能是否正常。#include pangolin/pangolin.h #include cmath int main(int argc, char** argv) { pangolin::CreateWindowAndBind(Pangolin Test, 640, 480); glEnable(GL_DEPTH_TEST); pangolin::OpenGlRenderState s_cam( pangolin::ProjectionMatrix(640, 480, 420, 420, 320, 240, 0.2, 100), pangolin::ModelViewLookAt(-2, 2, -2, 0, 0, 0, pangolin::AxisY) ); pangolin::View d_cam pangolin::CreateDisplay() .SetBounds(0.0, 1.0, 0.0, 1.0) .SetHandler(new pangolin::Handler3D(s_cam)); while (!pangolin::ShouldQuit()) { glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); d_cam.Activate(s_cam); glColor3f(0.8f, 0.3f, 0.2f); pangolin::glDrawColouredCube(); pangolin::FinishFrame(); } return 0; }编译命令g -o cube_demo cube_demo.cpp $(pkg-config --cflags --libs pangolin)这个程序值得实际跑一下因为它能暴露大多数运行时问题比如OpenGL版本不兼容、窗口系统初始化失败等。屏幕上出现彩色立方体并且能用鼠标拖拽旋转就说明Pangolin的整个渲染管线工作正常。4. 常见问题与排查技巧实录我在安装和使用Pangolin的过程中踩过不少坑有些问题网上能搜到答案有些则费了不少功夫才找到原因。这里整理几个高频问题按出现概率排序。4.1 常见报错速查表错误现象可能原因解决方案CMake提示找不到GLEW未安装libglew-devsudo apt install libglew-devCMake提示找不到GLFW未安装libglfw3-devsudo apt install libglfw3-dev编译时报错fatal error: pangolin/xxx.h: No such file or directory头文件路径未正确配置检查CMakeLists里的include目录确认指向/usr/local/include链接时报错cannot find -lpangolin动态库未安装或ldconfig未执行确认libpango*.so是否存在执行sudo ldconfig运行时报Segmentation Fault显卡驱动或OpenGL上下文问题检查OpenGL版本更新显卡驱动Python绑定导入失败Python版本不匹配或pybind11版本问题确认编译Python绑定时用的Python版本与运行时一致4.2 编译时缺头文件的典型场景有一次我在新机器上装Pangolin所有依赖都按常规装好了但编译到display/device/display_x11.cpp时报错说找不到X11/Xlib.h。排查下来发现是libx11-dev没装。这个问题看起来很基础但容易漏因为X11开发头文件只影响Pangolin的X11后端如果当时CMake检测到其他窗口后端可用就不会触发。为了避免这种问题我后来在装依赖时习惯把X11相关的一起装掉sudo apt install -y libx11-dev libxrandr-dev libxi-dev4.3 Python绑定编译失败的排查如果你在Ubuntu 22.04上编译Pangolin的Python绑定BUILD_PANGOLIN_PYTHONON可能会遇到pybind11找不到的报错。这是因为Pangolin v0.9的Python绑定依赖pybind11的特定版本系统通过apt装的pybind11可能版本不符。解决办法是给Pangolin指定外部pybind11的路径或者干脆用pip装一个新版pybind11pip3 install pybind11然后在CMake配置时指定路径cmake .. -Dpybind11_DIR$(python3 -m pybind11 --cmakedir)如果这个方案还不行我的建议是直接关掉Python绑定毕竟在SLAM和三维视觉的开发生态里主流项目调用Pangolin都是走C接口。Python绑定更多是实验性质不值得在上面耗太多时间。4.4 运行时报OpenGL版本过低的问题Ubuntu 22.04上如果你的机器显卡驱动没装好Pangolin创建窗口时会报出类似OpenGL 3.0 required的错误。这类问题的根源通常是系统在用默认的llvmpipe软件渲染而不是独立显卡。排查方法glxinfo | grep OpenGL version如果输出里出现llvmpipe说明在用CPU软渲染。解决思路是安装对应显卡的驱动NVIDIA卡装nvidia-driver-XXXAMD卡装mesa相关包。这里不展开讲驱动安装但可以给个通用建议在虚拟机里装Pangolin时如果OpenGL版本报错多半是虚拟机的3D加速没开检查一下虚拟机的显示设置开启3D加速通常能解决。4.5 卸载和重装Pangolin的卸载比较麻烦因为make install不会留下卸载脚本。如果你装出了问题想重装可以手动删除文件或者忽略旧安装直接从源码重新编译覆盖安装。我实际操作中验证过一种相对干净的卸载方式cd Pangolin/build sudo make uninstall新版CMake生成的构建规则里包含uninstall目标可以执行。如果提示没有这个target就手动清理sudo rm -rf /usr/local/include/pangolin sudo rm -f /usr/local/lib/libpango*.so* sudo rm -rf /usr/local/lib/cmake/Pangolin清理完再重新走一遍编译安装流程即可。5. 进阶实践静态编译与交叉编译要点标准流程跑通后有些场景会需要额外配置。我补充两种实际工程中可能遇到的进阶用法静态编译和交叉编译。这两种情况在日常SLAM项目里不多见但在特定场景部署到无图形环境的服务器、嵌入式设备中会用到。5.1 静态编译Pangolin默认情况下Pangolin编译生成的是动态库.so文件方便共享和链接。但如果你需要把程序部署到没有Pangolin运行环境的机器上静态链接是更省心的选择。静态编译的关键是让CMake生成静态库。可以在配置时指定cmake .. -DBUILD_SHARED_LIBSOFF同时要保证依赖库也是静态版。比如GLFW、GLEW都需要有对应的.a文件否则静态链接阶段会报找不到符号。这个方案理论上可行但我实际试下来发现GLFW和GLEW的静态库编译并不总是顺利建议除非确实有必要否则优先用动态库方案。真要在无图形环境的服务器上用Pangolin还有个思路是用虚拟屏幕比如Xvfb或者直接用Pangolin的无头模式。这些方案比静态编译省事得多。5.2 交叉编译的注意事项在ARM开发板如树莓派、Jetson上编译Pangolin需要用到交叉编译环境。这里只提示一个关键点Pangolin的第三方依赖GLFW、GLEW等也需要交叉编译直接使用宿主机上的x86版库是行不通的。如果你在嵌入式平台上用Pangolin我建议直接在目标板子上原生编译而不是交叉编译。Pangolin本身的编译开销在树莓派4上大概十几分钟Jetson系列更快完全可以接受。5.3 与ORB-SLAM系列搭配的配置细节最后补一个实际工程里最常见的场景给ORB-SLAM2或ORB-SLAM3配置Pangolin。这两个项目用Pangolin做轨迹和关键帧可视化安装Pangolin时建议保持默认配置也就是不要关掉示例程序因为ORB-SLAM的CMakeLists里有时候会依赖Pangolin的一些组件。编译ORB-SLAM3时如果链接阶段报Pangolin相关错误先确认是不是同时装过多个版本的Pangolin尤其是用apt install ros-xxx-pangolin之类命令装过的ROS版本Pangolin经常会和源码装的Pangolin冲突。遇到这种情况最干净的办法是卸载ROS版保留源码版或者反过来统一用ROS版。我个人在实际操作中更倾向于源码安装因为版本可控出问题好排查。Pangolin的安装总结起来就是三步装好依赖、编译安装、验证运行。大部分问题都出在依赖缺失和版本冲突上只要耐心排查都能解决。最后分享一个我自己的习惯装Pangolin这类基础库时会在装完之后顺手验证一下动态库依赖是否完整用ldd检查一下关键so文件的依赖ldd /usr/local/lib/libpango_display.so | grep not found如果这个命令没有任何输出说明所有依赖都齐了后续编译项目基本不会遇到链接错误。这个小检查花不了几秒钟但能省掉后面可能遇到的几个小时排障时间算是长期踩坑换来的经验。
