# Gempy 3x

> 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 與官方文件為準。

- Skill: `r14521128/gempy-3x-2` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add r14521128/gempy-3x-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/r14521128/gempy-3x-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: r14521128 (https://skillmd.com/u/r14521128)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/r14521128/gempy-3x-2

---


# GemPy 3.x 建模與石門多參數分析

本 skill 服務兩件事：(1) 正確使用 GemPy 3.x API；(2) 遵守 D:\gempy 石門聯通管
多參數分析專案的架構規範。兩者綁在一起，因為此專案所有 GemPy 工作都發生在同一套
資料夾架構與 notebook 流程模板上，改錯一個路徑或參數就會汙染整個機率統計分析。

## 核心原則

1. **禁止臆造 API**。GemPy 3.x 改版幅度大，網路上大量教學是 v1/v2 語法（Theano 時代），
   直接照抄會壞。寫任何 GemPy 程式碼前，先確認該用法出現在
   [references/gempy3-api.md](references/gempy3-api.md)（來自實際跑通的 notebook）
   或官方文件 docs.gempy.org。不確定就明講不確定，並提供查證方式。
2. **繁體中文**：所有註解與說明用繁體中文（專案硬性規定）。
3. **外科手術式修改**：只動使用者要求的部分。notebook 的其他 cell、變數命名
   （`geo_model`、`auto_extent`、`_INPUT`/`_OUTPUT` 等）保持原樣。
4. **每一步都要有可驗證輸出**：印出摘要、畫圖或存檔。這是專案 CLAUDE.md 的要求，
   也是 notebook 模板每個 Step 都有 print 檢查的原因。
5. **凍結參數勿動**：`SHIFT_X = 270000`、`SHIFT_Y = 2740000`（TWD97→局部座標平移量）
   與 `MANUAL_EXTENT = [800, 4800, 3500, 6500, 0, 1000]` 是全專案統一基準，
   改了會讓不同模型的成果無法疊合比較。除非使用者明確要求，否則不得修改。
6. **模型參數或地質假設有疑義時先問**：擾動哪個參數、用什麼分布、內插設定等
   屬於地質判斷，不要替使用者默默決定。

## 專案架構速覽

```
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](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](references/workflow.md)。

## 常見任務入口

- **新增一組模型（含 realizations）** → 讀 [references/multiparam.md](references/multiparam.md)
  的命名規範與 checklist，再複製最接近的基準 notebook 修改。
- **寫或改 GemPy 程式碼** → 先讀 [references/gempy3-api.md](references/gempy3-api.md)
  確認 API 簽名與已驗證用法。
- **動輸入資料 / 找檔案 / 理解資料來源** → 讀
  [references/project-structure.md](references/project-structure.md)（含 QGIS 前處理脈絡與
  MD5 資料血緣表）。
- **計算或討論地層位態（orientations）、V 字法則、三點法、凹口選點** → 讀
  [references/vnotch-orientation.md](references/vnotch-orientation.md)。此專案的
  orientations 不是拿整組露頭點 PCA 出來的——那樣會偏差；正規流程是 V 字三點法。
- **除錯 notebook** → 讀 [references/workflow.md](references/workflow.md) 對應 Step 的
  常見錯誤段落。
- **論文寫作引用 / 理論問題** → 讀
  [references/theory-references.md](references/theory-references.md)（引用鏈、完整書目、
  不可引用的資料警告）。

## 執行與驗證習慣

- 跑 notebook 用 jupyter 執行或請使用者在 VS Code 執行；改完 cell 後至少驗證
  JSON 結構有效、路徑存在、無殘留舊路徑（可用 python -c 快速檢查）。
- GemPy 模型每次重大修改後要能重新 compute 出結果才算完成（Step 7 成功 +
  Step 8 有圖），不要只改完程式碼就宣告完工。
- 產出檔案後回報實際路徑與筆數/尺寸，讓使用者能快速抽查。