How to Generate 2D DXF Drawings with the DXF Skill

The DXF Skill converts Python scripts using the build123d library into deterministic 2D DXF files through a decorator-based workflow that ensures reproducible CAD output.

The DXF Skill in the earthtojake/text-to-cad repository provides a streamlined interface for generating 2D DXF drawings directly from Python code. By leveraging the build123d geometry kernel, you can define complex 2D profiles programmatically and export them as industry-standard DXF files with guaranteed deterministic output.

Understanding the DXF Skill Architecture

The DXF Skill is documented in [skills/dxf/SKILL.md](https://github.com/earthtojake/text-to-cad/blob/main/skills/dxf/SKILL.md) and implements three distinct workflows: stand-alone drafting, drawing generation from 3D parts, and deterministic regeneration with validation. At its core, the skill interprets Python scripts containing decorated functions that return build123d geometry objects.

The architecture separates concerns between geometry construction and file emission. The [packages/cadgen/src/cadgen/dxf.py](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/dxf.py) module handles the @dxf decorator logic, while [packages/cadgen/src/cadgen/_internal/dxf_emit.py](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/_internal/dxf_emit.py) manages the low-level translation of build123d objects into ezdxf entities.

Setting Up Your Drawing Script

To generate 2D DXF drawings, create a Python file in your project's src/ directory. The script must define a single function decorated with @dxf that returns a build123d object such as bd.Face, bd.Polyline, or bd.Text.

The decorator accepts an out parameter specifying the output path, typically within the DXF/ directory. Your function should construct 2D geometry using build123d primitives like lines, circles, arcs, and polylines.

# src/plate_drawing.py

import build123d as bd
from cadgen import dxf

@dxf(out="DXF/plate_drawing.dxf")
def plate():
    # Create a rectangular plate with a centered hole

    plate = bd.Box(100, 200, 0)          # 2D box with zero thickness

    hole = bd.Circle(r=20)               # 2D circle

    return plate - hole                  # Subtract hole from plate

Executing the DXF Skill

Once your script contains the decorated function, invoke the skill using the $dxf alias or the explicit CLI command cadgen dxf. The engine executes your Python script, processes the returned geometry, and writes the DXF file to the specified output location.

Using the Command Line Interface

The primary entry point resides in [packages/cadgen/src/cadgen/cli/dxf_snapshot.py](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cli/dxf_snapshot.py). Pass your script path as the first argument:

# Using the skill alias

$dxf src/plate_drawing.py

# Or the explicit CLI form

cadgen dxf src/plate_drawing.py

The CLI prints progress information to stderr, concluding with the absolute path of the generated DXF file.

Validation and Deterministic Output

The DXF Skill guarantees byte-for-byte reproducibility. To verify that your drawing matches the source geometry exactly, run the validator using either the --validate or --json flags:

# Print deterministic hash as JSON

cadgen dxf src/plate_drawing.py --json

# Or validate directly

cadgen dxf src/plate_drawing.py --validate

This deterministic behavior ensures that identical geometry always produces identical DXF files, making the skill suitable for version-controlled CAD workflows.

Core Implementation Details

Understanding the internal pipeline helps troubleshoot complex drawings. The @dxf decorator in cadgen/dxf.py intercepts the decorated function's return value and passes it to the emission layer. The dxf_emit.py module translates build123d entities into DXF primitives using the ezdxf library, handling entity types including lines, circles, arcs, and text outlines.

The CLI layer in dxf_snapshot.py manages script execution context, ensuring that relative paths resolve correctly and that the build environment matches the skill's expectations.

Summary

• Place DXF generation scripts in the src/ directory with the @dxf decorator to define exportable geometry.
• Use cadgen dxf <script.py> or the $dxf alias to execute the skill and generate files in the DXF/ directory.
• Leverage build123d's 2D primitives—boxes, circles, polylines, and text—to construct complex profiles programmatically.
• Validate output determinism using --json or --validate flags to ensure reproducible builds.
• Key source files include skills/dxf/SKILL.md for documentation and packages/cadgen/src/cadgen/dxf.py for the core implementation.

Frequently Asked Questions

What Python libraries are required to use the DXF Skill?

The DXF Skill requires build123d for geometry construction and ezdxf for file format handling. Import the decorator from cadgen (provided by the text-to-cad framework) rather than installing it separately.

Where does the DXF Skill save generated files?

Output files are written to the path specified in the decorator's out parameter, typically DXF/<filename>.dxf relative to the project root. The CLI confirms the exact file location in the final output line.

How does the DXF Skill ensure deterministic output?

The skill implements deterministic emission logic in dxf_emit.py that orders entities consistently and fixes floating-point precision. This ensures that identical geometry produces byte-for-byte identical DXF files across different execution environments.

Can I generate 2D drawings from existing 3D parts?

Yes. The DXF Skill supports extracting 2D projections and sections from 3D build123d parts. Define your @dxf function to accept 3D geometry as input and return a 2D projection using build123d's slicing or projection methods before DXF export.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}