cad2image 0.1.0__py3-none-any.whl

cad2image/__init__.py

@@ -0,0 +1,34 @@
+"""cad2image — DWG/DXF → PNG/SVG 渲染管线。
+
+用 ODA File Converter（DWG→DXF）+ ezdxf（DXF→PNG/SVG）重建 Acme CAD Converter
+的渲染能力，消除 GDI 栅格化路径产生的「残余杂线」问题。
+
+公开接口：
+    - convert_dwg_to_dxf / convert_directory：DWG → DXF（ODA File Converter 封装）
+    - render_dxf / render_to_png / render_to_svg：DXF → PNG/SVG（ezdxf 渲染核心）
+    - process_dwg / process_directory：单文件 / 目录批处理
+    - RenderOptions：渲染参数
+"""
+
+from cad2image.batch import BatchResult, process_directory, process_dwg
+from cad2image.config import RenderOptions, get_oda_converter_path
+from cad2image.dwg2dxf import convert_directory, convert_dwg_to_dxf
+from cad2image.plotstyle import get_lineweight, load_ctb
+from cad2image.render import render_dxf, render_to_png, render_to_svg
+
+__all__ = [
+    "BatchResult",
+    "RenderOptions",
+    "convert_directory",
+    "convert_dwg_to_dxf",
+    "get_lineweight",
+    "get_oda_converter_path",
+    "load_ctb",
+    "process_directory",
+    "process_dwg",
+    "render_dxf",
+    "render_to_png",
+    "render_to_svg",
+]
+
+__version__ = "0.1.0"

cad2image/__main__.py

@@ -0,0 +1,6 @@
+"""支持 ``python -m cad2image`` 直接调用 CLI。"""
+
+from cad2image.cli import app
+
+if __name__ == "__main__":
+    app()

cad2image/batch.py

@@ -0,0 +1,158 @@
+"""批量处理：多文件转换与渲染，支持部分失败不中断整批。
+
+批处理遵循「单条失败不中止整批」原则：每个文件独立转换与渲染，异常被捕获并记录，
+最终返回包含 ``successes`` / ``failures`` 的结果对象。
+"""
+
+from __future__ import annotations
+
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from cad2image.config import RenderOptions
+from cad2image.dwg2dxf import convert_directory, convert_dwg_to_dxf
+from cad2image.render import render_dxf
+
+# 支持输出的图片格式。
+_SUPPORTED_FORMATS = {"png", "svg"}
+
+
+@dataclass
+class BatchFailure:
+    """单个文件处理失败的信息。
+
+    Attributes:
+        source: 源 DWG 文件路径。
+        stage: 失败阶段，``convert``（DWG→DXF）或 ``render``（DXF→图片）。
+        error: 错误信息。
+    """
+
+    source: Path
+    stage: str
+    error: str
+
+
+@dataclass
+class BatchResult:
+    """批处理结果。
+
+    Attributes:
+        successes: 成功生成的图片文件路径列表。
+        failures: 失败项列表。
+    """
+
+    successes: list[Path] = field(default_factory=list)
+    failures: list[BatchFailure] = field(default_factory=list)
+
+    @property
+    def success_count(self) -> int:
+        """成功文件数。"""
+        return len(self.successes)
+
+    @property
+    def failure_count(self) -> int:
+        """失败文件数。"""
+        return len(self.failures)
+
+
+def process_dwg(
+    dwg_path: str | Path,
+    output_dir: str | Path,
+    options: RenderOptions,
+    *,
+    output_format: str = "png",
+    oda_path: str | Path | None = None,
+) -> Path:
+    """处理单个 DWG：DWG→DXF→图片。
+
+    Args:
+        dwg_path: 源 DWG 文件路径。
+        output_dir: 图片输出目录。
+        options: 渲染参数。
+        output_format: 输出格式，``png`` 或 ``svg``。
+        oda_path: ODA File Converter 可执行文件路径。
+
+    Returns:
+        生成的图片文件路径。
+
+    Raises:
+        ValueError: 当 ``output_format`` 不受支持时。
+        FileNotFoundError: 当源文件或 ODA 可执行文件不存在时。
+        RuntimeError: 当转换或渲染失败时。
+    """
+    _validate_format(output_format)
+    source = Path(dwg_path)
+    target_dir = Path(output_dir)
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    with tempfile.TemporaryDirectory(prefix="oda_single_") as dxf_dir:
+        dxf = convert_dwg_to_dxf(source, dxf_dir, oda_path=oda_path)
+        output = target_dir / f"{source.stem}.{output_format}"
+        render_dxf(dxf, output, options)
+        return output
+
+
+def process_directory(
+    input_dir: str | Path,
+    output_dir: str | Path,
+    options: RenderOptions,
+    *,
+    output_format: str = "png",
+    recursive: bool = False,
+    oda_path: str | Path | None = None,
+) -> BatchResult:
+    """批量处理目录内全部 DWG 文件。
+
+    先一次性目录级转换 DWG→DXF，再逐文件渲染。单文件失败不中断整批。
+
+    Args:
+        input_dir: 包含 DWG 的输入目录。
+        output_dir: 图片输出目录。
+        options: 渲染参数。
+        output_format: 输出格式，``png`` 或 ``svg``。
+        recursive: 是否递归处理子目录。
+        oda_path: ODA File Converter 可执行文件路径。
+
+    Returns:
+        包含成功与失败明细的 ``BatchResult``。
+    """
+    _validate_format(output_format)
+    source_dir = Path(input_dir)
+    target_dir = Path(output_dir)
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    dwg_files = sorted(source_dir.rglob("*.dwg") if recursive else source_dir.glob("*.dwg"))
+    result = BatchResult()
+    if not dwg_files:
+        return result
+
+    with tempfile.TemporaryDirectory(prefix="oda_batch_") as dxf_dir:
+        try:
+            convert_directory(source_dir, dxf_dir, oda_path=oda_path, recursive=recursive)
+        except (FileNotFoundError, RuntimeError) as exc:
+            for dwg in dwg_files:
+                result.failures.append(BatchFailure(dwg, "convert", str(exc)))
+            return result
+
+        for dwg in dwg_files:
+            relative = dwg.relative_to(source_dir)
+            dxf = Path(dxf_dir) / relative.with_suffix(".dxf")
+            if not dxf.is_file():
+                result.failures.append(BatchFailure(dwg, "convert", "未生成 DXF 文件"))
+                continue
+            try:
+                output = target_dir / relative.with_suffix(f".{output_format}")
+                output.parent.mkdir(parents=True, exist_ok=True)
+                render_dxf(dxf, output, options)
+                result.successes.append(output)
+            except (FileNotFoundError, ValueError, RuntimeError) as exc:
+                result.failures.append(BatchFailure(dwg, "render", str(exc)))
+
+    return result
+
+
+def _validate_format(output_format: str) -> None:
+    """校验输出格式，非法时 fail-fast。"""
+    if output_format not in _SUPPORTED_FORMATS:
+        raise ValueError(f"不支持的输出格式 '{output_format}'，仅支持：{', '.join(sorted(_SUPPORTED_FORMATS))}")

cad2image/cli.py

@@ -0,0 +1,152 @@
+"""命令行入口（typer）。
+
+支持三种输入：
+
+- 单个 DXF 文件 → 直接渲染为 PNG/SVG
+- 单个 DWG 文件 → 先经 ODA 转 DXF，再渲染
+- 目录 → 批量处理（部分失败不中断整批）
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+import typer
+
+from cad2image.batch import BatchResult, process_directory
+from cad2image.config import RenderOptions
+from cad2image.dwg2dxf import convert_dwg_to_dxf
+from cad2image.render import render_dxf
+
+app = typer.Typer(
+    name="cad2image",
+    help="DWG/DXF → PNG/SVG 渲染管线（ODA File Converter + ezdxf）。",
+    add_completion=False,
+)
+
+# 进程退出码语义（对齐 Acme 报告：0 成功 / 1 通用失败）。
+_EXIT_OK = 0
+_EXIT_ERROR = 1
+
+
+@app.command()
+def render(
+    input_path: Path = typer.Argument(..., exists=True, help="输入：DWG/DXF 文件，或包含 DWG 的目录"),
+    output: Path = typer.Option(None, "--output", "-o", help="输出文件/目录；缺省与输入同目录"),
+    dpi: int = typer.Option(300, "--dpi", help="PNG 分辨率（DPI）"),
+    output_format: str = typer.Option("png", "--format", "-f", help="输出格式：png / svg"),
+    background: str = typer.Option("white", "--background", help="背景策略：default/white/black/off"),
+    color: str = typer.Option("color", "--color", help="颜色策略：color/monochrome/grayscale/black/white"),
+    lineweight: str = typer.Option("absolute", "--lineweight", help="线宽策略：absolute/relative"),
+    lineweight_scaling: float = typer.Option(1.0, "--lineweight-scaling", help="线宽整体缩放系数（仅绝对线宽生效）"),
+    min_lineweight: float = typer.Option(None, "--min-lineweight", help="最小打印线宽（mm）"),
+    relative_max_stroke_width: float = typer.Option(0.001, "--relative-max-stroke-width", help="相对线宽：最粗线宽占页面较小边比例（默认 0.1%）"),
+    relative_min_stroke_width: float = typer.Option(0.05, "--relative-min-stroke-width", help="相对线宽：最细线宽占最粗线宽比例（默认 5%）"),
+    ctb: str = typer.Option("", "--ctb", help="CTB 打印样式表路径"),
+    font_dir: str = typer.Option("", "--font-dir", help="附加的 SHX/TTF 字体目录"),
+    layout: str = typer.Option(None, "--layout", help="布局名；缺省渲染模型空间"),
+    width: float = typer.Option(None, "--width", help="页面宽度（mm）"),
+    height: float = typer.Option(None, "--height", help="页面高度（mm）"),
+    fit: bool = typer.Option(False, "--fit", help="按内容包围盒自适应页面尺寸"),
+    margin: float = typer.Option(3.0, "--margin", help="内容自适应页面时的四周余量（%，相对内容较小边）"),
+    recursive: bool = typer.Option(False, "--recursive", help="目录批量时递归处理子目录"),
+    oda_path: Path = typer.Option(None, "--oda-path", help="ODAFileConverter.exe 路径；缺省从环境变量/默认路径解析"),
+) -> None:
+    """把 DWG/DXF 渲染为 PNG 或 SVG。"""
+    options = RenderOptions(
+        dpi=dpi,
+        background=background,
+        color_policy=color,
+        lineweight_policy=lineweight,
+        lineweight_scaling=lineweight_scaling,
+        min_lineweight=min_lineweight,
+        relative_max_stroke_width=relative_max_stroke_width,
+        relative_min_stroke_width=relative_min_stroke_width,
+        ctb=ctb,
+        font_dir=font_dir,
+        layout_name=layout,
+        width_mm=width,
+        height_mm=height,
+        fit_to_extents=fit,
+        margin=margin,
+    )
+    try:
+        _run(input_path, output, options, output_format, recursive, oda_path)
+    except (FileNotFoundError, ValueError, RuntimeError, NotImplementedError) as exc:
+        typer.echo(f"错误：{exc}", err=True)
+        raise typer.Exit(code=_EXIT_ERROR) from exc
+
+
+def _run(
+    input_path: Path,
+    output: Path | None,
+    options: RenderOptions,
+    output_format: str,
+    recursive: bool,
+    oda_path: Path | None,
+) -> None:
+    """根据输入类型分发到单文件或目录批处理。"""
+    if input_path.is_dir():
+        _run_batch(input_path, output or input_path, options, output_format, recursive, oda_path)
+        return
+
+    if input_path.suffix.lower() == ".dxf":
+        target = output or input_path.with_suffix(f".{output_format}")
+        render_dxf(input_path, target, options)
+        typer.echo(f"已生成：{target}")
+        return
+
+    if input_path.suffix.lower() == ".dwg":
+        _run_single_dwg(input_path, output, options, output_format, oda_path)
+        return
+
+    raise ValueError(f"不支持的文件类型 '{input_path.suffix}'，仅支持 .dwg / .dxf")
+
+
+def _run_single_dwg(
+    input_path: Path,
+    output: Path | None,
+    options: RenderOptions,
+    output_format: str,
+    oda_path: Path | None,
+) -> None:
+    """处理单个 DWG：临时目录转换 + 渲染到指定输出。"""
+    target = output or input_path.with_suffix(f".{output_format}")
+    with tempfile.TemporaryDirectory(prefix="oda_cli_") as dxf_dir:
+        dxf = convert_dwg_to_dxf(input_path, dxf_dir, oda_path=oda_path)
+        render_dxf(dxf, target, options)
+    typer.echo(f"已生成：{target}")
+
+
+def _run_batch(
+    input_dir: Path,
+    output_dir: Path,
+    options: RenderOptions,
+    output_format: str,
+    recursive: bool,
+    oda_path: Path | None,
+) -> None:
+    """批量处理目录，打印汇总报告；存在失败时返回非零退出码。"""
+    result = process_directory(
+        input_dir,
+        output_dir,
+        options,
+        output_format=output_format,
+        recursive=recursive,
+        oda_path=oda_path,
+    )
+    _print_report(result)
+    if result.failure_count > 0:
+        raise typer.Exit(code=_EXIT_ERROR)
+
+
+def _print_report(result: BatchResult) -> None:
+    """打印批处理汇总，失败明细输出到 stderr。"""
+    typer.echo(f"完成：成功 {result.success_count}，失败 {result.failure_count}")
+    for failure in result.failures:
+        typer.echo(f"  失败[{failure.stage}] {failure.source.name}: {failure.error}", err=True)
+
+
+if __name__ == "__main__":
+    app()

cad2image/config.py

@@ -0,0 +1,164 @@
+"""配置解析与渲染参数映射。
+
+提供两部分能力：
+
+1. ODA File Converter 可执行文件路径的解析（环境变量优先，默认安装路径兜底）。
+2. 将面向用户的 ``RenderOptions`` 映射为 ezdxf ``Configuration``，
+   集中处理 Acme CAD Converter 参数语义到 ezdxf 的对应关系。
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from ezdxf.addons.drawing import config as draw_config
+
+# ODA File Converter 的默认安装路径（Windows）。允许通过环境变量覆盖。
+_DEFAULT_ODA_PATH = Path(r"D:\ODA\ODAFileConverter_title 21.5.0\ODAFileConverter.exe")
+
+# 覆盖 ODA 安装路径的环境变量名。
+_ODA_PATH_ENV = "ODA_FILE_CONVERTER_PATH"
+
+# 合法的背景、颜色与线宽策略取值，用于 fail-fast 校验。
+_BACKGROUND_CHOICES = {"default", "white", "black", "off", "none"}
+_COLOR_POLICY_CHOICES = {"color", "monochrome", "grayscale", "black", "white"}
+_LINEWEIGHT_POLICY_CHOICES = {"absolute", "relative"}
+
+
+def get_oda_converter_path() -> Path:
+    """返回 ODA File Converter 可执行文件的路径。
+
+    优先读取环境变量 ``ODA_FILE_CONVERTER_PATH``，未设置时回退到默认安装路径。
+
+    Returns:
+        ``ODAFileConverter.exe`` 的绝对路径。
+    """
+    env_path = os.getenv(_ODA_PATH_ENV)
+    if env_path:
+        return Path(env_path).expanduser()
+    return _DEFAULT_ODA_PATH
+
+
+@dataclass
+class RenderOptions:
+    """面向用户的渲染参数。
+
+    Attributes:
+        dpi: 输出分辨率（PNG）。默认 300。
+        background: 背景策略，``default/white/black/off``。默认 ``white``。
+        color_policy: 颜色策略，``color/monochrome/grayscale/black/white``。默认 ``color``。
+        lineweight_policy: 线宽策略，``absolute/relative``。默认 ``absolute``。
+        lineweight_scaling: 线宽整体缩放系数，乘到每条线的线宽上（仅绝对线宽策略生效）。默认 1.0。
+        min_lineweight: 最小打印线宽（mm），``None`` 表示不设下限。
+        relative_max_stroke_width: 相对线宽策略下，最粗线宽（2.11mm）占页面较小边的比例。默认 0.001（0.1%）。
+        relative_min_stroke_width: 相对线宽策略下，最细线宽（0.05mm）占最粗线宽的比例。默认 0.05（5%）。
+        ctb: CTB 打印样式表路径，``""`` 表示不使用。
+        font_dir: 附加的 SHX/TTF 字体目录，``""`` 表示仅用系统字体。
+        layout_name: 要渲染的布局名，``None`` 表示模型空间。默认 ``None``。
+        width_mm: 显式页面宽度（mm），``None`` 表示按布局/范围自适应。
+        height_mm: 显式页面高度（mm），``None`` 表示按布局/范围自适应。
+        fit_to_extents: 是否按模型空间内容范围自适应页面尺寸。默认 ``False``。
+        margin: 内容范围自适应时的四周余量，按内容较小边的百分比（0–100）。默认 3.0。
+    """
+
+    dpi: int = 300
+    background: str = "white"
+    color_policy: str = "color"
+    lineweight_policy: str = "absolute"
+    lineweight_scaling: float = 1.0
+    min_lineweight: float | None = None
+    relative_max_stroke_width: float = 0.001
+    relative_min_stroke_width: float = 0.05
+    ctb: str = ""
+    font_dir: str = ""
+    layout_name: str | None = None
+    width_mm: float | None = None
+    height_mm: float | None = None
+    fit_to_extents: bool = False
+    margin: float = 3.0
+
+
+def build_drawing_configuration(options: RenderOptions) -> draw_config.Configuration:
+    """将 ``RenderOptions`` 映射为 ezdxf ``Configuration``。
+
+    在边界处完成校验（fail-fast），非法的策略取值抛出 ``ValueError``。
+
+    Args:
+        options: 面向用户的渲染参数。
+
+    Returns:
+        可直接传给 ``ezdxf.addons.drawing.Frontend`` 的配置对象。
+
+    Raises:
+        ValueError: 当背景/颜色/线宽策略或 DPI 取值非法时。
+    """
+    if options.dpi <= 0:
+        raise ValueError(f"DPI 必须为正整数，得到 {options.dpi}")
+    if options.lineweight_scaling <= 0:
+        raise ValueError(f"线宽缩放系数必须为正数，得到 {options.lineweight_scaling}")
+    if options.min_lineweight is not None and options.min_lineweight <= 0:
+        raise ValueError(f"最小线宽必须为正数，得到 {options.min_lineweight}")
+    if options.relative_max_stroke_width <= 0:
+        raise ValueError(f"相对线宽最粗比例必须为正数，得到 {options.relative_max_stroke_width}")
+    if options.relative_min_stroke_width <= 0:
+        raise ValueError(f"相对线宽最细比例必须为正数，得到 {options.relative_min_stroke_width}")
+    if options.margin < 0:
+        raise ValueError(f"页面余量百分比必须为非负数，得到 {options.margin}")
+
+    background = _map_background_policy(options.background)
+    color_policy = _map_color_policy(options.color_policy)
+    lineweight_policy = _map_lineweight_policy(options.lineweight_policy)
+
+    return draw_config.Configuration(
+        background_policy=background,
+        color_policy=color_policy,
+        lineweight_policy=lineweight_policy,
+        lineweight_scaling=options.lineweight_scaling,
+        min_lineweight=options.min_lineweight,
+    )
+
+
+def _map_background_policy(value: str) -> draw_config.BackgroundPolicy:
+    """把背景策略字符串映射为 ``BackgroundPolicy`` 枚举。"""
+    normalized = value.strip().lower()
+    if normalized not in _BACKGROUND_CHOICES:
+        raise ValueError(f"非法的背景策略 '{value}'，可选：{', '.join(sorted(_BACKGROUND_CHOICES))}")
+    return {
+        "default": draw_config.BackgroundPolicy.DEFAULT,
+        "white": draw_config.BackgroundPolicy.WHITE,
+        "black": draw_config.BackgroundPolicy.BLACK,
+        "off": draw_config.BackgroundPolicy.OFF,
+        "none": draw_config.BackgroundPolicy.OFF,
+    }[normalized]
+
+
+def _map_color_policy(value: str) -> draw_config.ColorPolicy:
+    """把颜色策略字符串映射为 ``ColorPolicy`` 枚举。
+
+    Note:
+        ezdxf 1.1.x 无独立的灰度策略，``grayscale`` 暂以 ``MONOCHROME`` 近似，
+        待 Phase 2 通过像素级后处理实现真正的 256 级灰度。
+    """
+    normalized = value.strip().lower()
+    if normalized not in _COLOR_POLICY_CHOICES:
+        raise ValueError(f"非法的颜色策略 '{value}'，可选：{', '.join(sorted(_COLOR_POLICY_CHOICES))}")
+    return {
+        "color": draw_config.ColorPolicy.COLOR,
+        "monochrome": draw_config.ColorPolicy.MONOCHROME,
+        "grayscale": draw_config.ColorPolicy.MONOCHROME,
+        "black": draw_config.ColorPolicy.BLACK,
+        "white": draw_config.ColorPolicy.WHITE,
+    }[normalized]
+
+
+def _map_lineweight_policy(value: str) -> draw_config.LineweightPolicy:
+    """把线宽策略字符串映射为 ``LineweightPolicy`` 枚举。"""
+    normalized = value.strip().lower()
+    if normalized not in _LINEWEIGHT_POLICY_CHOICES:
+        raise ValueError(f"非法的线宽策略 '{value}'，可选：{', '.join(sorted(_LINEWEIGHT_POLICY_CHOICES))}")
+    return {
+        "absolute": draw_config.LineweightPolicy.ABSOLUTE,
+        "relative": draw_config.LineweightPolicy.RELATIVE,
+    }[normalized]

cad2image/dwg2dxf.py

@@ -0,0 +1,175 @@
+"""DWG → DXF 转换：ODA File Converter 封装。
+
+ODA File Converter 是**目录级**转换工具：一次调用把输入目录内全部文件转换为指定
+格式输出到输出目录。本模块负责处理「单文件 → 临时目录 → 收集输出 → 清理」的编排，
+以及目录级批量转换，全部用 ``tempfile`` + ``with`` 管理临时资源。
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from cad2image.config import get_oda_converter_path
+
+# ODA File Converter 的输入版本（对 DWG 而言通常自动识别，指定为近年版本即可）。
+DEFAULT_INPUT_VERSION = "ACAD2018"
+# 输出版本为 "DXF" 表示输出 ASCII DXF（与 Acme 迁移方案一致）。
+DEFAULT_OUTPUT_VERSION = "DXF"
+
+# 单次转换的超时（秒），避免复杂文件导致进程挂死。
+_CONVERSION_TIMEOUT_SECONDS = 300
+
+
+def convert_dwg_to_dxf(
+    dwg_path: str | Path,
+    output_dir: str | Path,
+    *,
+    oda_path: str | Path | None = None,
+    input_version: str = DEFAULT_INPUT_VERSION,
+    output_version: str = DEFAULT_OUTPUT_VERSION,
+) -> Path:
+    """把单个 DWG 文件转换为 DXF。
+
+    由于 ODA FC 是目录级工具，本函数会把目标 DWG 复制到临时输入目录，转换后从
+    临时输出目录收集生成的 DXF 到 ``output_dir``，最后清理临时目录。
+
+    Args:
+        dwg_path: 源 DWG 文件路径。
+        output_dir: 生成的 DXF 的存放目录。
+        oda_path: ODA File Converter 可执行文件路径，缺省时从环境/默认路径解析。
+        input_version: 输入版本，默认 ``ACAD2018``。
+        output_version: 输出版本，默认 ``DXF``。
+
+    Returns:
+        生成的 DXF 文件路径。
+
+    Raises:
+        FileNotFoundError: 当源 DWG 或 ODA 可执行文件不存在时。
+        RuntimeError: 当转换失败（ODA 退出码非零或未生成 DXF）时。
+    """
+    source = Path(dwg_path)
+    if not source.is_file():
+        raise FileNotFoundError(f"源 DWG 文件不存在：{source}")
+
+    destination = Path(output_dir)
+    destination.mkdir(parents=True, exist_ok=True)
+
+    oda_exe = Path(oda_path) if oda_path else get_oda_converter_path()
+    if not oda_exe.is_file():
+        raise FileNotFoundError(f"ODA File Converter 可执行文件不存在：{oda_exe}")
+
+    with tempfile.TemporaryDirectory(prefix="oda_in_") as in_dir, tempfile.TemporaryDirectory(
+        prefix="oda_out_"
+    ) as out_dir:
+        _copy_source_to_input(source, Path(in_dir))
+        _run_converter(
+            oda_exe,
+            input_dir=Path(in_dir),
+            output_dir=Path(out_dir),
+            input_version=input_version,
+            output_version=output_version,
+        )
+        return _collect_single_dxf(Path(out_dir), source.stem, destination)
+
+
+def convert_directory(
+    input_dir: str | Path,
+    output_dir: str | Path,
+    *,
+    oda_path: str | Path | None = None,
+    input_version: str = DEFAULT_INPUT_VERSION,
+    output_version: str = DEFAULT_OUTPUT_VERSION,
+    recursive: bool = False,
+) -> list[Path]:
+    """把输入目录内全部 DWG 转换为 DXF。
+
+    直接调用 ODA FC 的目录级能力，一次转换整个目录，效率优于逐文件转换。
+
+    Args:
+        input_dir: 包含 DWG 文件的输入目录。
+        output_dir: DXF 输出目录。
+        oda_path: ODA File Converter 可执行文件路径，缺省时从环境/默认路径解析。
+        input_version: 输入版本，默认 ``ACAD2018``。
+        output_version: 输出版本，默认 ``DXF``。
+        recursive: 是否递归处理子目录。
+
+    Returns:
+        生成的 DXF 文件路径列表。
+
+    Raises:
+        FileNotFoundError: 当输入目录或 ODA 可执行文件不存在时。
+        RuntimeError: 当 ODA 转换失败时。
+    """
+    source_dir = Path(input_dir)
+    if not source_dir.is_dir():
+        raise FileNotFoundError(f"输入目录不存在：{source_dir}")
+
+    target_dir = Path(output_dir)
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    oda_exe = Path(oda_path) if oda_path else get_oda_converter_path()
+    if not oda_exe.is_file():
+        raise FileNotFoundError(f"ODA File Converter 可执行文件不存在：{oda_exe}")
+
+    _run_converter(
+        oda_exe,
+        input_dir=source_dir,
+        output_dir=target_dir,
+        input_version=input_version,
+        output_version=output_version,
+        recursive=recursive,
+    )
+    return sorted(target_dir.glob("**/*.dxf") if recursive else target_dir.glob("*.dxf"))
+
+
+def _copy_source_to_input(source: Path, input_dir: Path) -> None:
+    """把单个源 DWG 复制到临时输入目录。"""
+    shutil.copy2(source, input_dir / source.name)
+
+
+def _run_converter(
+    oda_exe: Path,
+    *,
+    input_dir: Path,
+    output_dir: Path,
+    input_version: str,
+    output_version: str,
+    recursive: bool = False,
+) -> None:
+    """调用 ODA File Converter 命令行执行转换。"""
+    command = [
+        str(oda_exe),
+        str(input_dir),
+        str(output_dir),
+        input_version,
+        output_version,
+        "1" if recursive else "0",
+        "1",  # audit：转换前审计文件
+    ]
+    try:
+        completed = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            timeout=_CONVERSION_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise RuntimeError(f"ODA File Converter 转换超时（>{_CONVERSION_TIMEOUT_SECONDS}s）：{input_dir}") from exc
+
+    if completed.returncode != 0:
+        stderr = (completed.stderr or "").strip()
+        raise RuntimeError(f"ODA File Converter 转换失败（退出码 {completed.returncode}）：{stderr or '未知错误'}")
+
+
+def _collect_single_dxf(output_dir: Path, stem: str, destination: Path) -> Path:
+    """从临时输出目录收集生成的 DXF 并移动到目标目录。"""
+    generated = output_dir / f"{stem}.dxf"
+    if not generated.is_file():
+        raise RuntimeError(f"ODA 未生成预期的 DXF 文件：{stem}.dxf")
+    target = destination / generated.name
+    shutil.move(str(generated), str(target))
+    return target