0
# ezdxf
1

2
A comprehensive Python library for creating, reading, modifying, and writing DXF (Drawing Exchange Format) documents. ezdxf provides full support for DXF versions R12 through R2018, enabling seamless manipulation of CAD files while preserving all content including third-party extensions. The library offers both high-level convenience functions and low-level access to DXF structures, making it suitable for everything from simple CAD file processing to complex CAD application development.
3

4
## Package Information
5

6
- **Package Name**: ezdxf
7
- **Language**: Python
8
- **Installation**: `pip install ezdxf`
9
- **Supported Python**: 3.9+
10
- **Optional Dependencies**: 
11
  - `pip install ezdxf[draw]` for rendering support (PySide6, matplotlib, PyMuPDF, Pillow)
12
  - Cython for optional C-extensions (faster performance)
13

14
## Core Imports
15

16
```python
17
import ezdxf
18
```
19

20
Common usage patterns:
21

22
```python
23
# Document operations
24
from ezdxf import new, read, readfile
25

26
# Math utilities
27
from ezdxf.math import Vec3, Matrix44, BSpline
28

29
# Entity classes
30
from ezdxf.entities import Line, Circle, Text
31

32
# Rendering utilities
33
from ezdxf.render import MeshBuilder
34
from ezdxf.path import Path
35

36
# Colors and enums
37
from ezdxf.colors import RGB
38
from ezdxf.enums import TextHAlign
39
```
40

41
## Basic Usage
42

43
```python
44
import ezdxf
45
from ezdxf.math import Vec3
46

47
# Create a new DXF document
48
doc = ezdxf.new('R2018', setup=True)
49

50
# Get model space (main drawing area)
51
msp = doc.modelspace()
52

53
# Add basic entities
54
line = msp.add_line(start=(0, 0), end=(10, 10))
55
circle = msp.add_circle(center=(5, 5), radius=3)
56
text = msp.add_text("Hello World", height=2.5).set_placement((0, 0))
57

58
# Add a polyline with multiple points
59
points = [Vec3(0, 0), Vec3(3, 0), Vec3(6, 3), Vec3(6, 6)]
60
polyline = msp.add_lwpolyline(points)
61

62
# Save the document
63
doc.saveas('example.dxf')
64

65
# Read an existing DXF file
66
doc2 = ezdxf.readfile('existing.dxf')
67

68
# Query entities by type
69
lines = doc2.modelspace().query('LINE')
70
for line in lines:
71
    print(f"Line from {line.dxf.start} to {line.dxf.end}")
72

73
# Audit and repair
74
auditor = doc2.audit()
75
if auditor.has_errors:
76
    print(f"Found {len(auditor.errors)} errors")
77
    auditor.print_report()
78
```
79

80
## Architecture
81

82
The ezdxf library is built around several key architectural components:
83

84
- **Document**: Top-level container managing DXF file structure, metadata, and all drawing content
85
- **Layouts**: Organize drawing content into Model Space (3D geometry) and Paper Space (plotting layouts)
86
- **Entity Database**: Efficient storage and retrieval system for all DXF entities with handle-based references
87
- **Math Package**: Comprehensive geometric calculations, transformations, and curve mathematics
88
- **Rendering System**: Convert complex entities to basic geometric primitives for display or analysis
89
- **Path System**: Vector path representation for advanced geometric operations and conversions
90

91
This modular design supports both simple CAD file manipulation and sophisticated CAD application development, with clear separation between high-level convenience functions and low-level DXF structure access.
92

93
## Capabilities
94

95
### Document Operations
96

97
Core functionality for creating, reading, writing, and managing DXF documents across all supported versions. Includes file I/O, document structure management, and validation.
98

99
```python { .api }
100
def new(dxfversion: str = 'R2018', setup: bool = None, units: int = 1): ...
101
def read(stream, *, errors: str = 'surrogateescape'): ...
102
def readfile(filename: str, *, encoding: str = None, errors: str = 'surrogateescape'): ...
103
def readzip(zipfile: str, filename: str = None, *, errors: str = 'surrogateescape'): ...
104
```
105

106
[Document Operations](./document-operations.md)
107

108
### Entity Creation and Manipulation
109

110
Complete set of entity classes for all DXF entity types from basic geometry (lines, circles, arcs) to complex entities (hatches, meshes, dimensions). Includes entity creation, modification, and property management.
111

112
```python { .api }
113
class Line(DXFGraphic):
114
    def __init__(self): ...
115
    @property
116
    def start(self) -> Vec3: ...
117
    @property  
118
    def end(self) -> Vec3: ...
119

120
class Circle(DXFGraphic):
121
    def __init__(self): ...
122
    @property
123
    def center(self) -> Vec3: ...
124
    @property
125
    def radius(self) -> float: ...
126
```
127

128
[Entities](./entities.md)
129

130
### Layout Management
131

132
Organization and management of drawing content through Model Space and Paper Space layouts. Includes layout creation, entity placement, and viewport management.
133

134
```python { .api }
135
class Layout:
136
    def add_line(self, start, end, dxfattribs: dict = None): ...
137
    def add_circle(self, center, radius: float, dxfattribs: dict = None): ...
138
    def add_text(self, text: str, dxfattribs: dict = None): ...
139
    def query(self, query: str = '*'): ...
140
```
141

142
[Layouts](./layouts.md)
143

144
### Mathematical Operations
145

146
Comprehensive mathematical utilities for 2D/3D geometry, transformations, curve calculations, and geometric constructions. Essential for CAD calculations and entity manipulation.
147

148
```python { .api }
149
class Vec3:
150
    def __init__(self, x: float = 0, y: float = 0, z: float = 0): ...
151
    def __add__(self, other): ...
152
    def __mul__(self, scalar: float): ...
153
    def normalize(self): ...
154

155
class Matrix44:
156
    def __init__(self): ...
157
    @classmethod
158
    def translate(cls, dx: float, dy: float, dz: float): ...
159
    @classmethod
160
    def scale(cls, sx: float, sy: float = None, sz: float = None): ...
161
```
162

163
[Math](./math.md)
164

165
### Rendering and Mesh Operations
166

167
Advanced geometry processing including mesh construction, curve tessellation, and entity rendering to basic primitives. Supports both 2D and 3D geometry processing.
168

169
```python { .api }
170
class MeshBuilder:
171
    def __init__(self): ...
172
    def add_face(self, vertices): ...
173
    def add_mesh(self, other_mesh): ...
174
    def render_mesh(self, layout, dxfattribs: dict = None): ...
175

176
def forms.circle(radius: float = 1, segments: int = None): ...
177
def forms.ngon(count: int, radius: float = 1): ...
178
```
179

180
[Rendering](./rendering.md)
181

182
### Path Processing
183

184
Vector path representation and manipulation for advanced geometric operations. Supports path creation from entities, transformations, and conversions between different geometric representations.
185

186
```python { .api }
187
class Path:
188
    def __init__(self): ...
189
    def line_to(self, location): ...
190
    def curve3_to(self, location, ctrl): ...
191
    def curve4_to(self, location, ctrl1, ctrl2): ...
192
    def transform(self, matrix): ...
193

194
def make_path(entity): ...
195
def to_lines(paths): ...
196
def to_polylines3d(paths): ...
197
```
198

199
[Path Processing](./path-processing.md)
200

201
### Colors and Visual Properties
202

203
Color management system supporting RGB colors, AutoCAD Color Index (ACI), transparency, and color conversions. Includes predefined color palettes and utility functions.
204

205
```python { .api }
206
class RGB:
207
    def __init__(self, r: int, g: int, b: int): ...
208
    def to_hex(self) -> str: ...
209
    @classmethod
210
    def from_hex(cls, color: str): ...
211

212
def int2rgb(value: int): ...
213
def rgb2int(rgb): ...
214
def transparency2float(value: int) -> float: ...
215
```
216

217
[Colors](./colors.md)
218

219
### Tools and Utilities
220

221
Specialized utility functions for text processing, pattern management, standards setup, date/time conversion, and various CAD-specific operations.
222

223
```python { .api }
224
def setup_linetypes(doc): ...
225
def setup_styles(doc): ...
226
def setup_dimstyles(doc): ...
227

228
class PatternAnalyser:
229
    def __init__(self, pattern): ...
230
    def analyse(self): ...
231
```
232

233
[Tools](./tools.md)
234

235
### Add-on Modules
236

237
Extended functionality including import/export utilities, geometry generators, table creation, dimension tools, and specialized format support.
238

239
```python { .api }
240
class Importer:
241
    def __init__(self, source_doc, target_doc): ...
242
    def import_entities(self, entities): ...
243

244
class MengerSponge:
245
    def __init__(self, level: int = 3, size: float = 1): ...
246
    def render(self, layout): ...
247
```
248

249
[Add-ons](./addons.md)
250

251
## Types
252

253
### Core Types
254

255
```python { .api }
256
# Document and structure types
257
class Drawing:
258
    """Main DXF document class"""
259
    
260
class EntityDB:
261
    """Entity database for efficient storage and retrieval"""
262
    
263
class Auditor:
264
    """Document validation and error reporting"""
265

266
# Vector and matrix types  
267
AnyVec = Union[Vec2, Vec3, Sequence[float]]
268
UVec = Union[UVec, Vertex]
269

270
# Entity base types
271
class DXFEntity:
272
    """Base class for all DXF entities"""
273
    
274
class DXFGraphic(DXFEntity):
275
    """Base class for graphical entities"""
276
    
277
class DXFEntity(DXFEntity):
278
    """Base class for non-graphical objects"""
279
```
280

281
### Exception Types
282

283
```python { .api }
284
class DXFError(Exception):
285
    """Base exception for all DXF-related errors"""
286

287
class DXFStructureError(DXFError):
288
    """DXF document structure errors"""
289
    
290
class DXFVersionError(DXFError):
291
    """DXF version compatibility errors"""
292
    
293
class DXFAttributeError(DXFError):
294
    """DXF attribute access errors"""
295
```