0
# Colors
1

2
Color management system supporting RGB colors, AutoCAD Color Index (ACI), transparency, and color conversions. The color system provides comprehensive support for all DXF color representations and utility functions for color manipulation.
3

4
## Capabilities
5

6
### RGB Color Management
7

8
RGB color representation with comprehensive conversion and manipulation methods.
9

10
```python { .api }
11
class RGB:
12
    """RGB color representation (0-255 per channel)"""
13
    
14
    def __init__(self, r: int, g: int, b: int): ...
15
    
16
    @property
17
    def r(self) -> int:
18
        """Red component (0-255)"""
19
        
20
    @property
21
    def g(self) -> int:
22
        """Green component (0-255)"""
23
        
24
    @property
25
    def b(self) -> int:
26
        """Blue component (0-255)"""
27
        
28
    @property
29
    def luminance(self) -> float:
30
        """Perceived luminance (0-1)"""
31
        
32
    def to_floats(self) -> tuple:
33
        """Convert to float tuple (0.0-1.0 range)"""
34
        
35
    @classmethod
36
    def from_floats(cls, rgb: tuple) -> 'RGB':
37
        """Create from float tuple (0.0-1.0 range)"""
38
        
39
    def to_hex(self) -> str:
40
        """Convert to hex color string (#RRGGBB)"""
41
        
42
    @classmethod
43
    def from_hex(cls, color: str) -> 'RGB':
44
        """Create from hex color string (#RGB or #RRGGBB)"""
45
        
46
    def __eq__(self, other) -> bool: ...
47
    def __str__(self) -> str: ...
48

49
class RGBA(RGB):
50
    """RGBA color with alpha channel"""
51
    
52
    def __init__(self, r: int, g: int, b: int, a: int = 255): ...
53
    
54
    @property
55
    def a(self) -> int:
56
        """Alpha component (0-255, 0=transparent, 255=opaque)"""
57
        
58
    def to_floats(self) -> tuple:
59
        """Convert to (r, g, b, a) float tuple"""
60
        
61
    @classmethod
62
    def from_floats(cls, values: tuple) -> 'RGBA':
63
        """Create from (r, g, b, a) float tuple"""
64
        
65
    def to_hex(self) -> str:
66
        """Convert to hex string with alpha (#RRGGBBAA)"""
67
        
68
    @classmethod
69
    def from_hex(cls, color: str) -> 'RGBA':
70
        """Create from hex string (#RGB, #RRGGBB, #RRGGBBAA)"""
71
```
72

73
Usage examples:
74
```python
75
from ezdxf.colors import RGB, RGBA
76

77
# Create RGB colors
78
red = RGB(255, 0, 0)
79
green = RGB(0, 255, 0)
80
blue = RGB(0, 0, 255)
81

82
# Create from hex strings
83
orange = RGB.from_hex('#FF8000')
84
purple = RGB.from_hex('#800080')
85

86
# Convert to different formats
87
red_floats = red.to_floats()  # (1.0, 0.0, 0.0)
88
green_hex = green.to_hex()    # '#00FF00'
89

90
# RGBA with transparency
91
semi_transparent = RGBA(255, 0, 0, 128)  # 50% transparent red
92
transparent_hex = semi_transparent.to_hex()  # '#FF000080'
93

94
# Color analysis
95
luminance = orange.luminance  # Perceived brightness
96
print(f"Orange luminance: {luminance:.3f}")
97
```
98

99
### AutoCAD Color Index (ACI)
100

101
AutoCAD Color Index constants and utilities for standard DXF colors.
102

103
```python { .api }
104
# Special ACI values
105
BYBLOCK: int = 0      # Color determined by block
106
BYLAYER: int = 256    # Color determined by layer  
107
BYOBJECT: int = 257   # Color determined by object
108

109
# Standard ACI colors (1-255)
110
RED: int = 1
111
YELLOW: int = 2
112
GREEN: int = 3
113
CYAN: int = 4
114
BLUE: int = 5
115
MAGENTA: int = 6
116
BLACK: int = 7        # Black/white depending on background
117
WHITE: int = 7        # Same as BLACK
118
GRAY: int = 8
119
LIGHT_GRAY: int = 9
120

121
# Color type constants
122
COLOR_TYPE_BY_LAYER: int = 0
123
COLOR_TYPE_BY_BLOCK: int = 1
124
COLOR_TYPE_RGB: int = 2
125
COLOR_TYPE_ACI: int = 3
126
```
127

128
Usage examples:
129
```python
130
from ezdxf.colors import RED, BLUE, BYLAYER, BYBLOCK
131

132
# Use ACI colors in entity attributes
133
line_attribs = {
134
    'color': RED,        # Use ACI red
135
    'layer': '0'
136
}
137

138
circle_attribs = {
139
    'color': BYLAYER,    # Use layer color
140
    'linetype': 'DASHED'
141
}
142

143
# Create entities with colors
144
line = msp.add_line((0, 0), (10, 10), dxfattribs=line_attribs)
145
circle = msp.add_circle((5, 5), 3, dxfattribs=circle_attribs)
146
```
147

148
### Color Conversion Functions
149

150
Utility functions for converting between different color representations.
151

152
```python { .api }
153
def int2rgb(value: int) -> RGB:
154
    """
155
    Convert integer color value to RGB.
156
    
157
    Parameters:
158
    - value: 24-bit integer color value (0xRRGGBB)
159
    
160
    Returns:
161
    RGB: RGB color object
162
    """
163

164
def rgb2int(rgb) -> int:
165
    """
166
    Convert RGB color to integer value.
167
    
168
    Parameters:
169
    - rgb: RGB color object or (r, g, b) tuple
170
    
171
    Returns:
172
    int: 24-bit integer color value
173
    """
174

175
def aci2rgb(index: int) -> RGB:
176
    """
177
    Convert AutoCAD Color Index to RGB.
178
    
179
    Parameters:
180
    - index: ACI color index (1-255)
181
    
182
    Returns:
183
    RGB: Corresponding RGB color
184
    """
185

186
def decode_raw_color(value: int) -> tuple:
187
    """
188
    Decode raw DXF color value to (type, color) tuple.
189
    
190
    Parameters:
191
    - value: raw DXF color value
192
    
193
    Returns:
194
    tuple: (color_type, color_value)
195
    """
196

197
def decode_raw_color_int(value: int) -> tuple:
198
    """Decode raw color value to integer components"""
199

200
def encode_raw_color(value) -> int:
201
    """Encode color value to raw DXF format"""
202

203
def luminance(color) -> float:
204
    """
205
    Calculate color luminance for contrast calculations.
206
    
207
    Parameters:
208
    - color: RGB color object or tuple
209
    
210
    Returns:
211
    float: Luminance value (0-1)
212
    """
213
```
214

215
Usage examples:
216
```python
217
from ezdxf.colors import int2rgb, rgb2int, aci2rgb, luminance
218

219
# Convert between formats
220
color_int = 0xFF8000    # Orange
221
orange_rgb = int2rgb(color_int)    # RGB(255, 128, 0)
222
back_to_int = rgb2int(orange_rgb)  # 0xFF8000
223

224
# Convert ACI to RGB
225
aci_red = aci2rgb(1)      # RGB(255, 0, 0)
226
aci_yellow = aci2rgb(2)   # RGB(255, 255, 0)
227

228
# Calculate luminance for contrast
229
white_lum = luminance((255, 255, 255))  # ~1.0
230
black_lum = luminance((0, 0, 0))        # ~0.0
231
text_contrast = white_lum / black_lum    # High contrast ratio
232
```
233

234
### Transparency Management
235

236
Transparency value constants and conversion functions.
237

238
```python { .api }
239
def transparency2float(value: int) -> float:
240
    """
241
    Convert DXF transparency value to float (0-1).
242
    
243
    Parameters:
244
    - value: DXF transparency value (0-255, higher = more transparent)
245
    
246
    Returns:
247
    float: Alpha value (0.0=transparent, 1.0=opaque)
248
    """
249

250
def float2transparency(value: float) -> int:
251
    """
252
    Convert float alpha to DXF transparency value.
253
    
254
    Parameters:
255
    - value: Alpha value (0.0-1.0, 0.0=transparent, 1.0=opaque)
256
    
257
    Returns:
258
    int: DXF transparency value (0-255)
259
    """
260

261
# Transparency constants
262
TRANSPARENCY_BYBLOCK: int = 0
263
OPAQUE: int = 0                    # Fully opaque
264
TRANSPARENCY_10: int = 25          # 10% transparent
265
TRANSPARENCY_20: int = 51          # 20% transparent
266
TRANSPARENCY_25: int = 64          # 25% transparent
267
TRANSPARENCY_30: int = 76          # 30% transparent
268
TRANSPARENCY_40: int = 102         # 40% transparent
269
TRANSPARENCY_50: int = 127         # 50% transparent
270
TRANSPARENCY_60: int = 153         # 60% transparent
271
TRANSPARENCY_70: int = 178         # 70% transparent
272
TRANSPARENCY_75: int = 191         # 75% transparent
273
TRANSPARENCY_80: int = 204         # 80% transparent
274
TRANSPARENCY_90: int = 229         # 90% transparent
275

276
# Raw color value constants
277
BY_LAYER_RAW_VALUE: int = 0xC0000100
278
BY_BLOCK_RAW_VALUE: int = 0xC0000000  
279
WINDOW_BG_RAW_VALUE: int = 0xC0000200
280
```
281

282
Usage examples:
283
```python
284
from ezdxf.colors import transparency2float, float2transparency
285
from ezdxf.colors import TRANSPARENCY_50, TRANSPARENCY_25
286

287
# Convert transparency values
288
dxf_transparency = TRANSPARENCY_50    # 50% transparent
289
alpha_float = transparency2float(dxf_transparency)  # 0.5
290

291
# Convert back
292
new_transparency = float2transparency(0.25)  # 75% opaque (25% transparent)
293

294
# Use in entity attributes
295
entity_attribs = {
296
    'color': RGB(255, 0, 0),           # Red color
297
    'transparency': TRANSPARENCY_25     # 25% transparent
298
}
299

300
circle = msp.add_circle((0, 0), 5, dxfattribs=entity_attribs)
301
```
302

303
### Color Palettes
304

305
Predefined color palettes for standard AutoCAD colors.
306

307
```python { .api }
308
DXF_DEFAULT_COLORS: List[RGB]
309
    """Standard AutoCAD 256-color palette (ACI 0-255)"""
310

311
DXF_DEFAULT_PAPERSPACE_COLORS: List[RGB]  
312
    """Paper space color palette for plotting"""
313
```
314

315
Usage examples:
316
```python
317
from ezdxf.colors import DXF_DEFAULT_COLORS, aci2rgb
318

319
# Access standard palette colors
320
palette_red = DXF_DEFAULT_COLORS[1]        # ACI 1 (red)
321
palette_yellow = DXF_DEFAULT_COLORS[2]     # ACI 2 (yellow)
322
palette_green = DXF_DEFAULT_COLORS[3]      # ACI 3 (green)
323

324
# Compare with direct conversion
325
direct_red = aci2rgb(1)
326
assert palette_red == direct_red  # Should be equal
327

328
# Iterate through palette
329
for i, color in enumerate(DXF_DEFAULT_COLORS[:16]):
330
    print(f"ACI {i}: {color.to_hex()}")
331
```
332

333
### Entity Color Properties
334

335
Working with entity color properties in DXF entities.
336

337
```python { .api }
338
# Entity color properties are typically accessed through:
339
# entity.dxf.color - ACI color index or RGB value
340
# entity.dxf.transparency - transparency value
341
# entity.rgb - RGB color tuple (if RGB color)
342
# entity.color - color index or RGB integer
343
```
344

345
Usage examples:
346
```python
347
import ezdxf
348
from ezdxf.colors import RGB, BLUE, TRANSPARENCY_30
349

350
doc = ezdxf.new()
351
msp = doc.modelspace()
352

353
# Create entity with ACI color
354
line = msp.add_line((0, 0), (10, 10), dxfattribs={
355
    'color': BLUE,              # ACI blue
356
    'transparency': TRANSPARENCY_30
357
})
358

359
# Create entity with RGB color
360
rgb_color = RGB(255, 128, 0)  # Orange
361
circle = msp.add_circle((5, 5), 3, dxfattribs={
362
    'color': rgb_color,
363
    'layer': 'GEOMETRY'
364
})
365

366
# Modify entity colors
367
line.dxf.color = RGB(255, 0, 255)  # Change to magenta
368
circle.dxf.transparency = TRANSPARENCY_50
369

370
# Query entity colors
371
if line.dxf.color == BYLAYER:
372
    print("Line uses layer color")
373
elif isinstance(line.dxf.color, RGB):
374
    print(f"Line RGB color: {line.dxf.color.to_hex()}")
375
else:
376
    print(f"Line ACI color: {line.dxf.color}")
377

378
# Color analysis
379
entities_by_color = {}
380
for entity in msp.query('*'):
381
    color = entity.dxf.color
382
    if color not in entities_by_color:
383
        entities_by_color[color] = []
384
    entities_by_color[color].append(entity)
385

386
print(f"Found {len(entities_by_color)} different colors")
387
```
388

389
## Complete Color Management Example
390

391
```python
392
import ezdxf
393
from ezdxf.colors import RGB, RGBA, aci2rgb, transparency2float
394
from ezdxf.colors import RED, GREEN, BLUE, BYLAYER, TRANSPARENCY_25
395

396
# Create document
397
doc = ezdxf.new()
398
msp = doc.modelspace()
399

400
# Define color scheme
401
primary_colors = [
402
    RGB(255, 0, 0),      # Red
403
    RGB(0, 255, 0),      # Green  
404
    RGB(0, 0, 255),      # Blue
405
    RGB(255, 255, 0),    # Yellow
406
    RGB(255, 0, 255),    # Magenta
407
    RGB(0, 255, 255),    # Cyan
408
]
409

410
# Create entities with different color approaches
411
x_offset = 0
412

413
# ACI colors
414
for aci in range(1, 8):
415
    circle = msp.add_circle((x_offset, 0), 2, dxfattribs={
416
        'color': aci,
417
        'layer': 'ACI_COLORS'
418
    })
419
    x_offset += 5
420

421
# RGB colors with transparency
422
x_offset = 0
423
for i, rgb_color in enumerate(primary_colors):
424
    transparency = int(255 * (i + 1) / len(primary_colors) * 0.5)  # Increasing transparency
425
    
426
    rectangle = msp.add_lwpolyline([
427
        (x_offset, 10), (x_offset + 4, 10), 
428
        (x_offset + 4, 14), (x_offset, 14)
429
    ], dxfattribs={
430
        'color': rgb_color,
431
        'transparency': transparency,
432
        'layer': 'RGB_COLORS'
433
    })
434
    rectangle.close()
435
    x_offset += 5
436

437
# Layer-based colors
438
layer = doc.layers.new('COLORED_LAYER', dxfattribs={
439
    'color': GREEN,
440
    'transparency': TRANSPARENCY_25
441
})
442

443
# Entities using layer color
444
for i in range(5):
445
    line = msp.add_line((i * 3, 20), (i * 3 + 2, 22), dxfattribs={
446
        'color': BYLAYER,  # Use layer color
447
        'layer': 'COLORED_LAYER'
448
    })
449

450
# Save document
451
doc.saveas('color_example.dxf')
452
```