README.md

---
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`（歷次變更摘要）