Color Analysis

This module provides color analysis and palette management capabilities.

Color Analysis Functions

Color analysis and palette management subsystem.

This package provides comprehensive color handling capabilities including contrast analysis, palette validation, and color space management for QR code generation.

Key Components:

Color Analysis:

• Contrast ratio calculations (WCAG standards)

• Luminance calculations

• Color parsing from various formats

Palette Management:

• Color palette validation

• Multi-color space support

• Accessibility compliance checking

The color subsystem handles:

• Color contrast validation for scanability

• WCAG accessibility compliance

• Color space conversions

• Palette optimization

• Color parsing (hex, rgb, named colors)

• Luminance calculations

Example

Basic color analysis:

from segnomms.color import calculate_contrast_ratio, parse_color

dark = parse_color("#1a1a2e")
light = parse_color("#ffffff")
ratio = calculate_contrast_ratio(dark, light)

Palette validation:

from segnomms.color import ColorPalette, ContrastStandard

palette = ColorPalette(
    foreground="#1a1a2e",
    background="#ffffff",
    standard=ContrastStandard.AA_NORMAL
)
is_valid = palette.validate_contrast()

See also

segnomms.color.color_analysis: Color analysis utilities segnomms.color.palette: Palette management

segnomms.color.calculate_contrast_ratio(color1, color2)

Calculate WCAG contrast ratio between two colors.

Parameters:

• color1 (str) – First color string

• color2 (str) – Second color string

Return type:

Optional[float]

Returns:

Contrast ratio (1.0-21.0), or None if colors can’t be parsed

segnomms.color.calculate_luminance(rgb)

Calculate relative luminance of a color.

Uses the W3C formula for relative luminance calculation.

Parameters:

rgb (Tuple[int, int, int]) – RGB color tuple (r, g, b) with values 0-255

Return type:

float

Returns:

Relative luminance value 0.0-1.0

segnomms.color.parse_color(color_str)

Parse a color string into RGB components.

Supports: - Hex colors: #RGB, #RRGGBB - RGB function: rgb(r, g, b) - Named colors: black, white, red, green, blue, etc.

Parameters:

color_str (str) – Color string to parse

Return type:

Optional[Tuple[int, int, int]]

Returns:

RGB tuple (r, g, b) with values 0-255, or None if unparseable

class segnomms.color.PaletteConfig(**data)

Bases: BaseModel

Enhanced palette configuration.

Parameters:

• dark (str)

• light (str)

• accent_colors (List[str])

• palette_type (PaletteType)

• min_contrast_ratio (float)

• color_space (ColorSpace)

• enforce_standards (bool)

• validate_accessibility (bool)

• allow_similar_colors (bool)

• max_colors (int)

get_all_colors()

Get all colors in the palette.

Return type:

List[str]

get_primary_contrast()

Get contrast analysis for primary dark/light colors.

Return type:

Optional[ContrastAnalysis]

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod validate_accent_colors(v)

Validate accent colors.

Return type:

List[str]

Parameters:

v (List[str])

classmethod validate_color_format(v)

Validate that color can be parsed.

Return type:

str

Parameters:

v (str)

validate_palette()

Validate the entire palette.

Return type:

PaletteValidationResult

dark: str

light: str

accent_colors: List[str]

palette_type: PaletteType

min_contrast_ratio: float

color_space: ColorSpace

enforce_standards: bool

validate_accessibility: bool

allow_similar_colors: bool

max_colors: int

class segnomms.color.PaletteType(*values)

Bases: str, Enum

Types of color palettes.

MONOCHROME = 'monochrome'

COMPLEMENTARY = 'complementary'

ANALOGOUS = 'analogous'

TRIADIC = 'triadic'

CUSTOM = 'custom'

class segnomms.color.ColorSpace(*values)

Bases: str, Enum

Supported color spaces for palette validation.

SRGB = 'sRGB'

DISPLAY_P3 = 'Display-P3'

REC2020 = 'Rec.2020'

class segnomms.color.ContrastStandard(*values)

Bases: str, Enum

WCAG contrast standards.

AA_NORMAL = 'AA-normal'

AA_LARGE = 'AA-large'

AAA_NORMAL = 'AAA-normal'

AAA_LARGE = 'AAA-large'

QR_OPTIMAL = 'QR-optimal'

class segnomms.color.PaletteValidationResult(**data)

Bases: BaseModel

Result of palette validation.

Parameters:

• is_valid (bool)

• primary_contrast (ContrastAnalysis | None)

• issues (List[str])

• warnings (List[str])

• suggestions (List[str])

• color_info (Dict[str, Dict[str, Any]])

• contrast_matrix (Dict[str, Dict[str, float]])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

is_valid: bool

primary_contrast: Optional[ContrastAnalysis]

issues: List[str]

warnings: List[str]

suggestions: List[str]

color_info: Dict[str, Dict[str, Any]]

contrast_matrix: Dict[str, Dict[str, float]]

Core Functions

segnomms.color.calculate_contrast_ratio(color1, color2)

Calculate WCAG contrast ratio between two colors.

Parameters:

• color1 (str) – First color string

• color2 (str) – Second color string

Return type:

Optional[float]

Returns:

Contrast ratio (1.0-21.0), or None if colors can’t be parsed

segnomms.color.calculate_luminance(rgb)

Calculate relative luminance of a color.

Uses the W3C formula for relative luminance calculation.

Parameters:

rgb (Tuple[int, int, int]) – RGB color tuple (r, g, b) with values 0-255

Return type:

float

Returns:

Relative luminance value 0.0-1.0

segnomms.color.parse_color(color_str)

Parse a color string into RGB components.

Supports: - Hex colors: #RGB, #RRGGBB - RGB function: rgb(r, g, b) - Named colors: black, white, red, green, blue, etc.

Parameters:

color_str (str) – Color string to parse

Return type:

Optional[Tuple[int, int, int]]

Returns:

RGB tuple (r, g, b) with values 0-255, or None if unparseable

Palette Management

class segnomms.color.PaletteConfig(**data)

Bases: BaseModel

Enhanced palette configuration.

Parameters:

• dark (str)

• light (str)

• accent_colors (List[str])

• palette_type (PaletteType)

• min_contrast_ratio (Annotated[float, Ge(ge=1.0), Le(le=21.0)])

• color_space (ColorSpace)

• enforce_standards (bool)

• validate_accessibility (bool)

• allow_similar_colors (bool)

• max_colors (Annotated[int, Ge(ge=2), Le(le=50)])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

dark: str

light: str

accent_colors: List[str]

palette_type: PaletteType

min_contrast_ratio: float

color_space: ColorSpace

enforce_standards: bool

validate_accessibility: bool

allow_similar_colors: bool

max_colors: int

classmethod validate_color_format(v)

Validate that color can be parsed.

Return type:

str

Parameters:

v (str)

classmethod validate_accent_colors(v)

Validate accent colors.

Return type:

List[str]

Parameters:

v (List[str])

get_primary_contrast()

Get contrast analysis for primary dark/light colors.

Return type:

Optional[ContrastAnalysis]

get_all_colors()

Get all colors in the palette.

Return type:

List[str]

validate_palette()

Validate the entire palette.

Return type:

PaletteValidationResult

class segnomms.color.PaletteValidationResult(**data)

Bases: BaseModel

Result of palette validation.

Parameters:

• is_valid (bool)

• primary_contrast (ContrastAnalysis | None)

• issues (List[str])

• warnings (List[str])

• suggestions (List[str])

• color_info (Dict[str, Dict[str, Any]])

• contrast_matrix (Dict[str, Dict[str, float]])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

is_valid: bool

primary_contrast: Optional[ContrastAnalysis]

issues: List[str]

warnings: List[str]

suggestions: List[str]

color_info: Dict[str, Dict[str, Any]]

contrast_matrix: Dict[str, Dict[str, float]]

Color Standards

class segnomms.color.ContrastStandard(*values)

Bases: str, Enum

WCAG contrast standards.

AA_NORMAL = 'AA-normal'

AA_LARGE = 'AA-large'

AAA_NORMAL = 'AAA-normal'

AAA_LARGE = 'AAA-large'

QR_OPTIMAL = 'QR-optimal'

class segnomms.color.ColorSpace(*values)

Bases: str, Enum

Supported color spaces for palette validation.

SRGB = 'sRGB'

DISPLAY_P3 = 'Display-P3'

REC2020 = 'Rec.2020'

Example Usage

Color contrast analysis:

from segnomms.color import calculate_contrast_ratio, parse_color

dark = parse_color("#1a1a2e")
light = parse_color("#ffffff")
ratio = calculate_contrast_ratio(dark, light)
print(f"Contrast ratio: {ratio:.2f}:1")

Palette validation:

from segnomms.color import PaletteConfig, ContrastStandard

palette = PaletteConfig(
    foreground="#1a1a2e",
    background="#ffffff",
    standard=ContrastStandard.AA_NORMAL
)
is_valid = palette.validate_contrast()