openMVG 特征提取工具 openMVG_main_ComputeFeatures 完全指南：参数、预设与掩码机制

• 计算机视觉
• 科研

导读

openMVG_main_ComputeFeatures是 openMVG（Open Multiple View Geometry，开源多视几何库）SfM 流水线中的第二个核心工具：它为sfm_data.json中登记的每一张视图（View）检测局部特征点（local regions）并计算描述子（descriptor），随后将结果持久化到磁盘，供下一阶段的特征匹配使用。本文以官方文档 ComputeFeatures.rst 为骨架，结合 main_ComputeFeatures.cpp 的源码实现，完整讲解该工具的命令行参数、描述器选择、预设配置、特征掩码（mask）机制与断点续算行为，读者读完后可以熟练配置并运行特征提取，为后续匹配与三维重建做好准备。

一、在 SfM 流水线中的位置

openMVG 的 SfM 流水线由四个连续步骤组成（见 SfM.rst）：

1. 图像列表（Image listing）：openMVG_main_SfMInit_ImageListing生成sfm_data.json，登记每张图像的路径、尺寸与相机内参；
2. 图像描述计算（Image description computation）：即本文主角openMVG_main_ComputeFeatures，对每个视图提取特征与描述子；
3. 对应图像与对应点计算（Correspondences computation）：openMVG_main_ComputeMatches基于上一步的描述子建立图像间匹配；
4. SfM 求解：openMVG_main_SfM（增量式或全局式）完成运动与结构恢复。

特征提取输出的质量直接决定了后续匹配的可靠性与重建精度，因此理解本工具的每个参数含义非常关键。官方还建议采用三目录数据组织方式：images（图像序列）、matches（存放 sfm_data、特征、描述子与匹配结果）、outReconstruction（存放重建结果与日志）。

二、基本用法与必需参数

命令格式（对应 ComputeFeatures.rst 中的示例）：

$ openMVG_main_ComputeFeatures -i [..\matches\sfm_data.json] -o [...\matches]

在 Linux 下典型调用为：

$ openMVG_main_ComputeFeatures -i ./matches/sfm_data.json -o ./matches

两个必需参数（在 main_ComputeFeatures.cpp 中通过make_option注册）：

源码行为细节：

• 输出目录不存在时会自动创建；若创建失败（如权限不足）则报错退出（main_ComputeFeatures.cpp）；
• 加载sfm_data.json时仅读取VIEWS | INTRINSICS两个数据块（视图与内参），文件不可读时直接失败退出（main_ComputeFeatures.cpp）；
• 若省略-o（输出目录为空字符串），工具会明确报错 "It is an invalid output directory"（main_ComputeFeatures.cpp）。

三、可选参数详解

1.-f/--force：是否强制重算

• 0（默认）：复用此前已计算的数据。适合进程被中断（如被 kill）后继续未完成的计算——已生成.feat/.desc文件的视图会被跳过，只补齐缺失的视图；
• 1：强制重算。当命令行参数（如描述器类型、预设）发生变化时使用，确保所有视图按新配置重新提取并覆盖保存。

这一行为与源码中的断点续算逻辑完全一致：循环遍历视图时，若!bForce且该视图的.feat与.desc文件都已存在，则直接跳过计算（main_ComputeFeatures.cpp）。

2.-m/--describerMethod：描述器方法

此外，源码还支持文档未在参数表中列出的SIFT_ANATOMY（基于论文《Anatomy of the SIFT Method》的开源实现，见 SIFT_Anatomy_Image_Describer.hpp），描述器工厂分配逻辑见 main_ComputeFeatures.cpp。

重要提示：-m的选择会影响后续匹配工具openMVG_main_ComputeMatches中-n/--nearest_matching_method的可用范围——标量描述子可使用 L2 系匹配（BRUTEFORCEL2、ANNL2、HNSWL2、CASCADEHASHINGL2 等），二进制描述子则应使用 HAMMING 距离系方法（BRUTEFORCEHAMMING、HNSWL1），详见 ComputeMatches.rst。

3.-u/--upright：是否提取直立特征

• 0（默认）：提取旋转不变特征，为每个关键点估计主方向；
• 1：提取直立特征，将所有关键点方向固定为 0°。适合图像方向基本一致（如航拍、扫描文档、无旋转的相机架设）的场景，可显著加快提取与匹配速度并减少误匹配，但会牺牲旋转不变性。

源码中该开关直接决定构造描述器时的bOrientation参数（!bUpRight），见 main_ComputeFeatures.cpp。

4.-p/--describerPreset：描述器配置预设

用于控制每张图像检测到的特征数量（即密度）：

预设的实质是调节关键点检测的对比度阈值（peak threshold），不同描述器实现方式如下（均有源码可查）：

• SIFT（SIFT_describer.hpp）：NORMAL阈值为0.04，HIGH降至0.01，ULTRA在0.01基础上进一步将first_octave设为-1（对原图进行上采样，从而在更细尺度上检测小特征）；
• SIFT_ANATOMY（SIFT_Anatomy_Image_Describer.hpp）：与 SIFT 完全相同的预设策略；
• AKAZE（image_describer_akaze.hpp）：NORMAL使用默认阈值，HIGH为默认阈值除以 10，ULTRA为默认阈值除以 100（阈值越低，检出的非线性尺度空间特征越多）。

预设通过基类纯虚接口Set_configuration_preset生效，枚举定义于 image_describer.hpp；若传入非法预设名，工具会报错 "Preset configuration failed" 并退出（main_ComputeFeatures.cpp）。

5.-n/--numThreads（仅 OpenMP 构建可用）

当 openMVG 以OPENMVG_USE_OPENMP编译时，特征提取循环由 OpenMP 并行化（#pragma omp parallel for schedule(dynamic)），可通过-n指定并行线程数；不指定时使用系统最大线程数，见 main_ComputeFeatures.cpp。

6. 可选参数速查表

四、输出产物与元数据机制

1. 特征与描述子文件

对每张视图，工具在输出目录生成一对文件（文件名取图像 basename，见 main_ComputeFeatures.cpp）：

• <image_name>.feat：特征点文件（坐标、尺度、方向等）；
• <image_name>.desc：对应的描述子文件。

2. 描述器配置元数据：image_describer.json

首次运行时，工具会把实际使用的描述器类型与配置序列化到输出目录的image_describer.json中，同时写入regions_type（main_ComputeFeatures.cpp）。后续运行（未加-f）时，工具会动态反序列化该文件，恢复上次使用的描述器设置（main_ComputeFeatures.cpp）。

这正是断点续算的底层机制：只要image_describer.json存在，即使你不记得上次用了什么-m/-p，工具也能沿用原配置继续计算。注意：如果你修改了命令行参数，务必加上-f 1强制重算，否则旧配置会被复用，参数改动不会生效。

3. 进度反馈

提取过程会通过LoggerProgress打印进度条（"- EXTRACT FEATURES -"），并在结束时输出总耗时（"Task done in (s): ..."），方便监控长耗时任务，见 main_ComputeFeatures.cpp。

五、特征掩码（Mask）机制：只在你关心的区域提取特征

1. 为什么需要掩码

官方文档指出，有些场景下你只想在图像的部分区域计算特征：

• 排除干扰区域：某些采集场景中，部分区域可能干扰 SfM 流水线（尽管 openMVG 对离群点有较强鲁棒性），降低重建质量。例如近景拍摄时你更希望移动物体而非相机，可以用掩码把背景遮挡掉；处理半球鱼眼镜头时，也可用掩码屏蔽传感器上的无用区域；
• 加速计算：减少特征点数量即减少后续 tie points（连接点）数量，从而加快匹配与重建。

2. 掩码文件的约定

掩码是一张与目标图像同宽同高的二值图像：

• 黑色区域（像素值为 0）表示"坏区域"，不计算描述子；
• 关键点位置的掩码像素值非 0时，该点才被保留（"A point is kept if the mask value at the point position is different than 0"）。

openMVG_main_ComputeFeatures中掩码与图像的关联是隐式的，按以下约定查找（源码见 main_ComputeFeatures.cpp）：

1. 全局掩码：尝试从图像存储目录（sfm_data.json的根路径）加载mask.png，作用于该目录下的所有图像；
2. 局部掩码：尝试从当前图像所在目录加载<image_name>_mask.png，仅作用于对应的那张图像。

优先级：局部掩码始终优先于全局掩码（"The individual mask always takes precedence over the global one"）。

3. 源码层面的三个关键细节

• 尺寸校验：无论局部还是全局掩码，只有当掩码的宽高与当前灰度图像完全一致时才会被使用（main_ComputeFeatures.cpp），尺寸不符的掩码会被静默忽略；
• 读取失败即终止：若掩码文件存在但无法读取（损坏或非 PNG），工具会记录错误并中止整个特征提取（preemptive_exit = true），而不是跳过该视图（main_ComputeFeatures.cpp）；
• 点级过滤：掩码过滤发生在特征点检测之后，源码对每个关键点执行if (maskIma(k.y, k.x) == 0) continue;进行剔除（例如 SIFT_Anatomy 实现见 SIFT_Anatomy_Image_Describer.hpp），掩码的语义在基类接口中定义为"非零值表示感兴趣区域"（image_describer.hpp）。

4. 掩码使用示例

假设图像目录为./images，全局掩码放置如下：

images/ ├── mask.png # 全局掩码，作用于所有图像 ├── photo_01.jpg ├── photo_02.jpg └── photo_03.jpg

若只想屏蔽photo_03.jpg的某个区域（例如天空），则额外放置：

images/ └── photo_03_mask.png # 局部掩码，优先于全局掩码

命令行无需任何额外参数：

$ openMVG_main_ComputeFeatures -i ./matches/sfm_data.json -o ./matches

工具会自动发现并应用上述掩码。

六、实战建议与进阶用法

1. 典型完整调用

# 默认 SIFT + NORMAL 预设 $ openMVG_main_ComputeFeatures -i ./matches/sfm_data.json -o ./matches # 高密度特征 + 旋转不变，适合一般照片集 $ openMVG_main_ComputeFeatures -i ./matches/sfm_data.json -o ./matches -m SIFT -p HIGH # 二进制描述子加速匹配 $ openMVG_main_ComputeFeatures -i ./matches/sfm_data.json -o ./matches -m AKAZE_MLDB -u 1

2. 球面（360° 全景）SfM 的建议配置

官方在 SfM.rst 的 "Notes about Spherical SfM" 中给出了处理等距柱状（equirectangular）全景图像时的明确建议：

$ openMVG_main_ComputeFeatures -i ./matches/sfm_data.json -o ./matches -m SIFT -p HIGH

理由：球面投影引入了畸变，使用HIGH预设提取更多特征可提高后续匹配成功率；同时建议在匹配阶段使用带角度约束的 Essential 矩阵（-g a）。

3. 长任务管理

• 特征提取是 SfM 流水线中较耗时的一步，ULTRA预设耗时显著，请评估后再用；
• 若中途中断，只需再次运行相同命令（保持-f 0），工具会跳过已完成视图继续计算；
• 若修改了-m/-p/-u等参数，必须加-f 1才会生效。

七、完成后做什么

特征提取完成后（文档原文 "Once openMVG_main_ComputeFeatures is done you can compute the Matches between the computed description"），下一步是运行openMVG_main_ComputeMatches计算图像间的匹配关系，其参数详见 ComputeMatches.rst。此外，若需可视化检查特征提取质量，可使用openMVG_main_exportKeypoints将检测到的关键点导出为 SVG 文件（该工具与特征导出功能位于 src/software/SfM 软件目录下）。

八、参考资源

• 工具官方文档：ComputeFeatures.rst
• 工具主程序实现：main_ComputeFeatures.cpp
• 描述器抽象基类与预设枚举：image_describer.hpp
• SIFT（VLFeat）实现与预设逻辑：SIFT_describer.hpp
• SIFT_Anatomy 实现与预设逻辑：SIFT_Anatomy_Image_Describer.hpp
• AKAZE 实现与预设逻辑：image_describer_akaze.hpp
• SfM 流水线总览：SfM.rst
• 匹配阶段文档：ComputeMatches.rst

• 计算机视觉
• 科研