VS2015编译OpenCV 3.2.0集成contrib完整指南

简介OpenCV 3.2.0是2017年发布的稳定版本这一资源将其与Visual Studio 2015以及opencv_contrib扩展模块集合一同编译好目标用户是在VS2015下进行图像处理、计算机视觉或深度学习开发的技术人员能够省去手动配置核心库和扩展模块的麻烦。压缩包采用RAR格式共包含456个文件其中hpp头文件有280个、h头文件57个用于提供编程接口声明dll动态库42个、lib导入库41个供运行时和链接使用还有21个xml配置、7个exe可执行文件以及CMake配置和License整体大小28.3MB结构基本完整。目前已有491人浏览学习该资源在Windows平台视觉开发中具有一定的参考热度。通过这个包开发者可以直接获得包含aruco二维码识别、optflow光流估计、xfeatures2d特征检测等contrib模块的编译产物同时涵盖VideoWriter、DNN、HighGUI等核心模块的更新改进方便快速搭建项目、研究模块构成或对比不同模块的接口用法从而将更多精力放在算法实现和业务逻辑上。1. 为什么非要在VS2015里自己编译OpenCV 3.2.0开门见山说结论如果你的项目还在用Visual Studio 2015而且又偏偏需要SIFT、SURF、FaceRecognizer这些OpenCV官方主仓库里不带的算法那“OpenCV 3.2.0 opencv_contrib-3.2.0 VS2015”这套组合就是绕不开的一条路。网上各种编译教程一搜一大把但真正把这个版本组合完整跑通、并且把中间那些坑都踩平的文章并不多我把自己实际编译的过程完整记录下来给后面入坑的朋友一个参考。先说这个组合的背景。OpenCV 3.2.0在2016年底发布很多老工业项目、学术代码、嵌入式视觉方案都是基于这个版本写的在很长一段时间里它都是“稳定”的代名词。而OpenCV 3.x时代开始官方把很多非核心模块拆到了opencv_contrib仓库里比如xfeatures2dSIFT/SURF、face人脸识别、text场景文字检测、aruco二维码标记检测等等。这些模块不会出现在官方编译好的exe预编译包里官方预编译包只包含主仓库的功能模块所以只要你的需求碰上了这些contrib模块就必须自己编译。那为什么非要配VS2015而不是VS2017或者VS2019本质上是因为OpenCV 3.2.0发布时官方预编译包里的二进制文件是按照VC14即VS2015工具集编译的对应的运行库是msvcp140.dll、vcruntime140.dll这一套。如果你用VS2017或VS2019打开VS2015编译出来的lib/dll绝大多数情况下可以正常链接使用但一旦你需要在源码级别调试、或者需要改OpenCV源码重新编译版本不匹配就会引发一堆运行时错误。更关键的是很多老项目的编译环境锁死就是VS2015比如某些工控机、某些客户现场系统环境和开发环境不允许升级那么就只能在VS2015里把这个版本的OpenCV编译出来没有别的选择。我自己实际编译过程中最大的感触是整个流程其实不复杂就是一个“下载源码 - CMake配置 - VS编译 - 配置环境”真正的难点全在细节上比如版本匹配、CMake路径、contrib文件缺失、非免费模块开关等等。任何一步踩偏等待你的可能就是一两个小时的编译时间结束后才发现链接不过去。顺便说一句如果你只是用OpenCV做简单图像处理并且不需要contrib模块那直接用官方预编译包就够了完全没必要自己编译。自己编译的意义只存在于以下场景必须用contrib模块、需要自定义OpenCV模块、或者需要调试OpenCV内部实现。如果你的需求不属于这几类先省省力气别浪费这个时间。2. 编译前准备版本匹配和工具链选型2.1 三个关键版本的严格匹配OpenCV的源码和contrib模块源码必须保证版本号完全一致这是一个铁律。OpenCV 3.2.0就必须配opencv_contrib-3.2.0不要试图用3.4.x的contrib配3.2.0的主仓那样CMake配置阶段就会报各种奇葩错误因为contrib中的模块可能会调用主仓中不存在的接口。具体需要下载的文件就三个OpenCV 3.2.0 Windows源码包在官网的Releases页面下载选Sources选项文件名为opencv-3.2.0.zip注意不是那个OpenCV 3.2.0 for Windows的exe预编译版那个里面没有contrib。opencv_contrib-3.2.0源码包同样在GitHub上OpenCV官方组织下opencv_contrib仓库的3.2.0标签处下载zip包。CMake构建工具建议使用CMake 3.8.x左右的版本不要用太新的CMake后面单独说原因。另外还要确认VS2015的版本最好是已经打了Update 3补丁的VS2015Update 3对C编译器的修复比较关键直接影响后面编译C代码的成功率。如果你手头的是VS2015 Community版其实也没问题Community版对个人开发者是免费的功能上用于编译OpenCV完全够用。网上还经常有人问VS2015产品密匙的问题其实Community版本不需要激活码即可使用如果你用的专业版或企业版产品密钥的问题自己去MSDN看这里不展开。2.2 为什么CMake不能太新也不能太旧这是个很多人忽略的坑。OpenCV 3.2.0的CMake脚本是好几年前写的新版CMake比如3.20以上在变量处理、FindPackage逻辑上有些变化OpenCV 3.2.0对“OpenCV_CUDA”等选项的处理逻辑在那些新版本CMake上可能出问题导致生成VS工程后编译一大片错误。太旧的CMake3.5以下又可能不认识VS2015的某些工具集属性。我实测下来CMake 3.8.0这个版本对这个组合兼容性最好当然CMake 3.8.2、3.9.x也可以尝试。CMake不用装最新版直接在cmake.org下载对应的Windows安装包安装时勾选“Add CMake to the system PATH for all users”后面在命令行里方便调用不过如果只是用GUI界面不勾选也没关系。安装路径选择默认位置即可注意路径中不要有中文。2.3 磁盘和路径的规划在动手之前先把路径规划好这个经验能帮你省掉后面很多莫名其妙的报错。OpenCV源码解压后目录内不能有中文不能用空格。比如D:\opencv-3.2.0这个路径是可以的C:\Users\张三\新建文件夹\opencv就不行。同样的规则适用于CMake的构建目录务必用一个独立的、英文路径的目录来存放CMake生成的文件千万别直接在源码目录里原地构建那样会把源码目录搞乱。磁盘剩余空间至少要预留10GB以上。我一开始以为编译这个顶多花个3~5GB结果实际编译过程中中间文件非常庞大Release和Debug如果都编译的话随便就是15GB以上。如果你磁盘紧张建议只编译Release版本后面会讲怎么操作。3. CMake配置阶段详解每个选项都要知道为什么3.1 指定源码目录和构建目录打开CMake GUI上面两个输入框就是核心Source code填源码目录就是opencv-3.2.0解压后的那个文件夹注意不是它的上一级目录Build binaries填构建目录比如D:\opencv-build这个目录不需要提前创建CMake会自己建。填完之后点击Configure按钮弹出选择编译器的对话框这里有几个关键选择。Generator要选“Visual Studio 14 2015 Win64”其中Visual Studio 14就是VS2015的内部版本号Win64表示生成64位工程。如果你的项目是32位的那就选“Visual Studio 14 2015”不带Win64后缀但我强烈建议有条件的都用64位OpenCV的处理性能在64位下会更好而且contrib里的部分模块对32位支持不太友好。下方的Platform选项选择x64Specify toolchain file不用勾选直接点Finish开始第一次配置。第一次配置过程中CMake会检查很多依赖项比如IPPICV、FFMPEG、TBB等等这些检查通常会联网下载一些第三方组件这也是很多人卡住最多的地方。特别是IPPICV这个优化库文件大概几十MB下载速度看人品有时候会超时失败。遇到这种情况先不要慌稍后单独处理。3.2 关键选项contrib路径、非免费模块、BUILD配置第一次Configure跑完后CMake的选项列表会刷新出来在搜索框里输入“OPENCV_EXTRA_MODULES_PATH”将这个变量的值设置为opencv_contrib-3.2.0解压目录下的modules文件夹就是包含alexnet、aruco、xfeatures2d等子文件夹的那个modules目录。这一行是最核心的路径设置它决定了contrib模块是否会参与编译。接下来继续在搜索框里输“OPENCV_ENABLE_NONFREE”勾选这个选项。如果不勾选即便你把contrib路径配置上SIFT、SURF这些模块依然不会被编译出来因为根据算法专利权约定OpenCV把这类算法默认关掉了。SIFT/SURF这两个算法在特征匹配、物体检测领域太常用很多人编译contrib就是冲着它们来的所以这一步千万别漏掉。还要注意几个BUILD选项。搜索框里输入“BUILD”重点看 BUILD_opencv_world如果你希望把所有的lib和dll合并成一个OpenCV_world320.lib / dll那可以勾上这样后续链接配置更简单但缺点是想单独更新某个模块还得重新全量编译。我个人建议不勾选保持每个模块单独生成lib虽然链接时配置麻烦一点但调试定位问题更方便。BUILD_TESTS和BUILD_EXAMPLES建议取消勾选测试和示例程序对咱们实际使用并没有帮助反而会拉长编译时间。关于BUILD_opencv_python3这个选项要小心OpenCV 3.2.0那个年代对Python 3的支持还比较古早如果你机器上的Python版本比较新比如3.7编译时大概率报错。除非你明确需要Python接口否则建议取消勾选所有和Python相关的模块只编C接口后面真正用Python时可以直接装官方编译好的wheel包没必要在这里死磕。3.3 IPPICV和其他下载失败的处理方法CMake配置中网络下载失败是个高频问题你可能会在Configure输出中看到类似“ICV: Downloading ippicv_2017u3_win_intel64_general_20170822.zip... failed”之类的信息。原因就是CMake脚本试图从官方GitHub下载预编译的IPP优化库但国内网络访问GitHub不稳定文件容易下不全。解决办法有两种。第一种是手动下载把URL对应的zip文件手动下载下来放到opencv-3.2.0.cache\ippicv路径下注意文件名和路径要和CMake脚本的期望完全一致。这个可以被代理工具辅助但如果你不方便就用第二种直接在CMake里改CMakeLists.txt临时屏蔽IPP下载。打开opencv-3.2.0根目录下的CMakeLists.txt找到和“ippicv”相关的段落把set(OPENCV_ICV_PACKAGE...这段的URL指向你本地下载好的文件路径或者直接把do_download相关的代码注释掉让编译系统跳过OTA优化库。实际上没有IPPOpenCV的某些基本操作会慢一点大概5%~15%但功能完全不受影响对学习和验证来说足够了。如果FFMPEG相关的下载也失败处理方法完全一样到opencv源码的.cache\ffmpeg目录下看版本信息手动下载后重命名到对应文件名就行。在配置阶段把这些坑一次性搞定远比编译过程中再爆出一堆错误再回头处理来得痛快。4. VS2015编译全过程漫长的等待与可能遇到的错误4.1 生成解决方案Release优先原则CMake配置阶段全部完成后点击Generate生成VS工程文件这步几乎不会报错。然后在你设置的构建目录下找到OpenCV.sln用VS2015打开这个解决方案。打开后第一时间要做的不是点击绿色三角的“本地Windows调试器”而是打开上方的配置管理器把解决方案配置从Debug切换成Release平台保持x64。为什么建议先编Release三个原因第一Release编译出来的库性能要比Debug好太多第二Debug版本的库链入你自己的Debug项目时如果混入的运行时设置不一致会有一堆麻烦第三相同代码量下Debug编译时间普遍是Release的1.3~1.5倍第一次编译时能省则省。接下来在解决方案管理器中右键“解决方案‘OpenCV’”选择“生成解决方案”。这时整台电脑就会进入持续20~40分钟的满负荷编译状态。如果你用的是HDD机械硬盘时间还会翻倍所以建议一定要在SSD上编译这个区别非常明显。编译期间最好别开太多程序CPU保持安静电源插好避免意外断电。4.2 核心踩坑boostdesc和vgg_generated文件缺失编译中最常见的报错集中在xfeatures2d模块具体表现为一堆类似这样的错误fatal error C1083: Cannot open include file: boostdesc_bgm.i: No such file or directory或者LNK1181: cannot open input file vgg_generated_48.i这两个错误可以说是OpenCV contrib编译史上最著名的坑。opencv_contrib-3.2.0的xfeatures2d模块源码里用到了一些训练好的私有描述子文件这些文件本来是应该在CMake配置阶段自动从网上拉取的但GitHub的release访问不稳定导致这些.i文件没有下载成功而源码本身又没携带这些文件最终编译时直接找不到。解决办法是手动下载这些文件把它们放到opencv_contrib-3.2.0\modules\xfeatures2d\src目录下。需要下载的文件包括boostdesc_bgm.i、boostdesc_bgm_bi.i、boostdesc_bgm_hd.i、boostdesc_lbgm.i、boostdesc_binboost_064.i等一整套boostdesc系列以及vgg_generated_48.i、vgg_generated_64.i、vgg_generated_80.i、vgg_generated_120.i这几个vgg系列。这些文件可以通过GitHub上opencv_contrib的3.2.0标签对应路径找到用浏览器打开页面后点击下载即可文件都不大每个只有几百KB到几MB。下载完后别忘了把文件名大小写和源码里的引用保持完全一致。比如源码里引用的是boostdesc_bgm.i你下载的文件就就叫boostdesc_bgm.i不能改后缀或改大小写。文件名匹配不上依然会报C1083错误。踩过这个坑之后基本上后面的编译就会比较顺畅。如果中途因为网络问题或者误操作中途失败不用全部重新编直接再次右键“生成解决方案”即可VS的增量编译会自动跳过已经编译成功的项目只重新尝试失败的内容。4.3 编译完成后的验证当解决方案中所有项目都显示“已成功生成”时可以在构建目录的lib\Release和bin\Release下看到密密麻麻的lib文件和dll文件其中lib文件大约40~60个dll文件数量相当。如果你之前勾选了BUILD_opencv_world那就只会看到一个opencv_world320.lib和opencv_world320.dll但我刚才建议过不勾选所以看到一堆文件才是正常的。验证编译产物是否完整去lib\Release下找这几个关键文件opencv_xfeatures2d320.lib、opencv_face320.lib、opencv_dnn320.lib等这些都是contrib模块特有的产物如果它们存在说明contrib部分编译成功了。随后打开bin\Release目录看看opencv_xfeatures2d320.dll是否存在因为dll才是运行时真正加载的文件。下一步把这些dll所在的目录加入系统环境变量Path至于怎么加和使用下一节统一说明。5. 环境配置与测试Demo让编译成果真正可用5.1 环境变量与VS项目配置把D:\opencv-build\bin\Release这一目录加上系统环境变量Path。右键计算机 - 属性 - 高级系统设置 - 环境变量 - 在系统变量中找到Path项编辑并新增这个目录。之所以要加这一步是因为dll文件如果不在你的工程exe同目录下也不在系统Path中运行时就会提示“找不到opencv_xfeatures2d320.dll无法继续执行代码”这是最常见的运行时错误之一。然后配置VS2015的C工程打开项目属性页在VC目录里设置两个内容包含目录中添加opencv-3.2.0源码下的include目录以及include\opencv、include\opencv2这三级目录库目录中添加D:\opencv-build\lib\Release。然后在链接器 - 输入 - 附加依赖项里填入你实际会用到的lib文件名列表常用的大概有下面这些opencv_core320.lib opencv_imgproc320.lib opencv_imgcodecs320.lib opencv_highgui320.lib opencv_features2d320.lib opencv_xfeatures2d320.lib注意lib文件有Debug和Release的区别Debug版目录的lib会带一个d后缀比如opencv_core320d.lib不能混用否则会链接报错。用Release工程就链接Release目录下的lib用Debug工程就链接Debug目录下的lib这个是VS开发中非常基础的坑但很多人第一次编译OpenCV时都会掉进去。5.2 用SIFT特征点检测验证contrib模块配置好后写一段最简代码来验证contrib是否真正生效我最常用的验证代码是提取SIFT特征点。#include opencv2/opencv.hpp #include opencv2/xfeatures2d.hpp #include iostream int main() { cv::Mat img cv::imread(D:/test.jpg); if (img.empty()) { std::cout image load failed! std::endl; return -1; } cv::Ptrcv::xfeatures2d::SIFT sift cv::xfeatures2d::SIFT::create(); std::vectorcv::KeyPoint kps; sift-detect(img, kps); std::cout keypoints count: kps.size() std::endl; cv::Mat out; cv::drawKeypoints(img, kps, out); cv::imshow(sift, out); cv::waitKey(0); return 0; }如果这段代码能正常运行并打印出特征点数说明你整个编译链路没有任何问题OpenCV 3.2.0 contrib的编译成功收官。如果你的工程中引用了opencv_world320.lib但始终报链接错误大概率是你编译时没勾BUILD_opencv_world或者lib文件路径配置错误对照上一节的内容逐一检查即可。6. 常见问题速查表与最后的经验之谈编译这个组合时踩坑的频率相当高把最典型的问题汇总成一张速查表遇到报错先来这里对号入座。问题现象原因分析解决方案Configure时报ICV下载失败ippicv包未能从GitHub下载手动下载zip放到.cache\ippicv对应路径或屏蔽IPP下载C1083找不到boostdesc_bgm.i等xfeatures2d私有描述文件缺失去源码仓库手动下载并放到xfeatures2d\src下LNK1181找不到vgg_generated_48.i同类问题文件未下载成功同上下载对应文件放好链接时opencv_world320.lib不存在编译时未勾选BUILD_opencv_world要么勾选重新生成工程要么改用单独模块的lib运行时找不到opencv_xfeatures2d320.dllbin\Release未加入环境变量Path将dll所在目录加入系统Path编译过程计算机内存耗尽并行编译项目数过大MSBuild中限制并行编译数量或者关闭部分浏览器等内存大户Debug工程链接了Release的liblib运行时库设置不一致Debug工程链接opencv_core320d.lib等带d的libConfigure超时或卡死网络访问GitHub不稳定且无代理增加代理或者用离线缓存方式必要时用手机热点最后讲一点我的个人心得。在OpenCV版本迭代到4.x甚至5.x的今天花两三个小时去编译一个3.2.0的老版本看起来确实是一件有点“复古”的事情但如果你的工作场景是维护旧项目、对接老设备、复现几年前的开源算法这套老版本组合反而是最有价值的稳定靶点。编译过程中虽然会碰到各种小麻烦但只要搞清楚CMake配置、contrib源码下载、VS工程链接这几个核心环节整体难度其实不大。比起去网上找那些不知道从哪里来的预编译dll自己从头编译一次至少你能确切知道自己拿到的库是从哪个源码、什么配置出来的后续排查问题时心里也更有底。如果你手头还有充足的编译时间不妨再试着把Debug版本也编译出来或者尝试把contrib中自己用不到的模块通过CMake裁剪掉这些操作能进一步加深你对OpenCV构建系统的理解。我当年多花的时间后来在其他需要定制OpenCV的嵌入式项目里都加倍还了回来这大概就是自己动手编译最大的收获。本文还有配套的精品资源点击获取