docs: refactor waveform loading and processing steps for improved caching and error handling

app.py

@@ -806,112 +806,116 @@ def load_observed_intensity_image(event_name):
     return None
 
 
-def load_and_display_waveform(event_name, duration):
-    """載入並顯示波形，讓使用者確認範圍
-
-    從全域 earthquake_metadata 讀取震央座標
+# ============ 步驟 1：載入 mseed + 選擇測站（快取到 gr.State）============
+def step1_load_mseed_and_select_stations(event_name):
+    """
+    步驟 1：載入 mseed 檔案並選擇最近的 25 個測站
 
-    spec #2：測站選擇上限 (25 站)、波形取樣率 (100 Hz)、時間窗長度 (30 秒)
+    這一步只執行一次（切換事件時），結果會快取在 gr.State 中
     """
     try:
-        # 從全域 earthquake_metadata 讀取震央座標
         epicenter_lat = earthquake_metadata[event_name]["epicenter_lat"]
         epicenter_lon = earthquake_metadata[event_name]["epicenter_lon"]
         mseed_file = earthquake_metadata[event_name]["mseed_file"]
-        first_pick = earthquake_metadata[event_name]["first_pick"]
-
-        # 計算結束時間（用於顯示資訊）
 
-
-        # 1. 載入完整的 mseed 檔案
-        logger.info(f"載入地震事件: {event_name}")
+        logger.info(f"[步驟 1] 載入地震事件: {event_name}")
         st = read(mseed_file)
         logger.info(f"載入了 {len(st)} 個 trace")
 
-        # 2. 根據震央距離選擇最近的 25 個測站
+        # 選擇距離震央最近的 25 個測站
         logger.info(f"選擇距離震央 ({epicenter_lat}, {epicenter_lon}) 最近的測站...")
         selected_stations = select_nearest_stations(
             st, epicenter_lat, epicenter_lon, n_stations=25
         )
 
         if len(selected_stations) == 0:
-            return (
-                None,
-                None,
-                "錯誤：找不到有效的測站資料",
-                gr.update(interactive=False),
-            )
-
-        waveform_plot = plot_waveform(st, selected_stations, first_pick, duration)
+            logger.error("找不到有效的測站資料")
+            return None, None, None, None, gr.update(interactive=False)
 
-        # 4. 創建輸入測站地圖
+        # 創建輸入測站地圖
         station_map = create_input_station_map(
             selected_stations, epicenter_lat, epicenter_lon
         )
 
-        logger.info("波形載入完成")
-        return station_map, waveform_plot, gr.update(interactive=True)
+        logger.info("[步驟 1] 完成 - mseed 已載入，測站已選擇")
+        return st, selected_stations, station_map, None, gr.update(interactive=False)
 
     except Exception as e:
-        logger.error(f"波形載入發生錯誤: {e}")
+        logger.error(f"[步驟 1] 發生錯誤: {e}")
         import traceback
-
         traceback.print_exc()
-        return None, None, gr.update(interactive=False)
+        return None, None, None, None, gr.update(interactive=False)
 
 
-def predict_intensity(event_name, duration):
+# ============ 步驟 2：提取波形（使用快取的 stream + stations）============
+def step2_extract_and_plot_waveforms(cached_stream, cached_stations, event_name, duration):
     """
-    執行震度預測
-
-    介面改以 start+duration，使用固定高度 800 的地圖輸出
-    從全域 earthquake_metadata 讀取震央座標
+    步驟 2：根據時間範圍提取波形並繪圖
 
-    spec #2：測站選擇上限 (25 站)、波形取樣率 (100 Hz)、時間窗長度 (30 秒)
-    spec #3：推論流程、PGA → 震度轉換
+    使用快取的 stream 和 selected_stations，避免重複讀檔
+    用戶調整時間範圍時會重複執行此步驟
     """
     try:
-        # 從全域 earthquake_metadata 讀取震央座標
-        epicenter_lat = earthquake_metadata[event_name]["epicenter_lat"]
-        epicenter_lon = earthquake_metadata[event_name]["epicenter_lon"]
-        mseed_file = earthquake_metadata[event_name]["mseed_file"]
-
-
-        # 1. 載入完整的 mseed 檔案
-        logger.info(f"載入地震事件: {event_name}")
-        st = read(mseed_file)
-        logger.info(f"載入了 {len(st)} 個 trace")
+        if cached_stream is None or cached_stations is None:
+            logger.warning("[步驟 2] 快取資料不存在，請先載入波形")
+            return None, None, None, gr.update(interactive=False)
 
-        # 2. 根據震央距離選擇最近的 25 個測站
-        logger.info(f"選擇距離震央 ({epicenter_lat}, {epicenter_lon}) 最近的測站...")
-        selected_stations = select_nearest_stations(
-            st, epicenter_lat, epicenter_lon, n_stations=25
-        )
+        first_pick = earthquake_metadata[event_name]["first_pick"]
 
-        if len(selected_stations) == 0:
-            return None, None, "錯誤：找不到有效的測站資料"
+        logger.info(f"[步驟 2] 提取波形資料（P 波後 {duration} 秒）...")
 
-        # 3. 從選定的測站提取波形（vs30_input 使用預設值 600，會被資料庫值覆蓋）
-        logger.info(
-            f"提取波形資料（時間範圍: 初動��� {duration} 秒）..."
-        )
+        # 提取波形資料
         waveforms, station_info_list, valid_stations, missing_components_count = (
             extract_waveforms_from_stream(
-                event_name, st, selected_stations, duration, vs30_input=600
+                event_name, cached_stream, cached_stations, duration, vs30_input=600
             )
         )
 
         if len(waveforms) == 0:
-            return None, "錯誤：無法提取波形資料"
+            logger.error("[步驟 2] 無法提取波形資料")
+            return None, None, None, gr.update(interactive=False)
+
+        # 繪製波形圖
+        waveform_plot = plot_waveform(cached_stream, cached_stations, first_pick, duration)
+
+        logger.info(f"[步驟 2] 完成 - 已提取 {len(waveforms)} 個測站的波形")
+        return waveforms, station_info_list, waveform_plot, gr.update(interactive=True)
+
+    except Exception as e:
+        logger.error(f"[步驟 2] 發生錯誤: {e}")
+        import traceback
+        traceback.print_exc()
+        return None, None, None, gr.update(interactive=False)
+
+
+# ============ 步驟 3：執行模型推論（使用快取的波形）============
+def step3_predict_intensity(cached_waveforms, cached_station_info, event_name):
+    """
+    步驟 3：執行震度預測
+
+    直接使用快取的波形資料和測站資訊，無需重新讀檔或提取波形
 
-        # 4. Padding 到 25 個測站（模型要求）
+    spec #2：測站選擇上限 (25 站)、波形取樣率 (100 Hz)、時間窗長度 (30 秒)
+    spec #3：推論流程、PGA → 震度轉換
+    """
+    try:
+        if cached_waveforms is None or cached_station_info is None:
+            logger.warning("[步驟 3] 快取資料不存在，請先載入並提取波形")
+            return None, None
+
+        epicenter_lat = earthquake_metadata[event_name]["epicenter_lat"]
+        epicenter_lon = earthquake_metadata[event_name]["epicenter_lon"]
+
+        logger.info("[步驟 3] 開始模型推論...")
+
+        # Padding 到 25 個測站（模型要求）
         max_stations = 25
         waveform_padded = np.zeros((max_stations, 3000, 3))
         station_info_padded = np.zeros((max_stations, 4))
 
-        for i in range(min(len(waveforms), max_stations)):
-            waveform_padded[i] = waveforms[i]
-            station_info_padded[i] = station_info_list[i]
+        for i in range(min(len(cached_waveforms), max_stations)):
+            waveform_padded[i] = cached_waveforms[i]
+            station_info_padded[i] = cached_station_info[i]
 
         # 準備所有目標測站資訊（分批處理）
         all_pga_list = []
@@ -956,14 +960,14 @@ def predict_intensity(event_name, duration):
             for i in range(len(target_list)):
                 target_padded[i] = target_list[i]
 
-            # 6. 組合成 torch tensor
+            # 組合成 torch tensor
             tensor_data = {
                 "waveform": torch.tensor(waveform_padded).unsqueeze(0).double(),
                 "station": torch.tensor(station_info_padded).unsqueeze(0).double(),
                 "target": torch.tensor(target_padded).unsqueeze(0).double(),
             }
 
-            # 7. 執行預測
+            # 執行預測
             with torch.no_grad():
                 weight, sigma, mu = model(tensor_data)
                 batch_pga = (
@@ -988,65 +992,20 @@ def predict_intensity(event_name, duration):
             pga_list, target_names, epicenter_lat, epicenter_lon
         )
 
-        # 載入實際觀測震度圖（filepath；左側以 800 高顯示）
+        # 載入實際觀測震度圖
         observed_intensity_path = load_observed_intensity_image(event_name)
 
-        logger.info("預測完成！")
+        logger.info("[步驟 3] 預測完成！")
         return observed_intensity_path, intensity_map
 
     except Exception as e:
-        logger.error(f"預測過程發生錯誤: {e}")
+        logger.error(f"[步驟 3] 發生錯誤: {e}")
         import traceback
 
         traceback.print_exc()
         return None, None
 
 
-def on_full_workflow(event_name,  duration):
-    """
-    執行完整的工作流：波形載入 → 測站選擇 → 推論 → 結果展示
-
-    此函數用於首次應用加載與事件切換時自動執行完整流程
-
-    返回所有必要的 UI 組件輸出：
-    (station_map, waveform_plot, predicted_map, observed_img)
-
-    spec #2：測站選擇上限 (25 站)、波形取樣率 (100 Hz)、時間窗長度 (30 秒)
-    spec #3：推論流程、PGA → 震度轉換
-    """
-    try:
-        logger.info(f"[on_full_workflow] 開始執行完整工作流 - 事件: {event_name}")
-
-        # 步驟 1: 載入波形
-        logger.info(f"[on_full_workflow] 步驟 1/3: 波形載入...")
-        station_map, waveform_plot, _ = load_and_display_waveform(
-            event_name, duration
-        )
-
-        if station_map is None:
-            logger.error("[on_full_workflow] 波形載入失敗")
-            return None, None, None, None
-
-        # ��驟 2: 執行推論
-        logger.info(f"[on_full_workflow] 步驟 2/3: 模型推論...")
-        observed_img, predicted_map = predict_intensity(
-            event_name, duration
-        )
-
-        if predicted_map is None:
-            logger.error("[on_full_workflow] 推論失敗")
-            return station_map, waveform_plot, None, observed_img
-
-        logger.info(f"[on_full_workflow] 步驟 3/3: 完成")
-
-        return station_map, waveform_plot, predicted_map, observed_img
-
-    except Exception as e:
-        logger.error(f"[on_full_workflow] 完整工作流發生錯誤: {e}")
-        import traceback
-
-        traceback.print_exc()
-        return None, None, f"錯誤: {str(e)}", None, f"錯誤: {str(e)}", None
 
 # ============ Gradio 介面 ============
 with gr.Blocks(title="TTSAM 震度預測系統", fill_height=True) as demo:
@@ -1059,12 +1018,11 @@ with gr.Blocks(title="TTSAM 震度預測系統", fill_height=True) as demo:
             gr.Markdown("## 使用步驟")
             gr.Markdown(
                 """
-                1. 選擇地震事件和時間範圍
-                2. 輸入震央位置和場址參數
-                3. 點擊載入波形確認波形範圍
-                4. 確認無誤後點擊執行預測
+                1. 選擇地震事件（自動載入測站）
+                2. 調整 P 波後時間範圍（即時更新波形）
+                3. 點擊「執行預測」查看震度分布
                 
-                系統會自動選擇距離震央最近的 25 個測站
+                系統會自動選擇距離震央最近的 25 個測站，並快取資料避免重複讀檔。
             """
             )
         with gr.Column(scale=1):
@@ -1112,44 +1070,59 @@ with gr.Blocks(title="TTSAM 震度預測系統", fill_height=True) as demo:
                 value=load_observed_intensity_image(list(earthquake_metadata.keys())[0]),
             )
 
-    # 綁定事件
+    # ========== 隱藏的 State 變數（用於快取中間結果）==========
+    cached_stream = gr.State(None)          # ObsPy Stream object
+    cached_stations = gr.State(None)        # 選中的 25 個測站列表
+    cached_waveforms = gr.State(None)       # 提取的波形資料
+    cached_station_info = gr.State(None)    # 測站資訊列表
+
+    # ========== 事件綁定（使用鏈式觸發 + gr.State 快取）==========
+
+    # 【觸發點 1】事件切換：重新執行步驟 1 → 步驟 2
     event_dropdown.change(
-        fn=lambda event_name,  duration: (
-            *on_full_workflow(event_name,  duration),
-        ),
-        inputs=[event_dropdown, duration_slider],
-        outputs=[
-            input_station_map,
-            waveform_plot,
-            predicted_intensity_map,
-            observed_intensity_image,
-        ],
+        fn=step1_load_mseed_and_select_stations,
+        inputs=[event_dropdown],
+        outputs=[cached_stream, cached_stations, input_station_map, waveform_plot, predict_btn]
+    ).then(  # 鏈式觸發步驟 2
+        fn=step2_extract_and_plot_waveforms,
+        inputs=[cached_stream, cached_stations, event_dropdown, duration_slider],
+        outputs=[cached_waveforms, cached_station_info, waveform_plot, predict_btn]
+    )
+
+    # 【觸發點 2】時間範圍調整：只重新執行步驟 2（快速，不重新讀檔）
+    duration_slider.change(
+        fn=step2_extract_and_plot_waveforms,
+        inputs=[cached_stream, cached_stations, event_dropdown, duration_slider],
+        outputs=[cached_waveforms, cached_station_info, waveform_plot, predict_btn]
     )
 
+    # 【觸發點 3】載入波形按鈕：手動觸發步驟 1 → 步驟 2
     load_waveform_btn.click(
-        fn=load_and_display_waveform,
-        inputs=[event_dropdown, duration_slider],
-        outputs=[input_station_map, waveform_plot, predict_btn],
+        fn=step1_load_mseed_and_select_stations,
+        inputs=[event_dropdown],
+        outputs=[cached_stream, cached_stations, input_station_map, waveform_plot, predict_btn]
+    ).then(
+        fn=step2_extract_and_plot_waveforms,
+        inputs=[cached_stream, cached_stations, event_dropdown, duration_slider],
+        outputs=[cached_waveforms, cached_station_info, waveform_plot, predict_btn]
     )
 
+    # 【觸發點 4】執行預測：使用快取的波形執行步驟 3
     predict_btn.click(
-        fn=predict_intensity,
-        inputs=[event_dropdown, duration_slider],
-        outputs=[observed_intensity_image, predicted_intensity_map],
+        fn=step3_predict_intensity,
+        inputs=[cached_waveforms, cached_station_info, event_dropdown],
+        outputs=[observed_intensity_image, predicted_intensity_map]
     )
 
-    # 應用啟動時自動執行完整工作流
+    # 【冷啟動】應用載入時自動執行步驟 1 → 步驟 2
     demo.load(
-        fn=lambda event_name, duration: (
-            *on_full_workflow(event_name, duration),
-        ),
-        inputs=[event_dropdown, duration_slider],
-        outputs=[
-            input_station_map,
-            waveform_plot,
-            predicted_intensity_map,
-            observed_intensity_image,
-        ],
+        fn=step1_load_mseed_and_select_stations,
+        inputs=[event_dropdown],
+        outputs=[cached_stream, cached_stations, input_station_map, waveform_plot, predict_btn]
+    ).then(
+        fn=step2_extract_and_plot_waveforms,
+        inputs=[cached_stream, cached_stations, event_dropdown, duration_slider],
+        outputs=[cached_waveforms, cached_station_info, waveform_plot, predict_btn]
     )
 
 demo.launch()