README.md

metadata

title: TTSAM
emoji: 🏢
colorFrom: blue
colorTo: gray
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: gpl-3.0

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

專案簡介

TTSAM（Taiwan Transformer-based Shake Alert Model）是一個以 Transformer 為核心的地震預警/震度推估原型，提供互動式 GUI 用於載入歷史事件、查看波形、並在地圖上比對「預測震度」與「實際震度」。

主要功能

• 互動式 GUI（app.py）：
  • 選擇歷史事件、時間窗、震央座標並載入波形。
  • 顯示輸入測站分布與波形（按震央距離排序）。
  • 執行模型推論並在 Folium 地圖上顯示預測震度（高度固定 800px）。
  • 若有實際震度圖，支援與預測對照；若缺失則以空白占位並提示。
• 穩健的資料處理：
  • 取樣率固定 100 Hz；模型輸入固定 30 秒（不足補 0）。
  • 輸入測站最多 25 站；不足仍可推論並在 UI 顯示警告。
  • N/E 分量缺失時以 Z 替代，並統計缺分站數於摘要。
• 目標點批次推論：
  • 目標測站每批最多 25 點，最後合併結果。
• 場址參數與降級：
  • Vs30 以 SeisBlue/TaiwanVs30 下載為主；查詢/下載失敗時使用預設值 600 m/s 並記錄 log。
• 易於擴充：
  • 不需改模型與核心流程即可新增事件與目標測站（更新資料檔即可）。

快速開始

需求

• Python 3.10–3.11（建議）
• 主要套件見 requirements.txt

安裝與執行

• 安裝相依套件
  • pip install -r requirements.txt
• 執行 GUI
  • python app.py
  • 或使用腳本：./run_local.sh

資料與資源

• 事件波形：waveform/*.mseed
• 實際震度圖（選用）：intensity_map/YYYYMMDD.png
• 站台資料：station/site_info.csv, station/eew_target.csv

常見任務

• 新增事件：
  • 將 .mseed 放入 waveform/，並更新 app.py 的 EARTHQUAKE_EVENTS。
  • 若有實際震度圖，放入 intensity_map/，檔名 YYYYMMDD.png。
• 新增目標測站：
  • 於 station/eew_target.csv 增補列，欄位：station, latitude, longitude, elevation。
• 新增輸入測站：
  • 於 station/site_info.csv 增補列，欄位：Station, Latitude, Longitude, Elevation；去除重複站名列。

規格不變條件（摘要）

• 取樣率：100 Hz；輸入長度：30 秒（3000 點，不足補 0）。
• 輸入測站：最多 25；不足允許，需在 UI 顯示警告。
• 缺分量：N/E 缺失以 Z 替代並統計。
• 目標批次：每批最多 25，合併全部結果。
• 地圖高度：Folium 地圖固定 800px；實際震度圖缺失以占位。
• Vs30：優先使用 SeisBlue/TaiwanVs30；失敗則使用預設 600 m/s 並記錄 log。

完整細節請參考 docs/spec.md。

專案結構

• app.py：Gradio GUI 與推論主流程
• ttsam_realtime.py：即時流程樣板（非 GUI 主流程）
• station/site_info.csv：輸入測站表
• station/eew_target.csv：目標測站表
• waveform/：事件波形（.mseed）
• intensity_map/：實際震度圖（可選）
• docs/spec.md：規格與設計說明（契約）
• .github/copilot-instructions.md：生成程式碼指南
• docs/task.md：目前進行中的任務拆解（完成後可重置）
• change-log.md：每次變更的高層摘要
• docs/task-template.md：任務模板（重建 docs/task.md 時使用）

疑難排解（Troubleshooting）

• Vs30 下載失敗或查無資料
  • 行為：使用預設值 600 m/s；log 會有 WARNING 訊息。
  • 檢查網路或稍後再試；必要時在 UI/設定中調整預設值。
• 實際震度圖缺失
  • 行為：左側顯示空白占位與提示；不影響預測地圖。
• 少於 25 個輸入測站
  • 行為：UI 顯示警告，仍可推論。
• 缺少 N/E 分量
  • 行為：以 Z 分量代替並在摘要統計。

授權

• License：GPL-3.0

進一步閱讀

• docs/spec.md（契約與不變條件）
• .github/copilot-instructions.md（開發與貢獻指南）
• change-log.md（歷次變更摘要）