tessl/pypi-ezdxf

A comprehensive Python package for creating, reading, modifying, and writing DXF (Drawing Exchange Format) documents with support for multiple DXF versions.

—

Pending

Overview

Eval results

Files

Colors

Name: tessl/pypi-ezdxf
Author: tessl

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.

Capabilities

RGB Color Management

RGB color representation with comprehensive conversion and manipulation methods.

class RGB:
    """RGB color representation (0-255 per channel)"""
    
    def __init__(self, r: int, g: int, b: int): ...
    
    @property
    def r(self) -> int:
        """Red component (0-255)"""
        
    @property
    def g(self) -> int:
        """Green component (0-255)"""
        
    @property
    def b(self) -> int:
        """Blue component (0-255)"""
        
    @property
    def luminance(self) -> float:
        """Perceived luminance (0-1)"""
        
    def to_floats(self) -> tuple:
        """Convert to float tuple (0.0-1.0 range)"""
        
    @classmethod
    def from_floats(cls, rgb: tuple) -> 'RGB':
        """Create from float tuple (0.0-1.0 range)"""
        
    def to_hex(self) -> str:
        """Convert to hex color string (#RRGGBB)"""
        
    @classmethod
    def from_hex(cls, color: str) -> 'RGB':
        """Create from hex color string (#RGB or #RRGGBB)"""
        
    def __eq__(self, other) -> bool: ...
    def __str__(self) -> str: ...

class RGBA(RGB):
    """RGBA color with alpha channel"""
    
    def __init__(self, r: int, g: int, b: int, a: int = 255): ...
    
    @property
    def a(self) -> int:
        """Alpha component (0-255, 0=transparent, 255=opaque)"""
        
    def to_floats(self) -> tuple:
        """Convert to (r, g, b, a) float tuple"""
        
    @classmethod
    def from_floats(cls, values: tuple) -> 'RGBA':
        """Create from (r, g, b, a) float tuple"""
        
    def to_hex(self) -> str:
        """Convert to hex string with alpha (#RRGGBBAA)"""
        
    @classmethod
    def from_hex(cls, color: str) -> 'RGBA':
        """Create from hex string (#RGB, #RRGGBB, #RRGGBBAA)"""

Usage examples:

from ezdxf.colors import RGB, RGBA

# Create RGB colors
red = RGB(255, 0, 0)
green = RGB(0, 255, 0)
blue = RGB(0, 0, 255)

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

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

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

# Color analysis
luminance = orange.luminance  # Perceived brightness
print(f"Orange luminance: {luminance:.3f}")

AutoCAD Color Index (ACI)

AutoCAD Color Index constants and utilities for standard DXF colors.

# Special ACI values
BYBLOCK: int = 0      # Color determined by block
BYLAYER: int = 256    # Color determined by layer  
BYOBJECT: int = 257   # Color determined by object

# Standard ACI colors (1-255)
RED: int = 1
YELLOW: int = 2
GREEN: int = 3
CYAN: int = 4
BLUE: int = 5
MAGENTA: int = 6
BLACK: int = 7        # Black/white depending on background
WHITE: int = 7        # Same as BLACK
GRAY: int = 8
LIGHT_GRAY: int = 9

# Color type constants
COLOR_TYPE_BY_LAYER: int = 0
COLOR_TYPE_BY_BLOCK: int = 1
COLOR_TYPE_RGB: int = 2
COLOR_TYPE_ACI: int = 3

Usage examples:

from ezdxf.colors import RED, BLUE, BYLAYER, BYBLOCK

# Use ACI colors in entity attributes
line_attribs = {
    'color': RED,        # Use ACI red
    'layer': '0'
}

circle_attribs = {
    'color': BYLAYER,    # Use layer color
    'linetype': 'DASHED'
}

# Create entities with colors
line = msp.add_line((0, 0), (10, 10), dxfattribs=line_attribs)
circle = msp.add_circle((5, 5), 3, dxfattribs=circle_attribs)

Color Conversion Functions

Utility functions for converting between different color representations.

def int2rgb(value: int) -> RGB:
    """
    Convert integer color value to RGB.
    
    Parameters:
    - value: 24-bit integer color value (0xRRGGBB)
    
    Returns:
    RGB: RGB color object
    """

def rgb2int(rgb) -> int:
    """
    Convert RGB color to integer value.
    
    Parameters:
    - rgb: RGB color object or (r, g, b) tuple
    
    Returns:
    int: 24-bit integer color value
    """

def aci2rgb(index: int) -> RGB:
    """
    Convert AutoCAD Color Index to RGB.
    
    Parameters:
    - index: ACI color index (1-255)
    
    Returns:
    RGB: Corresponding RGB color
    """

def decode_raw_color(value: int) -> tuple:
    """
    Decode raw DXF color value to (type, color) tuple.
    
    Parameters:
    - value: raw DXF color value
    
    Returns:
    tuple: (color_type, color_value)
    """

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

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

def luminance(color) -> float:
    """
    Calculate color luminance for contrast calculations.
    
    Parameters:
    - color: RGB color object or tuple
    
    Returns:
    float: Luminance value (0-1)
    """

Usage examples:

from ezdxf.colors import int2rgb, rgb2int, aci2rgb, luminance

# Convert between formats
color_int = 0xFF8000    # Orange
orange_rgb = int2rgb(color_int)    # RGB(255, 128, 0)
back_to_int = rgb2int(orange_rgb)  # 0xFF8000

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

# Calculate luminance for contrast
white_lum = luminance((255, 255, 255))  # ~1.0
black_lum = luminance((0, 0, 0))        # ~0.0
text_contrast = white_lum / black_lum    # High contrast ratio

Transparency Management

Transparency value constants and conversion functions.

def transparency2float(value: int) -> float:
    """
    Convert DXF transparency value to float (0-1).
    
    Parameters:
    - value: DXF transparency value (0-255, higher = more transparent)
    
    Returns:
    float: Alpha value (0.0=transparent, 1.0=opaque)
    """

def float2transparency(value: float) -> int:
    """
    Convert float alpha to DXF transparency value.
    
    Parameters:
    - value: Alpha value (0.0-1.0, 0.0=transparent, 1.0=opaque)
    
    Returns:
    int: DXF transparency value (0-255)
    """

# Transparency constants
TRANSPARENCY_BYBLOCK: int = 0
OPAQUE: int = 0                    # Fully opaque
TRANSPARENCY_10: int = 25          # 10% transparent
TRANSPARENCY_20: int = 51          # 20% transparent
TRANSPARENCY_25: int = 64          # 25% transparent
TRANSPARENCY_30: int = 76          # 30% transparent
TRANSPARENCY_40: int = 102         # 40% transparent
TRANSPARENCY_50: int = 127         # 50% transparent
TRANSPARENCY_60: int = 153         # 60% transparent
TRANSPARENCY_70: int = 178         # 70% transparent
TRANSPARENCY_75: int = 191         # 75% transparent
TRANSPARENCY_80: int = 204         # 80% transparent
TRANSPARENCY_90: int = 229         # 90% transparent

# Raw color value constants
BY_LAYER_RAW_VALUE: int = 0xC0000100
BY_BLOCK_RAW_VALUE: int = 0xC0000000  
WINDOW_BG_RAW_VALUE: int = 0xC0000200

Usage examples:

from ezdxf.colors import transparency2float, float2transparency
from ezdxf.colors import TRANSPARENCY_50, TRANSPARENCY_25

# Convert transparency values
dxf_transparency = TRANSPARENCY_50    # 50% transparent
alpha_float = transparency2float(dxf_transparency)  # 0.5

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

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

circle = msp.add_circle((0, 0), 5, dxfattribs=entity_attribs)

Color Palettes

Predefined color palettes for standard AutoCAD colors.

DXF_DEFAULT_COLORS: List[RGB]
    """Standard AutoCAD 256-color palette (ACI 0-255)"""

DXF_DEFAULT_PAPERSPACE_COLORS: List[RGB]  
    """Paper space color palette for plotting"""

Usage examples:

from ezdxf.colors import DXF_DEFAULT_COLORS, aci2rgb

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

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

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

Entity Color Properties

Working with entity color properties in DXF entities.

# Entity color properties are typically accessed through:
# entity.dxf.color - ACI color index or RGB value
# entity.dxf.transparency - transparency value
# entity.rgb - RGB color tuple (if RGB color)
# entity.color - color index or RGB integer

Usage examples:

import ezdxf
from ezdxf.colors import RGB, BLUE, TRANSPARENCY_30

doc = ezdxf.new()
msp = doc.modelspace()

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

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

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

# Query entity colors
if line.dxf.color == BYLAYER:
    print("Line uses layer color")
elif isinstance(line.dxf.color, RGB):
    print(f"Line RGB color: {line.dxf.color.to_hex()}")
else:
    print(f"Line ACI color: {line.dxf.color}")

# Color analysis
entities_by_color = {}
for entity in msp.query('*'):
    color = entity.dxf.color
    if color not in entities_by_color:
        entities_by_color[color] = []
    entities_by_color[color].append(entity)

print(f"Found {len(entities_by_color)} different colors")

Complete Color Management Example

import ezdxf
from ezdxf.colors import RGB, RGBA, aci2rgb, transparency2float
from ezdxf.colors import RED, GREEN, BLUE, BYLAYER, TRANSPARENCY_25

# Create document
doc = ezdxf.new()
msp = doc.modelspace()

# Define color scheme
primary_colors = [
    RGB(255, 0, 0),      # Red
    RGB(0, 255, 0),      # Green  
    RGB(0, 0, 255),      # Blue
    RGB(255, 255, 0),    # Yellow
    RGB(255, 0, 255),    # Magenta
    RGB(0, 255, 255),    # Cyan
]

# Create entities with different color approaches
x_offset = 0

# ACI colors
for aci in range(1, 8):
    circle = msp.add_circle((x_offset, 0), 2, dxfattribs={
        'color': aci,
        'layer': 'ACI_COLORS'
    })
    x_offset += 5

# RGB colors with transparency
x_offset = 0
for i, rgb_color in enumerate(primary_colors):
    transparency = int(255 * (i + 1) / len(primary_colors) * 0.5)  # Increasing transparency
    
    rectangle = msp.add_lwpolyline([
        (x_offset, 10), (x_offset + 4, 10), 
        (x_offset + 4, 14), (x_offset, 14)
    ], dxfattribs={
        'color': rgb_color,
        'transparency': transparency,
        'layer': 'RGB_COLORS'
    })
    rectangle.close()
    x_offset += 5

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

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

# Save document
doc.saveas('color_example.dxf')

Install with Tessl CLI