VisualOdometry VO Tool

OpenCV + PySide6 で、前後魚眼OSV動画から単眼VO軌跡を推定し、GUIで3D表示・出力するプロトタイプです。

1. 何ができるか

• OSV/MP4の前後分割読み込み（左右/上下/別ファイル）
• キャリブレーションXMLの自動抽出 + 手編集
• 魚眼補正（ON/OFF、比較ビュー、mapキャッシュ）
• 単眼VO（ORB + Essential + recoverPose）
• 3D軌跡表示（front/back）
• 解析結果のCSV/JSON/デバッグ画像出力

2. 処理フロー（どのファイルで何をしているか）

1. GUI起動

• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/main.py
  • Qtアプリ起動、メインウィンドウ生成

2. GUI全体制御

• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/gui/main_window.py
  • 各パネル接続、Preview処理、解析スレッド起動/停止、進捗/ログ更新
  • VOAnalysisThread 内でフレームループ・VO実行・出力保存を実施

3. 動画入力設定UI

• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/gui/widgets/video_selector.py
  • 入力モード（one_file/two_files）、split方式、frame index を収集

4. 動画読み込みとfront/back抽出

• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/core/video_io.py
  • VideoReader が cv2.VideoCapture からフレーム取得
  • FramePacket(index, timestamp_sec, frame_front, frame_back, raw_frame) を返す
• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/core/osv_split.py
  • split_front_back() で left_right / top_bottom を切り出し
  • overlay_split_guide() で分割境界を描画

5. キャリブレーションUI

• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/gui/widgets/calib_panel.py
  • XML選択、抽出値の表示、手編集、manual override生成

6. XML抽出ロジック

• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/core/calib_xml.py
  • 汎用探索（タグ/属性/ネスト）で fx,fy,cx,cy,f,k1..k4,p1,p2,width,height を抽出
  • OpenCV Camera_Matrix / Distortion_Coefficients を直接解釈
  • CalibrationParseResult と warning を返す

7. 魚眼補正

• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/core/fisheye_undistort.py
  • cv2.fisheye.initUndistortRectifyMap + cv2.remap
  • 画像サイズ単位でmapをキャッシュ
  • 補正前後比較画像（エッジ重畳）を生成

8. VO設定UI

• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/gui/widgets/vo_panel.py
  • target(front/back/both), start/end/step, min_inliers, output_dir, undistort, debug を設定

9. 単眼VO計算

• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/core/vo_mono.py
  • ORB特徴抽出
  • BFMatcher + ratio test
  • findEssentialMat(RANSAC)
  • recoverPose で相対姿勢推定
  • camera-to-world姿勢を逐次積分（スケール任意）
  • inlier不足時はスキップして姿勢維持

10. メトリクス集計

• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/core/metrics.py
  • success率、平均inlier、平均処理ms、推定FPSを集計

11. 3D軌跡表示

• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/gui/widgets/trajectory_view.py
  • pyqtgraph.opengl でfront/back軌跡を線描画（front=青, back=赤）

12. 出力保存

• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/core/export.py
  • trajectory_*.csv/json、inlier_ratio.csv、match_debug_*.png、undistort_preview.png

13. 設定保存/再読込

• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/core/config_io.py
  • project_config.json のload/save

3. ディレクトリ

• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/core
  • 計算・I/O・保存ロジック
• /Users/satoshi/01_development/VisualOdometry/vo_tool/app/gui
  • UIと制御
• /Users/satoshi/01_development/VisualOdometry/tests
  • split / XML抽出 / VOスモーク テスト

4. セットアップ

cd /Users/satoshi/01_development/VisualOdometry
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

5. 起動

cd /Users/satoshi/01_development/VisualOdometry
python -m vo_tool.app.main

6. 推奨入力（提供ファイル）

• 動画
  • /Users/satoshi/01_development/360split/test/CAM_20260205141214_0023_D.OSV
• XML
  • /Users/satoshi/01_development/360split/test/camcalib1.xml
  • /Users/satoshi/01_development/360split/test/camcalib2.xml

7. 出力ファイル

出力先（既定: /Users/satoshi/01_development/VisualOdometry/outputs）に保存:

• trajectory_front.csv, trajectory_back.csv
• trajectory_front.json, trajectory_back.json
• inlier_ratio.csv
• match_debug_<camera>_<frame>.png
• undistort_preview.png

8. 制約

• 単眼VOのためスケールは任意（相対値）
• 外部スケール（IMU/GNSS/ステレオ外部キャリブ）なしでは絶対距離は不定
• front/back統合スケール推定、ループ閉じ、GPU最適化は未実装