dxf

name	dxf
description	Generate, regenerate, and validate 2D DXF drawings from Python ezdxf sources. Use for DXF files, `.dxf.py` generators, gen_dxf() sources, 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. Use the installed local skill files as the runtime source of truth; the repository link is only for provenance and release review.

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 dedicated Python generator file named <name>.dxf.py defining gen_dxf(); the CLI owns output paths.

The default build product is the drawing package — a render artifact the CAD Viewer serves and auto-regenerates:

<model-folder>/__cadgen__/models/<name>.dxf.py/
  drawing.json    # provenance + freshness descriptor
  drawing.dxf     # the built DXF (the exchange artifact)
  preview.glb     # the baked 3D flat pattern (what the viewer renders)

preview.glb is baked from drawing.dxf by a Node child of the build, inside the same generation lock, so a build produces both payloads or neither. It needs node on PATH (or CADGEN_NODE).

The sibling <name>.dxf file is written on demand only (--write, -o, or a SOURCE=OUTPUT pair) for deliverables handed to cutting services or other tools. An exported .dxf is a point-in-time deliverable, totally detached from its generator: rebuilds never delete, rewrite, or staleness-track it (same as an exported STEP file) — re-export when you want it refreshed. Do not commit generated .dxf outputs; the package cache is gitignored and rebuilt on demand.

The three DXF workflows

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

1. DXF generated from scratch (standalone drafting — gaskets, panels, templates, cut layouts with no 3D model behind them): a <name>.dxf.py that builds an ezdxf document directly.

2. DXF derived from a generated STEP part (flat patterns / profiles of a $cad model): a <name>.dxf.py beside the <name>.step.py it projects. Generator entry files use dotted extensions and cannot be imported by module name, so reuse the STEP source's geometry by path-loading it:

   from pathlib import Path
   from cadgen.sources import load_source_module
   
   _step = load_source_module(Path(__file__).with_name("bracket.step.py"))
   
   def gen_dxf():
       return {"document": _step.build_dxf()}
   

   Keep the shared drawing logic (e.g. a build_dxf() helper that unfolds the part via cadgen.flatten) in the .step.py or a plain helper module; the .dxf.py is the drawing entry point. The loaded .step.py and its imports are recorded in the drawing's source closure, so editing the 3D part automatically invalidates the cached drawing.

3. DXF derived from an imported STEP (a .step/.stp file with no Python source): a <name>.dxf.py that reads the STEP (e.g. build123d.import_step) and projects it with cadgen.flatten. Only Python sources are freshness inputs — like a gen_step() that composes imported STEPs, the drawing does not auto-rebuild when the imported file changes; rerun with --force after replacing it.

gen_dxf() must live in a dedicated .dxf.py file: a source defining both gen_step() and gen_dxf() is rejected. A plain <name>.py defining only gen_dxf() is still accepted as an explicit CLI target (the CLI is naming-agnostic), but only .dxf.py files are catalog entries the CAD Viewer lists and rebuilds.

Use this skill when

Use this skill when the user asks for DXF files, 2D drawings, profiles, outlines, templates, gaskets, panels, flat patterns, or cut layouts for laser, plasma, waterjet, or CNC routing.

Use $cad for the 3D part or assembly a DXF derives from. Use $sendcutsend for SendCutSend-specific upload preflight.

Defaults

Use these defaults unless the user specifies otherwise:

• Units: millimeters; set them explicitly on the document (doc.units = ezdxf.units.MM).
• Geometry lives in modelspace at 1:1 scale.
• Cut profiles are closed polylines or closed line/arc loops; open contours only for engraving or reference geometry (generation validation enforces this — see Validation).
• For CAD-backed parts, derive DXF cut contours from the actual STEP/solid topology with cadgen.flatten: select the real planar faces (planar_faces), project and union them (union_projected_faces), and emit clean closed contours (add_shapely_geometry). Use hand-drawn parametric outlines only when there is no reliable 3D topology to project.
• Apply kerf / tool-radius compensation with cadgen.flatten.offset_geometry / offset_closed_points when the cutting process requires it; do not hand-offset coordinates.
• Layers carry intent: keep cut geometry and bend/fold lines on separate layers, and include "bend" in bend-layer names so downstream tools classify them as bends rather than cuts.
• DXF layers are drawing structure, not STEP part/assembly structure.

Tool

The skill has two launchers, split on who the source is — the same split the CAD skill uses between scripts/gen and scripts/artifact:

python scripts/gen targets... [flags]        # gen_dxf() Python generators
python scripts/artifact target [flags]       # one drawing, INCLUDING an imported .dxf
python scripts/snapshot --input <drawing> --output <file.png>   # render it

Use the active project Python interpreter; treat python as an interpreter placeholder, and use --help for the full interface. Target paths resolve from the command's current working directory; run from the workspace that owns the artifacts with cwd-relative target paths. Keep a drawing generator in the same directory as the geometry it derives from, named <name>.dxf.py.

A DXF target is a Python source defining:

def gen_dxf():
    ...
    return {"document": document}  # or a bare ezdxf document

Every run builds/refreshes the drawing package. Flags:

• --write — also write the sibling <name>.dxf export.
• -o/--output PATH — export to a custom path; only with one plain generated Python target.
• SOURCE.dxf.py=OUTPUT.dxf positional pairs — per-target custom export paths.
• --force — rebuild even when the cached drawing package is current (an unchanged source closure is otherwise skipped).
• --validate — validate existing .dxf FILES with the generation-time drawing checks instead of generating.

Do not put output paths in the gen_dxf() return value.

scripts/gen runs generators only. An imported .dxf has no generator to run, so it goes through scripts/artifact instead:

python scripts/artifact path/to/imported.dxf
python scripts/artifact path/to/source.dxf.py --force

That builds the same hidden __cadgen__ drawing package the CAD Viewer builds on demand — the drawing DXF plus the 3D preview.glb the viewport renders — and accepts either source kind, so it is also how you debug a generated drawing's package build. Flags: --write PATH (also write the package's drawing DXF there), --force, --verbose.

scripts/snapshot renders a drawing's 3D flat pattern to a PNG still or an orbit GIF:

python scripts/snapshot --input path/to/imported.dxf --output review.png
python scripts/snapshot --input path/to/source.dxf.py --output turntable.gif --mode orbit

It builds/refreshes the drawing package first, then renders that package's preview.glb through the shared snapshot CLI (cadgen.snapshot_cli) and the same headless browser runtime every rendering skill uses — so geometry and materials render identically to the CAD Viewer; the default snapshot theme differs from the viewport only by dropping the grid, origin axis and shadows. The package build is the same locked artifact_build(DRAWING_PACKAGE) that scripts/artifact and the viewer run, so a snapshot cannot race one of them.

Flags: --mode view|orbit|list, --camera, --theme, --size-profile, --width/--height, --job, --force, --json. Theme settings live under one --theme, mirroring the viewer's Theme tab; the default theme is snapshot, Workbench Light without the ground grid, origin axis or shadows. There is no --display, and no selector, parameter, section or exploded options: a drawing carries no CAD topology, and display settings are CAD topology settings.

No CLI inspects an existing .dxf. For entity/layer checks use ezdxf directly, and --validate for the drawing checks; review geometry visually with $cad-viewer.

Workflow

1. Convert the request into a short brief: outline dimensions, holes and slots, layers, units, output path, and validation targets.
2. Pick the workflow: standalone drafting, projection of a generated STEP (create and validate the STEP geometry with $cad first), or projection of an imported STEP (declare it in sources).
3. Write or edit the <name>.dxf.py source with meaningful dimensions as named parameters, reusing the STEP source's geometry helpers instead of duplicating formulas.
4. Run scripts/gen on explicit Python source targets only; do not run directory-wide generation.

python scripts/gen path/to/source.dxf.py
python scripts/gen path/to/source.dxf.py --write
python scripts/gen path/to/source.dxf.py -o path/to/output.dxf
python scripts/gen path/to/a.dxf.py=out/a.dxf path/to/b.dxf.py=out/b.dxf

5. Validate the generated DXF deterministically, then hand off and report.

Viewer integration

<name>.dxf.py files are CAD Viewer catalog entries, listed whether or not their drawing package has been built. Opening one triggers the unified render-artifact flow: a missing or stale package (any source-closure file — the generator, its path-loaded .step.py sources, and helper modules — newer than the descriptor) rebuilds automatically. The viewer's export dropdown offers "Download DXF" on generated drawings (it refreshes the package first, so the export is never stale). An imported .dxf is artifact-managed too — the viewer builds its drawing package on demand, exactly as it does for an imported .step — but it is never a dxf CLI target: the CLI builds .dxf.py generators only.

Validation

Validation happens IN generation, not after: every gen_dxf() build runs the drawing checks on the in-memory document before the package or any export is written, and a build with error findings fails. The checks: cut-layer profiles must close (polylines, circles, or chained line/arc loops), zero-length/degenerate entities are rejected, exact duplicate geometry (double-cut risk) is rejected, explicitly unitless documents are rejected, and an empty modelspace is rejected. Open geometry is allowed only on bend/engrave/reference-intent layers (matched by name).

The same checks run post-hoc on any existing .dxf file:

python scripts/gen --validate path/to/file.dxf

Beyond the built-in checks, verify requested dimensions with targeted ezdxf reads (entity counts by layer, drawing extents, every dimension the user specified) against the built DXF in the drawing package (or the exported path when one was requested), and review geometry visually in the CAD Viewer:

import ezdxf

doc = ezdxf.readfile("path/to/__cadgen__/models/source.dxf.py/drawing.dxf")
msp = doc.modelspace()
profiles = [e for e in msp.query("LWPOLYLINE") if e.closed]
holes = msp.query('CIRCLE[layer=="0"]')

Report only checks that actually ran.

Handoff

After creating or modifying DXF drawings, you must ALWAYS hand the explicit .dxf.py file path(s) to $cad-viewer when that skill is installed and include its live viewer link(s) in the final response. If $cad-viewer is unavailable or startup fails, report that and rely on ezdxf checks instead of silently omitting the handoff.

Final responses should include generated files, returned viewer links, validation actually run, and assumptions.