Skip to content

Commit 99afabb

Browse files
JheisonMBJheisonMB
committed
docs(readme): document CLI, layout examples, and DXF/PNG output flow
1 parent f5957f1 commit 99afabb

1 file changed

Lines changed: 193 additions & 27 deletions

File tree

‎README.md‎

Lines changed: 193 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,91 @@
1-
# CADforge
1+
██████ ████████ ██████ ████████ ██ ██ ██ ███████ ████████
2+
██░░███ ░░███░░███░░░░░███ ░░███░░███░███ ░███ ██░███░░░░░░░███░
3+
░███ ░░░ ░███ ░███ ███████ ░███ ░░░ ░███ ░██████░░█████ ░███
4+
░███ ███ ░███ ░███ ███░░███ ░███ ░███ ░███░░░ ░███░░█ ░███
5+
░░██████ ░███████░░████████ ░███ ░███████████ ███████ ░████████
6+
░░░░░░ ░░░░░░░ ░░░░░░░░ ░░░ ░░░░░░░░░░░ ░░░░░░ ░░░░░░░
27

3-
Architecture as Code — deterministic geometry engine for reproducible architectural design.
8+
<p align="center">
9+
<a href="https://github.com/UniverLab/cadforge/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/UniverLab/cadforge/ci.yml?branch=main&style=for-the-badge&label=CI" alt="CI"/></a>
10+
<a href="https://crates.io/crates/cadforge"><img src="https://img.shields.io/crates/v/cadforge?style=for-the-badge&logo=rust&logoColor=white" alt="Crates.io"/></a>
11+
<img src="https://img.shields.io/badge/Status-Active-27AE60?style=for-the-badge" alt="Status"/>
12+
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-2E8B57?style=for-the-badge" alt="License"/></a>
13+
</p>
414

5-
## Quick Start
15+
cadforge is an **Architecture as Code** CLI tool and Rust library for declarative 2D CAD modeling. Write geometry as code in `.cf` TOML format, compile to DXF, and generate PNG previews for AI agents.
616

7-
```bash
8-
# Create a new project
9-
cadforge new mi-proyecto
10-
cd mi-proyecto
17+
---
1118

12-
# Edit .cf files (TOML format)
13-
# Then compile to DXF
14-
cadforge build
19+
## Features
1520

16-
# Validate without generating output
17-
cadforge check
21+
### 🎯 Core Platform
1822

19-
# List layers
20-
cadforge layers
21-
```
23+
- **📐 Declarative Geometry** — Define architectural elements (lines, rects, circles, arcs, polylines, text, dimensions) in TOML `.cf` files. Deterministic, reproducible, version-controlled.
24+
- **🔗 Layer System** — Organize geometry by layer with custom names, colors, and line weights. Compile single layers or full projects.
25+
- **📄 DXF Export** — Compile `.cf` → DXF (AutoCAD-compatible). Full layer support, LWPOLYLINE for polylines, HATCH for solid fills, MTEXT for annotations.
26+
- **🖼️ PNG Preview** — Generate raster previews with metadata JSON for AI agent integration. Renders fills, hatches, strokes, and text with boundary resolution. Configurable resolution and layer filtering.
27+
- **✅ Validation Engine** — `cadforge check` validates geometry without generating output. Shows project metadata, layer colors, and entity counts.
28+
29+
### 🏗️ Project Management
30+
31+
- **Project Scaffolding** — `cadforge new` creates a complete multi-layer project (muros, puertas, mobiliario, cotas) with meaningful architectural examples.
32+
- **Multi-Layer Compilation** — Compile all layers or target specific layers with `--layer`. Custom output path with `--output`.
33+
- **Auto-Rebuild** — `cadforge watch` monitors `.cf` and `.toml` files and auto-rebuilds on changes with 300ms debounce.
34+
- **Code Formatting** — `cadforge fmt` normalizes `.cf` files. `--check` mode for CI validation.
35+
- **Boundary Resolution** — Automatic detection of closed boundaries for hatch generation. Shared boundary resolution across overlapping entities.
36+
- **Polyline Support** — Full LWPOLYLINE support with bulge factors for arcs. Proper vertex handling and closure detection.
37+
38+
### 🔧 Architecture
39+
40+
- **Compiler Pipeline** — Parse → Resolve → Compile → Emit. Modular design for easy extension.
41+
- **DXF Writer** — Direct DXF entity writing with proper AutoCAD compatibility. Layer/color/lineweight mapping.
42+
- **Preview Renderer** — Tiny-skia based raster rendering with anti-aliasing. PNG + JSON metadata output.
43+
- **Error Reporting** — Structured errors with file, line, and context. Fast-fail on validation errors.
44+
45+
---
2246

2347
## Commands
2448

2549
| Command | Description |
26-
|---|---|
27-
| `cadforge new <name>` | Create a new project directory |
28-
| `cadforge init` | Initialize in current directory |
29-
| `cadforge build` | Compile .cf → DXF |
30-
| `cadforge build --layer <name>` | Compile a single layer |
31-
| `cadforge check` | Validate project without output |
32-
| `cadforge layers` | List layers with entity count |
50+
|---------|-------------|
51+
| `cadforge new <name>` | Create a new project with multi-layer scaffold |
52+
| `cadforge init` | Initialize CADforge in current directory |
53+
| `cadforge build` | Compile project to DXF |
54+
| `cadforge build --check` | Validate project and constraints without generating DXF |
55+
| `cadforge build --output <path>` | Compile to custom output path |
56+
| `cadforge build --layer <name>` | Compile specific layer only |
57+
| `cadforge check` | Validate with project metadata and layer colors |
58+
| `cadforge layers` | List layers with entity counts and colors |
59+
| `cadforge preview` | Generate PNG preview + metadata JSON |
60+
| `cadforge preview --width 1024 --height 768` | Custom resolution preview |
61+
| `cadforge preview --layer <name>` | Preview specific layer only |
62+
| `cadforge fmt` | Format .cf files (normalize whitespace) |
63+
| `cadforge fmt --check` | Check formatting without modifying (CI) |
64+
| `cadforge watch` | Auto-rebuild on file changes |
65+
| `cadforge import <file.dxf>` | Import DXF into `.cf` layers + `project.toml` |
66+
| `cadforge import <file.dxf> --layer <name>` | Import only one DXF layer |
67+
| `cadforge view` | Open the dedicated `cadforge-view` viewer |
68+
| `cadforge view --layer <name>` | Open only one layer in the viewer |
69+
| `cadforge config set <key> <value>` | Set global defaults (`author`, `units`) |
70+
| `cadforge config show` | Show global defaults |
71+
72+
### Viewer controls (MVP)
73+
74+
- HUD flotante en pantalla con proyecto, vista, distancia, capas, selección y ayuda de atajos
75+
- `T` / `F` / `V` / `R` → top / front / right / isometric preset views
76+
- `Q` / `E` / `W` / `S` → orbit camera
77+
- Mouse left-drag → orbit
78+
- Mouse right-drag / arrows → pan
79+
- Mouse wheel / `+` / `-` → zoom
80+
- `1`..`9` → toggle layer visibility
81+
- Click entity edge → select primitive id
82+
- Selected entity is highlighted in amber in the viewport HUD context
83+
- `C` → copy selected id to clipboard
84+
85+
---
3386

3487
## .cf Format
3588

36-
Files use TOML with array-of-tables for primitives:
37-
3889
```toml
3990
[layer]
4091
name = "muros"
@@ -47,30 +98,145 @@ to = [8.5, 0.0]
4798
weight = 0.50
4899

49100
[[rect]]
101+
id = "rc-001"
50102
origin = [1.0, 1.0]
51103
width = 3.5
52104
height = 4.0
53105

54106
[[circle]]
107+
id = "ci-001"
55108
center = [4.0, 3.0]
56109
radius = 0.5
57110

58111
[[arc]]
112+
id = "ac-001"
59113
center = [2.0, 2.0]
60114
radius = 0.9
61115
from_angle = 0.0
62116
to_angle = 90.0
63117

118+
[[polyline]]
119+
id = "pl-001"
120+
vertices = [[0, 0], [5, 0], [5, 3], [0, 3]]
121+
closed = true
122+
64123
[[text]]
124+
id = "tx-001"
65125
position = [4.0, 3.0]
66126
content = "SALA"
67127
size = 0.2
128+
129+
[[dim]]
130+
id = "dm-001"
131+
from = [0, 0]
132+
to = [5, 0]
133+
offset = 0.5
134+
```
135+
136+
### Supported Primitives
137+
138+
`line`, `polyline`, `rect`, `circle`, `arc`, `text`, `point`, `dim`, `hatch`, `solid`
139+
140+
---
141+
142+
## Architecture Overview
143+
144+
```
145+
.cf file (TOML)
146+
│
147+
▼
148+
┌─────────┐ ┌──────────┐ ┌─────────┐ ┌─────────┐
149+
│ Parser │───▶│ Resolver │───▶│Compiler │───▶│ DXF Emit│
150+
└─────────┘ └──────────┘ └─────────┘ └─────────┘
151+
│
152+
▼
153+
┌──────────┐ ┌─────────────┐
154+
│ Boundary │───▶│ Preview PNG │
155+
│ Resolver │ │ + JSON meta │
156+
└──────────┘ └─────────────┘
157+
```
158+
159+
- **Parser** — TOML parsing with custom array-of-tables detection, primitive validation
160+
- **Resolver** — Layer dependency resolution, coordinate validation, boundary detection
161+
- **Compiler** — Entity compilation to DXF format, hatch generation, polyline closure
162+
- **DXF Writer** — Direct DXF entity emission with proper layer/color/lineweight mapping
163+
- **Preview Renderer** — Tiny-skia raster rendering with hatch/fill support
164+
165+
---
166+
167+
## Main Modules
168+
169+
- `compiler/` — Project compilation pipeline, layer targeting, validation, build stats
170+
- `dxf_writer/` — DXF entity writing, LWPOLYLINE, HATCH, MTEXT generation
171+
- `preview/` — PNG rendering with configurable resolution, layer filtering, metadata JSON
172+
- `parser/` — TOML parsing, primitive extraction, array-of-tables handling
173+
- `model/` — Data structures: Layer, Primitive, Project
174+
- `scaffold/` — Multi-layer project creation with architectural examples
175+
- `fmt/` — .cf file formatting and normalization
176+
- `watch/` — File system watcher with auto-rebuild and debounce
177+
- `color/` — Color parsing and DXF color mapping
178+
179+
---
180+
181+
## Data Storage
182+
183+
| Data | Location | Format |
184+
|------|----------|--------|
185+
| Project files | `./` | TOML (`.cf` + `project.toml`) |
186+
| Build output | `output/` | DXF |
187+
| Preview output | `output/preview.png` | PNG |
188+
| Preview metadata | `output/preview.json` | JSON |
189+
| Build cache | `target/` | Cargo build |
190+
191+
---
192+
193+
## Usage
194+
195+
**Create a new project:**
196+
```bash
197+
cadforge new mi-proyecto
198+
cd mi-proyecto
68199
```
69200

70-
## Supported Primitives
201+
**Edit `.cf` files** (TOML format with your geometry)
202+
203+
**Format and validate:**
204+
```bash
205+
cadforge fmt # normalize .cf files
206+
cadforge check # validate without generating DXF
207+
```
71208

72-
`line`, `polyline`, `rect`, `circle`, `arc`, `text`, `point`, `dim`
209+
**Compile to DXF:**
210+
```bash
211+
cadforge build # default output.dxf
212+
cadforge build --output plano.dxf # custom output path
213+
cadforge build --layer muros # compile single layer
214+
```
215+
216+
**Preview:**
217+
```bash
218+
cadforge preview # default 2048x1536
219+
cadforge preview --width 1024 --height 768 # custom resolution
220+
cadforge preview --layer muros # single layer preview
221+
```
222+
223+
**Auto-rebuild on changes:**
224+
```bash
225+
cadforge watch # monitors .cf and .toml files
226+
```
227+
228+
---
229+
230+
## Tech Stack
231+
232+
| Rust 2021 | clap | toml | toml_edit | tiny-skia | dxf | notify | anyhow | serde |
233+
234+
---
73235

74236
## License
75237

76-
MIT
238+
MIT — see [LICENSE](LICENSE) for details.
239+
240+
---
241+
242+
Made with ❤️ by [JheisonMB](https://github.com/JheisonMB) and [UniverLab](https://github.com/UniverLab)

0 commit comments

Comments
 (0)