file_converter

应用层：lib/io 的文件格式转换模块

职责：提供 Pythonic 的文件格式转换 API 允许类型：pd.DataFrame、np.ndarray、models.、dict、标量、Path 禁止类型：Dm 禁止 import DmPyBindInterface

ConversionFailedError

Bases: FileConversionError

文件转换失败

Source code in dimine_python_sdk\lib\io\file_converter.py

class ConversionFailedError(FileConversionError):
    """文件转换失败"""

    def __init__(
        self,
        message: str,
        source: Optional[Union[str, Path]] = None,
        target: Optional[Union[str, Path]] = None,
    ):
        super().__init__(message)
        self.source = Path(source) if source else None
        self.target = Path(target) if target else None

ConversionResult

文件转换结果

target 是用户传入的目标路径；output_path 是实际产物路径。 对 MapGIS（.mgis）等文件夹形式格式，两者不同：传入 .../新文件2.mgis，产物是 .../新文件2/ 文件夹。

Source code in dimine_python_sdk\lib\io\file_converter.py

class ConversionResult:
    """文件转换结果

    ``target`` 是用户传入的目标路径；``output_path`` 是实际产物路径。
    对 MapGIS（``.mgis``）等文件夹形式格式，两者不同：传入
    ``.../新文件2.mgis``，产物是 ``.../新文件2/`` 文件夹。
    """

    def __init__(
        self,
        success: bool,
        source: Path,
        target: Path,
        message: str = "",
        output_dir: Optional[Path] = None,
    ):
        self.success = success
        self.source = source
        self.target = target
        self.message = message
        # 仅文件夹形式格式（如 .mgis）非空
        self.output_dir = Path(output_dir) if output_dir else None

    def __bool__(self) -> bool:
        return self.success

    def __repr__(self) -> str:
        status = "成功" if self.success else "失败"
        return f"<ConversionResult {status}: {self.source.name} -> {self.target.name}>"

    @property
    def is_directory(self) -> bool:
        """产物是否为文件夹形式（如 MapGIS 的 .mgis）"""
        return self.output_dir is not None

    @property
    def output_path(self) -> Path:
        """实际产物路径：文件夹形式格式返回文件夹，其余返回目标文件"""
        return self.output_dir if self.output_dir is not None else self.target

is_directory property

产物是否为文件夹形式（如 MapGIS 的 .mgis）

output_path property

实际产物路径：文件夹形式格式返回文件夹，其余返回目标文件

ConvertOptions

Bases: BaseModel

文件转换选项

当前仅支持 overwrite，后续可扩展 cad_version、encoding、coordinate_system 等参数。

Source code in dimine_python_sdk\lib\io\file_converter.py

class ConvertOptions(BaseModel):
    """
    文件转换选项

    当前仅支持 overwrite，后续可扩展 cad_version、encoding、coordinate_system 等参数。
    """

    overwrite: bool = True

    def to_dict(self) -> Dict[str, Any]:
        return self.model_dump()

FileConversionError

Bases: RuntimeError

文件转换异常基类

Source code in dimine_python_sdk\lib\io\file_converter.py

class FileConversionError(RuntimeError):
    """文件转换异常基类"""
    pass

FileConverter

文件格式转换工具类，支持 AutoCAD、Surpac、MicroMine、DataMine、MapGIS、 DMF 与钻孔数据库（DMD/DMG）格式互转。

推荐用法（显式调用）::

result = FileConverter("input.dwg", "output.dmf").convert()
if result.success:
    print(result.output_path)

或使用便捷函数::

from dimine_python_sdk.lib.io import convert_file
convert_file("input.dwg", "output.dmf")

Source code in dimine_python_sdk\lib\io\file_converter.py

class FileConverter:
    """
    文件格式转换工具类，支持 AutoCAD、Surpac、MicroMine、DataMine、MapGIS、
    DMF 与钻孔数据库（DMD/DMG）格式互转。

    推荐用法（显式调用）::

        result = FileConverter("input.dwg", "output.dmf").convert()
        if result.success:
            print(result.output_path)

    或使用便捷函数::

        from dimine_python_sdk.lib.io import convert_file
        convert_file("input.dwg", "output.dmf")
    """

    def __init__(
        self,
        source: Union[str, Path],
        target: Union[str, Path],
        options: Optional[ConvertOptions] = None,
    ):
        self.source = Path(source)
        self.target = Path(target)
        self.options = options or ConvertOptions()

    @property
    def source_format(self) -> FileFormat:
        """源文件格式"""
        try:
            return FileFormat(self.source.suffix.lower())
        except ValueError:
            raise UnsupportedFormatError(f"不支持的源文件格式: {self.source.suffix}")

    @property
    def target_format(self) -> FileFormat:
        """目标文件格式"""
        try:
            return FileFormat(self.target.suffix.lower())
        except ValueError:
            raise UnsupportedFormatError(f"不支持的目标文件格式: {self.target.suffix}")

    @property
    def result(self) -> ConversionResult:
        """已废弃，请使用 .convert()"""
        warnings.warn(
            "FileConverter.result 已废弃，请使用 FileConverter.convert()",
            DeprecationWarning,
            stacklevel=3,
        )
        return self.convert()

    def convert(self) -> ConversionResult:
        """执行文件格式转换"""
        return convert_file_impl(self.source, self.target, self.options)

    def to_dmf(self) -> ConversionResult:
        """转换为 DMF 格式"""
        if self.target_format != FileFormat.DMF:
            raise UnsupportedFormatError(
                f"to_dmf() 要求目标格式为 .dmf，当前为 {self.target_format.value}"
            )
        return self.convert()

    def from_dmf(self) -> ConversionResult:
        """从 DMF 格式转换"""
        if self.source_format != FileFormat.DMF:
            raise UnsupportedFormatError(
                f"from_dmf() 要求源格式为 .dmf，当前为 {self.source_format.value}"
            )
        return self.convert()

    @classmethod
    def _legacy_convert(
        cls,
        source: Union[str, Path],
        target: Union[str, Path],
        *,
        _warn_msg: str,
    ) -> ConversionResult:
        """旧 API 的统一实现"""
        warnings.warn(_warn_msg, DeprecationWarning, stacklevel=3)
        return cls(source, target).convert()

    @classmethod
    def cad_to_dmf(
        cls, cad_file: Union[str, Path], dmf_file: Union[str, Path]
    ) -> ConversionResult:
        """AutoCAD 文件转 DMF 格式（已废弃）"""
        return cls._legacy_convert(
            cad_file,
            dmf_file,
            _warn_msg=(
                "FileConverter.cad_to_dmf() 已废弃，"
                "请使用 FileConverter(src, dst).convert()"
            ),
        )

    @classmethod
    def dmf_to_cad(
        cls, dmf_file: Union[str, Path], cad_file: Union[str, Path]
    ) -> ConversionResult:
        """DMF 文件转 AutoCAD 格式（已废弃）"""
        return cls._legacy_convert(
            dmf_file,
            cad_file,
            _warn_msg=(
                "FileConverter.dmf_to_cad() 已废弃，"
                "请使用 FileConverter(src, dst).convert()"
            ),
        )

    @classmethod
    def surpac_to_dmf(
        cls, surpac_file: Union[str, Path], dmf_file: Union[str, Path]
    ) -> ConversionResult:
        """Surpac 文件转 DMF 格式（已废弃）"""
        return cls._legacy_convert(
            surpac_file,
            dmf_file,
            _warn_msg=(
                "FileConverter.surpac_to_dmf() 已废弃，"
                "请使用 FileConverter(src, dst).convert()"
            ),
        )

    @classmethod
    def dmf_to_surpac(
        cls, dmf_file: Union[str, Path], surpac_file: Union[str, Path]
    ) -> ConversionResult:
        """DMF 文件转 Surpac 格式（已废弃）"""
        return cls._legacy_convert(
            dmf_file,
            surpac_file,
            _warn_msg=(
                "FileConverter.dmf_to_surpac() 已废弃，"
                "请使用 FileConverter(src, dst).convert()"
            ),
        )

    @classmethod
    def micromine_to_dmf(
        cls, micromine_file: Union[str, Path], dmf_file: Union[str, Path]
    ) -> ConversionResult:
        """MicroMine 文件转 DMF 格式（已废弃）"""
        return cls._legacy_convert(
            micromine_file,
            dmf_file,
            _warn_msg=(
                "FileConverter.micromine_to_dmf() 已废弃，"
                "请使用 FileConverter(src, dst).convert()"
            ),
        )

    @classmethod
    def dmf_to_micromine(
        cls, dmf_file: Union[str, Path], micromine_file: Union[str, Path]
    ) -> ConversionResult:
        """DMF 文件转 MicroMine 格式（已废弃）"""
        return cls._legacy_convert(
            dmf_file,
            micromine_file,
            _warn_msg=(
                "FileConverter.dmf_to_micromine() 已废弃，"
                "请使用 FileConverter(src, dst).convert()"
            ),
        )

    @classmethod
    def datamine_to_dmf(
        cls, datamine_file: Union[str, Path], dmf_file: Union[str, Path]
    ) -> ConversionResult:
        """DataMine 文件转 DMF 格式（已废弃）"""
        return cls._legacy_convert(
            datamine_file,
            dmf_file,
            _warn_msg=(
                "FileConverter.datamine_to_dmf() 已废弃，"
                "请使用 FileConverter(src, dst).convert()"
            ),
        )

    @classmethod
    def mapgis_to_dmf(
        cls, mapgis_file: Union[str, Path], dmf_file: Union[str, Path]
    ) -> ConversionResult:
        """MapGIS 文件转 DMF 格式（已废弃，且该方向当前不可用）。

        MapGIS 目前仅支持作为目标格式（``dmf -> mgis``）；``mgis -> dmf`` 原生
        转换不产出有效 DMF，因此直接抛出 UnsupportedFormatError。
        """
        warnings.warn(
            "FileConverter.mapgis_to_dmf() 已废弃，"
            "请使用 FileConverter(src, dst).convert()",
            DeprecationWarning,
            stacklevel=3,
        )
        raise UnsupportedFormatError(
            "暂不支持的转换方向: mgis -> dmf（MapGIS 仅支持作为目标格式，即 dmf -> mgis）"
        )

    @classmethod
    def dmf_to_mapgis(
        cls, dmf_file: Union[str, Path], mapgis_file: Union[str, Path]
    ) -> ConversionResult:
        """DMF 文件转 MapGIS 格式（已废弃）"""
        return cls._legacy_convert(
            dmf_file,
            mapgis_file,
            _warn_msg=(
                "FileConverter.dmf_to_mapgis() 已废弃，"
                "请使用 FileConverter(src, dst).convert()"
            ),
        )

result property

已废弃，请使用 .convert()

source_format property

源文件格式

target_format property

目标文件格式

cad_to_dmf(cad_file, dmf_file) classmethod

AutoCAD 文件转 DMF 格式（已废弃）

Source code in dimine_python_sdk\lib\io\file_converter.py

@classmethod
def cad_to_dmf(
    cls, cad_file: Union[str, Path], dmf_file: Union[str, Path]
) -> ConversionResult:
    """AutoCAD 文件转 DMF 格式（已废弃）"""
    return cls._legacy_convert(
        cad_file,
        dmf_file,
        _warn_msg=(
            "FileConverter.cad_to_dmf() 已废弃，"
            "请使用 FileConverter(src, dst).convert()"
        ),
    )

convert()

执行文件格式转换

Source code in dimine_python_sdk\lib\io\file_converter.py

def convert(self) -> ConversionResult:
    """执行文件格式转换"""
    return convert_file_impl(self.source, self.target, self.options)

datamine_to_dmf(datamine_file, dmf_file) classmethod

DataMine 文件转 DMF 格式（已废弃）

Source code in dimine_python_sdk\lib\io\file_converter.py

@classmethod
def datamine_to_dmf(
    cls, datamine_file: Union[str, Path], dmf_file: Union[str, Path]
) -> ConversionResult:
    """DataMine 文件转 DMF 格式（已废弃）"""
    return cls._legacy_convert(
        datamine_file,
        dmf_file,
        _warn_msg=(
            "FileConverter.datamine_to_dmf() 已废弃，"
            "请使用 FileConverter(src, dst).convert()"
        ),
    )

dmf_to_cad(dmf_file, cad_file) classmethod

DMF 文件转 AutoCAD 格式（已废弃）

Source code in dimine_python_sdk\lib\io\file_converter.py

@classmethod
def dmf_to_cad(
    cls, dmf_file: Union[str, Path], cad_file: Union[str, Path]
) -> ConversionResult:
    """DMF 文件转 AutoCAD 格式（已废弃）"""
    return cls._legacy_convert(
        dmf_file,
        cad_file,
        _warn_msg=(
            "FileConverter.dmf_to_cad() 已废弃，"
            "请使用 FileConverter(src, dst).convert()"
        ),
    )

dmf_to_mapgis(dmf_file, mapgis_file) classmethod

DMF 文件转 MapGIS 格式（已废弃）

Source code in dimine_python_sdk\lib\io\file_converter.py

@classmethod
def dmf_to_mapgis(
    cls, dmf_file: Union[str, Path], mapgis_file: Union[str, Path]
) -> ConversionResult:
    """DMF 文件转 MapGIS 格式（已废弃）"""
    return cls._legacy_convert(
        dmf_file,
        mapgis_file,
        _warn_msg=(
            "FileConverter.dmf_to_mapgis() 已废弃，"
            "请使用 FileConverter(src, dst).convert()"
        ),
    )

dmf_to_micromine(dmf_file, micromine_file) classmethod

DMF 文件转 MicroMine 格式（已废弃）

Source code in dimine_python_sdk\lib\io\file_converter.py

@classmethod
def dmf_to_micromine(
    cls, dmf_file: Union[str, Path], micromine_file: Union[str, Path]
) -> ConversionResult:
    """DMF 文件转 MicroMine 格式（已废弃）"""
    return cls._legacy_convert(
        dmf_file,
        micromine_file,
        _warn_msg=(
            "FileConverter.dmf_to_micromine() 已废弃，"
            "请使用 FileConverter(src, dst).convert()"
        ),
    )

dmf_to_surpac(dmf_file, surpac_file) classmethod

DMF 文件转 Surpac 格式（已废弃）

Source code in dimine_python_sdk\lib\io\file_converter.py

@classmethod
def dmf_to_surpac(
    cls, dmf_file: Union[str, Path], surpac_file: Union[str, Path]
) -> ConversionResult:
    """DMF 文件转 Surpac 格式（已废弃）"""
    return cls._legacy_convert(
        dmf_file,
        surpac_file,
        _warn_msg=(
            "FileConverter.dmf_to_surpac() 已废弃，"
            "请使用 FileConverter(src, dst).convert()"
        ),
    )

from_dmf()

从 DMF 格式转换

Source code in dimine_python_sdk\lib\io\file_converter.py

def from_dmf(self) -> ConversionResult:
    """从 DMF 格式转换"""
    if self.source_format != FileFormat.DMF:
        raise UnsupportedFormatError(
            f"from_dmf() 要求源格式为 .dmf，当前为 {self.source_format.value}"
        )
    return self.convert()

mapgis_to_dmf(mapgis_file, dmf_file) classmethod

MapGIS 文件转 DMF 格式（已废弃，且该方向当前不可用）。

MapGIS 目前仅支持作为目标格式（dmf -> mgis）；mgis -> dmf 原生 转换不产出有效 DMF，因此直接抛出 UnsupportedFormatError。

Source code in dimine_python_sdk\lib\io\file_converter.py

@classmethod
def mapgis_to_dmf(
    cls, mapgis_file: Union[str, Path], dmf_file: Union[str, Path]
) -> ConversionResult:
    """MapGIS 文件转 DMF 格式（已废弃，且该方向当前不可用）。

    MapGIS 目前仅支持作为目标格式（``dmf -> mgis``）；``mgis -> dmf`` 原生
    转换不产出有效 DMF，因此直接抛出 UnsupportedFormatError。
    """
    warnings.warn(
        "FileConverter.mapgis_to_dmf() 已废弃，"
        "请使用 FileConverter(src, dst).convert()",
        DeprecationWarning,
        stacklevel=3,
    )
    raise UnsupportedFormatError(
        "暂不支持的转换方向: mgis -> dmf（MapGIS 仅支持作为目标格式，即 dmf -> mgis）"
    )

micromine_to_dmf(micromine_file, dmf_file) classmethod

MicroMine 文件转 DMF 格式（已废弃）

Source code in dimine_python_sdk\lib\io\file_converter.py

@classmethod
def micromine_to_dmf(
    cls, micromine_file: Union[str, Path], dmf_file: Union[str, Path]
) -> ConversionResult:
    """MicroMine 文件转 DMF 格式（已废弃）"""
    return cls._legacy_convert(
        micromine_file,
        dmf_file,
        _warn_msg=(
            "FileConverter.micromine_to_dmf() 已废弃，"
            "请使用 FileConverter(src, dst).convert()"
        ),
    )

surpac_to_dmf(surpac_file, dmf_file) classmethod

Surpac 文件转 DMF 格式（已废弃）

Source code in dimine_python_sdk\lib\io\file_converter.py

@classmethod
def surpac_to_dmf(
    cls, surpac_file: Union[str, Path], dmf_file: Union[str, Path]
) -> ConversionResult:
    """Surpac 文件转 DMF 格式（已废弃）"""
    return cls._legacy_convert(
        surpac_file,
        dmf_file,
        _warn_msg=(
            "FileConverter.surpac_to_dmf() 已废弃，"
            "请使用 FileConverter(src, dst).convert()"
        ),
    )

to_dmf()

转换为 DMF 格式

Source code in dimine_python_sdk\lib\io\file_converter.py

def to_dmf(self) -> ConversionResult:
    """转换为 DMF 格式"""
    if self.target_format != FileFormat.DMF:
        raise UnsupportedFormatError(
            f"to_dmf() 要求目标格式为 .dmf，当前为 {self.target_format.value}"
        )
    return self.convert()

FileFormat

Bases: StrEnum

支持的文件格式（枚举值为小写扩展名，含前导点）

Source code in dimine_python_sdk\models\file_format.py

class FileFormat(StrEnum):
    """支持的文件格式（枚举值为小写扩展名，含前导点）"""

    # 通用采矿软件交换格式
    DMF = ".dmf"
    DWG = ".dwg"
    SURPAC = ".dtm"
    MICROMINE = ".str"
    DATAMINE = ".dm"
    MAPGIS = ".mgis"

    # 钻孔数据库
    DMD = ".dmd"
    DMG = ".dmg"

UnsupportedFormatError

Bases: FileConversionError

不支持的文件格式或转换方向

Source code in dimine_python_sdk\lib\io\file_converter.py

class UnsupportedFormatError(FileConversionError):
    """不支持的文件格式或转换方向"""
    pass

convert_file(source, target, *, overwrite=True, options=None)

便捷函数：执行文件格式转换。

:param source: 源文件路径 :param target: 目标文件路径 :param overwrite: 是否覆盖已存在的目标文件 :param options: 高级转换选项（传入时忽略 overwrite） :return: ConversionResult（output_path 为实际产物；MapGIS 等文件夹形式 格式返回的是文件夹路径，可用 is_directory 判断）

Source code in dimine_python_sdk\lib\io\file_converter.py

def convert_file(
    source: Union[str, Path],
    target: Union[str, Path],
    *,
    overwrite: bool = True,
    options: Optional[ConvertOptions] = None,
) -> ConversionResult:
    """
    便捷函数：执行文件格式转换。

    :param source: 源文件路径
    :param target: 目标文件路径
    :param overwrite: 是否覆盖已存在的目标文件
    :param options: 高级转换选项（传入时忽略 overwrite）
    :return: ConversionResult（``output_path`` 为实际产物；MapGIS 等文件夹形式
        格式返回的是文件夹路径，可用 ``is_directory`` 判断）
    """
    opts = options or ConvertOptions(overwrite=overwrite)
    return FileConverter(source, target, options=opts).convert()

convert_file_impl(source, target, options=None)

执行文件格式转换。

:return: ConversionResult 结果对象 :raises UnsupportedFormatError: 格式或转换方向不支持 :raises ConversionFailedError: 转换执行失败

Source code in dimine_python_sdk\lib\io\file_converter.py

def convert_file_impl(
    source: Union[str, Path],
    target: Union[str, Path],
    options: Optional[ConvertOptions] = None,
) -> ConversionResult:
    """
    执行文件格式转换。

    :return: ConversionResult 结果对象
    :raises UnsupportedFormatError: 格式或转换方向不支持
    :raises ConversionFailedError: 转换执行失败
    """
    source_path = Path(source)
    target_path = Path(target)
    options = options or ConvertOptions()

    try:
        src_fmt = FileFormat(source_path.suffix.lower())
    except ValueError:
        raise UnsupportedFormatError(f"不支持的源文件格式: {source_path.suffix}")

    try:
        tgt_fmt = FileFormat(target_path.suffix.lower())
    except ValueError:
        raise UnsupportedFormatError(f"不支持的目标文件格式: {target_path.suffix}")

    # 产物不一定是 target 文件本身：.mgis 等格式产出同名文件夹
    output_path = _output_artifact_path(target_path)
    output_dir = output_path if output_path != target_path else None

    if output_path.exists() and not options.overwrite:
        return ConversionResult(
            success=False,
            source=source_path,
            target=target_path,
            message=f"目标文件已存在: {output_path}",
            output_dir=output_dir,
        )

    if src_fmt == FileFormat.DMD and tgt_fmt == FileFormat.DMG:
        fn = _dmd_to_dmg
    else:
        fn = None

    if fn is None:
        # 其它方向统一交给 native.io.convert_file 处理
        try:
            _native_convert_file(str(source_path), str(target_path))
        except NativeIOError as exc:
            message = str(exc)
            if "不支持" in message:
                raise UnsupportedFormatError(message) from exc
            raise ConversionFailedError(
                message,
                source=source_path,
                target=target_path,
            ) from exc
        except Exception as exc:
            raise ConversionFailedError(
                f"转换异常: {exc}",
                source=source_path,
                target=target_path,
            ) from exc

        return ConversionResult(
            success=True,
            source=source_path,
            target=target_path,
            message="转换成功",
            output_dir=output_dir,
        )

    try:
        ok = fn(str(source_path), str(target_path))
    except Exception as exc:
        raise ConversionFailedError(
            f"转换异常: {exc}",
            source=source_path,
            target=target_path,
        ) from exc

    if not ok:
        raise ConversionFailedError(
            f"转换失败: {source_path} -> {target_path}",
            source=source_path,
            target=target_path,
        )

    return ConversionResult(
        success=True,
        source=source_path,
        target=target_path,
        message="转换成功",
    )

dmf_to_other(s_file, t_file)

DMF 与 Cad/Surpac/Micromine/MapGis 互转、DataMine 转 DMF（已废弃）。

请使用 :func:convert_file 替代。

Source code in dimine_python_sdk\lib\io\file_converter.py

def dmf_to_other(
    s_file: Union[str, Path], t_file: Union[str, Path]
) -> ConversionResult:
    """
    DMF 与 Cad/Surpac/Micromine/MapGis 互转、DataMine 转 DMF（已废弃）。

    请使用 :func:`convert_file` 替代。
    """
    warnings.warn(
        "dmf_to_other() 已废弃，请使用 convert_file()",
        DeprecationWarning,
        stacklevel=2,
    )
    return convert_file(s_file, t_file)