dimine-python-sdk 0.2.4__py3-none-any.whl → 0.2.5__py3-none-any.whl

dimine_python_sdk/__init__.py

@@ -4,7 +4,7 @@ from pathlib import Path
 from typing import Any
 
 DOCS_PATH = Path(__file__).parent / "docs"
-__VERSION__ = "0.2.4"  # 由 build.bat 中的 generate_version.py 自动更新
+__VERSION__ = "0.2.5"  # 由 build.bat 中的 generate_version.py 自动更新
 
 
 _LAZY_IMPORTS: dict[str, Any] = {}

dimine_python_sdk/docs/guides/lib/io/dmd_file.md

@@ -1,196 +1,198 @@
-# DMD 钻孔数据库文件
-
-`dimine_python_sdk.lib.io` 提供 `DmdFile` 类用于读写 Dimine 钻孔数据库文件（`.dmd`）。DMD 是钻孔数据库的主引用文件，内部引用孔口表、测斜表、岩性表、样品表及扩展表的 `.dmt` 子表文件。API 将各表映射为 `pandas.DataFrame`，支持加载、修改、保存全流程操作。
-
----
-
-## 一、加载与保存
-
-### 从文件加载
-
-```python
-from dimine_python_sdk.lib.io import DmdFile
-
-dmd = DmdFile("钻孔数据.dmd")
-print(dmd.collar.head())
-print(dmd.info)
-```
-
-### 保存到文件
-
-```python
-dmd.collar = modified_collar_df
-dmd.save()                        # 覆盖原文件
-dmd.save("output.dmd")            # 另存为新文件
-```
-
-### 创建空文件并保存
-
-```python
-dmd = DmdFile()                   # 空构造，可直接设表
-dmd.collar = collar_df
-dmd.survey = survey_df
-dmd.lithology = lithology_df
-dmd.sample = sample_df
-dmd.save("新钻孔数据.dmd")
-```
-
-### 上下文管理器
-
-```python
-from dimine_python_sdk.lib.io import dmd_conn
-
-with dmd_conn("钻孔数据.dmd") as dmd:
-    print(dmd.info)
-    dmd.sample["CU"] = dmd.sample["CU"] * 1.1
-    dmd.save()
-```
-
----
-
-## 二、核心表访问
-
-DMD 文件包含四张核心表，均以 `pd.DataFrame` 形式读写：
-
-### 孔口表（collar）
-
-```python
-dmd.collar.head()
-#    工程号    横坐标    纵坐标    高程    勘探线  工程类型
-# 0  ZK001  1000.0  2000.0  500.0     L1   坑内钻
-
-dmd.collar = new_collar_df   # 替换整个表（自动校验列名）
-```
-
-### 测斜表（survey）
-
-```python
-dmd.survey.head()
-#    工程号  测斜深度  方位角  倾角
-# 0  ZK001    0.0   45.0  90.0
-
-dmd.survey = new_survey_df
-```
-
-### 岩性表（lithology）
-
-```python
-dmd.lithology.head()
-#    工程号  起始  结束  岩性编号
-# 0  ZK001  0.0  10.0   花岗岩
-
-dmd.lithology = new_lithology_df
-```
-
-### 样品表（sample）
-
-```python
-dmd.sample.head()
-#    工程号  样本编号  起始  结束  样长   CU
-# 0  ZK001   S001    0.0  2.0   2.0  0.85
-
-dmd.sample = new_sample_df
-```
-
-> **列名规范**：各表有必需的标准中文列名（孔口表需含 `工程号、横坐标、纵坐标、高程`，测斜表需含 `工程号、测斜深度、方位角、倾角` 等）。设置表数据时自动校验，缺列会抛出 `DmdError`。详细列名映射见 [钻孔数据库操作指南](../prospecting/drill_db.md#13-standard-column-mapping)。
-
-### 统一表访问
-
-```python
-dmd["collar"]      # 等价于 dmd.collar
-dmd["survey"]      # 等价于 dmd.survey
-dmd["lithology"]   # 等价于 dmd.lithology
-dmd["sample"]      # 等价于 dmd.sample
-
-"collar" in dmd    # True
-len(dmd)           # 表总数（含扩展表）
-```
-
----
-
-## 三、扩展表
-
-DMD 支持附加自定义扩展表（如分层表），以 `NativeExtendTable` 形式管理：
-
-```python
-# 查看扩展表
-for ext in dmd.extend_tables:
-    print(ext.table_name, ext.dmt_filename)
-    print(ext.df.head())
-
-# 通过表名访问扩展表数据
-ext_df = dmd["分层表"]
-```
-
-扩展表通过 `dmt_filename` 参数指定文件名（如 `分层表.dmt`），在 DMD 保存时一并写入伴随的 `.dmt` 文件。
-
----
-
-## 四、文件信息
-
-```python
-dmd.name           # "钻孔数据" — 文件名（不含扩展名）
-dmd.file_path      # "钻孔数据.dmd"
-dmd.table_names    # ["collar", "survey", "lithology", "sample", "分层表"]
-dmd.ref_dict       # .dmd 引用字典（只读）
-
-dmd.info
-# {
-#   "file": "钻孔数据.dmd",
-#   "name": "钻孔数据",
-#   "loaded": True,
-#   "tables": {
-#     "collar": {"columns": [...], "rows": 150},
-#     "survey": {"columns": [...], "rows": 300},
-#     "lithology": {"columns": [...], "rows": 80},
-#     "sample": {"columns": [...], "rows": 450},
-#   },
-#   "extend_table_count": 1,
-#   "extend_table_names": ["分层表"],
-#   "extend_tables": [...],
-# }
-```
-
----
-
-## 五、保存为 DMG
-
-可将钻孔数据库直接打包为三维可视化格式 DMG：
-
-```python
-dmd.save_as_dmg("output.dmg")
-```
-
-> 更多 DMG 操作见 [DMG 钻孔可视化指南](dmg_file.md)。
-
----
-
-## 六、异常处理
-
-```python
-from dimine_python_sdk.lib.io import DmdError, DmdLoadError, DmdSaveError
-
-try:
-    dmd = DmdFile("not_exist.dmd")
-except DmdLoadError as e:
-    print(f"加载失败: {e}")
-
-try:
-    dmd = DmdFile()
-    dmd.save()  # 未指定路径
-except DmdSaveError as e:
-    print(f"保存失败: {e}")
-```
-
-异常层次：
-- `DmdError(RuntimeError)` — 基类
-- `DmdLoadError(DmdError)` — 加载失败
-- `DmdSaveError(DmdError)` — 保存失败
-
----
-
-## 参考链接
-
-- [钻孔数据库操作指南](../prospecting/drill_db.md) — 完整的钻孔数据库使用场景（CSV 导入、列名映射、组合样、特高品位处理）
-- [DMG 钻孔可视化](dmg_file.md) — 将 DMD 转为三维可视化格式
-- [API 参考：dmd_file](../../../reference/lib/io/dmd_file.md)
+# DMD 钻孔数据库文件
+
+`dimine_python_sdk.lib.io` 提供 `DmdFile` 类用于读写 Dimine 钻孔数据库文件（`.dmd`）。DMD 是钻孔数据库的主引用文件，内部引用孔口表、测斜表、岩性表、样品表及扩展表的 `.dmt` 子表文件。API 将各表映射为 `pandas.DataFrame`，支持加载、修改、保存全流程操作。
+
+---
+
+## 一、加载与保存
+
+### 从文件加载
+
+```python
+from dimine_python_sdk.lib.io import DmdFile
+
+dmd = DmdFile("钻孔数据.dmd")
+print(dmd.collar.head())
+print(dmd.info)
+```
+
+### 保存到文件
+
+```python
+dmd.collar = modified_collar_df
+dmd.save()                        # 覆盖原文件
+dmd.save("output.dmd")            # 另存为新文件
+```
+
+### 创建空文件并保存
+
+```python
+dmd = DmdFile()                   # 空构造，可直接设表
+dmd.collar = collar_df
+dmd.survey = survey_df
+dmd.lithology = lithology_df
+dmd.sample = sample_df
+dmd.save("新钻孔数据.dmd")
+```
+
+### 上下文管理器
+
+```python
+from dimine_python_sdk.lib.io import dmd_conn
+
+with dmd_conn("钻孔数据.dmd") as dmd:
+    print(dmd.info)
+    dmd.sample["CU"] = dmd.sample["CU"] * 1.1
+    dmd.save()
+```
+
+---
+
+## 二、核心表访问
+
+DMD 文件包含四张核心表，均以 `pd.DataFrame` 形式读写：
+
+### 孔口表（collar）
+
+```python
+dmd.collar.head()
+#    工程号    横坐标    纵坐标    高程    勘探线  工程类型
+# 0  ZK001  1000.0  2000.0  500.0     L1   坑内钻
+
+dmd.collar = new_collar_df   # 替换整个表（自动校验列名）
+```
+
+### 测斜表（survey）
+
+```python
+dmd.survey.head()
+#    工程号  测斜深度  方位角  倾角
+# 0  ZK001    0.0   45.0  90.0
+
+dmd.survey = new_survey_df
+```
+
+### 岩性表（lithology）
+
+```python
+dmd.lithology.head()
+#    工程号  起始  结束  岩性编号
+# 0  ZK001  0.0  10.0   花岗岩
+
+dmd.lithology = new_lithology_df
+```
+
+### 样品表（sample）
+
+```python
+dmd.sample.head()
+#    工程号  样本编号  起始  结束  样长   CU
+# 0  ZK001   S001    0.0  2.0   2.0  0.85
+
+dmd.sample = new_sample_df
+```
+
+> **列名规范**：各表有必需的标准中文列名（孔口表需含 `工程号、横坐标、纵坐标、高程`，测斜表需含 `工程号、测斜深度、方位角、倾角` 等）。设置表数据时自动校验，缺列会抛出 `DmdError`。详细列名映射见 [钻孔数据库操作指南](../prospecting/drill_db.md#13-standard-column-mapping)。
+
+### 统一表访问
+
+```python
+dmd["collar"]      # 等价于 dmd.collar
+dmd["survey"]      # 等价于 dmd.survey
+dmd["lithology"]   # 等价于 dmd.lithology
+dmd["sample"]      # 等价于 dmd.sample
+
+"collar" in dmd    # True
+len(dmd)           # 表总数（含扩展表）
+```
+
+---
+
+## 三、扩展表
+
+DMD 支持附加自定义扩展表（如分层表），以 `NativeExtendTable` 形式管理：
+
+```python
+# 查看扩展表
+for ext in dmd.extend_tables:
+    print(ext.table_name, ext.dmt_filename)
+    print(ext.df.head())
+
+# 通过表名访问扩展表数据
+ext_df = dmd["分层表"]
+```
+
+扩展表通过 `dmt_filename` 参数指定文件名（如 `分层表.dmt`），在 DMD 保存时一并写入伴随的 `.dmt` 文件。
+
+---
+
+## 四、文件信息
+
+```python
+dmd.name           # "钻孔数据" — 文件名（不含扩展名）
+dmd.file_path      # "钻孔数据.dmd"
+dmd.table_names    # ["collar", "survey", "lithology", "sample", "分层表"]
+dmd.ref_dict       # .dmd 引用字典（只读）
+
+dmd.info
+# {
+#   "file": "钻孔数据.dmd",
+#   "name": "钻孔数据",
+#   "loaded": True,
+#   "tables": {
+#     "collar": {"columns": [...], "rows": 150},
+#     "survey": {"columns": [...], "rows": 300},
+#     "lithology": {"columns": [...], "rows": 80},
+#     "sample": {"columns": [...], "rows": 450},
+#   },
+#   "extend_table_count": 1,
+#   "extend_table_names": ["分层表"],
+#   "extend_tables": [...],
+# }
+```
+
+---
+
+## 五、保存为 DMG（可选）
+
+> **注意**：`.dmd` 文件可以直接在 Dimine 中打开并展示三维钻孔，无需转换。DMG 是另一种可视化格式，适用于需要特殊展示效果的场景。
+
+可将钻孔数据库打包为 DMG 格式：
+
+```python
+dmd.save_as_dmg("output.dmg")
+```
+
+> 更多 DMG 操作见 [DMG 钻孔可视化指南](dmg_file.md)。
+
+---
+
+## 六、异常处理
+
+```python
+from dimine_python_sdk.lib.io import DmdError, DmdLoadError, DmdSaveError
+
+try:
+    dmd = DmdFile("not_exist.dmd")
+except DmdLoadError as e:
+    print(f"加载失败: {e}")
+
+try:
+    dmd = DmdFile()
+    dmd.save()  # 未指定路径
+except DmdSaveError as e:
+    print(f"保存失败: {e}")
+```
+
+异常层次：
+- `DmdError(RuntimeError)` — 基类
+- `DmdLoadError(DmdError)` — 加载失败
+- `DmdSaveError(DmdError)` — 保存失败
+
+---
+
+## 参考链接
+
+- [钻孔数据库操作指南](../prospecting/drill_db.md) — 完整的钻孔数据库使用场景（CSV 导入、列名映射、组合样、特高品位处理）
+- [DMG 钻孔可视化](dmg_file.md) — 将 DMD 转为三维可视化格式
+- [API 参考：dmd_file](../../../reference/lib/io/dmd_file.md)