又是一个编译夜。COLMAP这套三维重建工具箱用起来是真顺手但每次说到“从源码编译”我身边不少朋友直接叹气。尤其是到了Ubuntu 24.04 CUDA 12.9这种新组合网上能搜到的教程还停留在CUDA 11.x、Ubuntu 20.04的年代照着抄必然翻车。这篇文章就专门聊聊COLMAP 3.13.0配CUDA 12.9在Ubuntu 24.04上的完整编译过程把版本搭配逻辑、依赖安装的坑、CMake配置的关键开关一次说透。无论你是第一次编译的小白还是被依赖折腾过几次的进阶玩家这份实操记录应该都能省下你一晚上的折腾时间。1. 版本搭配的逻辑为什么是Ubuntu 24.04 CUDA 12.9 COLMAP 3.13.0编译COLMAP这件事难点从来不是COLMAP本身而是它脚下那一摞依赖。选对版本组合等于先把地基打稳。先说结论Ubuntu 24.04的glibc版本和gcc版本都比较新老一套CUDA 10.x、11.x在这里反而水土不服直接裸露在系统里的旧版本驱动也容易引发各种运行时崩溃。连带CUDA Toolkit推荐直接上12.x12.9是一个稳定可用的minor版本对Ubuntu 24.04的支持很友好。1.1 这套组合解决了什么核心痛点以前编译COLMAP最头疼的配置是“Ubuntu 20.04 CUDA 11.4 gcc 9”而现在系统默认gcc已经大步迈向了13.x老版本算力适配非常别扭。CUDA 12.9对gcc 13的支持比之前版本完善很多这就少了很多“Unsupported GNU version”一类的编译报错。另外Ubuntu 24.04里默认的Qt版本是Qt6COLMAP 3.13.0的GUI部分对Qt6的兼容性也做了不少跟进不再需要像老教程里那样特地把整个工具链拽回Qt5时代。组件推荐版本Ubuntu 24.04下的主要收益系统Ubuntu 24.04 LTS库版本较新编译生态友好CUDA12.9支持gcc 13兼容性稳定COLMAP3.13.0GUI/CLI整合完善支持Qt6编译器gcc-13系统自带无需额外降级1.2 什么情况下不建议这套组合如果你还在用RTX 20系这种老显卡并且手里已经有了一套跑得顺的旧环境那就没有折腾新编译的必要。这套组合适合的是新装机器、新项目打底、或者想跟上游代码保持同步的人。COLMAP 3.13.0加了若干新功能但你要是只需要稠密重建和简单的特征匹配稳定版预编译包反而省心。自己编译最大的价值在于你能打开Ceres、CUDA架构扩展等底层选项调出更适合自己数据规模和显卡算力的构建版本。我也不建议在WSL里跑这套方案。WSL里的GPU直通依赖Windows侧驱动CUDA运行时和显卡驱动之间的版本匹配逻辑跟纯Linux环境不完全一样编译和运行的报错会让你分不清是环境问题还是代码问题。如果有条件老老实实用双系统或整机Linux编译过程中省下的时间远超装系统的时间。2. 依赖安装的顺序与关键细节别急着敲那一串apt installCOLMAP对依赖很敏感。apt install敲下去一时爽编译到一半报错才是真的难受。我在Ubuntu 24.04上完整跑通后整理了这样一套稳妥的依赖安装顺序。2.1 先装基础工具链和必要构建工具sudo apt update sudo apt upgrade -y sudo apt install -y \ build-essential \ cmake \ ninja-build \ git \ pkg-config \ wget \ unzip紧接着装COLMAP官方文档列出的核心库依赖sudo apt install -y \ libboost-program-options-dev \ libboost-filesystem-dev \ libboost-graph-dev \ libboost-system-dev \ libboost-test-dev \ libeigen3-dev \ libsuitesparse-dev \ libfreeimage-dev \ libmetis-dev \ libgoogle-glog-dev \ libgflags-dev \ libglew-dev \ qtbase5-dev \ libqt5opengl5-dev \ libcgal-dev \ libflann-dev \ libsqlite3-dev \ libhdf5-dev \ libpng-dev \ libjpeg-dev \ libtiff-dev \ liblz4-dev \ libzstd-dev注意这里用的是qtbase5-dev而不是Qt6相关的包。虽然COLMAP 3.13.0支持Qt6但我在实测中Qt5的稳定性和兼容表现更好尤其是在QScintilla这类辅助组件上。如果你在摸索新版时想试试Qt6直接替换成qt6-base-dev和libqt6opengl6-dev即可但后面QScintilla的编译条件会有差异这一点下文会具体说。2.2 关键组件单独处理GTS和FLANN的坑COLMAP的网格处理依赖libgts但Ubuntu 24.04的软件源里没有新版本而老版本又带不出来。比较稳的做法是自己编译GTSgit clone https://github.com/DLR-RM/gts.git cd gts autoreconf -f -i ./configure make -j$(nproc) sudo make installGTS编译本身很简单坑在于它的依赖libglib2.0-dev不能少否则autoreconf阶段就会报错。装好之后COLMAP的CMake会通过GTS_FOUND识别它。再说FLANN。Ubuntu 24.04源里的FLANN版本偏旧而且默认没有打开CUDA支持。COLMAP用的FLANN主要在特征匹配阶段做近邻搜索如果只是CPU版本也能跑但既然都上了CUDA 12.9就干脆自己编一版带CUDA的FLANNgit clone https://github.com/flann-lib/flann.git cd flann mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease -DBUILD_CUDA_LIBON make -j$(nproc) sudo make installFLANN编译的时候有概率报thrust相关的错误这是因为老版本FLANN对新的CUDA Thrust头文件兼容不到位。解决方法是拉取最新master分支或者在CMake里加-DCMAKE_CXX_STANDARD14。实测2024年之后的master分支在CUDA 12.9上编译无压力。2.3 Boost几何模块一个容易被跳过但绝对不能少的模块COLMAP的colmap/geometry大量使用Boost.Geometry但Ubuntu 24.04里libboost-all-dev太重而只装基础boost包又会把几何模块漏掉。我的做法是单独确认sudo apt install -y libboost-dev dpkg -L libboost-dev | grep geometry如果grep结果为空就再补一个libboost-geometry-dev。这个模块缺失时编译COLMAP会在colmap_geometry相关文件上报“找不到boost/geometry.hpp”这类错误非常容易让人误判成CMake配置问题。有几次我在网上帮人看日志十有八九都是漏了这个要命的几何头文件。提示如果不想在boost上浪费人生直接在apt命令里装libboost-all-dev也行就是多占用一点磁盘空间但能避免各种细碎缺失。3. CUDA 12.9安装与驱动对齐编译之前必须确认的事COLMAP编译过程中涉及大量CUDA核函数和Ceres自动求导这一步没对齐后面全是千奇百怪的编译错误。很多人在这轮翻车其实不是CUDA装得有毛病而是驱动版本和Toolkit版本对不上。3.1 驱动与Toolkit的匹配原则Ubuntu 24.04对NVIDIA显卡驱动的支持相当省心用系统自带的ubuntu-drivers工具就能装到合适版本sudo ubuntu-drivers install sudo reboot重启后用nvidia-smi确认驱动版本。这里的关键是nvidia-smi里显示的CUDA Version是驱动支持的最大CUDA版本它必须不低于你要装的CUDA 12.9。比如说驱动显示CUDA Version 12.4那装CUDA 12.9就是自己给自己找麻烦要么升级驱动要么把Toolkit换到12.4以下。3.2 安装CUDA Toolkit 12.9去NVIDIA官方页面下载对应runfile安装包是惯用做法。网络如果稳定用apt源反而更省事wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt update sudo apt install -y cuda-toolkit-12-9装完之后环境变量务必写进shell配置export PATH/usr/local/cuda-12.9/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-12.9/lib64:$LD_LIBRARY_PATH export CUDA_HOME/usr/local/cuda-12.9建议放到~/.bashrc而不是/etc/environment因为后者影响所有用户有时候反而会干扰系统的默认库查找。然后执行nvcc --version确认版本号。注意nvcc属于cuda-toolkit的一部分如果只装驱动是没有nvcc的很多新人卡在这一步误以为自己没装成功。3.3 CUDA与gcc 13的兼容性验证CUDA 12.9对gcc 13的支持是开箱即用的但保不齐你系统里还留存着老版本gcc系统/usr/bin/gcc的优先级可能会把老版本拽起来。稳妥起见在编译COLMAP之前先跑一句gcc --version确认默认gcc是13.x。如果默认还是老版本用update-alternatives切一下就行。编译过程中如果出现unsupported GNU version前缀的告警多半就是这个问题。CUDA 12.x在检测到不支持的gcc版本时会直接停下来而不是像以前那样只给warning所以提前确认很有必要。另外编译这类大项目时/usr/local/cuda这个软链接的指向也会造成问题。如果系统里有过多个CUDA版本/usr/local/cuda可能指错地方导致编译时头文件错乱。我习惯在编译前直接检查一下ls -l /usr/local/cuda确保它指向/usr/local/cuda-12.9。CUDA引导文件的错乱问题在“cuda samples找不到”之类的报错里最常见。4. Ceres Solver的编译选型自动求导库直接影响重建质量COLMAP的整个优化后端都建立在Ceres之上这块值得单独拿出来说因为它的编译选项直接决定了你之后重建的速度和精度。4.1 为什么编译Ceres时要打开CUDA支持默认的Ceres构建会把CUDA关掉只是用TBB做多线程加速。但COLMAP的Bundle Adjustment涉及大量雅可比矩阵计算Ceres开启CUDA后能用GPU做并行求导加速大场景重建的优化速度能快出一个量级。git clone https://ceres-solver.googlesource.com/ceres-solver cd ceres-solver mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease \ -DCUDAON \ -DCUDA_ARCHall \ -DTBBON make -j$(nproc) sudo make install这里的CUDA_ARCHall是为了兼容不同代显卡代价是编译时间变长、库体积变大。如果你明确知道自己显卡的算力版本比如RTX 4080是sm_120可以用CUDA_ARCHsm_120缩短编译时间。4.2 实测效果与可能踩的雷实测下来开着CUDA的Ceres在COLMAP做Bundle Adjustment时单次迭代耗时比纯CPU版本缩短了30%到50%数据集越大差距越明显。不过第一次编译Ceres时极其容易败在gflags的版本检测上——Ceres对gflags的版本要求比较敏感如果系统里同时存在glog自带的gflags和apt装好的gflagsCMake可能会在链接阶段报重复定义。解决办法是统一使用apt的libgoogle-glog-dev和libgflags-dev不要让Ceres去源码编译gflags。注意Ceres的CUDA支持依赖C14及以上标准在编译命令里显式加上-DCMAKE_CXX_STANDARD14可以减少很多莫名其妙的模板报错。5. COLMAP 3.13.0源码编译CMake选项逐一解析依赖全部就位之后终于轮到主角登场。5.1 拉取源码与编译实操git clone https://github.com/colmap/colmap.git cd colmap git checkout 3.13.0 mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease \ -DCMAKE_CUDA_ARCHITECTURESnative \ -DGUION make -j$(nproc)CMAKE_CUDA_ARCHITECTURESnative会去查询当前显卡的实际算力并编译对应的SASS代码这是最省心的做法。如果你需要把编译好的可执行文件拷贝到另一台配置不同的机器上跑就得改成类似-DCMAKE_CUDA_ARCHITECTURES75;86;120这样的列表。CMake配置成功的话输出里能看到一堆Found比如Found Ceres、Found CUDA、Found GTS等。如果某个核心依赖没找到CMake会明确提示并终止。5.2 GUI与CLI的关系以及Qt版本选择COLMAP的GUI部分和命令行工具默认是同时构建的。-DGUION时CMake会同时编译colmap可执行文件和带界面的colmap_gui入口。如果你在服务器上跑纯命令行比如做批处理重建关掉GUI可以显著缩短编译时间cmake .. -DCMAKE_BUILD_TYPERelease -DGUIOFF但要注意COLMAP的稠密重建和特征可视化等功能在源码层面上已经和GUI部分有了依赖单纯关掉GUI有概率导致部分CMake配置不满足。我在3.13.0实测中GUIOFF是能跑通的但官方并未把无GUI版本作为一等公民维护所以如果后续版本出现了找不到QApplication的报错别太惊讶把GUI打开就行。Qt版本方面Qt5和Qt6都能编译但3.13.0对Qt6的适配还有一些边角问题尤其是QScintilla组件。如果你用Qt6QScintilla必须单独编译并正确挂到Qt6的库目录下这个步骤更新且容易出错。除非你特别需要Qt6的某些特性否则我建议直接Qt5省事。5.3 QScintilla的正确处理QScintilla是COLMAP GUI里用来做代码高亮和日志显示的组件。它不属于COLMAP源码本身也不在apt源里需要手动编译git clone https://github.com/PyQt5/QScintilla.git cd QScintilla/src qmake make -j$(nproc) sudo make install如果是Qt6环境qmake要换成qmake6装完后的库也要确保在/usr/lib/x86_64-linux-gnu里能被CMake找到。很多人在这一步栽跟头报错信息常常是Could not find QScintilla。其实根本不是找不到而是CMake缓存了错误的Qt版本路径删掉COLMAP的build目录重新配置一遍就好。5.4 让配套工具也能被顺利找到OpenMVS和MeshLabCOLMAP的输出要得到漂亮的网格模型很多人会搭配OpenMVS使用。OpenMVS依赖COLMAP编译出来的库但它的CMake找COLMAP的方式比较死板需要在编译OpenMVS时指定COLMAP的安装前缀cmake .. -DCMAKE_BUILD_TYPERelease \ -DCOLMAP_INCLUDE_DIRS/path/to/colmap/src \ -DCOLMAP_LIBRARIES/path/to/colmap/build/libcolmap.a这一块不是COLMAP编译的必要环节但如果你计划走“COLMAP建稀疏点云 OpenMVS稠密重建网格化”这条完整链路就建议先把库路径理顺而不是等用到时再回来折腾。6. 编译报错排查按症状对症下药别再瞎猜这一章节把编译中最常见的几类报错按“症状—病因—解法”列出来你在实操中碰到的90%的问题应该都能在这里找到答案。6.1 “Could not find CUDA” / “CUDA_TOOLKIT_ROOT_DIR not defined”病因CMake没找到CUDA安装目录或者/usr/local/cuda软链接失效。解法sudo ln -sf /usr/local/cuda-12.9 /usr/local/cuda然后在CMake命令里显式指定cmake .. -DCUDA_TOOLKIT_ROOT_DIR/usr/local/cuda-12.96.2 “fatal error: boost/geometry.hpp: No such file or directory”病因boost头文件缺失几何模块没装。解法补装libboost-geometry-dev或者直接装libboost-all-dev。别用源码编译BoostUbuntu源里的版本对齐性已经足够省时省力。6.3 “Unsupported GNU version! gcc versions later than 13 are not supported!”病因这不是真正“不支持”而是CUDA检测到了未知版本的gcc。如果你系统里默认gcc是14.x或更高CUDA 12.9的兼容名单还没来得及覆盖。解法切换到gcc 13sudo apt install gcc-13 g-13 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-13 100 sudo update-alternatives --install /usr/bin/g g /usr/bin/g-13 1006.4 编译Ceres时“eigen3 invalid”之类报错病因Eigen头文件版本和Ceres要求的不匹配通常是系统里存在多个Eigen版本。解法检查是否存在/usr/include/eigen3和/usr/local/include/eigen3两套优先让CMake用apt安装的版本。确认干净后删除Ceres的build目录重新配置。6.5 链接阶段出现大量“undefined reference to ‘thrust::...’”病因FLANN编出来的CUDA库和COLMAP编译使用的Thrust版本不一致。解法重编FLANN时确保-DBUILD_CUDA_LIBON并且安装完FLANN以后sudo ldconfig刷新共享库缓存。必要时在COLMAP的CMake里加-DCMAKE_CXX_FLAGS-I/usr/local/cuda-12.9/include。6.6 GUI部分能编出来但启动闪退病因缺少OpenGL运行时库或者显示环境变量没配好。解法确认libglew-dev装上了并且glxinfo能看到渲染器信息如果是SSH远程调用要用vglrun或X11转发直接裸奔跑GUI大概率闪退。7. 编译完成后的验证与典型运行配置编译通过不等于一定能跑。我用一套简单可靠的验证流程确认整个COLMAP环境确实可用。7.1 版本信息与帮助输出./colmap -h ./colmap gui如果gui能弹出一个正常的窗口你的UI环境没有问题。如果只是想确认CLI运行colmap feature_extractor --help这类命令能看到参数说明就说明主程序已经正常链接了。7.2 小规模数据集快速跑通全流程我通常拿一个由20~30张图片组成的小数据集来验证直接跑手动标注或者无标注特征提取colmap feature_extractor --database_path ./db.db --image_path ./images colmap exhaustive_matcher --database_path ./db.db colmap mapper --database_path ./db.db --image_path ./images --output_path ./sparse三步都通过之后用colmap model_converter --input_path ./sparse/0 --output_path ./sparse_text --output_type TXT导出稀疏模型。能在这一步正常产出cameras.txt、images.txt、points3D.txt三个文件基本可以断定编译环境和CUDA运行时都没问题。提示如果只编译了GUI版本而没编译CLI版本以上命令需要换成colmap gui中的“File Import from images”和“Reconstruction”菜单操作。命令行直接输colmap feature_extractor会提示找不到指令这不代表编译失败只是入口不同。7.3 库共享问题换机器运行时的注意点自己编译的COLMAP是动态链接到系统库的拷贝到别的机器时如果那边缺少libcuda.so或libceres.so依赖就会直接启动失败。一个比较省心的做法是编译时加-DCMAKE_INSTALL_PREFIX/opt/colmap然后make install把COLMAP连同它的库一起装到固定前缀下。再把/opt/colmap/lib加进目标机器的LD_LIBRARY_PATH这样迁移环境下更不容易出乱子。8. 拿到编译版的COLMAP之后我的深入使用体会正常跑通编译链之后COLMAP本身就是一个顺手的三维重建工具但自己编译的价值不止于此。我这里说几个真正值得琢磨的扩展方向和使用细节。8.1 多版本共存与编译器切换我现在机器上除了CUDA 12.9 COLMAP 3.13.0还保留了一份CUDA 11.8 COLMAP 3.9.1的老环境。两个版本各有用处新版跑大场景点云效果更稳定老版本跑一些特殊传感器数据时反而更顺手。关键是环境变量要隔离干净。我的做法是写两个环境切换脚本每次干活前用source加载对应版本#!/bin/bash export PATH/usr/local/cuda-12.9/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-12.9/lib64:$LD_LIBRARY_PATH export CMAKE_PREFIX_PATH/opt/colmap另一台机器上我还封装过基于singularity的容器版COLMAP把CUDA、Ceres、COLMAP全编译进去跑大规模倾斜摄影数据时几乎不受宿主环境干扰。如果你要处理的数据涉及多台服务器这套容器化的思路值得提前布局。8.2 典型性能瓶颈与优化方向编译通过只是第一步真正用起来最影响体验的往往是稠密重建阶段的内存占用。COLMAP的dense重建默认会缓存多视角深度图和像素一致性图对显存和内存的消耗都是惊人的。可以在参数里调低--max_image_size或者限制--block_size实测能省下不少内存。另外CUDA架构设置也直接影响运行性能native编译出来的COLMAP跑在自己显卡上效率最高但拿去给别人用如果对方是另一代显卡性能就会明显下降。生产环境里我一般用-DCMAKE_CUDA_ARCHITECTURES86;120这种列表牺牲一点编译时间来换跨卡兼容。8.3 我踩过几次坑之后最想说的事重新编译这套环境最费时间的其实不是cmake和make而是依赖版本排查。第一次失败可能是在GTS上第二次可能卡在FLANN的CUDA库第三次也许是QScintilla的Qt版本错位。这类问题有一个共性它们都不是COLMAP自身的bug而是“版本环境不匹配”。所以先接受一个事实——新版本的大项目编译踩坑是常态顺利是运气。每一次排查都在加深你对这个工具链的理解。我个人的建议是第一次编译千万别贪多求全。先把纯CLI版编译跑通不用管GUI和QScintilla从拿到可执行文件到重建出一个小场景整个链路确认后再回去补GUI。这样能把编译问题和运行问题隔离开来排查时思路能清晰一大截。顺手把每个依赖的编译日志存成文本出错时回看日志往往比重新读一遍CMake输出更能定位问题。