/dxf

name: dxf
description: Generate, regenerate, and validate 2D DXF drawings from Python build123d sources. Use for DXF files, `.py` drawing scripts, @dxf models, 2D profiles, outlines, templates, gaskets, panels, flat patterns, laser/plasma/waterjet cut layouts, and 2D drawing exports of CAD geometry.

DXF generation and validation

Provenance: maintained in [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad). Use the installed local skill files as the runtime source of truth; the repository link is only for provenance and release review.

Setup

This skill's commands are thin entrypoints over the `cadgen` distribution, which carries the Python build runtime and the JavaScript it executes. Install it once:

python -m pip install -r requirements.txt

Drawings are build123d geometry, so a drawing build loads the CAD kernel like a STEP build does (~2.5s cold; the warm daemon absorbs it on re-runs). Only `cadgen dxf snapshot` additionally needs **Node 20 or newer on `PATH`** — it meshes the flat pattern on demand through a bundled Node one-shot; a missing `node` is reported at render time.

Purpose

Create or modify 2D DXF drawings from natural-language requirements or from CAD geometry, generate validated drawing artifacts, and return checked outputs. A DXF drawing's source of truth is a Python file named `<name>.py` defining one parameterless `@dxf` model function.

**A drawing is a model.** It has the same wrapper, record, freshness gate and build job a `@step` part has; its one output is the `.dxf` file; it has no geometry tree (nothing links to a drawing). Every run writes the sibling `<name>.dxf` (or the `out=` the decorator names); an unchanged source is a no-op; a drawing that calls a part model — `bracket()` inside its body — is stale whenever that part's GEOMETRY changes and current when it does not; `cadgen store why <drawing>.py` explains the verdict; `--force` rebuilds it anyway. The CAD Viewer and `dxf snapshot` read the `.dxf` file itself, so the file you hand a cutting service and the file the viewer renders are one and the same.

The contract

**A `@dxf` function takes no parameters and returns build123d 2D geometry. The engine writes the DXF.** You never construct a document, name a file, or place an entity — the same division of labor `@step` has.

from cadgen import build123d as bd
from cadgen import dxf


HOLE_D = 4.5


@dxf
def gasket():
    with bd.BuildSketch() as cut:
        bd.Rectangle(60, 40)
        bd.Circle(HOLE_D / 2, mode=bd.Mode.SUBTRACT)
    return cut.sketch          # bare shape -> the CUT layer


if __name__ == "__main__":
    gasket()

• **Bare shape** → one `CUT` layer. That is the whole contract for most drawings.
• **`{layer: shape}`** → named layers, when the drawing genuinely has more than

one CAM operation (`CUT` / `ENGRAVE` / `SCORE`). A `Compound` whose children are all labelled means the same thing.

• **No parameters.** Dimensions are module constants (`HOLE_D = 4.5`) or

constants imported from the part the drawing derives from; a different drawing is a different file.

• **Text** is `bd.Text(...)` engraved OUTLINES on a marking layer, never a DXF

`TEXT` entity: cut and marking toolchains consume geometry, and font rendering inside CAM is unreliable.

• **Geometry must lie in the XY plane.** A face taken from a solid sits at that

solid's height; relocate it (`flatten.flatten_face(face)`, or `bd.Location((0, 0, -z)) * face`). The engine REFUSES off-plane geometry rather than silently writing its XY shadow.

• **Output bytes are a function of the geometry.** Layers are sorted by name and

entities by geometric content, so an unchanged drawing rebuilds to an identical file, cold or warm, on any machine.

The three DXF workflows

Copy the full template for the applicable workflow from `references/generator-templates.md` when creating a new drawing.

1. **Drafted from scratch** (gaskets, panels, templates, cut layouts with no 3D model behind them): a `<name>.py` that builds sketches and returns them.

2. **Flat pattern of a generated STEP part**: a drawing script beside the model it derives from, with its OWN stem (one model per file — `bracket_drawing.py` beside `bracket.py`). Import the model and call it, exactly as an assembly composes a child: importing never builds, and inside the drawing's build the call returns the part's geometry (building the part first if it is stale).

   from cadgen import dxf, flatten
   from bracket import bracket        # a child: tracked by its RESULT

   KERF = 0.15


   @dxf
   def bracket_drawing():
       return flatten.flat_pattern(bracket(), coordinate=3.0, kerf=KERF)


   if __name__ == "__main__":
       bracket_drawing()

The drawing's record pins the part's tree, so a part edit that changes its geometry makes the drawing stale, and one that does not (a comment, a refactor, a colour) leaves it current. Constants imported from the part (`from bracket import THICKNESS`) are tracked by value the same way.

3. **Flat pattern of an imported STEP** (a `.step`/`.stp` with no Python source): read it with `cadgen.read_step`, not `build123d.import_step`. It records the file's content hash as a build INPUT, so replacing the vendor STEP makes the drawing stale on its own, with no `--force`; read it through build123d and the drawing stays "current" against a file that changed underneath it.

   from pathlib import Path

   from cadgen import dxf, flatten, read_step

   _HERE = Path(__file__).resolve().parent

   KERF = 0.15


   @dxf
   def panel_flat():
       panel = read_step(_HERE / "imported" / "vendor_panel.step")   # recorded input
       return flatten.flat_pattern(panel, coordinate=3.0, kerf=KERF)


   if __name__ == "__main__":
       panel_flat()

**Never read a STEP this project generates.** Reading the `.step` a `@step` model writes is not a l