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。
• 易於擴充：
  • 不需改模型與核心流程即可新增事件與目標測站（更新資料檔即可）。

設計思路

🎯 Project Scope: 互動式教育展示 Demo

本專案為地震模型的 展覽演示系統，而非生產級的早期預警系統。因此設計理念強調：

• 互動性優先：使用者操作立即反饋視覺化結果（波形圖、地圖、統計）
• 教育性為中心：清晰的介面與步驟引導，讓非地震專業人士理解「波形 → 模型 → 預測」的流程
• 功能簡潔化：無需追求完整覆蓋或極限性能；易於操作與理解最重要
• 預裝化設計：所有關鍵資源（模型權重、Vs30 資料庫、波形、測站表）預裝於 HF Space，無需運行時下載或外部依賴

📦 預裝架構

資源	位置	用途	預裝狀態
模型權重	ttsam_trained_model_11.pt	推論核心	✅ 預裝
Vs30 資料庫	Vs30ofTaiwan.nc	場址參數	✅ 預裝
波形資料	waveform/*.mseed	輸入資料	✅ 預裝（≥2 事件）
測站表	station/site_info.csv, station/eew_target.csv	元資料	✅ 預裝
實際震度圖	intensity_map/YYYYMMDD.png	對照參考	✅ 預裝（可選）

🛡️ 容錯設計

系統採用「預裝優先，降級不中斷」的容錯策略：

• 預裝資源失敗（模型損毀、測站表缺失）→ 應用無法啟動（提前發現問題）
• 非關鍵資源失敗（Vs30 初始化失敗、實際圖缺失）→ 使用預設值或占位，應用正常運作
• 單點資料缺失（缺分量、測站不足）→ 使用替代值或降級處理，UI 明示警告，推論繼續
• 結果異常（PGA 為 NaN）→ 記錄日誌，仍顯示於地圖

詳見 spec/03-error-handling.md。

🧪 展覽前檢查清單

在部署至 HF Space 前：

• 驗證所有預裝檔案完整（模型、Vs30、波形、測站表）
• 本地測試啟動流程（無外部網路依賴）
• 測試各事件的波形載入與預測
• 確認實際震度圖路徑與檔名正確
• 檢查日誌輸出（無錯誤訊息）

需求

• 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）
• 分量順序：Z, N, E；N/E 缺失時以 Z 代替

測站處理：

• 輸入測站：最多 25；不足允許但 UI 會顯示警告
• 目標測站批次：每批最多 25 點
• 缺分量統計：計數並在摘要中顯示

資源管理：

• 地圖高度：Folium 地圖固定 800px
• 實際震度圖缺失：以空白占位（不中止）
• Vs30 查詢失敗：使用預設值 600 m/s

詳細規格：見 spec/00-overview.md 與 spec/01-data-contract.md；容錯與降級決策見 spec/03-error-handling.md。

專案結構

• app.py：Gradio GUI 與推論主流程
• ttsam_realtime.py：即時流程樣板（非 GUI 主流程）
• station/site_info.csv：輸入測站表
• station/eew_target.csv：目標測站表
• waveform/：事件波形（.mseed）
• intensity_map/：實際震度圖（可選）
• spec/：模塊化規格檔案
  • 00-overview.md：核心目標、架構、設計原則
  • 01-data-contract.md：資料結構、必填欄位
  • 02-processing-rules.md：批次策略、處理規則
  • 03-error-handling.md：故障場景、容錯設計
  • 04-extensions.md：擴充空間、向後相容
• .github/copilot-instructions.md：生成程式碼指南
• changelog.md：變更摘要

疑難排解（Troubleshooting）

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

授權

• License：GPL-3.0

進一步閱讀

• spec/00-overview.md（核心目標、架構、不變條件）
• spec/01-data-contract.md（資料結構、必填欄位、冷啟動流程）
• spec/02-processing-rules.md（批次策略、輸入限制、資源限制）
• spec/03-error-handling.md（故障場景、降級策略、UI 訊息設計）
• spec/04-extensions.md（擴充空間、向後相容性）
• .github/copilot-instructions.md（開發與貢獻指南）
• changelog.md（歷次變更摘要）