DMF 文件读写

dimine_python_sdk.lib.io 提供 DmfFile 类对 Dimine 标准工程文件（.dmf）进行本地读写，无需启动 Dimine 桌面客户端。DMF 是 Dimine 的核心中转格式，内部采用图层-实体-要素三层模型管理几何对象与属性数据，API 完整映射到 Python 内存模型。

一、加载与保存

从文件加载

from dimine_python_sdk.lib.io import DmfFile

dmf = DmfFile("input.dmf")
print(dmf.info)
# {'file': 'input.dmf', 'name': 'input', 'layers': 3,
#  'total_entities': 42, 'layer_names': ['L0', 'L1', 'L2'],
#  'features': ['0'], 'feature_count': 1}

保存到文件

dmf.save("output.dmf")  # 另存为新文件
dmf.save()              # 覆盖原文件（仅当 file_path 已设置时）

上下文管理器（推荐）

with DmfFile("input.dmf") as dmf:
    # ... 操作图层和实体 ...
    dmf.save("output.dmf")
# 退出时自动释放资源

或使用 dmf_conn 便捷函数（与 DmfFile 构造等价）：

from dimine_python_sdk.lib.io import dmf_conn

with dmf_conn("input.dmf") as dmf:
    print(dmf.layer_count)

二、文件信息查询

dmf = DmfFile("input.dmf")

dmf.name            # "input" — 文件名（不含扩展名）
dmf.file_path       # "input.dmf" — 完整路径
dmf.layer_count     # 图层数量
dmf.layer_names     # ["L0", "L1", "L2"] — 所有图层名称
dmf.layers          # [DmfLayer, ...] — 图层列表（可直接修改内存模型）

dmf.info            # 字典：file, name, layers, total_entities, layer_names, features, feature_count

三、图层管理

查看图层

# 按索引访问
layer_0 = dmf[0]
layer_0 = dmf.get_layer(0)

# 按名称访问
layer = dmf["L1"]
layer = dmf.get_layer("L1")

# 遍历所有图层
for layer in dmf:
    print(layer.name, layer.entity_count)

添加图层

new_layer = dmf.add_layer("计算图层")
print(new_layer.name, new_layer.entity_count)  # "计算图层" 0

add_layer 仅修改内存模型，需调用 dmf.save() 才会写入文件。

四、实体插入

DmfFile 提供五种实体插入方法，均直接操作内存模型，支持 color 和 properties 参数：

插入点

import numpy as np

dmf.insert_point(
    "计算图层",
    np.array([1.0, 2.0, 3.0]),
    name="控制点",
    color=[255, 0, 0],
)

插入直线

dmf.insert_line(
    "计算图层",
    np.array([0.0, 0.0, 0.0]),
    np.array([10.0, 0.0, 0.0]),
    name="中心线",
    color=[0, 255, 0],
)

插入多段线

points = np.array([
    [0.0, 0.0, 0.0],
    [5.0, 3.0, 0.0],
    [10.0, 0.0, 5.0],
])
dmf.insert_polyline(
    "计算图层",
    points,
    name="折线",
    color=[0, 0, 255],
)

插入三维实体（Shell）

pts = np.array([
    [0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0],
    [0, 0, 1], [1, 0, 1], [1, 1, 1], [0, 1, 1],
], dtype=float)
faces = np.array([
    [0, 1, 2], [0, 2, 3],  # 底面
    [4, 5, 6], [4, 6, 7],  # 顶面
    [0, 1, 5], [0, 5, 4],  # 前面
], dtype=int)

dmf.insert_shell(
    "计算图层",
    points=pts,
    faces=faces,
    name="块体",
    color=[128, 128, 128],
)

插入文本标注

dmf.insert_text(
    "计算图层",
    position=np.array([5.0, 5.0, 0.0]),
    text="测点A",
    name="标注",
    color=[255, 255, 0],
)

携带属性值

所有插入方法支持 properties 参数，为实体附加自定义属性：

from dimine_python_sdk.models.types import PropertyValue

dmf.insert_point(
    "计算图层",
    np.array([1.0, 2.0, 3.0]),
    name="采样点",
    properties=[
        PropertyValue(name="品位", type="double", value=1.5),
        PropertyValue(name="岩性", type="string", value="花岗岩"),
    ],
)

五、要素管理

要素定义了实体上可附加的属性集合（schema），与 Dimine 中的 Feature 概念一一对应。

注册要素

from dimine_python_sdk.models.types import PropertyInfo

# 注册一个"矿体"要素，包含两个属性定义
feature = dmf.add_feature(
    "矿体",
    properties=[
        PropertyInfo(name="品位", type="double"),
        PropertyInfo(name="储量级别", type="string"),
    ],
)

查看已注册要素

dmf.features        # [DmfFeature("矿体", ...)]
dmf.feature_names   # ["矿体"]
dmf.info["features"]         # ["矿体"]
dmf.info["feature_count"]    # 1

注意：要素定义在文件级别注册，不绑定到特定图层。加载 DMF 文件时会自动读取 features。

六、直接操作内存模型

dmf.layers 返回图层列表，可直接修改每个图层上的实体：

# 在现有图层末尾追加实体
layer = dmf["L0"]
layer.insert_point(np.array([0.0, 0.0, 0.0]), name="追加点")

# 遍历所有实体
for layer in dmf:
    for entity in layer.entities:
        print(type(entity).__name__, entity.name, entity.geometry)

七、异常处理

from dimine_python_sdk.lib.io import DmfError, DmfLoadError, DmfSaveError

try:
    dmf = DmfFile("not_exist.dmf")
except DmfLoadError as e:
    print(f"加载失败: {e}")

try:
    dmf = DmfFile()  # 未绑定文件路径
    dmf.save()       # 未指定保存路径
except DmfSaveError as e:
    print(f"保存失败: {e}")

异常层次： - DmfError(RuntimeError) — 基类 - DmfLoadError(DmfError) — 加载失败（文件不存在、格式错误） - DmfSaveError(DmfError) — 保存失败 - DmfInsertError(DmfError) — 实体插入参数校验失败 - DmfParseError(DmfError) — 单个实体/图层解析失败