# visualizations

Python API: `luxonis_ml.data.utils.visualizations`

## Classes

| Name | Description |
| --- | --- |
|
[`ColorMap`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| A mapping that assigns distinct RGB colors to hashable labels. |

### class `ColorMap`

```python
class ColorMap(Mapping)
```

A mapping that assigns distinct RGB colors to hashable labels.

[ColorMap](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
generates and stores distinct colors for arbitrary hashable labels. Colors are lazily assigned on request using
[distinct_color_generator](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md).

Methods

| Name | Description |
| --- | --- |
|
[`__init__`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| |

#### method `__init__`

```python
def __init__()
```

## Functions

| Name | Description |
| --- | --- |
|
[`add_augmentation_footer`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Append the applied augmentations as a footer below the image. |
|
[`append_text_block`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Append a multi-line text block below the image. |
|
[`concat_images`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Concatenate images into a single labeled image. |
|
[`create_text_image`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Create an image with centered text. |
|
[`distinct_color_generator`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Generate distinct RGB colors using the golden ratio. |
|
[`draw_bbox_label`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Draw the class name label at the top-left corner of the bounding box. |
|
[`draw_cross`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Draw a cross on the image. |
|
[`draw_dashed_rectangle`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Draw a dashed rectangle on the image. |
|
[`draw_keypoint_label`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Draw a text label next to a keypoint on the image. |
|
[`get_contrast_color`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Return a contrasting color for the given RGB color. |
|
[`hsv_to_rgb`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Convert an HSV color to RGB. |
|
[`resolve_color`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Resolve a color to RGB. |
|
[`rgb_to_hsv`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Convert an RGB color to HSV. |
|
[`str_to_rgb`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Convert a string to its deterministic RGB color. |
|
[`visualize`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Visualize labels on the image. |
|
[`wrap_text`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/visualizations.md)
| Wrap text into lines that fit within the given width. |

### function `add_augmentation_footer`

```python
def add_augmentation_footer(image: np.ndarray, augmentations: list[str]) -> np.ndarray
```

Append the applied augmentations as a footer below the image.

### function `append_text_block`

```python
def append_text_block(
    image: np.ndarray,
    lines: list[str],
    font_scale: float,
    bg_color: Color = (245, 245, 245),
    text_color: Color = (32, 32, 32),
) -> np.ndarray
```

Append a multi-line text block below the image.

### function `concat_images`

```python
def concat_images(
    image_dict: dict[str, np.ndarray],
    padding: int = 10,
    label_height: int = 30,
) -> np.ndarray
```

Concatenate images into a single labeled image.

It will attempt to create a square grid of images.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `image_dict` | `dict[str, np.ndarray]` | Mapping of image names to images. | required |
| `padding` | `int` | Padding between images. | `10` |
| `label_height` | `int` | Height of each label. | `30` |

Returns

| Type | Description |
| --- | --- |
| `np.ndarray` | The concatenated image. |

### function `create_text_image`

```python
def create_text_image(
    text: str,
    width: int,
    height: int,
    font_size: float = 0.7,
    bg_color: Color = 255,
    text_color: Color = 0,
) -> np.ndarray
```

Create an image with centered text.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `text` | `str` | Text to display. | required |
| `width` | `int` | Image width. | required |
| `height` | `int` | Image height. | required |
| `font_size` | `float` | Font size for the text. | `0.7` |
| `bg_color` | `Color` | Background color. | `255` |
| `text_color` | `Color` | Text color. | `0` |

Returns

| Type | Description |
| --- | --- |
| `np.ndarray` | The generated image. |

### function `distinct_color_generator`

```python
def distinct_color_generator(stop: int = -1) -> Generator[RGB, None, None]
```

Generate distinct RGB colors using the golden ratio.

This generator produces a sequence of distinct colors in RGB format. The colors are generated by incrementing the hue by the
golden ratio and keeping saturation and value fixed. This ensures a wide distribution of visually distinct colors.

> **Examples**
> ```pycon
>>> colors = list(distinct_color_generator(stop=2))
>>> len(colors)
2
>>> all(len(color) == 3 for color in colors)
True
```

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `stop` | `int` | optional maximum number of colors to generate. If set to − 1, the generator continues indefinitely. | `-1` |

Returns

| Type | Description |
| --- | --- |
| `Generator[RGB, None, None]` |  |

Yields

| Type | Description |
| --- | --- |
|  | The next RGB color with each component in the range [0, 255]. |

### function `draw_bbox_label`

```python
def draw_bbox_label(
    image: np.ndarray,
    class_name: str,
    box: np.ndarray,
    color: tuple[int, int, int],
    font_scale: float,
)
```

Draw the class name label at the top-left corner of the bounding box.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `image` | `np.ndarray` | Image to draw on. | required |
| `class_name` | `str` | Name of the class. | required |
| `box` | `np.ndarray` | Bounding box coordinates in `[class_id, x1, y1, x2, y2]` format, where `(x1, y1)` is the top-left corner and `(x2, y2)` is the bottom-right corner. | required |
| `color` | `tuple[int, int, int]` | Label color. | required |
| `font_scale` | `float` | Font scale. | required |

### function `draw_cross`

```python
def draw_cross(
    img: np.ndarray,
    center: tuple[int, int],
    size: int = 5,
    color: Color = 0,
    thickness: int = 1,
)
```

Draw a cross on the image.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `img` | `np.ndarray` | Image to draw on. | required |
| `center` | `tuple[int, int]` | Center of the cross. | required |
| `size` | `int` | Size of the cross. | `5` |
| `color` | `Color` | Cross color. | `0` |
| `thickness` | `int` | Line thickness. | `1` |

### function `draw_dashed_rectangle`

```python
def draw_dashed_rectangle(
    image: np.ndarray,
    pt1: tuple[int, int],
    pt2: tuple[int, int],
    color: Color,
    thickness: int = 1,
    dash_length: int = 10,
)
```

Draw a dashed rectangle on the image.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `image` | `np.ndarray` | Image to draw on. | required |
| `pt1` | `tuple[int, int]` | Top-left corner of the rectangle. | required |
| `pt2` | `tuple[int, int]` | Bottom-right corner of the rectangle. | required |
| `color` | `Color` | Rectangle color. | required |
| `thickness` | `int` | Line thickness. | `1` |
| `dash_length` | `int` | Length of each dash. | `10` |

### function `draw_keypoint_label`

```python
def draw_keypoint_label(
    image: np.ndarray,
    text: str,
    point: tuple[int, int],
    size: int,
    color: tuple[int, int, int],
    font_scale: float,
)
```

Draw a text label next to a keypoint on the image.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `image` | `np.ndarray` | Image to draw on. | required |
| `text` | `str` | Text to draw. | required |
| `point` | `tuple[int, int]` | Keypoint coordinates. | required |
| `size` | `int` | Keypoint size. | required |
| `color` | `tuple[int, int, int]` | Text color. | required |
| `font_scale` | `float` | Font scale. | required |

### function `get_contrast_color`

```python
def get_contrast_color(color: Color) -> RGB
```

Return a contrasting color for the given RGB color.

> **Examples**
> ```pycon
>>> get_contrast_color((255, 0, 0))
(0, 255, 255)
>>> get_contrast_color(0)
(0, 0, 0)
```

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `color` | `Color` | Color to contrast. | required |

Returns

| Type | Description |
| --- | --- |
| `RGB` | The contrasting color. |

### function `hsv_to_rgb`

```python
def hsv_to_rgb(color: HSV) -> RGB
```

Convert an HSV color to RGB.

> **Examples**
> ```pycon
>>> hsv_to_rgb((0, 1, 1))
(255, 0, 0)
>>> hsv_to_rgb((120, 1, 1))
(0, 255, 0)
```

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `color` | `HSV` | HSV color to convert. | required |

Returns

| Type | Description |
| --- | --- |
| `RGB` | The converted RGB color. |

### function `resolve_color`

```python
def resolve_color(color: Color) -> RGB
```

Resolve a color to RGB.

> **Examples**
> ```pycon
>>> resolve_color(12)
(12, 12, 12)
>>> resolve_color((1, 2, 3))
(1, 2, 3)
>>> resolve_color(300)
Traceback (most recent call last):
...
ValueError: Color value 300 is out of range [0, 255]
```

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `color` | `Color` | Color to resolve. | required |

Returns

| Type | Description |
| --- | --- |
| `RGB` | The resolved RGB color. |

Raises

| Type | Description |
| --- | --- |
| `ValueError` | If an integer channel value is outside [0, 255]. |

### function `rgb_to_hsv`

```python
def rgb_to_hsv(color: Color) -> HSV
```

Convert an RGB color to HSV.

> **Examples**
> ```pycon
>>> tuple(round(v, 3) for v in rgb_to_hsv((255, 0, 0)))
(0.0, 1.0, 1.0)
>>> tuple(round(v, 3) for v in rgb_to_hsv(128))
(0.0, 0.0, 0.502)
```

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `color` | `Color` | Color to convert. | required |

Returns

| Type | Description |
| --- | --- |
| `HSV` | The converted HSV color. |

### function `str_to_rgb`

```python
def str_to_rgb(string: str) -> RGB
```

Convert a string to its deterministic RGB color.

> **Examples**
> ```pycon
>>> str_to_rgb("car") == str_to_rgb("car")
True
>>> len(str_to_rgb("car"))
3
```

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `string` | `str` | String to convert. | required |

Returns

| Type | Description |
| --- | --- |
| `RGB` | Deterministic RGB color. |

### function `visualize`

```python
def visualize(
    image: np.ndarray,
    source_name: str,
    labels: Labels,
    classes: dict[str, dict[str, int]],
    blend_all: bool = False,
    categorical_encodings: dict[str, dict[str, int]] | None = None,
    *,
    skeletons: dict[str, tuple[list[str], list[tuple[int, int]]]] | None = None,
    draw_skeletons: bool = False,
    keypoint_label_mode: Literal['none', 'numbers', 'names', 'full'] = 'numbers',
) -> np.ndarray
```

Visualize labels on the image.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `image` | `np.ndarray` | Image to visualize. | required |
| `source_name` | `str` | Name of the image source. | required |
| `labels` | `Labels` | Labels to visualize. | required |
| `classes` | `dict[str, dict[str, int]]` | Mapping from task names to class ID mappings. | required |
| `blend_all` | `bool` | Whether to blend all labels into a single image. This mixes labels that belong to different tasks. |
`False` |
| `categorical_encodings` | `dict[str, dict[str, int]] | None` | optional mapping for categorical metadata tasks. Keys are full
task identifiers such as `"task_name/metadata/key"` and values map string labels to encoded integers. | `None` |
| `skeletons` | `dict[str, tuple[list[str], list[tuple[int, int]]]] | None` | Optional keypoint skeleton metadata keyed by task
name. | `None` |
| `draw_skeletons` | `bool` | Whether to draw keypoint skeleton edges. | `False` |
| `keypoint_label_mode` | `Literal['none', 'numbers', 'names', 'full']` | Keypoint label mode. `"none"` hides keypoint labels,
`"numbers"` draws numeric indices, and `"full"` draws skeleton keypoint names when available. | `'numbers'` |

Returns

| Type | Description |
| --- | --- |
| `np.ndarray` | The visualized image. |

### function `wrap_text`

```python
def wrap_text(
    text: str,
    max_width: int,
    font_scale: float,
    thickness: int = 1,
) -> list[str]
```

Wrap text into lines that fit within the given width.
