本地文件格式转换

dimine_python_sdk.lib.io 提供了基于本地原生库（DmPyBindInterface）的文件格式转换功能，无需启动 Dimine 桌面客户端即可在 Python 脚本中完成 CAD、Surpac、MicroMine、DataMine、MapGIS 与 DMF 格式之间的互转。

---

支持的格式

格式	扩展名	说明
DMF	.dmf	Dimine 标准工程文件格式（中转核心格式）
DWG	.dwg	AutoCAD 图形文件
Surpac	.dtm	Surpac 矿业软件格式
MicroMine	.STR	MicroMine 矿业软件格式
DataMine	.dat	DataMine 矿业软件格式
MapGIS	.mgis	MapGIS 地理信息系统格式

支持的转换方向：

• 转 DMF：DWG → DMF、Surpac → DMF、MicroMine → DMF、DataMine → DMF、MapGIS → DMF
• 从 DMF 转出：DMF → DWG、DMF → Surpac、DMF → MicroMine、DMF → MapGIS

不支持任意两种非 DMF 格式之间的直接转换，若需此类转换，请分两步进行（例如：DWG → DMF → Surpac）。

---

快速开始

单文件转换

from dimine_python_sdk.lib.io import convert_file

result = convert_file("input.dwg", "output.dmf")
if result.success:
    print(f"转换成功，输出路径: {result.output_path}")
else:
    print(f"转换失败: {result.message}")

使用 FileConverter 显式调用

from dimine_python_sdk.lib.io import FileConverter

converter = FileConverter("input.dwg", "output.dmf")
result = converter.convert()
print(result)
# 输出: <ConversionResult 成功: input.dwg -> output.dmf>

---

FileConverter 详解

构造与配置

FileConverter 的 __init__ 仅保存参数，不会立即执行转换，需显式调用 .convert()：

from dimine_python_sdk.lib.io import FileConverter, ConvertOptions

# 基础用法
converter = FileConverter("input.dtm", "output.dmf")

# 自定义选项：禁止覆盖已存在的目标文件
opts = ConvertOptions(overwrite=False)
converter = FileConverter("input.sur", "output.dmf", options=opts)

转换选项（ConvertOptions）

参数	类型	默认值	说明
overwrite	bool	True	目标文件已存在时是否覆盖

from dimine_python_sdk.lib.io import ConvertOptions

opts = ConvertOptions(overwrite=False)

获取转换结果

result = converter.convert()

# 判断成功与否
if result:
    ...

# 访问结果属性
print(result.success)       # bool
print(result.source)        # Path("input.dwg")
print(result.target)        # Path("output.dmf")
print(result.output_path)   # 同 target
print(result.message)       # "转换成功" 或错误描述

方向快捷方法

若需明确表达转换语义，可使用以下快捷方法：

# 任意支持格式 → DMF
result = FileConverter("input.dwg", "output.dmf").to_dmf()

# DMF → 任意支持格式
result = FileConverter("input.dmf", "output.dwg").from_dmf()

若格式与方向不匹配（例如对 .dwg 调用 from_dmf()），将抛出 UnsupportedFormatError。

---

便捷函数：convert_file

对于简单的单次转换，可直接使用模块级便捷函数：

from dimine_python_sdk.lib.io import convert_file

# 基础调用
result = convert_file("input.dwg", "output.dmf")

# 禁止覆盖
result = convert_file("input.dwg", "output.dmf", overwrite=False)

# 传入完整选项对象
from dimine_python_sdk.lib.io import ConvertOptions
opts = ConvertOptions(overwrite=False)
result = convert_file("input.dwg", "output.dmf", options=opts)

---

异常处理

转换过程中可能抛出以下异常，建议按业务需求捕获：

from dimine_python_sdk.lib.io import (
    convert_file,
    UnsupportedFormatError,
    ConversionFailedError,
)

try:
    result = convert_file("input.xyz", "output.dmf")
except UnsupportedFormatError as e:
    # 不支持的源/目标格式，或不支持的转换方向
    print(f"格式不支持: {e}")
except ConversionFailedError as e:
    # 底层转换函数返回失败或抛出异常
    print(f"转换失败: {e}")
    print(f"源文件: {e.source}")
    print(f"目标文件: {e.target}")

异常层次

RuntimeError
└── FileConversionError
    ├── UnsupportedFormatError    # 格式/方向不支持
    └── ConversionFailedError     # 转换执行失败（可携带 source、target 路径）

---

批量转换示例

批量将 DWG 转为 DMF

from pathlib import Path
from dimine_python_sdk.lib.io import convert_file, ConversionFailedError

input_dir = Path("D:/data/dwg_files")
output_dir = Path("D:/data/dmf_files")
output_dir.mkdir(parents=True, exist_ok=True)

for dwg_file in input_dir.glob("*.dwg"):
    dmf_file = output_dir / (dwg_file.stem + ".dmf")
    try:
        result = convert_file(str(dwg_file), str(dmf_file), overwrite=True)
        print(f"✓ {dwg_file.name} -> {dmf_file.name}")
    except ConversionFailedError as e:
        print(f"✗ {dwg_file.name} 转换失败: {e}")

两步转换：DWG → DMF → Surpac

from dimine_python_sdk.lib.io import convert_file, UnsupportedFormatError

dwg = "input.dwg"
sur = "output.dtm"

# 不支持 DWG → Surpac 直接转换，需以 DMF 为中转
temp_dmf = "temp.dmf"

result1 = convert_file(dwg, temp_dmf)
assert result1.success

result2 = convert_file(temp_dmf, sur)
assert result2.success

print("两步转换完成")

---

旧 API 迁移说明

以下旧 API 仍保留以保证向后兼容，但会在调用时发出 DeprecationWarning，建议迁移到新 API：

旧 API（已废弃）	新 API 替代方案
FileConverter.cad_to_dmf(src, dst)	FileConverter(src, dst).convert()
FileConverter.dmf_to_cad(src, dst)	FileConverter(src, dst).convert()
FileConverter.surpac_to_dmf(src, dst)	FileConverter(src, dst).convert()
FileConverter.dmf_to_surpac(src, dst)	FileConverter(src, dst).convert()
FileConverter.micromine_to_dmf(src, dst)	FileConverter(src, dst).convert()
FileConverter.dmf_to_micromine(src, dst)	FileConverter(src, dst).convert()
FileConverter.datamine_to_dmf(src, dst)	FileConverter(src, dst).convert()
FileConverter.mapgis_to_dmf(src, dst)	FileConverter(src, dst).convert()
FileConverter.dmf_to_mapgis(src, dst)	FileConverter(src, dst).convert()
dmf_to_other(src, dst)	convert_file(src, dst)
FileConverter(...).result	FileConverter(...).convert()

迁移示例：

# 旧写法（仍能运行，但会报警告）
# result = FileConverter.cad_to_dmf("a.dwg", "b.dmf")

# 新写法
result = FileConverter("a.dwg", "b.dmf").convert()

---

完整示例：带日志和错误处理的转换脚本

import sys
import warnings
from pathlib import Path
from dimine_python_sdk.lib.io import (
    FileConverter,
    ConvertOptions,
    UnsupportedFormatError,
    ConversionFailedError,
)


def convert_single(source: str, target: str, overwrite: bool = True) -> bool:
    """转换单个文件，返回是否成功。"""
    opts = ConvertOptions(overwrite=overwrite)
    converter = FileConverter(source, target, options=opts)

    try:
        result = converter.convert()
        if result.success:
            print(f"[成功] {source} -> {target}")
            return True
        else:
            print(f"[跳过] {result.message}")
            return False
    except UnsupportedFormatError as e:
        print(f"[不支持] {e}")
    except ConversionFailedError as e:
        print(f"[失败] {e} (源: {e.source}, 目标: {e.target})")

    return False


if __name__ == "__main__":
    # 抑制废弃警告（若需查看迁移提示可注释掉）
    warnings.filterwarnings("ignore", category=DeprecationWarning)

    ok = convert_single("data/input.dwg", "data/output.dmf", overwrite=True)
    sys.exit(0 if ok else 1)