color_tools.naming

Color naming utilities for generating descriptive names from RGB values.

This module provides intelligent color naming that: - Matches exact CSS colors when possible - Identifies near matches to CSS colors - Generates descriptive names based on HSL properties - Avoids collisions with existing color names

color_tools.naming.get_lightness_modifier(l)[source]

Get lightness modifier based on LAB L* value.

Parameters:: l (float) – LAB L* value (0-100)
Returns:: “very light”, “light”, “medium”, “dark”, “very dark”, or “”
Return type:: str

color_tools.naming.get_saturation_modifier(s, l)[source]

Get saturation modifier based on HSL saturation and lightness.

Parameters:

s (float) – HSL saturation (0-100)
l (float) – LAB L* value (0-100) for context

Returns:

“pale”, “muted”, “dull”, “bright”, “deep”, “vivid”, or “”

Return type:

str

color_tools.naming.get_hue_with_ish(h, s)[source]

Get “-ish” hue variant if near a boundary, otherwise None.

When a hue is within ±8° of a major hue boundary, we can describe it with an “-ish” modifier for more variety and precision.

Parameters:

h (float) – HSL hue (0-360)
s (float) – HSL saturation (0-100) - only apply -ish to saturated colors

Return type:

str | None

Returns:

“-ish” hue variant (e.g., “reddish orange”) or None if not near boundary

color_tools.naming.determine_base_hue(h, s, l)[source]

Determine base hue name including special cases and “-ish” variants.

Special cases like brown, pink, gold, etc. are determined by combinations of hue, saturation, and lightness.

When near hue boundaries (±8°), returns “-ish” variants for more descriptive names (e.g., “yellowish orange”, “reddish brown”).

Parameters:

h (float) – HSL hue (0-360)
s (float) – HSL saturation (0-100)
l (float) – LAB L* value (0-100)

Return type:

str

Returns:

Base hue name (e.g., “red”, “brown”, “teal”, “yellowish orange”)

color_tools.naming.get_generic_hue(h)[source]

Get generic hue name from hue angle (fallback for collision avoidance).

This uses simple hue ranges without special cases like brown, teal, etc.

Parameters:: h (float) – HSL hue (0-360)
Return type:: str
Returns:: Generic hue name

color_tools.naming.is_unique_near_claim(rgb, css_name, palette_colors=None, threshold=5.0)[source]

Return whether an RGB value uniquely qualifies as near a CSS color.

Return type:

bool

Parameters:

rgb (tuple[int, int, int])
css_name (str)
palette_colors (list[tuple[int, int, int]] | None)
threshold (float)

color_tools.naming.iter_color_names(rgb_colors, palette_colors=None, near_threshold=5.0)[source]

Lazily generate names while loading the CSS palette at most once.

The palette is loaded when the first input color is requested. Empty iterables therefore perform no palette loading.

Return type:

Iterator[tuple[str, Literal['exact', 'near', 'generated']]]

Parameters:

rgb_colors (Iterable[tuple[int, int, int]])
palette_colors (list[tuple[int, int, int]] | None)
near_threshold (float)

color_tools.naming.generate_color_names(rgb_colors, palette_colors=None, near_threshold=5.0)[source]

Generate names for RGB colors with one shared CSS palette load.

Return type:

list[tuple[str, Literal['exact', 'near', 'generated']]]

Parameters:

rgb_colors (Iterable[tuple[int, int, int]])
palette_colors (list[tuple[int, int, int]] | None)
near_threshold (float)

color_tools.naming.generate_color_name(rgb, palette_colors=None, near_threshold=5.0)[source]

Generate a descriptive name and match classification for one RGB color.

Naming prioritizes exact CSS matches, then unique near matches, and finally descriptive HSL/LAB-based names.

Examples

>>> generate_color_name((255, 0, 0))
('red', 'exact')
>>> generate_color_name((255, 10, 10))
('near red', 'near')

Return type:

tuple[str, Literal['exact', 'near', 'generated']]

Parameters:

rgb (tuple[int, int, int])
palette_colors (list[tuple[int, int, int]] | None)
near_threshold (float)