DMG 钻孔可视化

dimine_python_sdk.lib.io 提供 DmgFile 类用于操作 Dimine 钻孔数据库三维可视化文件（.dmg）。DMG 是一种特殊的 DMF 文件（DmgFile 继承自 DmfFile），以三维线段模型直观展示钻孔轨迹、孔口位置及样品分段信息。支持从 DmdFile 钻孔数据库或自定义分段 DataFrame 两种方式生成 DMG 文件。

一、DMG 文件结构

DMG 文件内部包含 4 个图层：

图层名称	说明
`钻孔轨迹`	每个样品段对应一条线段（Line），携带 BHID、SAMPLE-ID、SAMFROM、SAMTO、元素品位等属性
`岩性钻孔轨迹`	岩性分段线段（预留图层）
`孔口符号`	每个钻孔一个点（Point），显示孔口位置
`孔口文本`	钻孔编号文字标注（Text），偏移在孔口右侧

DmgFile 继承 DmfFile 的全部图层/实体访问能力，可使用 layer_names、layers、insert_* 等方法。

二、从钻孔数据库生成 DMG

方式一：直接保存（`save_from_drill_db`）

将 DmdFile 实例直接打包为 DMG 文件：

from dimine_python_sdk.lib.io import DmdFile, DmgFile

dmd = DmdFile("钻孔数据.dmd")
dmg = DmgFile()
dmg.save_from_drill_db("output.dmg", dmd)

此方法内部调用 DmdFile.save_as_dmg()，适用于 DMD 数据已完整校验的场景。

方式二：通过分段 DataFrame（`save_from_drill_db_dataframe`）

先将 DmdFile 拆解为分段 DataFrame（计算每个样品段的三维轨迹坐标），再保存为 DMG：

dmg = DmgFile()
dmg.save_from_drill_db_dataframe("output.dmg", dmd)

此方法内部执行以下步骤： 1. 合并孔口表、测斜表、样品表、岩性表 2. 通过测斜数据计算每个样品段的三维起点/终点坐标 3. 调用 save_from_segments 构建 DMG

注意：此方法需要孔口表包含 工程号、横坐标、纵坐标、高程，测斜表包含 工程号、测斜深度、方位角、倾角，样品表包含 工程号、样本编号、起始、结束。缺失任一必需列将抛出 DmgValidationError。

三、从分段 DataFrame 生成 DMG

如果需要自定义分段数据（例如从外部系统导入的钻孔数据），可直接使用 save_from_segments：

import pandas as pd
from dimine_python_sdk.lib.io import DmgFile

df = pd.DataFrame({
    "BHID": ["ZK001", "ZK001", "ZK002"],
    "start_x": [100.0, 100.0, 200.0],
    "start_y": [50.0, 50.0, 80.0],
    "start_z": [0.0, -10.0, 0.0],
    "end_x": [100.0, 100.0, 200.0],
    "end_y": [50.0, 50.0, 80.0],
    "end_z": [-10.0, -20.0, -15.0],
    "勘探线": ["L1", "L1", "L2"],
    "工程类型": ["坑内钻", "坑内钻", "坑内钻"],
    "ROCK-TYPE": ["花岗岩", "花岗岩", "片麻岩"],
    "SAMPLE-ID": ["S001", "S002", "S003"],
    "SAMFROM": [0.0, 10.0, 0.0],
    "SAMTO": [10.0, 20.0, 15.0],
    "样长": [10.0, 10.0, 15.0],
    "CU": [0.5, 1.2, 0.8],
    "TFE": [30.0, 28.0, 35.0],
})

dmg = DmgFile()
dmg.save_from_segments("output.dmg", df)

必需列

save_from_segments 要求 DataFrame 包含以下列：

列名	说明
`BHID`	钻孔编号
`start_x`, `start_y`, `start_z`	分段起点坐标
`end_x`, `end_y`, `end_z`	分段终点坐标
`勘探线`	勘探线编号
`工程类型`	工程类型（如"坑内钻"）
`ROCK-TYPE`	岩性编号
`SAMPLE-ID`	样本编号
`SAMFROM`, `SAMTO`	样品段起止深度
`样长`	样品段长度

元素品位列（可选）

列名全为大写字母且不在必需列中的列，自动识别为元素品位列（如 CU、AU、TFE）。这些列将以 double 类型写入 DMG 文件。

四、加载 DMG 文件

dmg = DmgFile("input.dmg")
print(dmg.info)
# {'file': 'input.dmg', 'name': 'input', 'layers': 4,
#  'total_entities': 150, 'layer_names': [...],
#  'features': ['0'], 'feature_count': 1,
#  'point_entities': 30, 'line_entities': 90}

加载后可遍历图层和实体：

for layer in dmg:
    print(f"图层 {layer.name}: {layer.entity_count} 个实体")
    for entity in layer.entities:
        print(type(entity).__name__, entity.geometry)

链式加载

dmg = DmgFile().load("input.dmg")
print(dmg.layer_names)

五、提取分段数据

从已加载的 DMG 文件中提取分段 DataFrame，还原为与 save_from_segments 输入一致的格式：

dmg = DmgFile("input.dmg")
df = dmg.to_segments_dataframe()
print(df.columns.tolist())
# ['BHID', 'start_x', 'start_y', 'start_z', 'end_x', 'end_y', 'end_z',
#  '勘探线', '工程类型', 'ROCK-TYPE', 'SAMPLE-ID', 'SAMFROM', 'SAMTO',
#  '样长', ...]
print(df.head())

注意：此方法读取"钻孔轨迹"图层中的线段实体，从实体属性和几何信息重构 DataFrame。要求 DMG 文件中存在"钻孔轨迹"图层且包含有效线段。

六、上下文管理器

from dimine_python_sdk.lib.io import dmg_conn

with dmg_conn("input.dmg") as dmg:
    print(dmg.info)
    df = dmg.to_segments_dataframe()

七、异常处理

from dimine_python_sdk.lib.io import DmgError, DmgValidationError

try:
    dmg = DmgFile()
    dmg.save_from_segments("output.dmg", df)  # df 缺失必需列
except DmgValidationError as e:
    print(f"数据校验失败: {e}")
except DmgError as e:
    print(f"DMG 操作失败: {e}")

异常层次： - DmgError(RuntimeError) — 基类 - DmgValidationError(DmgError) — 数据校验失败（缺少必需列、无效数据等）