Color Utils

GitHub Link to Code.

Central color utilities for consistent color generation across modules.

This module provides utilities for generating perceptually distinct colors using HSV color space. Used by plots, structure visualization, and other modules requiring color mapping.

class mdxplain.utils.color_utils.ColorUtils

Utility class for consistent color generation across all modules.

Provides static methods for generating perceptually distinct colors using HSV color space. Colors are distributed evenly across the hue spectrum with variations in saturation and value for distinction.

Examples

>>> colors = ColorUtils.generate_distinct_colors(3)
>>> len(colors)
3
>>> colors[0]
'#bf4040'

>>> # Add special color for noise/undefined
>>> colors_with_special = ColorUtils.add_special_color(colors, -1, "#000000")
>>> len(colors_with_special)
4
static generate_distinct_colors(n_items: int) → Dict[int, str]

Generate perceptually distinct colors using HSV color space.

Creates a mapping of indices to hex color strings with colors distributed evenly across the hue spectrum. Variations in saturation and value provide additional distinction.

Parameters

n_itemsint

Number of distinct colors to generate

Returns

Dict[int, str]

Mapping from index (0 to n_items-1) to hex color string

Examples

>>> colors = ColorUtils.generate_distinct_colors(3)
>>> len(colors)
3
>>> colors[0]
'#bf4040'

>>> colors = ColorUtils.generate_distinct_colors(100)
>>> len(colors)
100

Notes

  • Uses HSV color space for perceptually distinct colors

  • Hue varies across full spectrum (0-1)

  • Saturation varies 0.65-0.85 for visual variety

  • Value (brightness) varies 0.75-0.90 for readability

  • Deterministic: same n_items always gives same colors

static add_special_color(colors: Dict[int, str], special_index: int, color: str) → Dict[int, str]

Add special color to existing color dictionary.

Parameters

colorsDict[int, str]

Existing color mapping

special_indexint

Index for special color (e.g., -1 for noise)

colorstr

Hex color string for special index

Returns

Dict[int, str]

Updated color mapping with special color added

Examples

>>> colors = ColorUtils.generate_distinct_colors(3)
>>> colors_with_noise = ColorUtils.add_special_color(
...     colors, -1, "#000000"
... )
>>> len(colors_with_noise)
4
>>> colors_with_noise[-1]
'#000000'

Notes

Does not modify original dictionary - returns new dict with special color added.