Skip to content

dmg_file

DMG 文件业务层：DmgFile、dmg_conn 与相关功能

职责： - 提供 Pythonic 的 DMG 钻孔数据库三维可视化文件接口； - 从分段 DataFrame 构建 DMG（save_from_segments）。

允许类型：models.、np.ndarray、pd.DataFrame、Path、str、标量 禁止类型：Dm 禁止 import DmPyBindInterface

DmgError

Bases: RuntimeError

DMG 操作异常基类

Source code in dimine_python_sdk\lib\io\dmg_file.py 
50
51
52
53
class DmgError(RuntimeError):
    """DMG 操作异常基类"""

    pass

DmgFile

Bases: DmfFile

DMG 文件管理器，继承自 DmfFile。

DMG 是钻孔数据库的三维可视化格式（一种特殊的 DMF 文件）。 当前支持： - 保存：从 DrillDBManager 保存为 DMG（直接调用 native 层 save_as_dmg） - 保存：从分段 DataFrame 保存为 DMG（save_from_segments） - 加载：加载 DMG 文件，通过继承的 DMF API 查看图层和实体结构 - 提取：从实体几何中提取孔口坐标等结构信息（属性数据受限于 C++ API 暂不可读）

用法 - 从 DrillDBManager 保存 DMG::

from dimine_python_sdk.lib.prospecting import DrillDBManager
db = DrillDBManager("钻孔数据.dmd")
dmg = DmgFile()
dmg.save_from_drill_db("output.dmg", db)

用法 - 从分段 DataFrame 保存 DMG::

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

用法 - 加载 DMG 查看结构::

dmg = DmgFile("input.dmg")
print(dmg.info)                 # {file, layers, total_entities, ...}
print(dmg.layer_names)          # ['L0', 'L1', 'L2']
for layer in dmg:               # 遍历图层和实体
    for entity in layer.entities:
        print(type(entity).__name__, entity.geometry)

继承自 DmfFile，可使用所有图层/实体操作方法。

Source code in dimine_python_sdk\lib\io\dmg_file.py 
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
class DmgFile(DmfFile):
    """
    DMG 文件管理器，继承自 ``DmfFile``。

    DMG 是钻孔数据库的三维可视化格式（一种特殊的 DMF 文件）。
    当前支持：
    - **保存**：从 ``DrillDBManager`` 保存为 DMG（直接调用 native 层 ``save_as_dmg``）
    - **保存**：从分段 DataFrame 保存为 DMG（``save_from_segments``）
    - **加载**：加载 DMG 文件，通过继承的 DMF API 查看图层和实体结构
    - **提取**：从实体几何中提取孔口坐标等结构信息（属性数据受限于 C++ API 暂不可读）

    用法 - 从 DrillDBManager 保存 DMG::

        from dimine_python_sdk.lib.prospecting import DrillDBManager
        db = DrillDBManager("钻孔数据.dmd")
        dmg = DmgFile()
        dmg.save_from_drill_db("output.dmg", db)

    用法 - 从分段 DataFrame 保存 DMG::

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

    用法 - 加载 DMG 查看结构::

        dmg = DmgFile("input.dmg")
        print(dmg.info)                 # {file, layers, total_entities, ...}
        print(dmg.layer_names)          # ['L0', 'L1', 'L2']
        for layer in dmg:               # 遍历图层和实体
            for entity in layer.entities:
                print(type(entity).__name__, entity.geometry)

    继承自 ``DmfFile``，可使用所有图层/实体操作方法。
    """

    # ------------------------------------------------------------------
    # 生命周期
    # ------------------------------------------------------------------

    def load(self, file_path: str) -> "DmgFile":
        """
        加载 .dmg 文件（继承 DmfFile.load）

        Returns:
            self（支持链式调用）

        Raises:
            DmfLoadError: 文件不存在或加载失败
        """
        super().load(file_path)
        return self

    def save_from_drill_db(
        self,
        file_path: str,
        drill_db: Any,
    ) -> None:
        """
        从钻孔数据库对象保存为 DMG 文件

        直接通过 DrillDBManager.save_as_dmg 保存为 DMG 格式。

        Args:
            file_path: 目标 .dmg 文件路径
            drill_db: DrillDBManager 实例

        Usage::

            from dimine_python_sdk.lib.prospecting import DrillDBManager
            db = DrillDBManager("钻孔数据.dmd")
            DmgFile().save_from_drill_db("output.dmg", db)
        """
        if not isinstance(drill_db, DrillDBManager):
            raise DmgError("drill_db 必须是 DrillDBManager 实例")

        try:
            drill_db.save_as_dmg(file_path)
        except Exception as exc:
            raise DmgError(f"保存 .dmg 失败: {file_path}") from exc

        self.file_path = str(file_path)

    def save_from_segments(
        self,
        file_path: str,
        df: pd.DataFrame,
    ) -> None:
        """
        从分段 DataFrame 构建并保存为 DMG 文件

        输入 DataFrame 每行代表某个钻孔下某一段的完整信息，包含起点坐标、
        终点坐标、样品信息及元素品位等。

        必需列：
            BHID、start_x、start_y、start_z、end_x、end_y、end_z、
            勘探线、工程类型、ROCK-TYPE、SAMPLE-ID、SAMFROM、SAMTO、样长。

        可选列：
            任意大写元素品位列（如 CU、TFE 等），类型为浮点型。

        Args:
            file_path: 目标 .dmg 文件路径
            df: 钻孔分段 DataFrame

        Usage::

            DmgFile().save_from_segments(
                "output.dmg",
                df,
            )
        """
        try:
            handle = NativeDatabaseHandle.create_local()
            _build_dmg_from_segments(handle, df)
            handle.save(str(file_path))
        except Exception as exc:
            raise DmgError(f"保存 .dmg 失败: {file_path}") from exc

        self.file_path = str(file_path)

    def save_from_drill_db_dataframe(
        self,
        file_path: str,
        drill_db: DrillDBManager,
    ) -> None:
        """
        从钻孔数据库对象构建分段 DataFrame 并保存为 DMG 文件

        将 ``DrillDBManager`` 中的孔口表、测斜表、样品表、岩性表合并，
        通过测斜数据计算每个样品段的三维起点/终点坐标，再调用
        ``save_from_segments`` 保存为 DMG。

        Args:
            file_path: 目标 .dmg 文件路径
            drill_db: ``DrillDBManager`` 实例

        Usage::

            from dimine_python_sdk.lib.prospecting import DrillDBManager
            db = DrillDBManager("钻孔数据.dmd")
            DmgFile().save_from_drill_db_dataframe("output.dmg", db)
        """
        if not isinstance(drill_db, DrillDBManager):
            raise DmgError("drill_db 必须是 DrillDBManager 实例")

        try:
            segment_df = _drill_db_to_segment_df(drill_db)
            self.save_from_segments(file_path, segment_df)
        except Exception as exc:
            raise DmgError(
                f"从钻孔数据库构建 DMG 分段失败: {file_path}"
            ) from exc

    # ------------------------------------------------------------------
    # 属性
    # ------------------------------------------------------------------

    @property
    def info(self) -> Dict[str, Any]:
        """DMG 文件摘要信息"""
        base = super().info
        # 统计各类实体数量
        point_count = 0
        line_count = 0
        for layer in self.layers:
            for entity in layer.entities:
                if isinstance(entity, Point):
                    point_count += 1
                elif isinstance(entity, Line):
                    line_count += 1
        base["point_entities"] = point_count
        base["line_entities"] = line_count
        return base

    def __repr__(self) -> str:
        return (
            f"DmgFile('{self.file_path or ''}', "
            f"layers={self.layer_count}, "
            f"entities={sum(layer.entity_count for layer in self.layers)})"
        )

info property

DMG 文件摘要信息

load(file_path)

加载 .dmg 文件（继承 DmfFile.load）

Returns:

Type Description
'DmgFile'

self（支持链式调用）

Raises:

Type Description
DmfLoadError

文件不存在或加载失败
Source code in dimine_python_sdk\lib\io\dmg_file.py 
106
107
108
109
110
111
112
113
114
115
116
117
def load(self, file_path: str) -> "DmgFile":
    """
    加载 .dmg 文件（继承 DmfFile.load）

    Returns:
        self（支持链式调用）

    Raises:
        DmfLoadError: 文件不存在或加载失败
    """
    super().load(file_path)
    return self

save_from_drill_db(file_path, drill_db)

从钻孔数据库对象保存为 DMG 文件

直接通过 DrillDBManager.save_as_dmg 保存为 DMG 格式。

Parameters:

Name Type Description Default
file_path str

目标 .dmg 文件路径

 required
drill_db Any

DrillDBManager 实例

 required

Usage::

from dimine_python_sdk.lib.prospecting import DrillDBManager
db = DrillDBManager("钻孔数据.dmd")
DmgFile().save_from_drill_db("output.dmg", db)
Source code in dimine_python_sdk\lib\io\dmg_file.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def save_from_drill_db(
    self,
    file_path: str,
    drill_db: Any,
) -> None:
    """
    从钻孔数据库对象保存为 DMG 文件

    直接通过 DrillDBManager.save_as_dmg 保存为 DMG 格式。

    Args:
        file_path: 目标 .dmg 文件路径
        drill_db: DrillDBManager 实例

    Usage::

        from dimine_python_sdk.lib.prospecting import DrillDBManager
        db = DrillDBManager("钻孔数据.dmd")
        DmgFile().save_from_drill_db("output.dmg", db)
    """
    if not isinstance(drill_db, DrillDBManager):
        raise DmgError("drill_db 必须是 DrillDBManager 实例")

    try:
        drill_db.save_as_dmg(file_path)
    except Exception as exc:
        raise DmgError(f"保存 .dmg 失败: {file_path}") from exc

    self.file_path = str(file_path)

save_from_drill_db_dataframe(file_path, drill_db)

从钻孔数据库对象构建分段 DataFrame 并保存为 DMG 文件

将 DrillDBManager 中的孔口表、测斜表、样品表、岩性表合并， 通过测斜数据计算每个样品段的三维起点/终点坐标，再调用 save_from_segments 保存为 DMG。

Parameters:

Name Type Description Default
file_path str

目标 .dmg 文件路径

 required
drill_db DrillDBManager

DrillDBManager 实例

 required

Usage::

from dimine_python_sdk.lib.prospecting import DrillDBManager
db = DrillDBManager("钻孔数据.dmd")
DmgFile().save_from_drill_db_dataframe("output.dmg", db)
Source code in dimine_python_sdk\lib\io\dmg_file.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
def save_from_drill_db_dataframe(
    self,
    file_path: str,
    drill_db: DrillDBManager,
) -> None:
    """
    从钻孔数据库对象构建分段 DataFrame 并保存为 DMG 文件

    将 ``DrillDBManager`` 中的孔口表、测斜表、样品表、岩性表合并，
    通过测斜数据计算每个样品段的三维起点/终点坐标，再调用
    ``save_from_segments`` 保存为 DMG。

    Args:
        file_path: 目标 .dmg 文件路径
        drill_db: ``DrillDBManager`` 实例

    Usage::

        from dimine_python_sdk.lib.prospecting import DrillDBManager
        db = DrillDBManager("钻孔数据.dmd")
        DmgFile().save_from_drill_db_dataframe("output.dmg", db)
    """
    if not isinstance(drill_db, DrillDBManager):
        raise DmgError("drill_db 必须是 DrillDBManager 实例")

    try:
        segment_df = _drill_db_to_segment_df(drill_db)
        self.save_from_segments(file_path, segment_df)
    except Exception as exc:
        raise DmgError(
            f"从钻孔数据库构建 DMG 分段失败: {file_path}"
        ) from exc

save_from_segments(file_path, df)

从分段 DataFrame 构建并保存为 DMG 文件

输入 DataFrame 每行代表某个钻孔下某一段的完整信息，包含起点坐标、 终点坐标、样品信息及元素品位等。

必需列： BHID、start_x、start_y、start_z、end_x、end_y、end_z、 勘探线、工程类型、ROCK-TYPE、SAMPLE-ID、SAMFROM、SAMTO、样长。

可选列： 任意大写元素品位列（如 CU、TFE 等），类型为浮点型。

Parameters:

Name Type Description Default
file_path str

目标 .dmg 文件路径

 required
df DataFrame

钻孔分段 DataFrame

 required

Usage::

DmgFile().save_from_segments(
    "output.dmg",
    df,
)
Source code in dimine_python_sdk\lib\io\dmg_file.py 
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def save_from_segments(
    self,
    file_path: str,
    df: pd.DataFrame,
) -> None:
    """
    从分段 DataFrame 构建并保存为 DMG 文件

    输入 DataFrame 每行代表某个钻孔下某一段的完整信息，包含起点坐标、
    终点坐标、样品信息及元素品位等。

    必需列：
        BHID、start_x、start_y、start_z、end_x、end_y、end_z、
        勘探线、工程类型、ROCK-TYPE、SAMPLE-ID、SAMFROM、SAMTO、样长。

    可选列：
        任意大写元素品位列（如 CU、TFE 等），类型为浮点型。

    Args:
        file_path: 目标 .dmg 文件路径
        df: 钻孔分段 DataFrame

    Usage::

        DmgFile().save_from_segments(
            "output.dmg",
            df,
        )
    """
    try:
        handle = NativeDatabaseHandle.create_local()
        _build_dmg_from_segments(handle, df)
        handle.save(str(file_path))
    except Exception as exc:
        raise DmgError(f"保存 .dmg 失败: {file_path}") from exc

    self.file_path = str(file_path)

DmgValidationError

Bases: DmgError

DMG 数据校验失败（缺少必需列、无效数据等）

Source code in dimine_python_sdk\lib\io\dmg_file.py 
56
57
58
59
class DmgValidationError(DmgError):
    """DMG 数据校验失败（缺少必需列、无效数据等）"""

    pass

dmg_conn(file_path=None)

DMG 文件连接上下文管理器

Source code in dimine_python_sdk\lib\io\dmg_file.py 
249
250
251
252
253
254
255
256
@contextmanager
def dmg_conn(file_path: Optional[str] = None) -> Generator[DmgFile, None, None]:
    """DMG 文件连接上下文管理器"""
    dmg = DmgFile(file_path)
    try:
        yield dmg
    finally:
        dmg.close()