| name | gempy-3x |
| description | GemPy 3.x 三維地質建模與石門聯通管多參數分析專案（D:\gempy）的完整工作規範。 只要使用者提到 GemPy、gempy_engine、gempy_viewer、隱式地質建模、位勢場插值、 地質模型、surface points / orientations CSV、lith_block、地質網格匯出（STL/PLY）、 D:\gempy 底下任何檔案、m1/m4 等模型代號、多參數分析、地質不確定性、realizations、 地層位態（orientation/dip/azimuth）計算、V 字法則、三點法、QGIS 前處理， 或要新增/修改/批次執行建模 notebook，都必須使用本 skill——即使使用者沒有明講 「GemPy」三個字（例如只說「幫我加一組模型」「改剖面」「算位態」）。 嚴禁憑記憶臆造 GemPy API：一律以本 skill 的 references 與官方文件為準。 |
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。
常見任務入口
執行與驗證習慣
- 跑 notebook 用 jupyter 執行或請使用者在 VS Code 執行；改完 cell 後至少驗證
JSON 結構有效、路徑存在、無殘留舊路徑（可用 python -c 快速檢查）。
- GemPy 模型每次重大修改後要能重新 compute 出結果才算完成（Step 7 成功 +
Step 8 有圖），不要只改完程式碼就宣告完工。
- 產出檔案後回報實際路徑與筆數/尺寸，讓使用者能快速抽查。
