海洋內波波速分析與視覺化專案 (Wave Speed Visualization)

本專案是一個自動化的 Python 工具，旨在從連續的衛星影像序列中，分析海洋內波 (Internal Wave) 的傳播速度，並產生可用於學術研究與報告的專業級視覺化圖表及統計數據。

✨ 核心功能

• 自動化關鍵點偵測: 採用基於參考框架的演算法，穩定地識別內波在不同時間的特徵點。
• 精確的波速計算: 透過匹配相鄰時間的關鍵點，計算每個點的位移，並結合影像時間間隔與空間解析度，得出準確的波速場（單位：m/s）。
• 專業級學術視覺化: 一鍵生成包含原始影像、分割遮罩、關鍵點標記、波速向量和統計摘要的多合一學術圖表，支援高 DPI 輸出。
• 詳盡的統計報告: 自動生成時間序列圖、箱型圖等多種統計圖表，並可將結果匯出為 LaTeX、Excel 或 CSV 格式。
• 高度可配置: 所有重要參數（如檔案路徑、物理參數、演算法閾值）皆透過 config.yaml 檔案集中管理，易於調整與擴充。

📂 檔案結構

📦wave_speed_visualization_5Points
 ┣ 📂data/                      # (由使用者設定) 存放原始資料
 ┃ ┣ 📂Img1/                  # 原始衛星影像
 ┃ ┗ 📂Deeplab1/              # 影像分割後的遮罩 (Mask)
 ┣ 📂output/                    # (由使用者設定) 存放所有輸出結果
 ┣ 📂scripts/                   # 主要執行腳本
 ┃ ┣ 📜main_analysis.py       # 核心分析流程：計算波速並生成視覺化圖檔
 ┃ ┗ 📜generate_reports.py    # 統計報告生成器
 ┣ 📂wave_analyzer/             # 專案核心程式碼套件
 ┃ ┣ 📂core/                  # 核心演算法 (波速計算)
 ┃ ┣ 📂processing/            # 資料前處理 (檔案讀取、影像處理)
 ┃ ┣ 📂stats/                 # 統計分析與視覺化
 ┃ ┣ 📂visualization/         # 主要的學術圖表產生器
 ┃ ┗ 📜config.py              # 設定檔載入器
 ┣ 📜config.yaml                # 專案設定檔
 ┣ 📜.env.example               # 環境變數範本檔 (需自行建立)
 ┣ 📜requirements.txt           # 依賴套件清單 (需自行建立)
 ┗ 📜readme.md                  # 本說明文件

⚙️ 環境部署 (Environment Deployment)

請依照以下步驟來設定您的開發環境。

1. 前置準備

• 確認您已安裝 Python 3.9 或更高版本。
• 安裝 Git 版本控制工具。

2. 取得專案

打開您的終端機，並複製 (clone) 此專案儲存庫：

git clone <your-repository-url>
cd wave_speed_visualization_5Points

3. 建立虛擬環境

強烈建議使用虛擬環境來隔離專案的依賴套件。

# 建立一個名為 venv 的虛擬環境
python -m venv venv

# 啟用虛擬環境
# On Windows:
# venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

4. 安裝依賴套件

建立一個名為 requirements.txt 的檔案，並填入以下內容：

# requirements.txt
numpy
scikit-image
matplotlib
pandas
seaborn
PyYAML
python-dotenv
pydantic

執行以下指令進行安裝：

pip install -r requirements.txt

5. 設定環境變數

此專案使用 .env 檔案來管理本地的資料路徑，以避免將絕對路徑寫死在程式碼中。

1. 建立一個名為 .env 的檔案。

2. 在 .env 檔案中填入以下內容，並將路徑修改為您電腦上的絕對路徑：

   # .env
   DATA_ROOT="C:/Users/YourUser/Documents/my_ocean_data"
   OUTPUT_ROOT="C:/Users/YourUser/Documents/project_outputs"

6. 準備輸入資料

1. 在您於 .env 中設定的 DATA_ROOT 路徑下，建立兩個資料夾：Img1 和 Deeplab1。
2. 將您的原始衛星影像 (例如 YYYYMMDDHHMM.png) 放入 Img1 資料夾。
3. 將對應的影像分割遮罩 (例如 YYYYMMDDHHMM_predict.png) 放入 Deeplab1 資料夾。

至此，您的環境已部署完成！

🚀 使用教學 (Usage)

分析流程分為兩大步驟：執行主要分析和生成統計報告。

步驟一：執行核心分析

此步驟會處理成對的影像，計算波速，並生成主要的學術視覺化圖檔和原始數據（JSON 檔案）。

在您的終端機中執行 main_analysis.py 腳本：

python scripts/main_analysis.py

可選參數：

• --output_suffix <SUFFIX>: 為輸出的檔名添加後綴，方便區分不同實驗。

  python scripts/main_analysis.py --output_suffix "run1"

• --high_dpi: 使用 600 DPI 進行輸出，適合期刊投稿等級的解析度。

  python scripts/main_analysis.py --high_dpi

執行後，結果將儲存在您於 .env 中設定的 OUTPUT_ROOT 路徑下。

步驟二：生成統計報告

在完成核心分析後，你可以用這個腳本來匯總所有原始數據，並產生綜合的統計圖表和報告。

執行 generate_reports.py 腳本：

python scripts/generate_reports.py --generate_plots --export_format latex

可選參數：

• --generate_plots: 生成時間序列圖、箱型圖等統計圖表。
• --export_format <FORMAT>: 將統計摘要匯出為指定格式。可選格式：latex, excel, csv。

執行後，所有統計圖表和報告將儲存在 OUTPUT_ROOT 路徑下的 statistics 資料夾中。

🔧 專案設定 (config.yaml)

本專案的所有核心參數都可在 config.yaml 中進行調整，無需修改程式碼。

• data_sources: 定義不同資料夾的檔名規則。
• physical_params: 設定物理參數，如像素與公尺的換算比例。
• algorithm_params: 調整演算法相關的閾值。
• visualization: 控制輸出的視覺化設定。
• geo_params: 設定地理空間相關資訊，如觀測站座標。

📄 授權 (License)

本專案採用 MIT License 授權 (可自行修改)。