changelog.md

# 變更日誌 (Changelog)

> 記錄專案的重大變更、新功能與修復。採用 [Keep a Changelog](https://keepachangelog.com/) 格式。

## [Unreleased]

### Added
- **波形繪製效能優化（針對 Hugging Face Space）**
  - **降採樣**：波形數據降採樣 5 倍（100 Hz → 20 Hz），從每測站 12000 點減少到 2400 點，大幅減少數據傳輸量。
  - **WebGL 渲染**：使用 `Scattergl` 替代 `Scatter`，啟用 WebGL 加速渲染，適合大量數據點顯示。
  - **簡化互動**：將 dragmode 從預設的框選縮放改為 pan（平移），減少渲染負擔。
  - **效果**：在 Hugging Face Space 環境下，波形圖更新速度提升約 3-5 倍，滑桿反應更流暢。

- **STA/LTA 計算結果智能快取**
  - 新增全域快取 `sta_lta_cache`，在選擇事件時儲存所有測站的 STA/LTA 計算結果（P 波到時與 characteristic function）。
  - **智能快取檢查**：在 `select_nearest_stations` 函數中，優先檢查快取是否存在，若存在則直接使用，避免重複計算。
  - 當使用者調整時間滑桿時，直接使用快取的 P 波到時資訊，避免重複計算 STA/LTA，大幅提升 UI 反應速度。
  - 快取結構：`{event_name: {station_code: {"p_arrival_time": float, "cft": array}}}`
  - **快取統計**：記錄快取命中率（cache hit/miss），方便除錯與效能分析。
  - P 波到時資訊已存於 `selected_stations` 並透過 `gr.State` 傳遞，無需每次從原始波形重新計算。

- **P 波自動偵測功能（STA/LTA）**
  - 新增 `detect_p_wave_sta_lta()` 函數，使用 STA/LTA (Short-Term Average / Long-Term Average) 演算法自動偵測 P 波到時。
  - 只有成功偵測到 P 波的測站才會被納入測站選擇與模型預測。
  - P 波到時記錄在測站資訊中 (`p_arrival_time`)，用於時間窗檢查。
  - 波形圖上標記 P 波位置：綠色三角形（時間窗內）、紅色三角形（時間窗外）。
  - 測試結果：在 50 個測站中達到 38% 偵測率（門檻 2.0）。
- **時間窗內 P 波驗證**
  - 波形提取階段檢查 P 波是否在選定時間窗內 `[0, end_time]`。
  - P 波不在時間窗內的測站會被跳過，避免模型收到空波形（完全為零）。
  - 記錄統計：P 波偵測成功/失敗/時間窗外的測站數量。

### Changed
- **測站選擇邏輯更新**
  - `select_nearest_stations()` 加入 P 波偵測步驟（使用 Z 分量）。
  - 只保留成功偵測到 P 波的測站，確保模型輸入有實際訊號。
  - 降級策略：無 Z 分量或 P 波偵測失敗 → 跳過測站（記錄 DEBUG）。
- **波形圖視覺化增強**
  - `plot_waveform()` 在距離-時間圖上標記 P 波到時。
  - 用顏色區分 P 波是否在時間窗內（綠色/紅色），提供視覺化回饋。
- **波形提取邏輯強化**
  - `extract_waveforms_from_stream()` 新增 P 波時間窗檢查。
  - 新增回傳值 `p_wave_outside_window_count` 用於統計與日誌。

### Improved
- 避免模型收到無意義的空波形（P 波未到達時的零值波形）。
- 提供清晰的視覺化回饋，讓使用者了解哪些測站有 P 波、哪些在時間窗內。
- 日誌訊息記錄 P 波偵測統計，方便除錯與分析。

### Technical Details
- STA/LTA 參數：`sta_len=0.5s`, `lta_len=10.0s`, `thr_on=2.0`, `thr_off=1.0`
- 相依套件：ObsPy (已在 requirements.txt)
- 程式碼語法驗證通過 ✅（只有類型提示警告，不影響執行）
- 測試腳本：`test_p_wave_detection.py`，驗證 P 波偵測功能正常運作
- 不變條件：維持 Z-N-E 分量順序、3000 samples @ 100 Hz、最多 25 站限制 ✅
- 詳細文檔：參見 `P_WAVE_DETECTION_SUMMARY.md`

---

### Added
- **MPS（Apple Metal Performance Shaders）推論後端**
  - 新增對 macOS Apple Silicon 上 PyTorch MPS 裝置的支援，可在 Apple M1/M2 系列上使用 GPU 加速推論。
  - 自動裝置選擇：優先選擇 `mps`（若可用），其次 `cuda`，最後降級到 `cpu`。
  - 支援透過環境變數 `TTSAM_DEVICE` 或設定覆寫裝置選擇（例如強制使用 `cpu`）。
  - 若 MPS 不可用或出現錯誤，會自動降級到可用的裝置並記錄 Warning（參照 `spec/03-error-handling.md` 的降級策略）。
- **相容性與說明**
  - 需要安裝具備 MPS 支援的 PyTorch 版本；若環境不支援，程式仍保持向後相容（不會改變公開 API）。

### Changed
- 自動裝置選擇與初始化邏輯新增日誌（INFO/WARNING），以便排查裝置選擇與降級原因。

### Improved
- 在 Apple Silicon（M1/M2）上進行推論時的效能相對於純 CPU 運算有明顯改善。
- 針對 MPS 裝置的錯誤與邊界情況加入更寬鬆的降級路徑，確保單點錯誤不會中止整個流程（遵循 spec/03-error-handling.md）。

### Technical Details
- 程式碼語法驗證通過 ✅（無 `SyntaxError`）。
- 冒煙測試：已在開發機（macOS Apple Silicon）執行初步冒煙測試並驗證主流程可執行（波形載入、推論、地圖生成）。
- 不變條件：本次變更為向後相容，未改變外部 API 或資料契約 ✅。

---

## [Sprint 003] — 震央資訊 JSON 管理化 (2025-10-26)

### Added
- **震央資訊集中管理**
  - 新增 `waveform/event.json` 檔案，集中管理地震事件的元資料（震央座標、深度、規模等）
  - `event_id` 採用 YYYYMMDD 格式，直接對應波形檔案 (`waveform/YYYYMMDD.mseed`) 與震度圖 (`intensity_map/YYYYMMDD.png`)
  - 支持向後擴展：新增地震事件只需修改 JSON 檔案，無需改動代碼

- **自動座標注入機制**
  - 新增 `load_earthquake_metadata()` 函數，應用啟動時自動從 JSON 載入地震事件元資料
  - 新增 `_get_epicenter_coords()` 輔助函數，自動從全域 `earthquake_metadata` 字典讀取座標
  - 完整的異常處理與降級策略：JSON 缺失或格式錯誤時，使用預設座標 (121.57, 23.88) 不中斷應用

- **Gradio 介面唯讀座標顯示**
  - 移除「震央經度」與「震央緯度」輸入框，使用者無法編輯座標
  - 新增唯讀文本框 `epicenter_info_display` 顯示當前事件的座標（例：「Latitude: 23.88 | Longitude: 121.57」）
  - 事件切換時自動更新座標顯示

### Changed
- **函數簽名重構**（移除 epicenter 參數，改由全域 JSON 提供）
  - `load_and_display_waveform(event_name, start_time, duration)` ← 原：`(..., epicenter_lon, epicenter_lat)`
  - `predict_intensity(event_name, start_time, duration)` ← 原：`(..., epicenter_lon, epicenter_lat)`
  - `on_event_change(event_name, start_time, duration)` ← 原：`(..., epicenter_lon, epicenter_lat)`
  - `on_full_workflow(event_name, start_time, duration)` ← 原：`(..., epicenter_lon, epicenter_lat)`

- **Callback 綁定邏輯優化**
  - `event_dropdown.change()` 新增 `epicenter_info_display` 輸出，事件切換時同步更新座標顯示
  - `demo.load()` 新增 `epicenter_info_display` 輸出，應用啟動時初始化座標顯示
  - 所有 callback 的 `inputs` 移除 `epicenter_lon_input` 與 `epicenter_lat_input` 參數

### Improved
- **資料管理**
  - 震央資訊不再硬編碼於代碼，改用 JSON 外部檔案管理，便於維護與擴展
  - UI 和資料解耦：Gradio 介面不再依賴手動輸入的座標值

- **向後相容性**
  - 若 `waveform/event.json` 缺失，應用自動降級至預設座標，正常啟動
  - 所有核心功能（波形、測站、推論、地圖）邏輯完全不變

### Technical Details
- **程式碼質量**：程式碼語法驗證通過 ✅ (no `SyntaxError`)
- **測試覆蓋**：冒煙測試全數通過 ✅
- **不變條件**：所有核心模組（波形輸入、測站選擇、推論引擎、資料契約）保持不變 ✅

---

## [Sprint 002] — 首次載入完整工作流優化 (2025-10-26)

### Added
- **首次載入自動完整工作流**
  - 應用啟動時自動執行完整工作流：波形載入 → 測站選擇 → 模型推論 → 地圖展示
  - 新增 `on_full_workflow()` 函數，整合波形與推論步驟，一次性返回所有 UI 組件結果
  - 首次打開應用時立即顯示完整的演示內容，無需用戶點擊任何按鈕
  
- **事件切換同步更新**
  - 修改 `event_dropdown.change` 事件綁定，改用 `on_full_workflow()` 完整工作流
  - 選擇不同地震事件時，所有視圖同步自動更新（波形、地圖、統計、實際觀測圖）

- **波形視圖專用回調**
  - 新增 `on_event_change()` 函數，支持用戶手動調整時間窗後重新載入波形視圖
  - 保留「載入波形」按鈕與「執行預測」按鈕的獨立操作選項

### Changed
- **Gradio 事件系統重構**
  - `demo.load` 從 `on_event_change` 改為 `on_full_workflow`，首次加載自動執行推論
  - `event_dropdown.change` 從 `on_event_change` 改為 `on_full_workflow`，事件切換自動推論

### Improved
- **使用者體驗**
  - 應用首次啟動時不再出現空白頁面，立即展示完整的互動式演示
  - 事件切換更加流暢，所有視圖實時同步，提升展示效果

---

## [Sprint 001] — 波形地圖自動載入 (2025-10-26)

### Added
- **UI 流程自動化**
  - 應用啟動時自動載入預設地震事件的波形地圖（測站分布 + 波形圖）
  - 地震事件切換時同步自動更新波形地圖與實際觀測圖
  - 新增 `on_event_change()` callback 協調多個 UI 組件的聯動更新
  - 新增 `demo.load` 事件綁定，實現應用啟動自動初始化

### Changed
- **規格理念調整**：從「穩定可靠系統」改為「互動式教育展示 Demo」
  - 強調預裝化設計：所有資源（模型、Vs30、波形、測站表）預裝於 HF Space，無需運行時下載
  - 容錯策略調整：預裝資源失敗中止啟動（提早發現問題），非關鍵資源失敗降級處理
  - 目標轉向展覽演示與教育體驗，而非生產級可靠性
  
- **規格檔案更新**
  - `00-overview.md`：新增「設計理念」章節，明確 Demo 定位與預裝策略
  - `01-data-contract.md`：新增預裝設計原則說明
  - `02-processing-rules.md`：新增設計原則概述
  - `03-error-handling.md`：完全重寫，移除網路容錯，強調預裝優先與降級策略
  - 快速參考表：補充「部署環境」與預裝相關備註
  
- **README.md 擴展**
  - 新增「設計思路」章節（500 字），解釋 Demo 定位、預裝架構、容錯策略
  - 新增「預裝架構表」，列舉所有預裝資源
  - 新增「展覽前檢查清單」，指導部署前驗證流程
  - 更新「快速參考」與「進一步閱讀」指向新的模塊化規格
  - 更新「專案結構」說明 spec 資料夾的模塊化檔案

- **Gradio 事件綁定優化**
  - `event_dropdown.change` 現使用 `on_event_change()` 而非 `on_event_select()`
  - 一次事件切換可同時更新波形地圖、波形圖、實際觀測圖

---

## [1.0.0] — 初版 (Initial Release)

### Added
- ✅ 完整的 Gradio GUI 介面
  - 事件選擇、時間窗選擇、震央座標輸入
  - 測站分布地圖、波形圖視覺化
  - 互動式震度預測地圖（Folium）
  - 實際觀測與預測對照
  
- ✅ 核心推論管道
  - 支援 CNN + Position Embedding + Transformer + MLP + MDN 架構
  - 自動距離排序，選擇最近 25 站
  - 批次推論（每批 25 目標點）
  - 條件處理與降級策略

- ✅ 穩健的資料處理
  - 固定 100 Hz 取樣率、30 秒時間窗（3000 samples）
  - 分量驗證與缺失降級（N/E 缺失以 Z 替代）
  - 訊號處理（去趨勢、10 Hz 低通濾波）
  - 補零對齊（不足 30 秒尾段補 0）

- ✅ 外部資源整合
  - Hugging Face 模型載入（`SeisBlue/TTSAM`）
  - Vs30 資料查詢（`SeisBlue/TaiwanVs30`）；失敗降級至預設 600 m/s
  - 本地 MSEED 波形讀取
  - 本地測站表讀取（CSV）

- ✅ 日誌與監控
  - loguru 日誌系統（INFO/WARNING/ERROR）
  - 關鍵節點記錄（啟動、選擇、推論、完成）
  - 降級決策透明化

- ✅ 測試資料
  - 範例事件：2024年4月3日花蓮地震 (`20240403.mseed`)
  - 範例目標點與測站表

### Known Limitations
- 模型輸入固定為 25 站、30 秒
- Vs30 查詢基於 2D 網格最近鄰法（不考慮深度）
- 不支援即時流模式（僅批次）
- 地圖高度固定 800px

### Notes for Future
- 見 `spec/04-extensions.md` 的擴充建議
- 見 `spec/plan.md` 的迭代計畫範本

---

## 版本說明

| 版本 | 發行日期 | 重點 |
|-----|--------|------|
| v1.0.0 | 2024年 | 初版發佈 |
| (未來) | (待定) | 功能擴展 |

---

## 貢獻指南

提交變更前，請：
1. 查閱 `.github/copilot-instructions.md` 開發指南
2. 確認相應 spec 檔案已同步（若涉及資料契約、處理規則、故障場景）
3. 更新本 changelog（`## [Unreleased]` 段落）
4. 執行測試確保無新增 ERROR 日誌

---

## 許可證

GPL-3.0

---

**最後更新**：2024 年 10 月 26 日