dxf

Files (4)

• LICENSE
• SKILL.md
• openai.yaml · agents/
• generator-templates.md · references/

SKILL.md (first lines)

# 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

Run cadgen through the `cadgen` command its installation writes, so this skill's commands
share one installation, and its engine server, with the CAD app's:

- `cadgen` below means `cadgen +0.8.1` (`~/.local/bin/cadgen +0.8.1` where `~/.local/bin` is not on your PATH)
- `python` below means `cadgen +0.8.1 run`

If `cadgen` is not on your PATH, or it says 0.8.1 is not installed, run
`uvx --no-config --managed-python --python 3.13 --from cadgen==0.8.1 cadgen doctor` once,
outside any sandbox or with its permission: it installs cadgen, registers it, writes the
`cadgen` command and starts the engine. With the CAD app's server running, nothing else
needs the sandbox's permission: it starts the engine and holds it. Without it, a sandboxed
shell cannot start the engine; when a command says no engine is running, run `cadgen server`
outside the sandbox once.

`cadgen doctor <skill-dir>` reports the installation in use and checks that it is
the one this skill pins, that the CAD kernel loads, and whether the engine every
build runs in is running, starting it when none is; use it for installation or kernel load errors.

Drawings are build123d geometry, so a drawing builds in the engine's warm worker
like any model: the first run of a script loads the CAD kernel (a few seconds),
and later runs reuse it.

## Purpose

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

**A drawing is a model.** It builds as any `$cad` model does: `python <name>.py`
rebuilds it in the engine, prints its document's `id:` and page, and writes nothing.
The DXF is exported from that document, by build123d's own exporter, once the drawing
checks pass: `cadgen export <id> drawing.dxf`. A drawing that calls a part model
(`bracket()` in its body) builds that part in the same run. The CAD Viewer and
`cadgen snapshot` read the `.dxf` itself, so the file you hand a cutting service,
the file the viewer draws and the file a snapshot renders are one and the same.

## The contract

**A drawing is a `@model` function that takes no parameters and returns build123d 2D
geometry on z=0: a sketch, a face, wires or edges. `cadgen export` writes the DXF.**
You never construct a document, name an entity, or write a file from the model.

```python
import build123d as bd
from cadgen import model

HOLE_D = 4.5


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


if __name__ == "__main__":
    gasket()                   # decoration only declares: this call builds it
```

```bash
python src/gasket.py                       # prints id: and view:
cadgen export "$ID" DXF/gasket.dxf         # ID: the id: line it printed
```

- **One shape** is one layer, `CUT`. That is the whole contract for most drawings.
- **A layer per part** when the drawing genuinely has more than one CAM operation:
  return a `Compound` of labelled children, each label its layer
  (`profile.label, marks.label = "CUT", "ENGRAVE"`). Children sharing a label share
  a layer, and several shapes make one part of a layer as
  `bd.Compound([a, b], label="ENGRAVE")`. A layer name may not be empty or hold any
  of `<>/\":;?*|=` and a backtick.
- **Planar means 2D, on z=0.** The export refuses a document holding a solid
  (`bracket is 3D: a DXF is drawn from 2D geometry a model returns`) and an edge with
  any point more than 1e-6 mm off z=0, by its element name. 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`).
- **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 `@model` function.
- **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.
- **Output bytes are a function of the geometry.** Layers are written in name order
  and entities in an order of their content, so an unchanged drawing exports an
  identical file, on any machine, and the file is replaced only when its bytes
  change.
- **Drawings delivered after every change** go in an `exports.py` beside them that
  imports each drawing and calls `export(drawing, path)` (the model function itself,
  or the handle its call returns):

  ```python
  # src/exports.py
  from pathlib import Path

  from cadgen import export

  from gasket import gasket

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

  if __name__ == "__main__":
      export(gasket, ROOT / "DXF/gasket.dxf")
  ```

## The three DXF workflows

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

From earthtojake/text-to-cad, MIT.

More from earthtojake/text-to-cad