hoops_ai.insights.utils.ColorPalette

class hoops_ai.insights.utils.ColorPalette(mapping)

Bases: object

Container for label-to-color mappings with convenient access methods.

Stores both RGB colors and text descriptions for each label, providing a clean interface for visualization workflows.

Examples

>>> labels_desc = {0: "background", 17: "through hole", 23: "blind hole"}
>>> palette = ColorPalette.from_labels(
...     labels_desc,
...     cmap_name='hsv',
...     reserved_colors={17: (255, 0, 0), 23: (0, 0, 255)}
... )
>>> palette.get_color(17)
(255, 0, 0)
>>> palette.get_description(17)
'through hole'
>>> len(palette)
3
>>> 17 in palette
True
Parameters:

mapping (Dict[int, Tuple[Tuple[int, int, int], str]])

classmethod from_labels(labels, cmap_name='tab20', reserved_colors=None, use_distinct_colors=True)

Create ColorPalette from label descriptions with automatic color generation.

Parameters:

  • labels (Dict[int, str]) – Dict mapping label_id -> description string

  • cmap_name (str) – Matplotlib colormap name (‘tab20’, ‘hsv’, ‘Set3’, ‘viridis’, etc.) Ignored if use_distinct_colors=True

  • reserved_colors (Dict[int, Tuple[int, int, int]] | None) – Optional dict to force specific colors for certain labels Example: {0: (200, 200, 200), 17: (255, 0, 0)}

  • use_distinct_colors (bool) – If True, use algorithm to maximize color distinction (recommended)

Returns:

ColorPalette instance with colors assigned to all labels

Raises:

ImportError – If matplotlib is not available

Return type:

ColorPalette

Examples

>>> labels = {0: "no-label", 1: "hole", 2: "pocket"}
>>> palette = ColorPalette.from_labels(
...     labels,
...     reserved_colors={0: (200, 200, 200)},
...     use_distinct_colors=True
... )
get_all_colors()

Get dict of all label -> color mappings.

Returns:

Dict mapping label_id -> (R, G, B) tuple

Return type:

Dict[int, Tuple[int, int, int]]

get_all_descriptions()

Get dict of all label -> description mappings.

Returns:

Dict mapping label_id -> description string

Return type:

Dict[int, str]

get_color(label)

Get RGB color for a label.

Parameters:

label (int) – Label ID

Returns:

(R, G, B) tuple with 0-255 values

Raises:

KeyError – If label not in palette

Return type:

Tuple[int, int, int]

get_description(label)

Get text description for a label.

Parameters:

label (int) – Label ID

Returns:

Description string

Raises:

KeyError – If label not in palette

Return type:

str

get_label(label)

Alias for get_description() for more intuitive API.

Parameters:

label (int) – Label ID

Returns:

Description string

Return type:

str

items()

Iterate over (label_id, (color, description)) pairs.

Yields:

Tuples of (label_id, (color_rgb, description))