Hugging Face's logo

Spaces:
SeisBlue
/
TTSAM
Running

App Files Community
3
TTSAM / changelog.md
jimmy60504's picture
jimmy60504
feat: optimize waveform rendering performance for Hugging Face Space with downsampling and WebGL
2fc487d
preview code
|
raw
history blame contribute delete
13.1 kB

A newer version of the Gradio SDK is available: 6.3.0

Upgrade

變更日誌 (Changelog)

記錄專案的重大變更、新功能與修復。採用 Keep a Changelog 格式。

[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 日