📷

colmapとpycolmapのCLI/API比較表

に公開
colmap
SfM
pycolmap
tech

COLMAPのコマンドラインインターフェース（CLI）とPyCOLMAPのPython APIの機能を整理します。

最新の情報は、各OSSの公式ページを参照してください。

📊 COLMAP CLI と PyCOLMAP API の機能比較表

機能カテゴリ 小機能カテゴリ COLMAP CLI コマンド PyCOLMAP API 関数・クラス
pycolmap.xxx
特徴抽出とマッチング 特徴抽出 feature_extractor extract_features()
特徴マッチング exhaustive_matcher
sequential_matcher
spatial_matcher
vocab_tree_matcher 		match_exhaustive()
match_sequential()
match_spatial()
match_vocabulary_tree()
スパース再構成（SfM） インクリメンタル再構成 mapper
hierarchical_mapper 		incremental_mapping()
三角測量 point_triangulator point_triangulator()
バンドル調整 bundle_adjuster
rig_bundle_adjuster 		BundleAdjuster クラス
デンス再構成（MVS） 画像の歪み補正 image_undistorter undistort_images()
パッチマッチステレオ patch_match_stereo patch_match_stereo()
ステレオフュージョン stereo_fusion stereo_fusion()
メッシュ生成 poisson_mesher
delaunay_mesher 		対応なし
モデルの操作と変換 モデルの整列 model_aligner
model_orientation_aligner 		align_reconstruction_to_locations()
align_reconstructions_via_points()
モデルの変換・統合 model_converter
model_merger 		対応なし
モデルの解析 model_analyzer compare_reconstructions()
ポーズ推定と最適化 ポーズ推定 対応なし estimate_absolute_pose()
refine_absolute_pose()
estimate_and_refine_absolute_pose()
データベースと画像の管理 データベース操作 database_creator
image_deleter 		Database クラス
画像の整流処理 image_rectifier 対応なし
画像の登録 image_registrator 対応なし
合成データセット生成 合成データセット生成 対応なし synthesize_dataset()
GUIの提供 GUIの起動 gui 対応なし

🧩 小機能カテゴリの説明

  • 特徴抽出:
    • 画像から特徴点（通常はSIFT）を抽出し、データベースに保存します。
  • 特徴マッチング:
    • 抽出された特徴点を用いて、画像間の対応関係を確立します。手法には全探索、連続、空間的、ボキャブラリツリーを用いたマッチングがあります。
  • インクリメンタル再構成:
    • 特徴マッチング結果を基に、画像を逐次追加しながらスパースな3Dモデルを構築します。
  • 三角測量:
    • 既存のカメラポーズとマッチング結果から、3D点の位置を計算します。
  • バンドル調整:
    • カメラパラメータと3D点の位置を同時に最適化し、再構成精度を向上させます。
  • 画像の歪み補正:
    • カメラのレンズ歪みを補正し、デンス再構成の前処理を行います。
  • パッチマッチステレオ:
    • 複数の画像間で視差マップを計算し、デンスな3D情報を取得します。
  • ステレオフュージョン:
    • 複数の視差マップを統合し、デンスな点群を生成します。
  • メッシュ生成:
    • デンスな点群からメッシュモデルを生成します。Poisson法やDelaunay法が用いられます。
  • モデルの整列:
    • 再構成されたモデルを外部座標系や他のモデルと整列させます。
  • モデルの変換・統合:
    • 再構成モデルのフォーマット変換や、複数モデルの統合を行います。
  • モデルの解析:
    • 再構成モデルの統計情報や品質を解析します。
  • ポーズ推定:
    • 2D-3D対応点からカメラの位置と向きを推定します。
  • データベース操作:
    • COLMAPのSQLiteデータベースの作成や画像の追加・削除を行います。
  • 画像の整流処理:
    • ステレオマッチングのために画像を整流（リファイン）します。
  • 画像の登録:
    • 新しい画像を既存の再構成モデルに追加します。
  • 合成データセット生成:
    • シミュレーション用の合成画像データセットを生成します。
  • GUIの起動:
    • COLMAPのグラフィカルユーザーインターフェースを起動します。

📚 出典情報

colmapのhierarchical_mapperとmapperのパラメータ

パラメータ hierarchical_mapper 既定値 mapper 既定値 備考
共通 (トップレベル)
--random_seed 0 0 乱数シード
--log_to_stderr 0 0 標準エラーへのログ出力
--log_level 2 2 glog レベル
--project_path (なし) (なし) プロジェクトルート
--database_path (なし) (なし) COLMAP DB ファイル
--image_path (なし) (なし) 画像ディレクトリ
--output_path (なし) (なし) 出力 (モデル) 保存先
トップレベル : 片方にのみ存在
--num_workers -1 ― 階層的マッピング各ノードの並列ワーカー数
--image_overlap 50 ― 隣接クラスタ間で共有する画像数 (%)
--leaf_max_num_images 500 ― 末端クラスタ 1 つ当たりの最大画像枚数
--input_path ― (なし) 既存モデルを入力して継続マッピング
--image_list_path ― (なし) マッピング対象画像リスト
Mapper. オプション (両者共通)*
Mapper.min_num_matches 15 15 画像ペア登録に必要な最小マッチ数
Mapper.ignore_watermarks 0 0 ウォーターマーク除外
Mapper.multiple_models 1 1 複数モデル生成を許可
Mapper.max_num_models 50 50 生成モデル数上限
Mapper.max_model_overlap 20 20 モデル間で共有可能な画像上限
Mapper.min_model_size 10 10 有効モデルとする最小画像枚数
Mapper.init_image_id1 / 2 -1 / -1 -1 / -1 初期画像 ID を固定する場合に指定
Mapper.init_num_trials 200 200 初期ペア探索試行回数
Mapper.extract_colors 1 1 点群色推定を行う
Mapper.num_threads -1 -1 スレッド数 (-1 は自動)
Mapper.min_focal_length_ratio 0.1 0.1 最小 f / image_size
Mapper.max_focal_length_ratio 10 10 最大 f / image_size
Mapper.max_extra_param 1 1 歪みパラメータ最大数
Mapper.ba_refine_focal_length 1 1 BA で f を最適化
Mapper.ba_refine_principal_point 0 0 BA で主点を最適化
Mapper.ba_refine_extra_params 1 1 BA で歪みも最適化
Mapper.ba_min_num_residuals_for_multi_threading 50000 50000 BA を並列化する閾値
Mapper.ba_local_num_images 6 6 ローカル BA の画像窓幅
Mapper.ba_local_function_tolerance 0 0 ローカル BA 収束閾値
Mapper.ba_local_max_num_iterations 25 25 ローカル BA 最大反復
Mapper.ba_global_use_pba 0 0 PBA を用いてグローバル BA
Mapper.ba_global_pba_gpu_index -1 -1 PBA 使用 GPU (-1 で自動)
Mapper.ba_global_images_ratio 1.1 1.1 グローバル BA 画像増加閾値
Mapper.ba_global_points_ratio 1.1 1.1 グローバル BA 点増加閾値
Mapper.ba_global_images_freq 500 500 画像増加頻度 (step)
Mapper.ba_global_points_freq 250000 250000 点群増加頻度
Mapper.ba_global_function_tolerance 0 0 グローバル BA 収束閾値
Mapper.ba_global_max_num_iterations 50 50 グローバル BA 最大反復
Mapper.ba_global_max_refinements 5 5 グローバル BA 最大再最適化回数
Mapper.ba_global_max_refinement_change 0.0005 0.0005 BA 再最適化終了閾値
Mapper.ba_local_max_refinements 2 2 ローカル BA 最大再最適化回数
Mapper.ba_local_max_refinement_change 0.001 0.001 ローカル BA 再最適化終了閾値
Mapper.snapshot_path (なし) (なし) 途中スナップショット保存先
Mapper.snapshot_images_freq 0 0 スナップショット間隔
Mapper.fix_existing_images 0 0 既存画像パラメータ固定
Mapper.init_min_num_inliers 100 100 初期ペア RANSAC インライア数
Mapper.init_max_error 4 4 初期ペア RANSAC 最大誤差
Mapper.init_max_forward_motion 0.95 0.95 進行方向比率上限
Mapper.init_min_tri_angle 16 16 三角測量最小角度
Mapper.init_max_reg_trials 2 2 初期ペア登録最大試行
Mapper.abs_pose_max_error 12 12 PnP 最大 reproj 誤差
Mapper.abs_pose_min_num_inliers 30 30 PnP 最小インライア
Mapper.abs_pose_min_inlier_ratio 0.25 0.25 PnP インライア比率
Mapper.filter_max_reproj_error 4 4 outlier filter reproj 閾値
Mapper.filter_min_tri_angle 1.5 1.5 outlier filter 角度閾値
Mapper.max_reg_trials 3 3 1 枚画像登録最大試行
Mapper.local_ba_min_tri_angle 6 6 ローカル BA 対象点角度
Mapper.tri_max_transitivity 1 1 視線伝播最大次数
Mapper.tri_create_max_angle_error 2 2 新規点生成 max 誤差
Mapper.tri_continue_max_angle_error 2 2 追加入力 max 誤差
Mapper.tri_merge_max_reproj_error 4 4 点マージ reproj 閾値
Mapper.tri_complete_max_reproj_error 4 4 点補完 reproj 閾値
Mapper.tri_complete_max_transitivity 5 5 点補完伝播上限
Mapper.tri_re_max_angle_error 5 5 点再三角測量 max 誤差
Mapper.tri_re_min_ratio 0.2 0.2 点再三角測量最小比率
Mapper.tri_re_max_trials 1 1 点再三角測量最大試行
Mapper.tri_min_angle 1.5 1.5 有効点最小角度
Mapper.tri_ignore_two_view_tracks 1 1 2-view Track 無視

Discussion