file_conversion

应用层：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

文件转换结果

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

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

    def __init__(
        self,
        success: bool,
        source: Path,
        target: Path,
        message: str = "",
    ):
        self.success = success
        self.source = source
        self.target = target
        self.message = message

    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 output_path(self) -> Path:
        """输出文件路径"""
        return self.target

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 格式（已废弃）"""
        return cls._legacy_convert(
            mapgis_file,
            dmf_file,
            _warn_msg=(
                "FileConverter.mapgis_to_dmf() 已废弃，"
                "请使用 FileConverter(src, dst).convert()"
            ),
        )

    @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 格式（已废弃）

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 格式（已废弃）"""
    return cls._legacy_convert(
        mapgis_file,
        dmf_file,
        _warn_msg=(
            "FileConverter.mapgis_to_dmf() 已废弃，"
            "请使用 FileConverter(src, dst).convert()"
        ),
    )

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\lib\io\file_converter.py

class FileFormat(StrEnum):
    """支持的文件格式"""

    DMF = ".dmf"
    DWG = ".dwg"
    SURPAC = ".dtm"
    MICROMINE = ".str"
    DATAMINE = ".dat"
    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

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
    """
    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}")

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

    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="转换成功",
        )

    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)

DMD 转 DMG

FileConverter 与 convert_file() 支持将数据表形式存储的钻孔数据库（.dmd）打包为三维模型 + 数据形式（.dmg）。该转换方向为单向，暂不支持 DMG → DMD。

from dimine_python_sdk.lib.io import convert_file

result = convert_file("钻孔数据.dmd", "钻孔数据.dmg")
print(result)  # <ConversionResult 成功: 钻孔数据.dmd -> 钻孔数据.dmg>