?本系列文章旨在系統性地闡述如何利用 Python 與 OpenCV 庫，從零開始構建一個完整的雙目立體視覺系統。
本項目github地址：https://github.com/present-cjn/stereo-vision-python.git
項目架構設計：藍圖、分工與工作流
在上一篇文章中，我們了解了雙目立體視覺的基本原理和核心流程。在正式編寫算法之前，我們必須先做好一件事——搭建一個堅實、清晰、可擴展的項目框架。
這就像建造一座大廈，我們不能直接開始砌墻，而是需要先有一份精密的建筑藍圖。一個好的項目架構，能讓我們的代碼思路清晰、易于維護、便于測試，并且在未來增加新功能時游刃有余。告別將所有代碼都堆砌在單個文件里的“面條式代碼”，是每一位開發者從入門走向專業的必經之路。
本文將詳細剖析我們這個雙目視覺項目的“建筑藍圖”，解釋每個模塊的職責分工和它們之間的協作關系。
📂 項目目錄結構一覽
下面是項目的整體目錄結構，這個結構是我們所有討論的基礎。
stereo-vision-project/
├── main.py # 主程序入口，命令行界面
├── config.py # 所有配置參數
├── requirements.txt # 項目依賴
│
├── calibration/ # 相機標定模塊
│ └── calibrator.py
├── processing/ # 核心處理模塊
│ ├── stereo_matcher.py # 立體匹配
│ └── reconstructor.py # 三維重建
├── utils/ # 通用工具函數
│ ├── file_utils.py # 文件讀寫
│ ├── image_utils.py # 圖像處理
│ └── sorting_utils.py # 自然排序
├── visualization/ # 可視化模塊
│ └── visualizer.py
├── tests/ # 測試代碼
│ └── ...
└── data/ # 數據├── calibration_images/└── test_images/程序入口與任務調度：main.py
main.py 是我們整個項目的唯一入口和總指揮。它的職責不是執行具體的算法，而是扮演一個“應用啟動器”和“任務分發器”的角色。
- 命令行界面 (CLI): 我們使用 Python 內置的
argparse庫，將main.py打造成一個專業的命令行工具。用戶可以通過python main.py calibrate或python main.py run來執行不同的任務，并通過--verbose或--view-3d等參數來控制程序的行為。 - 任務編排:
main.py負責按照邏輯順序，調用其他模塊中的類和函數，將整個雙目視覺的流水線串聯起來。它負責加載配置、執行標定或主應用流程，并最終呈現結果。
全局配置與狀態管理：config.py
這個文件是我們項目的全局配置中心。它遵循一個重要的設計原則：配置與代碼分離。
- 集中管理: 所有可以調整的參數，如文件路徑、算法超參數（SGBM的參數）、標定板的默認尺寸等，都集中存放在這里。
- 便于調試與維護: 當我們需要調整算法效果時，只需要修改
config.py中的數值，而無需觸及核心的算法邏輯代碼。這極大地提高了代碼的可維護性。 - 運行時狀態: 它也承載了像
VERBOSE_MODE這樣的全局運行時狀態，由main.py在啟動時根據命令行參數設置，供所有其他模塊查詢。
核心算法模塊：calibration/ 與 processing/
這兩個目錄存放了項目最核心的算法邏輯，每個模塊都負責一個獨立的、高度內聚的功能。
calibration/calibrator.py: 負責相機標定。該模塊實現了完整的兩步標定法，用于計算相機的內外參及畸變參數，并生成最終的stereo_params.yml配置文件。processing/stereo_matcher.py: 負責立體匹配。該模塊使用 SGBM (半全局塊匹配) 算法，接收校正后的圖像對，計算并生成包含深度信息的視差圖。processing/reconstructor.py: 負責三維重建。該模塊接收視差圖和相機幾何參數，通過reprojectImageTo3D函數將2D視差信息轉換為3D空間中的點云。
通用工具函數模塊：utils/
utils/ 目錄存放了各種通用的、可被項目中任何模塊復用的輔助函數。
file_utils.py: 負責所有與文件系統交互的操作，如保存和加載.yml標定文件、保存.ply點云文件。image_utils.py: 負責通用的圖像處理任務，最核心的就是rectify_stereo_pair函數，用于立體校正。sorting_utils.py: 提供natural_sort_key函數，解決在加載文件時left_10.jpg排在left_2.jpg前面的問題。
將這些工具函數獨立出來，能避免在多個地方寫重復的代碼，并讓核心算法模塊的邏輯更純粹。
可視化與用戶交互模塊：visualization/
這個模塊負責所有與用戶界面和結果展示相關的工作。它的職責是將程序內部的數據，以一種人類可讀的方式呈現出來。
- 它包含了顯示各種中間結果（如角點圖、校正圖、視差圖）和最終成果（點云、交互式深度圖）的函數。
- 它還負責處理所有的用戶界面交互，比如
_wait_for_key_or_window_close輔助函數，確保程序能正確響應用戶的鍵盤和鼠標操作。
自動化測試模塊：tests/
tests/ 目錄存放了我們所有的自動化測試腳本。
- 單元測試: 驗證某個獨立的函數或類是否按預期工作。
- 穩定性測試: 驗證我們的算法（如兩步標定法）是否對輸入順序等無關變量不敏感，保證其健壯性。
- 自動化: 通過
pytest框架，我們可以一鍵運行所有測試，確保任何新的代碼改動都沒有破壞已有的功能。這是保證項目長期健康、可維護的基石。
總結
通過這樣一種模塊化的架構設計，我們將一個復雜的大問題，分解成了一系列職責單一、易于管理的小問題。每個模塊都可以被獨立地開發、測試和改進。
在下一篇文章中，我們將正式深入第一個核心算法模塊——calibration，剖析相機標定的每一個技術細節和代碼實現。
