r14521128 GemPy 3.x 建模與石門多參數分析
本 skill 服務兩件事：(1) 正確使用 GemPy 3.x API；(2) 遵守 D:\gempy 石門聯通管 多參數分析專案的架構規範。兩者綁在一起，因為此專案所有 GemPy 工作都發生在同一套 資料夾架構與 notebook 流程模板上，改錯一個路徑或參數就會汙染整個機率統計分析。
核心原則
- 禁止臆造 API。GemPy 3.x 改版幅度大，網路上大量教學是 v1/v2 語法（Theano 時代）， 直接照抄會壞。寫任何 GemPy 程式碼前，先確認該用法出現在 references/gempy3-api.md（來自實際跑通的 notebook） 或官方文件 docs.gempy.org。不確定就明講不確定，並提供查證方式。
- 繁體中文：所有註解與說明用繁體中文（專案硬性規定）。
- 外科手術式修改：只動使用者要求的部分。notebook 的其他 cell、變數命名
（
geo_model、auto_extent、_INPUT/_OUTPUT等）保持原樣。 - 每一步都要有可驗證輸出：印出摘要、畫圖或存檔。這是專案 CLAUDE.md 的要求， 也是 notebook 模板每個 Step 都有 print 檢查的原因。
- 凍結參數勿動：
SHIFT_X = 270000、SHIFT_Y = 2740000（TWD97→局部座標平移量） 與MANUAL_EXTENT = [800, 4800, 3500, 6500, 0, 1000]是全專案統一基準， 改了會讓不同模型的成果無法疊合比較。除非使用者明確要求，否則不得修改。 - 模型參數或地質假設有疑義時先問：擾動哪個參數、用什麼分布、內插設定等 屬於地質判斷，不要替使用者默默決定。
專案架構速覽
D:\gempy\
├── input\ 共用輸入（唯一資料來源）：dem\20m_dem.tif、surface\、borehole\、
│ assumption\（m4 輸入）、fault\（預留，空）、tunnel\（預留，空）
├── code\ 建模 notebook：m1_surf_only.ipynb、m4_faultdip.ipynb、
│ Investigates_QGIS_to_gempy .ipynb（位態計算前處理，檔名含空格）
├── output\mX\ 各模型計算輸出（剖面圖、lith_block、平移後 DEM）
├── mesh\mX\ 各模型 STL/PLY 網格（供 FLAC3D/3DEC 使用）
├── compare\ 模型比較 ├── concept\ 概念模型 ├── database\ 資料前處理
└── AI_Agent\ AI 協作資料（本 skill 的同步副本在 AI_Agent\skill\）
鐵則：**輸入只從 input\ 讀，輸出只寫進自己模型代號的 output\mX\ 與 mesh\mX\**。
notebook 內只有兩處路徑設定：Step 1 的 _INPUT/_OUTPUT 與 Step 9 的
mesh_output_dir。新增模型時就只改這兩處加上輸入檔名。
⚠️ 資料血緣（詳見 references/project-structure.md；
2026-07-09 重整後）：assumption\ 是 **m4 的計算輸入**（309 點 = 鑽孔 303 + 6 個
深部假設控制點）；orientations 為遞增鏈 surface(18) ⊂ borehole(20) ⊂ assumption(26)，
同位置參數一致；fault\ 與 tunnel\ 為空的預留資料夾。擾動或修改輸入資料前，
先跑 code\input_inventory.py 確認現況，改完再跑一次留下變更記錄。
建模流程模板（Step 0～10）
所有模型 notebook 共用同一套流程，m1 與 m4 只差輸入檔與少數 cell：
| Step | 內容 | 關鍵輸出 |
|---|---|---|
| 0 | 匯入套件（gempy、gempy_viewer、pyvista、rasterio） | GemPy 版本號 |
| 1 | 路徑設定 _INPUT/_OUTPUT + 檔案存在檢查 |
✅/⚠️ 檔案清單 |
| 2 | 讀 CSV + 欄位驗證 + 地層名稱交叉比對 | 筆數、地層種類 |
| 3 | 座標平移（SHIFT_X/Y）+ DEM 仿射平移 + MANUAL_EXTENT | dem_cropped_local.tif |
| 4 | gp.create_geomodel(...) 初始化 |
解析度、網格尺寸 |
| 5 | 地層堆疊 map_stack_to_surfaces + ERODE/ONLAP + 顏色 |
structural_frame 表 |
| 6 | gp.set_topography_from_file(...) 套地形 |
DEM 驗證訊息 |
| 7 | 自訂剖面 set_section_grid + gp.compute_model |
_MODEL_COMPUTED |
| 7.5 | lith_block 匯出（npy + csv + ID 對照表） | lith_block_3d.npy |
| 8A/8B | 2D 剖面視覺化（俯視圖、X/Y 剖面、自訂剖面） | PNG 圖組 |
| 9 | 網格匯出：STL（原始）+ PLY（地表裁切+精簡）+ CSV | mesh\mX\*.stl/.ply |
| 10 | 互動式 3D（gpv.plot_3d，預設註解掉） |
— |
每個 Step 的細節、常見錯誤與陷阱（例如 lith_block 的 C/F order 轉換、
cropped_dem_path 其實是「平移」不是「裁切」）見
references/workflow.md。
常見任務入口
- 新增一組模型（含 realizations） → 讀 references/multiparam.md 的命名規範與 checklist，再複製最接近的基準 notebook 修改。
- 寫或改 GemPy 程式碼 → 先讀 references/gempy3-api.md 確認 API 簽名與已驗證用法。
- 動輸入資料 / 找檔案 / 理解資料來源 → 讀 references/project-structure.md（含 QGIS 前處理脈絡與 MD5 資料血緣表）。
- 計算或討論地層位態（orientations）、V 字法則、三點法、凹口選點 → 讀 references/vnotch-orientation.md。此專案的 orientations 不是拿整組露頭點 PCA 出來的——那樣會偏差；正規流程是 V 字三點法。
- 除錯 notebook → 讀 references/workflow.md 對應 Step 的 常見錯誤段落。
- 論文寫作引用 / 理論問題 → 讀 references/theory-references.md（引用鏈、完整書目、 不可引用的資料警告）。
執行與驗證習慣
- 跑 notebook 用 jupyter 執行或請使用者在 VS Code 執行；改完 cell 後至少驗證 JSON 結構有效、路徑存在、無殘留舊路徑（可用 python -c 快速檢查）。
- GemPy 模型每次重大修改後要能重新 compute 出結果才算完成（Step 7 成功 + Step 8 有圖），不要只改完程式碼就宣告完工。
- 產出檔案後回報實際路徑與筆數/尺寸，讓使用者能快速抽查。