# utils

Python API: `luxonis_train.attached_modules.visualizers.utils`

可视化工具的辅助函数。

这些辅助函数在张量和图像之间进行转换，对输入图像进行反归一化，选择颜色和字体大小，绘制标签，并将标签图像和预测图像组合成一个图像。`Color` 是一种颜色的类型：颜色名称或十六进制字符串，例如 `"#FF0000"`，或 RGB 元组。

## 函数

### combine_visualizations

```python
def combine_visualizations(visualization: Tensor | tuple[Tensor, Tensor] | tuple[Tensor, list[Tensor]]) -> Tensor:
```

将可视化工具的输出组合成一个图像批次。

训练器在每个
[BaseVisualizer.run](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/base_visualizer.md)
的结果上调用此函数：

 * 单个张量：函数返回它不变。
 * 一对 `(labels, predictions)` 张量，以元组或列表形式：函数将两个批次的大小调整为较大的高度。每个批次保持其纵横比。然后函数将批次并排放置，标签在左侧。
 * 一个张量和一个张量列表或元组：函数引发 `NotImplementedError`。

> **示例**
> ```pycon
>>> import torch
>>> labels = torch.zeros(1, 3, 4, 4, dtype=torch.uint8)
>>> predictions = torch.zeros(1, 3, 8, 6, dtype=torch.uint8)
>>> combine_visualizations((labels, predictions)).shape
torch.Size([1, 3, 8, 14])
>>> combine_visualizations(labels) is labels
True
```

参数

 * `visualization` (`Tensor | tuple[Tensor, Tensor] | tuple[Tensor, list[Tensor]]`)：可视化工具的输出。图像的形状为 `[B, C, H, W]`，一对中的两个批次具有相同的 `B` 和 `C`。

返回

 * `Tensor`：形状为 `[B, C, H, W]` 的图像。对于一对，`H` 是较大的高度，`W` 是调整大小后的宽度之和。

引发

 * `NotImplementedError`：当第二个项目是张量列表或元组时。
 * `ValueError`：当 `visualization` 具有任何其他形式时。

### denormalize

```python
def denormalize(img: Tensor, mean: list[float] | float | None = None, std: list[float] | float | None = None, to_uint8: bool =
False) -> Tensor:
```

撤销图像的归一化。

对于每个通道 c，函数计算

yc = xcσc + μc

其中 μ 是 `mean`，σ 是 `std`。使用 `to_uint8`，它将结果乘以 `255`，将其裁剪到 `[0, 255]`，并将其截断为 `uint8`。

> **示例**
> ```pycon
>>> import torch
>>> img = torch.tensor([[[0.0]], [[1.0]], [[-1.0]]])
>>> denormalize(img, mean=0.5, std=0.25).flatten().tolist()
[0.5, 0.75, 0.25]
>>> image = denormalize(img, mean=0.5, std=0.25, to_uint8=True)
>>> image.flatten().tolist()
[127, 191, 63]
```

参数

 * `img` (`Tensor`)：形状为 `[C, H, W]` 的归一化图像。
 * `mean` (`list[float] | float | None`)：归一化的均值，每个通道一个值或所有通道一个 `float`。`None` 选择 `0`。
 * `std` (`list[float] | float | None`)：归一化的标准差，与 `mean` 形式相同。`None` 选择 `1`。
 * `to_uint8` (`bool`)：是否将结果缩放到 `uint8` 图像。

返回

 * `Tensor`：形状为 `[C, H, W]` 的新图像，如果 `to_uint8` 为 `uint8` 类型。

### draw_bounding_box_labels

```python
def draw_bounding_box_labels(img: Tensor, label: Tensor, **kwargs) -> Tensor:
```

在图像上绘制归一化边界框。

函数将框从归一化的 `xywh`（其中 `x` 和 `y` 是左上角）转换为具有图像大小的像素 `xyxy`。然后它调用 `torchvision.utils.draw_bounding_boxes`。它不改变 `label`。

> **示例**
> 宽度为 `8`、高度为 `4` 的图像上的框 `[0.25, 0.25, 0.5, 0.5]` 变为像素框 `[2, 1, 6, 3]`：

```pycon
>>> import torch
>>> img = torch.zeros(3, 4, 8, dtype=torch.uint8)
>>> label = torch.tensor([[0.25, 0.25, 0.5, 0.5]])
>>> draw_bounding_box_labels(img, label, colors="red")[0].tolist()
[[0, 0, 0, 0, 0, 0, 0, 0],
 [0, 0, 255, 255, 255, 255, 255, 0],
 [0, 0, 255, 0, 0, 0, 255, 0],
 [0, 0, 255, 255, 255, 255, 255, 0]]
```

参数

 * `img` (`Tensor`)：形状为 `[C, H, W]` 的 `uint8` 图像。
 * `label` (`Tensor`)：形状为 `[N, 4]` 的框，行格式为 `[x, y, w, h]`，归一化到 `[0, 1]`。
 * `**kwargs`：转发给 `draw_bounding_boxes` 的关键字参数，例如 `labels`、`colors` 和 `width`。

返回

 * `Tensor`：与 `img` 形状相同的新图像，并绘制了框。

### draw_keypoint_labels

```python
def draw_keypoint_labels(img: Tensor, label: Tensor, **kwargs) -> Tensor:
```

在图像上绘制归一化关键点。

函数将 `x` 和 `y` 值按图像宽度和高度缩放，将其截断为整数，并调用 `torchvision.utils.draw_keypoints`。它绘制每个关键点并忽略可见性。

副作用： 当 `label` 是连续的时，函数会就地缩放 `label` 的 `x` 和 `y` 值到像素坐标。

> **示例**
> 关键点落在第 `1` 行第 `2` 列的像素上。调用还会将 `label` 更改为像素坐标：

```pycon
>>> import torch
>>> img = torch.zeros(3, 4, 4, dtype=torch.uint8)
>>> label = torch.tensor([[0.5, 0.25, 2.0]])
>>> out = draw_keypoint_labels(img, label, colors="red", radius=1)
>>> out[0, 1, 2].item(), label.tolist()
(255, [[2.0, 1.0, 2.0]])
```

参数

 * `img` (`Tensor`)：形状为 `[C, H, W]` 的 `uint8` 图像。
 * `label` (`Tensor`)：形状为 `[N, 3K]` 的关键点，行格式为 `[x_1, y_1, v_1, ..., x_K, y_K, v_K]`。坐标归一化到 `[0, 1]`。
 * `**kwargs`：转发给 `draw_keypoints` 的关键字参数，例如 `colors`、`radius` 和 `connectivity`。

返回

 * `Tensor`：与 `img` 形状相同的新图像，并绘制了关键点。如果 `label` 不包含关键点，则返回 `img` 本身。

### draw_segmentation_targets

```python
def draw_segmentation_targets(image: Tensor, target: Tensor, alpha: float = 0.4, colors: Color | list[Color] | None = None) -> Tensor:
```

将分割掩码混合到图像中。

函数将图像和掩码移动到 CPU，并调用 `torchvision.utils.draw_segmentation_masks`。在混合之前，多个掩码中的像素会变为黑色。

> **示例**
> ```pycon
>>> import torch
>>> image = torch.zeros(3, 1, 3, dtype=torch.uint8)
>>> masks = torch.tensor([[[1, 1, 0]], [[0, 1, 1]]])
>>> out = draw_segmentation_targets(
...     image, masks, alpha=1.0, colors=["red", "blue"]
... )
>>> out[0].tolist(), out[2].tolist()
([[255, 0, 0]], [[0, 0, 255]])
```

参数

 * `image` (`Tensor`)：形状为 `[3, H, W]` 的 RGB 图像，`uint8` 类型，或 `[0, 1]` 范围内的浮点类型。
 * `target` (`Tensor`)：形状为 `[N, H, W]` 的掩码，或形状为 `[H, W]` 的单个掩码。每个非零值标记掩码的一个像素。
 * `alpha` (`float`)：掩码的不透明度，从 `0`（透明）到 `1`（不透明）。
 * `colors` (`Color | list[Color] | None`)：每个掩码一种颜色，或所有掩码一种颜色。当为 `None` 时，`torchvision` 选择颜色。

返回

 * `Tensor`：CPU 上的新图像，与 `image` 形状和类型相同。当 `target` 不包含掩码时，`torchvision` 会发出警告，函数返回未更改的图像。

### dynamically_determine_font_scale

```python
def dynamically_determine_font_scale(height: int, width: int, thickness: int, font_scale: float | None = None, scale_factor: float
= 500.0) -> tuple[float, int]:
```

为图像大小选择字体比例和线条粗细。

如果没有 `font_scale`，函数会根据高度 H 和宽度 W 的加权平均值推导出比例：

w = min⎛⎝0.4, (W)/(10max(H, 1))⎞⎠, s = ((1 − w)H + w**W)/(scale_factor)

比例低于 `1` 时，粗细为 `1`。比例为 `1` 或更高时，保持 `thickness`。

> **示例**
> ```pycon
>>> dynamically_determine_font_scale(500, 500, thickness=2)
(1.0, 2)
>>> dynamically_determine_font_scale(100, 200, thickness=2)
(0.24, 1)
```

参数

 * `height` (`int`)：图像高度，以像素为单位。
 * `width` (`int`)：图像宽度，以像素为单位。
 * `thickness` (`int`)：比例为 `1` 或更高时的线条粗细。
 * `font_scale` (`float | None`)：固定的字体比例。`None` 选择计算出的比例。
 * `scale_factor` (`float`)：产生比例 `1` 的有效图像大小，以像素为单位。

返回

 * `tuple[float, int]`：字体比例和线条粗细。

### figure_to_torch

```python
def figure_to_torch(fig: Figure, width: int, height: int) -> Tensor:
```

将 matplotlib 图形渲染为 RGB 图像张量并关闭它。

函数将图形保存为 PNG 图像，具有紧密的边界框且无填充，并将图像大小调整为 `width` 和 `height`。然后它使用 `plt.close` 关闭图形。

> **示例**
> ```pycon
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> _ = ax.plot([0, 1], [0, 1])
>>> figure_to_torch(fig, width=64, height=32).shape
torch.Size([3, 32, 64])
```

参数

 * `fig` (`Figure`)：要渲染的 matplotlib 图形。
 * `width` (`int`)：图像宽度，以像素为单位。
 * `height` (`int`)：图像高度，以像素为单位。

返回

 * `Tensor`：形状为 `[3, height, width]` 的 `uint8` 图像。

### get_color

```python
def get_color(seed: int) -> Color:
```

返回一个整数的独特 RGB 颜色。

颜色不是随机的。相同的 `seed` 总是给出相同的颜色。函数将 `45` 添加到 `seed`，并使用 [number_to_hsl](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md) 和 [hsl_to_rgb](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md) 转换结果。可视化工具将类索引作为 `seed` 传递。

> **示例**
> ```pycon
>>> get_color(0)
(25, 76, 229)
```

参数

 * `seed` (`int`)：选择颜色的整数。

返回

 * `Color`：红色、绿色和蓝色值，范围为 `[0, 255]`。

### get_denormalized_images

```python
def get_denormalized_images(cfg: Config, images: Tensor) -> Tensor:
```

将一批模型输入图像转换为 `uint8` 图像。

当 `trainer.preprocessing.normalize` 处于活动状态时，函数从其 `params` 读取 `mean` 和 `std`，并且
[preprocess_images](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md)
撤销归一化。缺失的键选择 ImageNet 值，`mean` 为 `[0.485, 0.456, 0.406]`，`std` 为 `[0.229, 0.224, 0.225]`。当归一化不处于活动状态时，函数只将图像转换为 `uint8`。

[LuxonisLightningModule](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)
和推理实用程序将结果用作可视化工具的画布。[GradCamCallback](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/callbacks/gradcam_visualizer.md)
在其上绘制热图。

参数

 * `cfg` (`Config`)：模型的配置。
 * `images` (`Tensor`)：形状为 `[B, C, H, W]` 的输入图像，如加载器返回的那样。

返回

 * `Tensor`：形状为 `[B, C, H, W]` 的新 `uint8` 张量。

### get_prediction_labels

```python
def get_prediction_labels(prediction: Tensor, label_dict: Mapping[int, str] | None, draw_labels: bool, draw_scores: bool) -> list[str] | None:
```

构建每个预测框的文本标签。

当设置 `draw_labels` 时，标签包含类名；当设置 `draw_scores` 时，标签包含置信度，保留两位小数。两者之间用空格分隔。

> **示例**
> ```pycon
>>> import torch
>>> prediction = torch.tensor(
...     [
...         [0.0, 0.0, 4.0, 4.0, 0.75, 1.0],
...         [1.0, 1.0, 2.0, 2.0, 0.5, 7.0],
...     ]
... )
>>> get_prediction_labels(prediction, {'1': "cat"}, True, True)
['cat 0.75', '7 0.50']
>>> get_prediction_labels(prediction, None, False, True)
['0.75', '0.50']
```

参数

 * `prediction` (`Tensor`)：形状为 `[M, 6]` 的框，行格式为 `[x1, y1, x2, y2, conf, class]`。
 * `label_dict` (`Mapping[int, str] | None`)：按类索引分类的类名。没有名称的类，或当为 `None` 时所有类，都将其索引作为名称。
 * `draw_labels` (`bool`)：标签是否包含类名。
 * `draw_scores` (`bool`)：标签是否包含置信度。

返回

 * `list[str] | None`：每个框一个标签，或者当 `draw_labels` 和 `draw_scores` 都为 `False` 时为 `None`。

### hsl_to_rgb

```python
def hsl_to_rgb(hsl: tuple[float, float, float]) -> Color:
```

将 HSL 颜色转换为 8 位 RGB 颜色。

函数将每个通道截断为整数。

> **示例**
> ```pycon
>>> hsl_to_rgb((0, 1.0, 0.5))
(255, 0, 0)
```

参数

 * `hsl` (`tuple[float, float, float]`)：色相（以度为单位，范围为 `[0, 360)`），饱和度和亮度（范围为 `[0, 1]`）。

返回

 * `Color`：红色、绿色和蓝色值，范围为 `[0, 255]`。

### number_to_hsl

```python
def number_to_hsl(seed: int) -> tuple[float, float, float]:
```

将整数映射到色相，具有固定的饱和度和亮度。

色相为 `(seed * 157) % 360`。素数因子将连续种子的色相分布在色轮上。饱和度为 `0.8`，亮度为 `0.5`。

> **示例**
> ```pycon
>>> number_to_hsl(3)
(111, 0.8, 0.5)
```

参数

 * `seed` (`int`)：要映射的整数。

返回

 * `tuple[float, float, float]`：色相（以度为单位，范围为 `[0, 360)`），饱和度和亮度。

### numpy_to_torch_img

```python
def numpy_to_torch_img(img: np.ndarray) -> Tensor:
```

将 NumPy 图像转换为 torch 图像。

结果与 `img` 共享内存并保持其 dtype。

> **示例**
> ```pycon
>>> import numpy as np
>>> numpy_to_torch_img(np.zeros((4, 6, 3), dtype=np.uint8)).shape
torch.Size([3, 4, 6])
```

参数

 * `img` (`np.ndarray`)：形状为 `[H, W, C]` 的图像。

返回

 * `Tensor`：形状为 `[C, H, W]` 的视图。

### potentially_upscale_masks

```python
def potentially_upscale_masks(image_masks: Tensor, scale: float = 1.0) -> Tensor:
```

使用最近邻插值按比例调整分割掩码的大小。

新的高度和宽度分别为 `int(H * scale)` 和 `int(W * scale)`，因此小于 `1` 的因子会缩小掩码。当因子为 `1` 时，函数返回未更改的 `image_masks`。

> **示例**
> ```pycon
>>> import torch
>>> masks = torch.tensor([[[True, False], [False, True]]])
>>> potentially_upscale_masks(masks, scale=2.0).int().tolist()
[[[1, 1, 0, 0], [1, 1, 0, 0], [0, 0, 1, 1], [0, 0, 1, 1]]]
```

参数

 * `image_masks` (`Tensor`)：形状为 `[N, H, W]` 的掩码。每个非零值标记掩码的一个像素。
 * `scale` (`float`)：调整大小的因子。

返回

 * `Tensor`：形状为 `[N, int(H * scale), int(W * scale)]` 的布尔掩码，或者当 `scale` 为 `1` 时为 `image_masks` 本身。

### preprocess_images

```python
def preprocess_images(imgs: Tensor, mean: list[float] | float | None = None, std: list[float] | float | None = None) -> Tensor:
```

将一批模型输入图像转换为 `uint8` 图像。

当给定 `mean` 或 `std` 时，[denormalize](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/utils.md) 恢复每个图像并将其缩放到 `[0, 255]`。否则，函数只将图像转换为 `uint8`，因此它们必须已经具有 `[0, 255]` 范围内的值。

> **示例**
> ```pycon
>>> import torch
>>> imgs = torch.zeros(2, 3, 4, 4)
>>> out = preprocess_images(imgs, mean=[0.5, 0.5, 0.5], std=0.5)
>>> out.dtype, out[0, :, 0, 0].tolist()
(torch.uint8, [127, 127, 127])
```

参数

 * `imgs` (`Tensor`)：形状为 `[B, C, H, W]` 的图像。
 * `mean` (`list[float] | float | None`)：归一化的均值，每个通道一个值或所有通道一个值。
 * `std` (`list[float] | float | None`)：归一化的标准差，与 `mean` 形式相同。

返回

 * `Tensor`：形状为 `[B, C, H, W]` 的新 `uint8` 张量。

### torch_img_to_numpy

```python
def torch_img_to_numpy(img: Tensor, reverse_colors: bool = False) -> npt.NDArray[np.uint8]:
```

将 torch 图像转换为 `uint8` NumPy 图像。

函数将浮点图像乘以 `255` 并将其截断为整数。它将所有值裁剪到 `[0, 255]`。

> **示例**
> ```pycon
>>> import torch
>>> img = torch.tensor([[[0.5]], [[1.0]], [[2.0]]])
>>> torch_img_to_numpy(img).tolist()
[[[127, 255, 255]]]
>>> torch_img_to_numpy(img, reverse_colors=True).tolist()
[[[255, 255, 127]]]
```

参数

 * `img` (`Tensor`)：形状为 `[C, H, W]` 的图像。浮点图像的值范围为 `[0, 1]`。
 * `reverse_colors` (`bool`)：是否交换第一个和第三个通道，例如从 RGB 到 BGR。图像必须有三个通道。

返回

 * `npt.NDArray[np.uint8]`：形状为 `[H, W, C]` 的新连续图像。

## 属性

### Color
