# DXF Skill Capabilities for Generating 2D Drawings in Text-to-CAD

> Explore the DXF skill's capabilities for generating 2D drawings from Python scripts. Create explicit DXF files efficiently with this lightweight command-line tool from earthtojake/text-to-cad.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: tutorial
- Published: 2026-07-31

---

**The DXF skill is a lightweight command-line utility in the earthtojake/text-to-cad repository that transforms Python scripts containing `gen_dxf()` functions into explicit DXF files while avoiding heavy CAD engine imports at startup.**

The DXF skill provides robust capabilities for generating 2D drawings within the text-to-cad ecosystem. This specialized tool, located in the `skills/dxf` directory of the earthtojake/text-to-cad repository, enables engineers and developers to convert programmatic geometry definitions into industry-standard CAD formats without the overhead of traditional CAD applications.

## Explicit Target Processing and Batch Generation

The CLI supports explicit target listing through the `main()` function in [`skills/dxf/scripts/dxf/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/dxf/scripts/dxf/cli.py). You can pass one or more Python source files that expose a `gen_dxf()` function, and the CLI generates a DXF for each file in the specified order.

To generate multiple DXFs from separate scripts:

```bash
dxf drawings/second.py drawings/first.py

```

This creates `second.dxf` and `first.dxf` adjacent to their respective source files, processing them in the exact sequence provided.

### Source-to-Output Pair Syntax

For precise control over output locations, the DXF skill accepts targets written as `SOURCE.py=OUTPUT.dxf`. This syntax allows you to specify distinct output paths per source file within a single command invocation.

```python
dxf.main(["part.py=part.dxf", "other.py=other.dxf"])

```

Via command line:

```bash
dxf drawings/part.py=DXF/part.dxf drawings/aux.py=DXF/aux.dxf

```

## Output Control and CLI Flags

### Single-Target Output Specification

When generating a single DXF file with a custom destination, use the `-o` or `--output` flag. The CLI validates that this flag appears only with one plain target and never alongside `SOURCE=OUTPUT` pairs.

```python
dxf.main(["drawings/part.py","-o","DXF/part.dxf"])

```

Command-line equivalent:

```bash
dxf drawings/part.py -o DXF/custom_name.dxf

```

Attempting to combine `--output` with multiple targets or source-output pairs triggers a parser error: `"--output cannot be combined with SOURCE=OUTPUT targets"`.

### Verbose Mode and Debugging

The `--verbose` flag enables detailed progress reporting and timing information, essential for debugging complex generations or monitoring long-running operations.

```bash
dxf drawings/complex.py --verbose

```

This functionality is implemented in the `build_parser` and `main` functions within [`skills/dxf/scripts/dxf/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/dxf/scripts/dxf/cli.py).

## Argument Validation and Error Handling

The DXF skill implements strict argument validation to prevent illegal combinations. The parser actively rejects incompatible flag configurations, ensuring users receive clear error messages before execution begins rather than mid-process failures.

## Architecture and Performance Optimization

### Zero-Cost Import Design

A critical capability of the DXF skill is its **zero-cost import** architecture. The CLI deliberately avoids importing heavy CAD modules such as `cadpy.step_scene` and `OCP` at import time. This design choice prevents unnecessary overhead and side effects, making the CLI fast to start and safe to run in constrained environments.

The implementation achieves this through lazy loading, importing `cadpy.generation.generate_dxf_targets` only at runtime when actual DXF generation occurs. This behavior is verified by `tests/python/skills/dxf/test_cli.py::test_cli_import_does_not_import_heavy_cad_modules`.

## Implementation Pipeline

Under the hood, the CLI forwards validated requests to `cadpy.generation.generate_dxf_targets`, defined in [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py). This function handles the actual DXF creation by reading each script's `gen_dxf()` implementation and translating it into valid DXF format.

The separation between CLI parsing ([`skills/dxf/scripts/dxf/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/dxf/scripts/dxf/cli.py)) and generation logic ([`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py)) ensures modular testing and maintenance. Unit tests in [`tests/python/skills/dxf/test_cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/tests/python/skills/dxf/test_cli.py) document expected behaviors including argument error handling, flag processing, and import safety.

## Summary

- The DXF skill converts Python scripts with `gen_dxf()` functions into DXF files via command-line interface
- Supports batch processing of multiple targets with order preservation and explicit source-to-output path mapping
- Provides single-target output control through the `-o/--output` flag with strict validation rules
- Implements zero-cost imports by deferring heavy CAD module loading until runtime
- Delivers comprehensive argument validation and verbose logging for debugging

## Frequently Asked Questions

### What Python function must scripts contain to work with the DXF skill?

Scripts must expose a `gen_dxf()` function that the DXF skill can detect and execute. The `cadpy.generation.generate_dxf_targets` function reads this implementation and translates it into the final DXF output format.

### Can I specify different output directories for multiple DXF files in one command?

Yes. Use the source=output pair syntax (`SOURCE.py=OUTPUT.dxf`) to define distinct output paths for each input file. However, you cannot mix this syntax with the `--output` flag, as the CLI validates against this combination to prevent ambiguous destination conflicts.

### Why does the DXF skill avoid importing CAD modules at startup?

The DXF skill implements a zero-cost import strategy to ensure fast CLI startup times and safe operation in resource-constrained environments. By deferring imports of heavy modules like `OCP` and `cadpy.step_scene` until actual generation time, the tool minimizes memory overhead and prevents side effects during command parsing and validation.

### Where is the DXF generation logic implemented?

The actual DXF creation logic resides in [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py) within the `generate_dxf_targets` function. The CLI frontend in [`skills/dxf/scripts/dxf/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/dxf/scripts/dxf/cli.py) handles argument parsing and validation before lazily importing and invoking this generation function at runtime.