# utils

Python API: `luxonis_train.attached_modules.metrics.mean_average_precision.utils`

平均精度均值指标的辅助函数。

[compute_metric_lists](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/mean_average_precision/utils.md)
将批次转换为 `torchmetrics`
的输入。[postprocess_metrics](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/mean_average_precision/utils.md)
将原始结果转换为主值和训练器记录的其他值。

## 函数

### add_f1_metrics

```python
def add_f1_metrics(metrics: dict[str, Tensor]) -> dict[str, Tensor]:
```

为每对精度和召回值添加 F1 分数。

对于每个包含 `"map"` 的键，函数会查找将 `"map"` 替换为 `"mar"` 的相同键。如果该键存在，函数会添加这两个值的调和平均值。新键将 `"map"` 替换为 `"f1"`：

F1 = (2⋅mAP⋅mAR)/(mAP + mAR)

当两个值都为 `0` 时，F1 分数为 `NaN`。函数会就地更改 `metrics`。

> **示例**
> 键 `"mar"` 不存在，因此 `"map"` 没有 F1 分数。

```pycon
>>> import torch
>>> metrics = {
...     "map": torch.tensor(0.4),
...     "map_small": torch.tensor(0.5),
...     "mar_small": torch.tensor(1.0),
... }
>>> result = add_f1_metrics(metrics)
>>> sorted(result)
['f1_small', 'map', 'map_small', 'mar_small']
>>> round(result["f1_small"].item(), 4)
0.6667
```

参数

 * `metrics` (`dict[str, Tensor]`): 指标值。

返回

 * `dict[str, Tensor]`: 相同的字典，添加了 F1 分数。

### compute_metric_lists

```python
def compute_metric_lists(boundinbox: list[Tensor], target_boundingbox: Tensor, height: int, width: int, *, masks: list[Tensor] | None = None, target_masks: Tensor | None = None) -> tuple[list[dict[str, Tensor]], list[dict[str, Tensor]]]:
```

将一批框转换为 `torchmetrics` 的输入。

该函数为批次中的每个图像构建一个预测字典和一个目标字典。它们的格式是 `torchmetrics` `MeanAveragePrecision` 的 `update` 方法的输入：

 * 预测字典包含 `"boxes"`，即预测框的前四列。它还包含 `"scores"`（第五列）和 `"labels"`（第六列，为 `int32`）。
 * 目标字典包含 `"boxes"`，即图像的目标框，格式为 `xyxy`，单位为像素。它还包含 `"labels"`，即类别列，为 `int32`。
 * 对于掩码，每个字典还包含 `"masks"`，即图像的掩码，为 `bool`。

> **示例**
> ```pycon
>>> import torch
>>> boxes = [torch.tensor([[10.0, 20.0, 50.0, 60.0, 0.5, 1.0]])]
>>> targets = torch.tensor([[0.0, 1.0, 0.25, 0.5, 0.5, 0.25]])
>>> preds, target = compute_metric_lists(
...     boxes, targets, height=200, width=100
... )
>>> preds[0]["scores"].tolist(), preds[0]["labels"].tolist()
([0.5], [1])
>>> target[0]["boxes"].tolist()
[[25.0, 100.0, 75.0, 150.0]]
```

参数

 * `boundinbox` (`list[Tensor]`): 每个图像的预测框，形状为 `[M_i, 6]`，格式为 `[x1, y1, x2, y2, score, class]`，单位为像素。
 * `target_boundingbox` (`Tensor`): 批次的目标框，形状为 `[N, 6]`，格式为 `[batch_index, class, x, y, w, h]`。`x` 和 `y` 是归一化的左上角坐标，`w` 和 `h` 是归一化的大小。
 * `height` (`int`): 图像高度，单位为像素。它用于缩放目标框的 `y` 坐标。
 * `width` (`int`): 图像宽度，单位为像素。它用于缩放目标框的 `x` 坐标。
 * `masks` (`list[Tensor] | None`): 每个图像的预测掩码，形状为 `[M_i, H, W]`。`None` 表示不添加掩码。
 * `target_masks` (`Tensor | None`): 批次的目标掩码，形状为 `[N, H, W]`，与 `target_boundingbox` 的每一行对应。`None` 表示不添加掩码。

返回

 * `tuple[list[dict[str, Tensor]], list[dict[str, Tensor]]]`: 预测字典和目标字典，`boundinbox` 的每个项目对应一个。

引发

 * `ValueError`: 当只给出 `masks` 和 `target_masks` 中的一个时。

### postprocess_metrics

```python
def postprocess_metrics(metrics: dict[str, Tensor], class_names: Mapping[int, str], main_metric: str, device: torch.device) ->
tuple[Tensor, dict[str, Tensor]]:
```

将原始指标值拆分为主值和其他值。

该函数使用 [add_f1_metrics](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/mean_average_precision/utils.md) 添加 F1 分数。然后，它使用 [process_class_metrics](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/mean_average_precision/utils.md) 拆分每个按类别张量。最后，它从字典中删除 `main_metric` 并单独返回该值。该函数会就地更改 `metrics`。

> **示例**
> ```pycon
>>> import torch
>>> metrics = {
...     "map": torch.tensor(0.5),
...     "map_small": torch.tensor(0.5),
...     "mar_small": torch.tensor(1.0),
...     "classes": torch.tensor([0]),
... }
>>> main, others = postprocess_metrics(
...     metrics, {0: "person"}, "map", torch.device("cpu")
... )
>>> main.item()
0.5
>>> {key: round(value.item(), 3) for key, value in others.items()}
{'map_small': 0.5, 'mar_small': 1.0, 'f1_small': 0.667}
```

参数

 * `metrics` (`dict[str, Tensor]`): 原始指标值。字典必须包含键 `"classes"`，请参阅
   [process_class_metrics](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/mean_average_precision/utils.md)。
 * `class_names` (`Mapping[int, str]`): 类别名称，以类别索引为键。
 * `main_metric` (`str`): 主值的键，例如 `"map"`。
 * `device` (`torch.device`): 当 `metrics` 没有键 `main_metric` 时，函数返回的零张量的设备。

返回

 * `tuple[Tensor, dict[str, Tensor]]`: 主值和其他值的字典。当 `metrics` 没有键 `main_metric` 时，主值是 `device` 上的零张量。

### process_class_metrics

```python
def process_class_metrics(metrics: dict[str, Tensor], class_names: Mapping[int, str]) -> dict[str, Tensor]:
```

将每个按类别张量拆分为每个类别一个标量值。

该函数删除键 `"classes"` 和每个以 `"_per_class"` 结尾的键。一个包含多个元素的按类别张量会为每个类别生成一个新键，即 `"<key>_<class name>"`。其值是类别在 `"classes"`
中位置的元素。类别名称中的空格会变成下划线。

一个包含一个元素的按类别张量不会生成新键。例如，当按类别指标关闭时，`torchmetrics` 返回 `[-1]`。该函数会就地更改 `metrics`。

> **示例**
> ```pycon
>>> import torch
>>> metrics = {
...     "map": torch.tensor(0.5),
...     "map_per_class": torch.tensor([0.25, 0.75]),
...     "classes": torch.tensor([0, 1]),
... }
>>> names = {0: "person", 1: "traffic light"}
>>> result = process_class_metrics(metrics, names)
>>> sorted(result)
['map', 'map_per_class_person', 'map_per_class_traffic_light']
>>> result["map_per_class_traffic_light"].item()
0.75
```

参数

 * `metrics` (`dict[str, Tensor]`): 指标值。字典必须包含键 `"classes"`，一个包含按类别值顺序的类别索引的张量。
 * `class_names` (`Mapping[int, str]`): 类别名称，以类别索引为键。它必须包含 `"classes"` 的每个索引。

返回

 * `dict[str, Tensor]`: 相同的字典，不包含 `"classes"` 和按类别张量，并包含每个类别的值。
