hoops_ai.insights.utils

Visualization utilities for HOOPS AI Insights.

Provides domain-agnostic utilities for coloring and visualizing predictions on CAD models. These tools work with any classification/labeling task.

Functions

group_predictions_by_label(predictions, palette)

Group face/element indices by their prediction label and attach colors.

Classes

ColorPalette(mapping)

Container for label-to-color mappings with convenient access methods.
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)

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.)

  • 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)}

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,
...     cmap_name='hsv',
...     reserved_colors={0: (200, 200, 200)}
... )
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))

hoops_ai.insights.utils.group_predictions_by_label(predictions, palette, exclude_labels=None)

Group face/element indices by their prediction label and attach colors.

Takes an array of predictions (one per face/element) and groups the indices by their predicted label, attaching the corresponding color and description from the palette.

Parameters:

  • predictions (numpy.ndarray) – Array where predictions[i] = label for element i

  • palette (ColorPalette) – ColorPalette with colors and descriptions for each label

  • exclude_labels (Set[int] | None) – Optional set of labels to skip (e.g., {0} for background)

Returns:

List of (indices, color, description) tuples, one per unique label

Return type:

List[Tuple[List[int], Tuple[int, int, int], str]]

Examples

>>> predictions = np.array([0, 17, 17, 23, 0, 23, 17])
>>> # After creating palette...
>>> groups = group_predictions_by_label(predictions, palette, exclude_labels={0})
>>> groups
[
    ([1, 2, 6], (255, 0, 0), 'through hole'),
    ([3, 5], (0, 0, 255), 'blind hole')
]