dxf-to-kcl

Translates 2D DXF files into KCL (KittyCAD Language) sketch profiles for use in Zoo Design Studio. The output is a .kcl file containing one sketch() block per profile, ready to open or import directly.

What it does

Reads a DXF file and emits a KCL 2.0 source string. Each closed or open geometric profile in the DXF becomes a sketch(on = XY) block. Standalone circles get their own sketch block. No extrusion is added — the output is purely 2D sketch geometry.

Supported DXF entities

Entity	Notes
LINE	Direct mapping
ARC	CCW only; see workarounds below
CIRCLE	Direct mapping
LWPOLYLINE	Bulge arcs expanded; mixed CCW/CW profiles supported (see workarounds)
POLYLINE (legacy R12)	Same bulge expansion as LWPOLYLINE
INSERT	Block references recursively expanded into modelspace
ELLIPSE	Approximated as chained line segments via flattening(0.01mm)
SPLINE	Approximated as chained line segments via flattening(0.01mm)

Entities not in this table (HATCH, TEXT, MTEXT, DIMENSION, 3DFACE, etc.) are silently ignored — they have no KCL equivalent.

KCL output format

All output targets KCL 2.0:

@settings(defaultLengthUnit = mm, kclVersion = 2.0)

sketch001 = sketch(on = XY) {
  line(start = [var 0, var 0], end = [var 10, var 0])
  arc(start = [var 10, var 0], end = [var 10, var 6], center = [var 10, var 3])
  ...
}

Units are read from the DXF $INSUNITS header and mapped to the nearest KCL unit (mm, cm, m, in, ft); files with no unit header default to mm.

Known limitations

CW arcs in mixed-direction profiles

DXF allows polylines with a mix of CCW and CW arc segments. In a profile where CCW and CW arcs alternate (e.g. an S-wave), the CW arcs are approximated as dense line segments rather than true arcs. Geometry is preserved to within 0.01mm. All-CW profiles (every arc clockwise) are translated faithfully as true arcs.

Ellipse and spline approximation

DXF ELLIPSE and SPLINE entities have no direct KCL equivalent and are approximated as chained line segments with a maximum chord-height deviation of 0.01mm.

Usage

As a Python library

from parser.dxf_reader import read_dxf
from emitter.kcl_writer import emit_kcl

kcl = emit_kcl(read_dxf("part.dxf"))
print(kcl)

As a CLI script

python scripts/translate.py part.dxf

As an MCP server

The package exposes an MCP server with two tools:

• translate_dxf — translates a DXF file and returns the KCL string
• preview_entities — returns a count of each DXF entity type without translating

Add to your MCP host config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "dxf-to-kcl": {
      "command": "dxf-to-kcl"
    }
  }
}

For Claude Desktop the config file is ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Installation

Requires Python 3.11+.

pip install -e .

Dependencies: ezdxf, mcp.

Testing

python -m ruff check .
python -m pyright parser/ emitter/
pytest

Tests run in two tiers per fixture: exact golden file match (always runs) and KCL syntax validation via zoo kcl format (requires the Zoo CLI, auto-skipped otherwise).