# visualizations

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

## Classes

### ColorMap

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

##### init

```python
def __init__(self):
```

## Functions

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

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

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

Parameters

 * `image_dict` (`dict[str, np.ndarray]`): Mapping of image names to images.
 * `padding` (`int`): Padding between images.
 * `label_height` (`int`): Height of each label.

Returns

 * `np.ndarray`: The concatenated image.

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

Parameters

 * `text` (`str`): Text to display.
 * `width` (`int`): Image width.
 * `height` (`int`): Image height.
 * `font_size` (`float`): Font size for the text.
 * `bg_color` (`Color`): Background color.
 * `text_color` (`Color`): Text color.

Returns

 * `np.ndarray`: The generated image.

### 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
```

Parameters

 * `stop` (`int`): optional maximum number of colors to generate. If set to − 1, the generator continues indefinitely.

Returns

 * `Generator[RGB, None, None]`

Yields

 * The next RGB color with each component in the range [0, 255].

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

Parameters

 * `image` (`np.ndarray`): Image to draw on.
 * `class_name` (`str`): Name of the class.
 * `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.
 * `color` (`tuple[int, int, int]`): Label color.
 * `font_scale` (`float`): Font scale.

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

Parameters

 * `img` (`np.ndarray`): Image to draw on.
 * `center` (`tuple[int, int]`): Center of the cross.
 * `size` (`int`): Size of the cross.
 * `color` (`Color`): Cross color.
 * `thickness` (`int`): Line thickness.

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

Parameters

 * `image` (`np.ndarray`): Image to draw on.
 * `pt1` (`tuple[int, int]`): Top-left corner of the rectangle.
 * `pt2` (`tuple[int, int]`): Bottom-right corner of the rectangle.
 * `color` (`Color`): Rectangle color.
 * `thickness` (`int`): Line thickness.
 * `dash_length` (`int`): Length of each dash.

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

Parameters

 * `image` (`np.ndarray`): Image to draw on.
 * `text` (`str`): Text to draw.
 * `point` (`tuple[int, int]`): Keypoint coordinates.
 * `size` (`int`): Keypoint size.
 * `color` (`tuple[int, int, int]`): Text color.
 * `font_scale` (`float`): Font scale.

### 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)
```

Parameters

 * `color` (`Color`): Color to contrast.

Returns

 * `RGB`: The contrasting color.

### 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)
```

Parameters

 * `color` (`HSV`): HSV color to convert.

Returns

 * `RGB`: The converted RGB color.

### 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]
```

Parameters

 * `color` (`Color`): Color to resolve.

Returns

 * `RGB`: The resolved RGB color.

Raises

 * `ValueError`: If an integer channel value is outside [0, 255].

### 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)
```

Parameters

 * `color` (`Color`): Color to convert.

Returns

 * `HSV`: The converted HSV color.

### 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
```

Parameters

 * `string` (`str`): String to convert.

Returns

 * `RGB`: Deterministic RGB color.

### 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) -> np.ndarray:
```

Visualize labels on the image.

Parameters

 * `image` (`np.ndarray`): Image to visualize.
 * `source_name` (`str`): Name of the image source.
 * `labels` (`Labels`): Labels to visualize.
 * `classes` (`dict[str, dict[str, int]]`): Mapping from task names to class ID mappings.
 * `blend_all` (`bool`): Whether to blend all labels into a single image. This mixes labels that belong to different tasks.
 * `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.

Returns

 * `np.ndarray`: The visualized image.

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