★ FEATURED ARTICLE 1. 为什么要在Windows上死磕COLMAP 3.6的源码编译如果你接触过三维重建大概率听说过COLMAP这个名字。它是一套开源的运动恢复结构Structure-from-Motion与多视图立体Multi-View Stereo流水线工具在学术界和工业界都被广泛用于从一组照片中恢复相机位姿并生成稠密点云。官方发布的Windows预编译包虽然开箱即用但版本往往滞后而且默认不带某些依赖库的完整功能。当你需要用到特定版本的算法、想开启CUDA加速的某些特性或者要把COLMAP嵌入自己的C项目时从源码编译就成了绕不开的一步。标题里提到的“colmap3.6”指的是COLMAP的一个较早期但非常稳定的版本分支很多经典论文的复现实验都基于这个版本。“gmp”和“mfpr”则是两个关键的数学库GMP是大数运算库MFPR是它的一个高性能分支在COLMAP的某些几何计算模块中会被间接依赖。在Windows下编译这三个东西难点不在于代码本身而在于Windows与Unix-like系统在构建工具链、依赖管理和路径处理上的巨大差异。我前后折腾过好几轮踩过的坑包括但不限于CMake找不到Boost、CUDA架构不匹配导致编译中断、GMP在MSVC下链接报错、以及最让人头疼的第三方库版本冲突。这篇文章面向的是有一定C基础、用过CMake、但可能在Windows上编译大型开源项目经验不多的开发者。我会把整个流程拆成可复现的步骤解释每一步为什么要这么做以及遇到报错时怎么排查。你不需要事先精通GMP或MFPR但需要有一台装了Visual Studio和CUDA的Windows机器以及足够的耐心。2. 编译前的环境准备与工具链选型2.1 编译器与构建工具的选择逻辑在Windows上编译COLMAP第一件事就是确定用哪套编译器。官方文档推荐的是Visual Studio 2019或2022的MSVC工具链原因很直接COLMAP的Windows分支对MSVC的支持最完善CMake脚本里针对MSVC做了大量条件判断。如果你试图用MinGW或Cygwin大概率会在链接阶段遇到符号不兼容的问题尤其是涉及CUDA的模块。我实测下来Visual Studio 2022 Community版就够用安装时务必勾选“使用C的桌面开发”工作负载并且确保Windows SDK版本在10.0.19041以上。CMake建议用3.20以上的版本因为COLMAP 3.6的CMakeLists.txt里用到了target_link_libraries的一些较新语法。CMake安装时记得勾选“Add CMake to the system PATH”否则后面在命令行里调用会很麻烦。注意不要用Visual Studio自带的CMake集成来构建COLMAP它的缓存机制有时会干扰第三方依赖的查找。老老实实用命令行或者CMake GUI。2.2 CUDA与cuDNN的版本匹配COLMAP的稠密重建模块依赖CUDA。如果你不需要GPU加速可以在CMake里关掉CUDA但那样就失去了COLMAP最大的性能优势。CUDA版本的选择要和你的显卡驱动、以及Visual Studio版本匹配。我用的组合是CUDA 11.8加VS2022这个组合在COLMAP 3.6上验证通过。CUDA 12.x理论上也可以但需要确认COLMAP 3.6的CMake脚本是否识别新的架构代号。安装CUDA时建议自定义安装取消掉GeForce Experience和驱动组件只保留CUDA Toolkit和开发头文件。cuDNN不是必须的COLMAP的稠密重建用的是自己实现的PatchMatch算法不直接调用cuDNN。但如果你后续要接深度学习模块可以提前装好。2.3 依赖库清单与获取方式COLMAP 3.6在Windows上编译需要以下第三方库依赖库用途推荐版本获取方式Boost文件系统、线程、程序选项1.74-1.82源码编译或预编译包Eigen线性代数3.3.9以上头文件库直接解压FreeImage图像读写3.18源码编译GMP/MFPR大数运算MFPR 4.1.0源码编译Ceres Solver非线性优化2.0以上源码编译Qt5GUI5.15官方安装包glewOpenGL扩展2.1源码编译CGAL计算几何5.0以上头文件为主这里最麻烦的是Boost、Ceres和GMP/MFPR。Boost和Ceres可以用vcpkg来装但vcpkg的Boost版本更新太快有时会和COLMAP 3.6的代码不兼容。我的建议是Boost用预编译的二进制包Ceres用源码编译并指定Eigen路径GMP/MFPR必须从源码编译因为Windows上没有现成的MSVC版本。3. GMP与MFPR在MSVC下的编译实操3.1 为什么COLMAP需要GMP和MFPRGMP是GNU多精度运算库MFPR是它的一个分支专注于更高效的浮点运算。COLMAP在计算相机位姿的某些几何约束时会用到高精度的有理数运算尤其是在处理大规模稀疏矩阵的分解时。虽然COLMAP的核心代码没有直接调用GMP的API但它依赖的Ceres Solver在启用某些选项时会链接GMP。而MFPR则是GMP的一个替代实现在某些场景下性能更好。在Linux下这两个库通常通过包管理器一键安装。但在Windows下MSVC不提供POSIX环境GMP的源码里大量使用了Unix特有的头文件和汇编代码直接编译会报错。所以我们需要用MFPR来替代GMP因为MFPR对MSVC的支持更友好。3.2 编译MFPR的详细步骤首先从MFPR的官方仓库下载源码包解压到一个没有空格和中文的路径比如D:\libs\mfpr-4.1.0。然后打开“x64 Native Tools Command Prompt for VS 2022”cd到源码目录。MFPR的编译需要先运行一个配置脚本。在Windows下我们用CMake来生成Visual Studio工程mkdir build cd build cmake .. -G Visual Studio 17 2022 -A x64 -DCMAKE_INSTALL_PREFIXD:\libs\mfpr-install -DENABLE_ASSERTOFF -DWITH_PICON这里解释几个关键参数-G指定生成器-A x64确保是64位-DCMAKE_INSTALL_PREFIX指定安装路径-DENABLE_ASSERTOFF关闭断言以提升性能-DWITH_PICON生成位置无关代码虽然Windows下DLL不需要PIC但某些静态链接场景会用到。CMake配置完成后用以下命令编译并安装cmake --build . --config Release --target install如果一切顺利你会在D:\libs\mfpr-install下看到include、lib和bin三个目录。lib目录里会有mfpr.lib和mfpr.dll或者只有静态库取决于配置。实操心得MFPR的CMake脚本在检测编译器时有时会把MSVC误判为其他编译器导致生成错误的汇编代码。如果编译过程中出现大量汇编错误检查CMakeCache.txt里的CMAKE_C_COMPILER是否指向cl.exe。如果不是手动指定-DCMAKE_C_COMPILERcl。3.3 解决链接时的符号冲突编译完MFPR后你可能会在链接COLMAP时遇到“无法解析的外部符号”错误提示缺少__gmpz_开头的函数。这是因为COLMAP的某些依赖比如Ceres默认去找GMP而不是MFPR。解决方法是在CMake配置COLMAP时显式指定GMP的路径指向MFPR的安装目录-DGMP_INCLUDE_DIRD:\libs\mfpr-install\include -DGMP_LIBRARYD:\libs\mfpr-install\lib\mfpr.lib如果Ceres已经编译好了并且链接了系统里的其他GMP版本你可能需要重新编译Ceres并在编译时传入同样的GMP路径。这就是为什么我建议把Ceres放在MFPR之后编译。4. COLMAP 3.6的CMake配置与编译过程4.1 获取源码与目录结构梳理从COLMAP的官方仓库下载3.6版本的源码压缩包解压到D:\projects\colmap-3.6。目录结构大致如下src下是核心代码cmake下是FindXXX模块lib下是第三方库的占位。COLMAP 3.6的CMake脚本会尝试自动下载一些依赖但在国内网络环境下经常失败所以最好提前把所有依赖准备好然后通过CMake变量指定路径。4.2 关键CMake变量的设置与解释打开CMake GUI设置源码路径为D:/projects/colmap-3.6构建路径为D:/projects/colmap-3.6/build。点击Configure选择Visual Studio 17 2022和x64。第一次Configure会报错提示找不到Boost、Eigen等。这时候需要手动添加以下变量变量名值说明BOOST_ROOTD:/libs/boost_1_82_0Boost根目录Eigen3_DIRD:/libs/eigen-3.4.0/share/eigen3/cmakeEigen的CMake配置目录FreeImage_DIRD:/libs/FreeImage/buildFreeImage的构建目录GMP_INCLUDE_DIRD:/libs/mfpr-install/includeMFPR头文件GMP_LIBRARYD:/libs/mfpr-install/lib/mfpr.libMFPR库文件CERES_DIRD:/libs/ceres-solver/buildCeres构建目录Qt5_DIRD:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5Qt5配置目录CUDA_TOOLKIT_ROOT_DIRC:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v11.8CUDA路径CMAKE_CUDA_ARCHITECTURES75;86根据你的显卡调整CMAKE_CUDA_ARCHITECTURES这个变量特别重要。如果你用的是RTX 30系显卡架构是8620系是7540系是89。填错了会导致编译出的CUDA内核无法在显卡上运行运行时直接报“no kernel image is available”。4.3 编译过程中的常见报错与即时处理点击Generate后如果一切正常会在build目录下生成COLMAP.sln。用Visual Studio打开这个解决方案选择Release配置然后“生成解决方案”。这个过程可能持续30分钟到2小时取决于机器性能。常见的报错及处理方式错误C2039某个成员不是XXX的成员。这通常是Boost版本不兼容导致的。COLMAP 3.6的代码基于Boost 1.74左右的API如果你用了Boost 1.85某些接口已经废弃。降级Boost或者手动修改代码。错误LNK2019无法解析的外部符号。检查是否所有依赖库的路径都正确尤其是GMP和Ceres。有时候需要把mfpr.lib和ceres.lib的目录加到链接器的“附加库目录”里。CUDA编译错误identifier atomicAdd is undefined。这是CUDA版本和MSVC版本不匹配的典型症状。CUDA 11.8配VS2022需要打一个补丁或者把CUDA升级到12.x。注意编译过程中如果某个模块失败不要急着重新生成整个解决方案。先单独编译那个失败的项目看具体错误信息。Visual Studio的错误列表有时会隐藏真正的根因。5. 编译后的验证与功能测试5.1 检查生成的可执行文件编译成功后在build/src/Release目录下会生成colmap.exe、colmap_gui.exe等可执行文件。先别急着跑用dumpbin /dependents colmap.exe检查一下依赖的DLL是否都在。如果提示缺少mfpr.dll把D:\libs\mfpr-install\bin加到系统PATH里或者直接把DLL复制到exe旁边。5.2 用示例数据集跑通完整流程COLMAP官方提供了一些示例数据集比如南门大桥的图片集。下载后用命令行跑一遍稀疏重建colmap feature_extractor --database_path test.db --image_path images colmap exhaustive_matcher --database_path test.db colmap mapper --database_path test.db --image_path images --output_path sparse如果这三步都能跑通并且在sparse目录下生成了.bin文件说明核心功能没问题。然后测试稠密重建colmap image_undistorter --image_path images --input_path sparse/0 --output_path dense colmap patch_match_stereo --workspace_path dense colmap stereo_fusion --workspace_path dense --output_path dense/fused.ply这一步会调用CUDA如果显卡架构设置正确应该能看到GPU利用率飙升。如果报错“CUDA error: no kernel image is available”回去检查CMAKE_CUDA_ARCHITECTURES。5.3 GUI功能的可用性确认双击colmap_gui.exe如果能正常打开界面并加载图片说明Qt的链接没问题。GUI里可以手动做特征提取和匹配适合调试小规模数据。如果GUI启动时报“找不到Qt5Core.dll”把Qt的bin目录加到PATH或者用windeployqt工具把依赖DLL复制过来。6. 踩坑记录与常见问题速查6.1 依赖库版本冲突的排查思路Windows下编译开源项目最大的痛点就是依赖库版本冲突。我的经验是把所有依赖库的版本号记在一个文本文件里每次编译失败先对照版本。COLMAP 3.6对Boost的版本特别敏感1.74到1.78之间最稳。Eigen用3.3.9或3.4.0都行但不要用3.4.1那个版本改了一些API导致COLMAP编译不过。Ceres的版本建议用2.0.0或2.1.02.2.0改了Manifold的接口COLMAP 3.6的代码还没适配。如果你非要用新版本Ceres需要手动改COLMAP的src/colmap/estimators下的几个文件。6.2 CUDA架构不匹配的典型症状CUDA架构不匹配的表现有三种编译时通过但运行时崩溃、编译时直接报错、或者编译出的程序在特定显卡上性能极低。最隐蔽的是第三种程序能跑但慢得离谱因为CUDA用了JIT编译。解决方法是在CMake里把CMAKE_CUDA_ARCHITECTURES设成你显卡的计算能力值不要用默认的“Auto”。6.3 内存不足与编译中断的应对COLMAP的某些源文件比如src/colmap/mvs下的非常大MSVC编译时可能吃掉8GB以上内存。如果你的机器只有16GB内存建议关掉其他程序或者用/MP选项开启多核编译但限制并行项目数。在Visual Studio里工具→选项→项目和解决方案→生成并运行把“最大并行项目生成数”设为2或3。如果编译到一半因为内存不足中断重新生成时可能会报“无法打开XXX.obj”的错误。这时候清理一下build目录里的中间文件或者直接删掉build重新来。6.4 常见问题速查表问题现象可能原因解决方法CMake找不到BoostBOOST_ROOT未设置或路径错误设置BOOST_ROOT为Boost根目录链接报错缺少gmpz符号GMP路径指向了错误的库重新指定GMP_LIBRARY为mfpr.libCUDA编译报atomicAdd未定义CUDA与MSVC版本不匹配升级CUDA或打VS补丁运行时提示no kernel imageCUDA架构设置错误修改CMAKE_CUDA_ARCHITECTURESGUI启动缺少Qt5Core.dllQt的bin目录不在PATH添加PATH或用windeployqt编译到一半内存不足单个源文件过大减少并行项目数或增加虚拟内存最后再分享一个小技巧如果你只是想在Windows上用COLMAP做重建不想折腾编译可以考虑用WSL2装Ubuntu然后在里面用apt装COLMAP。但如果你需要修改源码或者做二次开发Windows原生编译仍然是更好的选择因为调试器可以直接附加到进程上。我个人的体会是第一次编译花了两天第二次只用了两小时关键是把依赖库的版本和路径都固定下来写成一个CMake脚本以后换机器直接复用。
阅读完成 · 觉得有帮助？
