COLMAP 命令行接口CLI完全指南从自动重建到逐命令管线【免费下载链接】colmapCOLMAP - Structure-from-Motion and Multi-View Stereo项目地址: https://gitcode.com/GitHub_Trending/co/colmap导读COLMAP 是面向 Structure-from-MotionSfM与 Multi-View StereoMVS的开源三维重建系统。其命令行接口将全部核心能力封装为colmap可执行文件的若干子命令是自动化脚本、批处理流水线、集群与云端重建的首选入口。本文以官方文档 doc/cli.rst 为主体结合 src/colmap/exe/colmap.cc 等源码系统讲解命令的发现方式、端到端重建示例、优雅关闭与断点续跑机制、全局 SfM 的前置校准流程以及全部可用命令的功能速查帮助你快速上手并深入理解 COLMAP 的 CLI 设计。命令总览一切功能皆子命令COLMAP 的命令行接口为自动化脚本提供所有功能的访问入口每项核心功能都实现为colmap可执行文件的一条命令。运行colmap -h可列出全部可用命令Windows 下为COLMAP.bat -h。从 src/colmap/exe/colmap.cc 的main函数可以看到命令分发机制所有命令以std::vectorCommand注册每条命令绑定一个形如int RunXxx(int argc, char** argv)的函数指针并带有一个supports_graceful_shutdown标记对应文中的优雅关闭能力。入口先初始化 Glog 日志与 OpenImageIO随后解析第一个参数匹配命令名若命令不存在会打印Command %s not recognized. To list the available commands, run colmap help.并返回失败。执行命令时子命令会获得argc-1个参数且command_argv[0]被替换为程序路径因此每个命令内部仍可通过 OptionManager 独立解析自己的参数详见 src/colmap/exe/colmap.cc。提示如果从 CMake 构建目录运行 COLMAP可执行文件位于./src/colmap/exe/colmap。要启动图形界面运行colmap gui。快速上手示例假设你的项目图片存放在如下目录结构/path/to/project/... ── images │ ── image1.jpg │ ── image2.jpg │ ── ... │ ── imageN.jpg一键自动重建自动重建命令要求项目文件夹内必须存在名为images的文件夹包含全部图片# 项目文件夹必须包含一个名为 images 的文件夹存放所有图片 $ DATASET_PATH/path/to/project $ colmap automatic_reconstructor \ --workspace_path $DATASET_PATH \ --image_path $DATASET_PATH/images任何命令都可以通过-h, --help参数列出全部可用选项。当需要更精细地控制重建过程的各个参数时可以用下面这套分步命令序列替代自动重建。分步管线从特征提取到纹理网格# 项目文件夹必须包含一个名为 images 的文件夹存放所有图片 $ DATASET_PATH/path/to/dataset # 1) 特征提取 $ colmap feature_extractor \ --database_path $DATASET_PATH/database.db \ --image_path $DATASET_PATH/images # 2) 特征匹配穷举式 $ colmap exhaustive_matcher \ --database_path $DATASET_PATH/database.db # 3) 稀疏重建增量式 SfM $ mkdir -p $DATASET_PATH/sparse $ colmap mapper \ --database_path $DATASET_PATH/database.db \ --image_path $DATASET_PATH/images \ --output_path $DATASET_PATH/sparse # 4) 图像去畸变为 MVS 准备 workspace $ mkdir -p $DATASET_PATH/dense $ colmap image_undistorter \ --image_path $DATASET_PATH/images \ --input_path $DATASET_PATH/sparse/0 \ --output_path $DATASET_PATH/dense \ --output_type COLMAP \ --max_image_size 2000 # 5) 稠密重建PatchMatch 立体匹配开启几何一致性 $ colmap patch_match_stereo \ --workspace_path $DATASET_PATH/dense \ --workspace_format COLMAP \ --PatchMatchStereo.geom_consistency true # 6) 深度图/法向图融合为彩色点云 $ colmap stereo_fusion \ --workspace_path $DATASET_PATH/dense \ --workspace_format COLMAP \ --input_type geometric \ --output_path $DATASET_PATH/dense/fused.ply # 7) 泊松表面重建 $ colmap poisson_mesher \ --input_path $DATASET_PATH/dense/fused.ply \ --output_path $DATASET_PATH/dense/meshed-poisson.ply # 8) Delaunay 网格重建备选 $ colmap delaunay_mesher \ --input_path $DATASET_PATH/dense \ --output_path $DATASET_PATH/dense/meshed-delaunay.ply # 9) 前进波前网格重建备选需要 CGAL $ colmap advancing_front_mesher \ --input_path $DATASET_PATH/dense \ --output_path $DATASET_PATH/dense/meshed-advancing-front.ply # 10) 可选简化稠密网格以减小体积 $ colmap mesh_simplifier \ --input_path $DATASET_PATH/dense/meshed-poisson.ply \ --output_path $DATASET_PATH/dense/meshed-poisson-simplified.ply \ --MeshSimplification.target_face_ratio 0.25 # 11) 可选使用去畸变图像为网格生成纹理 $ colmap mesh_texturer \ --workspace_path $DATASET_PATH/dense \ --input_path $DATASET_PATH/dense/meshed-poisson.ply \ --output_path $DATASET_PATH/dense/textured这套序列对应了 COLMAP 完整的三维重建流水线特征提取 → 特征匹配 → 稀疏重建SfM→ 去畸变 → 稠密重建MVS→ 融合 → 网格化 →可选简化与纹理化。其中image_undistorter的--output_type COLMAP表示按 COLMAP 原生格式导出 MVS workspace--max_image_size 2000限制去畸变图像的最大边长。从源码角度看上述每个命令都由 src/colmap/exe/ 目录下的分发函数实现feature_extractor对应 RunFeatureExtractormapper对应 RunMapper稠密阶段命令对应 src/colmap/exe/mvs.cc 中的RunPatchMatchStereo、RunStereoFuser、RunPoissonMesher等。优雅关闭与断点续跑信号处理机制特征提取与匹配命令、mapper、pose_prior_mapper、bundle_adjuster、point_triangulator、image_registrator、图像去畸变命令、patch_match_stereo与stereo_fusion都协作式地处理SIGINT与SIGTERM。automatic_reconstructor在使用增量式 mapper 时也支持优雅关闭。信号处理的核心实现在 src/colmap/util/cancellation.cc 的ScopedSignalHandler构造函数安装SIGINT/SIGTERM处理器第一次信号通过原子变量received_signal记录compare_exchange_strong并在安全点停止工作、写出可用的中间结果第二次信号则直接_Exit(128 signal)立即终止。进程退出码为SIGINT对应 130SIGTERM对应 143即128 signal见 GetExitCode。命令注册时只有带kSupportsGracefulShutdown标记的命令才安装信号处理器见 src/colmap/exe/colmap.cc。各命令断点续跑的语义如下特征提取/匹配对同一个数据库重跑相同命令即可续跑已完成部分自动跳过。PatchMatch对同一个 workspace 重跑完整的深度图与法向图会被跳过。增量式重建中断的稀疏重建会写入其常规编号的模型目录如sparse/0通过--input_path指定该目录即可继续$ colmap mapper \ --database_path $DATASET_PATH/database.db \ --image_path $DATASET_PATH/images \ --input_path $DATASET_PATH/sparse/0 \ --output_path $DATASET_PATH/sparse/0三角化、图像配准、光束法平差退出前写出可用的部分结果。立体融合非空的部分结果写入包含.partial的同级路径避免覆盖已完成的结果。图像去畸变中断后重跑同一命令即可恢复。Ceres 优化在迭代之间停止。Caspar 光束法平差后端只能在当前 solver 调用完成后停止。全局 mapper 不支持优雅关闭其中间重建当前无法恢复。pycolmap 中的取消语义对应的 pycolmap 函数在 Python 主线程调用时会自动处理SIGINTCtrl-C执行优雅关闭并抛出KeyboardInterrupt。对于其他终止事件可以传入可选的cancellation_token显式取消会完成清理后抛出InterruptedError。这样应用可以把云上抢占信号如SIGTERM连接到 token而无需 pycolmap 替换宿主应用的信号处理器。注意自动SIGINT处理要求从 Python 主线程调用 pycolmap 函数从其他线程调用时应改用 cancellation token。import signal import pycolmap token pycolmap.CancellationToken() signal.signal(signal.SIGTERM, lambda *_: token.cancel()) pycolmap.incremental_mapping( database_path, image_path, output_path, cancellation_tokentoken, )使用全局 SfM 管线若要用全局 SfM 管线替代增量式 mapper只需把mapper步骤替换为global_mapper。全局方法通过旋转平均与全局定位同时求解所有相机位姿对大规模数据集可能更快但对离群值可能更不稳健。全局 mapper 依赖较好的焦距先验因此如果无法获得可靠的相机内参例如从 EXIF 或实验室标定获得应首先运行view_graph_calibrator。该步骤为可选但推荐用于提升全局 SfM 质量这也一直是 GLOMAP 的默认行为。注意view_graph_calibrator会原地修改数据库中的相机内参与两视图几何因此建议在数据库副本上操作$ colmap feature_extractor \ --database_path $DATASET_PATH/database.db \ --image_path $DATASET_PATH/images $ colmap exhaustive_matcher \ --database_path $DATASET_PATH/database.db # 可选但通常需要从视图图标定内参。 # 该操作会原地修改数据库请在副本上操作。 $ cp $DATASET_PATH/database.db $DATASET_PATH/database_global.db $ colmap view_graph_calibrator \ --database_path $DATASET_PATH/database_global.db $ mkdir -p $DATASET_PATH/sparse $ colmap global_mapper \ --database_path $DATASET_PATH/database_global.db \ --image_path $DATASET_PATH/images \ --output_path $DATASET_PATH/sparse从 RunGlobalMapperImpl 的源码可以看到全局 mapper 通过GlobalPipeline控制器执行其选项类型为GlobalPipelineOptions需要数据库、图像路径与输出路径三个输入。无显示环境与 GPU/CPU 切换如果你要在没有显示器的计算机上运行 COLMAP如集群或云服务COLMAP 会在系统支持时自动切换为使用 CUDA。若没有可用的 CUDA 设备可以手动选择基于 CPU 的特征提取与匹配$ colmap feature_extractor --FeatureExtraction.use_gpu 0 ... $ colmap feature_matching --FeatureMatching.use_gpu 0 ...即通过--FeatureExtraction.use_gpu 0与--FeatureMatching.use_gpu 0两个选项强制关闭 GPU。特征提取器在需要 OpenGL 上下文如 SIFT GPU时还会自动创建QApplication见 RunFeatureExtractor。帮助系统与参数来源命令列表可用命令可用以下方式列出$ colmap help输出示例节选自 colmap.cc 的 ShowHelp 与 doc/cli.rstUsage: colmap [command] [options] Documentation: https://colmap.github.io/ Example usage: colmap help [ -h, --help ] colmap gui colmap gui -h [ --help ] colmap automatic_reconstructor -h [ --help ] colmap automatic_reconstructor --image_path IMAGES --workspace_path WORKSPACE colmap feature_extractor --image_path IMAGES --database_path DATABASE colmap exhaustive_matcher --database_path DATABASE colmap mapper --image_path IMAGES --database_path DATABASE --output_path MODEL ... Available commands: help gui automatic_reconstructor bundle_adjuster color_extractor database_cleaner database_creator database_merger delaunay_mesher exhaustive_matcher feature_extractor feature_importer geometric_verifier global_mapper guided_geometric_verifier hierarchical_mapper image_deleter image_filterer image_rectifier image_registrator image_undistorter image_undistorter_standalone mapper matches_importer mesh_simplifier mesh_texturer model_aligner model_analyzer model_clusterer model_comparer model_converter model_cropper model_merger model_orientation_aligner model_splitter model_transformer patch_match_stereo point_filtering point_triangulator pose_prior_mapper poisson_mesher project_generator rig_configurator rotation_averager sequential_matcher spatial_matcher stereo_fusion transitive_matcher view_graph_calibrator vocab_tree_builder vocab_tree_matcher vocab_tree_retriever每条命令的帮助输出每条命令都有-h, --help参数显示用法与可用选项例如$ colmap feature_extractor -h选项既可以通过命令行指定也可以定义在.ini项目文件中并通过--project_path传入。以下为feature_extractor -h的典型输出摘自 doc/cli.rstOptions can either be specified via command-line or by defining them in a .ini project file passed to --project_path. -h [ --help ] --default_random_seed arg (0) --log_target arg (stderr_and_file) {stderr, stdout, file, stderr_and_file} --log_path arg --log_level arg (0) --log_severity arg (0) {INFO 0, WARNING 1, ERROR 2, FATAL 3} --log_color arg (1) --project_path arg --database_path arg --image_path arg --camera_mode arg (-1) --image_list_path arg --descriptor_normalization arg (L1_ROOT) {L1_ROOT, L2} --ImageReader.mask_path arg --ImageReader.camera_model arg (SIMPLE_RADIAL) {SIMPLE_PINHOLE, PINHOLE, SIMPLE_RADIAL, RADIAL, OPENCV, OPENCV_FISHEYE, FULL_OPENCV, FOV, SIMPLE_RADIAL_FISHEYE, RADIAL_FISHEYE, THIN_PRISM_FISHEYE, RAD_TAN_THIN_PRISM_FISHEYE, SIMPLE_DIVISION, DIVISION, SIMPLE_FISHEYE, FISHEYE, EUCM, EQUIRECTANGULAR} --ImageReader.single_camera arg (0) --ImageReader.single_camera_per_folder arg (0) --ImageReader.single_camera_per_image arg (0) --ImageReader.existing_camera_id arg (-1) --ImageReader.camera_params arg --ImageReader.default_focal_length_factor arg (1.2) --ImageReader.camera_mask_path arg --FeatureExtraction.type arg (SIFT) {SIFT, ALIKED_N16ROT, ALIKED_N32, LOMA_B, LOMA_B128} --FeatureExtraction.max_image_size arg (3200) --FeatureExtraction.num_threads arg (-1) --FeatureExtraction.use_gpu arg (1) --FeatureExtraction.gpu_index arg (-1) --SiftExtraction.max_num_features arg (8192) --SiftExtraction.first_octave arg (-1) --SiftExtraction.num_octaves arg (4) --SiftExtraction.octave_resolution arg (3) --SiftExtraction.peak_threshold arg (0.0066666666666666671) --SiftExtraction.edge_threshold arg (10) --SiftExtraction.estimate_affine_shape arg (0) --SiftExtraction.max_num_orientations arg (2) --SiftExtraction.upright arg (0) --SiftExtraction.domain_size_pooling arg (0) --SiftExtraction.dsp_min_scale arg (0.16666666666666666) --SiftExtraction.dsp_max_scale arg (3) --SiftExtraction.dsp_num_scales arg (10)参数来源与语义要点所有选项可通过命令行直接给出也可写入.ini项目文件经--project_path传入。OptionManager统一负责解析与合并并在 mapper 完成后向每个子模型目录写出project.ini见 RunMapper。--camera_mode默认 -1取值AUTO/SINGLE/PER_FOLDER/PER_IMAGE。由 UpdateImageReaderOptionsFromCameraMode 映射到single_camera、single_camera_per_folder、single_camera_per_image三个布尔标志。AUTO 模式下相机模型由 EXIF 中的相机厂商、型号、焦距、图像宽高五个参数唯一确定若任一标签缺失则该相机视为无效并像 PER_IMAGE 模式一样新建相机。--FeatureExtraction.type默认 SIFT可选 SIFT、ALIKED_N16ROT、ALIKED_N32、LOMA_B、LOMA_B128对应仓库 src/colmap/feature 下的多种特征提取实现。各选项后的(默认值)与{可选值}即为该参数的默认取值与合法取值枚举直接指导脚本参数校验。命令功能速查以下按 doc/cli.rst 的命令列表简述每条colmap [command]的功能gui图形用户界面详见 doc/gui.rst。automatic_reconstructor对一组输入图像自动重建稀疏与稠密模型。关键选项包括--qualityLOW、MEDIUM、HIGH、EXTREME、--data_typeINDIVIDUAL、VIDEO、INTERNET以针对不同拍摄场景调优、--featureSIFT、ALIKED、LOMA、LOMA128选择特征提取算法、--mapperINCREMENTAL、HIERARCHICAL、GLOBAL选择 SfM 管线、--mesherPOISSON、DELAUNAY、ADVANCING_FRONT选择表面重建方法。project_generator按不同质量设置生成项目文件。feature_extractor、feature_importer对一组图像执行特征提取或导入特征。exhaustive_matcher、vocab_tree_matcher、sequential_matcher、spatial_matcher、transitive_matcher、matches_importer在特征提取之后执行特征匹配。geometric_verifier对数据库中已有的特征匹配独立运行几何验证估计匹配图像对的两视图几何基础矩阵/本质矩阵、单应矩阵。guided_geometric_verifier由已有稀疏重建引导的几何验证利用已知相对相机位姿改进匹配验证结果。mapper在特征提取与匹配之后使用 SfM 对数据集进行稀疏三维重建/建图。global_mapper使用全局 SfM 管线进行稀疏重建。与增量式mapper不同全局方法通过旋转平均与全局定位同时求解所有相机位姿。对大规模数据集可能更快但对离群值可能更不稳健。全局 mapper 依赖合理的焦距先验运行前应使用view_graph_calibrator从视图图标定相机内参并估计相对位姿或手动提供相机标定。pose_prior_mapper使用位姿先验进行稀疏重建/建图。hierarchical_mapper在特征提取与匹配之后使用分层 SfM 对数据集进行稀疏重建。该方案将场景划分为重叠子模型并独立重建最后合并为单一重建从而并行化重建过程。此步骤之后建议再运行几轮点三角化与光束法平差。image_undistorter对图像去畸变并/或导出用于 MVS 或外部稠密重建软件如 CMVS/PMVS。image_rectifier对相机做立体校正并去畸变图像用于立体视差估计。image_filterer从稀疏重建中过滤图像。image_deleter从稀疏重建中删除指定图像。patch_match_stereo运行image_undistorter初始化 workspace 之后使用 MVS 进行稠密重建。stereo_fusion将patch_match_stereo的结果融合为彩色点云。poisson_mesher使用泊松表面重建对融合点云进行网格化。delaunay_mesher基于 Delaunay 三角化的图割与可见性投票对重建的稀疏或稠密点云进行网格化。advancing_front_mesher使用前进波前表面重建对融合点云网格化支持基于可见性的过滤与大场景分块并行处理需要 CGAL。mesh_simplifier使用二次误差度量QEM简减三角形网格PLY 格式在保持整体形状与外观的前提下减少面数。关键选项--MeshSimplification.target_face_ratio控制保留面数比例默认 0.1、--MeshSimplification.max_error设置最大二次误差阈值0 表示禁用、--MeshSimplification.boundary_weight控制边界边保留程度默认 1000并支持--MeshSimplification.num_threads多线程初始化。mesh_texturer使用已标定的多视图图像为三角网格生成纹理图集与 UV 坐标。image_registrator将数据库中的新图像配准到已有模型例如在mapper之后向数据库添加新图像并提取、匹配特征后使用。注意该命令不执行光束法平差或三角化。point_triangulator使用数据库中的特征匹配对已有模型中已配准图像的所有观测进行三角化。point_filtering通过强制约束如最小轨迹长度、最大重投影误差等过滤模型中的稀疏点。bundle_adjuster对重建场景运行全局光束法平差例如需要精化内参时或image_registrator之后。求解器后端通过--BundleAdjustment.backendCERES或CASPAR选择。Caspar 是实验性的 GPU 加速后端详见 doc/faq.rst。database_cleaner清理特定或全部数据库表。database_creator创建带必要数据库 schema 的空 COLMAP SQLite 数据库。database_merger将两个数据库合并为新数据库。注意相机不会被合并且合并过程中相机与图像的唯一标识可能变化。model_analyzer打印重建统计信息。model_clusterer将重建拆分为更小的子模型簇适合管理与处理大规模重建。model_aligner将模型对齐/地理配准到给定相机中心的坐标系。model_orientation_aligner基于 Manhattan 世界假设对齐模型的坐标轴。model_comparer比较两个重建的统计信息。model_converter将 COLMAP 导出格式转换为其他格式如 PLY 或 NVM。model_cropper将模型裁剪到以 GPS 或模型坐标系描述的特定包围盒。model_merger尝试合并两个不相连的重建若它们有共同的已配准图像。model_splitter按文件中指定的包围盒坐标、子模型最大范围或各维划分数将模型划分为矩形子模型。model_transformer变换模型的坐标系。color_extractor为模型的所有三维点提取平均颜色。rig_configurator在特征提取后配置 rig 与 frame。vocab_tree_builder从已提取特征的数据库创建词汇树。该过程为离线操作可运行一次同一词汇树可复用于其他数据集。经验法则至少应使用视觉词数量 10–100 倍的特征数。若想在精度/召回率与速度之间做出不同取舍可构建自定义树。vocab_tree_retriever执行基于词汇树的图像检索。rotation_averager对视图图独立运行旋转平均从成对相对旋转估计全局相机旋转。view_graph_calibrator使用视图图标定相机内参从成对几何关系估计焦距与其他内参参数。在global_mapper之前若无良好先验内参则应运行因为全局 mapper 依赖较好的焦距先验。注文档中提及的预训练词汇树下载地址为 https://demuc.de/colmap/属于文档外部资源说明在无网络环境或需要自定义精度/速度取舍时可自行使用vocab_tree_builder构建。重建结果的可视化若想快速可视化稀疏或稠密重建管线的输出COLMAP 提供以下途径稀疏点云通过 COLMAP GUI 导入模型文件查看mapper生成的稀疏点云。选择File Import Model选中包含稀疏模型文件cameras.txt、images.txt、points3D.txt等的文件夹。稠密点云通过 COLMAP GUI 导入fused.ply查看stereo_fusion生成的稠密点云。选择File Import Model from...然后选中fused.ply文件。稠密网格poisson_mesher或delaunay_mesher生成的meshed-*.ply目前无法直接用 COLMAP 可视化建议使用外部查看器如 Meshlab。可用mesh_simplifier命令减小网格体积以加速可视化或下游处理用mesh_texturer命令生成带纹理图集的网格即可在 Meshlab 或其他 3D 查看器中展示。小结COLMAP 的 CLI 通过统一的子命令模型封装了从特征提取、匹配、稀疏重建到稠密重建、网格化、纹理化的全链路能力。掌握colmap help与各命令-h的输出结构理解automatic_reconstructor的质量/数据类型/特征/mapper/mesher 预设组合并善用优雅关闭与断点续跑机制即可在脚本化、云端与大规模场景中稳定构建自动化三维重建流水线。进一步深入参数细节可阅读 src/colmap/controllers/option_manager.cc 与 src/colmap/exe/ 目录下的命令实现源码。【免费下载链接】colmapCOLMAP - Structure-from-Motion and Multi-View Stereo项目地址: https://gitcode.com/GitHub_Trending/co/colmap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考