# precision_bbox_head

Python API: `luxonis_train.nodes.heads.precision_bbox_head`

YOLOv8 检测头，它回归距离 bin 的分布而不是单一距离。

## 类

### PrecisionBBoxHead

精确边界框检测头。

 * `输入:`: * `inputs` (`list[Tensor]`): 每个尺度的 [B, Ci, Hi, Wi]，输入节点的最后 `n_heads` 个输出
 * `输出:`: * 训练: * `features` (`list[Tensor]`): 每个尺度的 [B, 4⋅regmax + nclasses, Hi, Wi]，logits
    * 评估: * `features` (`list[Tensor]`): 每个尺度的 [B, 4⋅regmax + nclasses, Hi, Wi]，logits
       * `boundingbox` (`list[Tensor]`): 每张图像的 [Mi, 6]，`[x1, y1, x2, y2, score, class]`，像素
       * `detections_pre_nms` (`Tensor`): [B, N, 5 + nclasses]，仅在请求时提供
    * 导出: * `boundingbox` (`list[Tensor]`): 每个尺度的 [B, 5 + nclasses, Hi, Wi]，DFL 解码

> **参考**
> * 来源：重新实现了 [Real-Time Flying Object Detection with YOLOv8](https://arxiv.org/abs/2305.09972) 和 [YOLOv6: A Single-Stage Object Detection Framework for Industrial Applications](https://arxiv.org/abs/2209.02976)。
 * 许可证：Apache-2.0 (本项目)

> **注意事项**
> 该头为每个尺度运行一个 [PreciseDecoupledBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)。回归分支预测框的每一侧在 `reg_max` 个距离 bin 上的分布。[DFL](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md) 将每个分布转换为预期的距离，以步幅单位表示。在评估模式下，该头将锚点周围的距离解码为框并运行 NMS。训练模式跳过此步骤，并且它优先于导出模式。导出模式提供每个尺度的距离和 sigmoid 类分数，不进行 NMS。

 * `变体:`: 无。通过 `params` 配置节点。

> **示例**
> 配置中 `model.nodes` 部分的节点条目：

```yaml
- name: PrecisionBBoxHead
  inputs: [RepPANNeck]
```

 * `兼容:`: * 必需标签: `boundingbox`
    * 损失:
      [PrecisionDFLDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md)
    * 指标: *
      [ConfusionMatrix](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/confusion_matrix/confusion_matrix.md)
       * [MeanAveragePrecision](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/mean_average_precision/mean_average_precision.md)
       * [PrecisionRecallCurve](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/precision_recall_curve.md)
    * 可视化工具:
      [BBoxVisualizer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/visualizers/bbox_visualizer.md)
    * 导出解析器: `YOLO`

#### 方法

##### init

```python
def __init__(n_heads: Literal[2, 3, 4] = 3, conf_thres: float = 0.25, iou_thres: float = 0.45, max_det: int = 300, reg_max: int = 16, **kwargs):
```

为每个尺度初始化一个解耦块。

每个回归分支的隐藏宽度是 `16`、`in_channels[0] // 4` 和 `4 * reg_max` 中的最大值。每个类分支的隐藏宽度是 `in_channels[0]` 和 `min(n_classes, 100)`
中的较大值。`in_channels[0]` 属于第一个尺度。构造函数还将 `grid_cell_offset` 设置为 `0.5`，将 `grid_cell_size` 设置为
`5.0`。[PrecisionDFLDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/precision_dfl_detection_loss.md)
从节点读取这两个值。

参数

 * `n_heads` (`Literal[2, 3, 4]`): 尺度数量。该头读取输入节点的最后 `n_heads` 个输出。`attach_index` 参数替换此选择。当该头获得的输出较少时，它会记录警告并使用该数量。当 `attach_index`
   选择更多输出时，该头为每个输出构建一个块，但只保留 `n_heads` 个步幅。然后构建失败，因为
   [initialize_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_bbox_head.md)
   引发 `ValueError`。
 * `conf_thres` (`float`): NMS 只保留最大类分数高于此值的框。该值必须在 `[0, 1]` 之间。否则，NMS 在评估模式下会引发 `ValueError`。
 * `iou_thres` (`float`): 当框与同类且分数更高的框的 IoU 高于此值时，NMS 会移除该框。该值必须在 `[0, 1]` 之间。否则，NMS 在评估模式下会引发 `ValueError`。
 * `max_det` (`int`): NMS 为每张图像保留的最大框数。
 * `reg_max` (`int`): 框的每一侧的距离 bin 数量。回归分支提供 `4 * reg_max` 个通道。当值大于 `1`
   时，[DFL](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
   将 bin 转换为距离。当值为 `1` 时，该头直接使用回归输出作为距离。
 * `**kwargs`:
   [BaseNode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   的关键字参数。它们必须包含 `original_in_shape`、通过 `input_shapes` 或 `in_sizes` 输入的大小，以及通过 `n_classes` 或 `dataset_metadata` 的类计数。

##### forward

```python
def forward(inputs: list[Tensor]) -> Packet[Tensor]:
```

运行每个尺度的块并构建模式的数据包。

[forward_heads](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_bbox_head.md)
提供每个尺度的特征、类 logits 和距离 bin logits。训练模式优先于导出模式。数据包取决于模式：

 * 训练模式：`"features"` 包含每个尺度的距离 bin logits 和类 logits，形状为 `[B, 4 * reg_max + n_classes, H_i, W_i]`。
 * 导出模式：`"boundingbox"` 包含每个尺度的一个形状为 `[B, 5 + n_classes, H_i, W_i]` 的映射。其通道是步幅单位的距离 `(l, t, r, b)`、最大类分数和类分数。当 `reg_max` 大于 `1`
   时，[DFL](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
   解码距离。分数是 sigmoid 概率。
 * 评估模式：`"features"` 与训练模式相同，以及 NMS 结果 `"boundingbox"`。该头将锚点周围的距离解码为像素中的框，并且不将其裁剪到图像。每张图像获得一个形状为 `[M_i, 6]` 的张量，行格式为 `[x1, y1, x2,
   y2, score, class]`。没有框的图像获得一个形状为 `[0, 5 + n_classes]` 的张量。调用
   [BaseDetectionHead.request_detections_pre_nms](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/base_detection_head.md)
   后，数据包还包含 `"detections_pre_nms"`。这是形状为 `[B, N, 5 + n_classes]` 的 NMS 输入：像素中的 `xyxy` 框、一个常量 `1` 和类分数。`N` 是 `H_i * W_i` 的总和。

> **示例**
> 一个新的头处于训练模式：

```pycon
>>> import torch
>>> from torch import Size
>>> from luxonis_train.nodes import PrecisionBBoxHead
>>> sizes = [Size([1, 8, 32, 32]), Size([1, 16, 16, 16])]
>>> head = PrecisionBBoxHead(
...     n_heads=2,
...     n_classes=3,
...     input_shapes=[{"features": sizes}],
...     original_in_shape=Size([3, 256, 256]),
... )
>>> inputs = [torch.zeros(size) for size in sizes]
>>> [f.shape for f in head(inputs)["features"]]
[torch.Size([1, 67, 32, 32]), torch.Size([1, 67, 16, 16])]
```

对于零输入，新头为每个类提供低于 `conf_thres` 的分数。因此，在评估模式下，NMS 不保留任何框：

```pycon
>>> out = head.eval()(inputs)
>>> sorted(out), out["boundingbox"][0].shape
(['boundingbox', 'features'], torch.Size([0, 8]))
```

导出模式为每个尺度提供一个映射：

```pycon
>>> head.export = True
>>> [b.shape for b in head(inputs)["boundingbox"]]
[torch.Size([1, 8, 32, 32]), torch.Size([1, 8, 16, 16])]
```

参数

 * `inputs` (`list[Tensor]`): 每个尺度的一个特征图，形状为 `[B, C_i, H_i, W_i]`。

返回

 * `Packet[Tensor]`: 当前模式的数据包。

##### forward_heads

```python
def forward_heads(inputs: list[Tensor]) -> tuple[list[Tensor], list[Tensor], list[Tensor]]:
```

运行每个尺度的解耦块。

该方法按顺序将块与 `inputs` 配对。它不应用 sigmoid，因此所有输出都是
logits。[PrecisionSegmentBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_seg_bbox_head.md)
也调用此方法。

> **示例**
> ```pycon
>>> import torch
>>> from torch import Size
>>> from luxonis_train.nodes import PrecisionBBoxHead
>>> sizes = [Size([1, 8, 32, 32]), Size([1, 16, 16, 16])]
>>> head = PrecisionBBoxHead(
...     n_heads=2,
...     n_classes=3,
...     reg_max=4,
...     input_shapes=[{"features": sizes}],
...     original_in_shape=Size([3, 256, 256]),
... )
>>> inputs = [torch.zeros(size) for size in sizes]
>>> features, classes, regressions = head.forward_heads(inputs)
>>> features[1].shape
torch.Size([1, 19, 16, 16])
>>> classes[1].shape[1], regressions[1].shape[1]
(3, 16)
```

参数

 * `inputs` (`list[Tensor]`): 每个尺度的一个特征图，形状为 `[B, C_i, H_i, W_i]`。列表必须为每个块包含一个映射。否则，`zip` 会引发 `ValueError`。

返回

 * `tuple[list[Tensor], list[Tensor], list[Tensor]]`: 三个列表，每个尺度一个张量，按 `inputs` 的顺序排列。 * 特征，沿通道轴连接距离 bin logits 和类 logits，形状为 `[B, 4 * reg_max + n_classes, H_i, W_i]`；
    * 类 logits，形状为 `[B, n_classes, H_i, W_i]`；
    * 距离 bin logits，形状为 `[B, 4 * reg_max, H_i, W_i]`。

##### get_custom_head_config

```python
def get_custom_head_config(self) -> Params:
```

返回 NN Archive 的 NMS 设置和步幅。

子类会将自己的键添加到此字典中，例如 `"subtype"`。

返回

 * `Params`: 一个字典，包含键 `"iou_threshold"`、`"conf_threshold"`、`"max_det"` 和 `"strides"`。它们分别包含 `iou_thres`、`conf_thres`、`max_det` 和 `stride`，其中 `stride` 是一个列表，每个尺度一个整数。

##### initialize_weights

```python
def initialize_weights(method: str | None = None):
```

初始化每个尺度最后一层的偏差。

该方法首先使用 `method` 调用 [BaseNode.initialize_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)。然后，对于步幅为 s 的每个尺度，它设置两个分支的最后一个卷积的偏差。回归偏差的每个值变为 `1`。类偏差的每个值变为：

b = log(5)/(nclasses(H ⁄ s)2)

H 是 `original_in_shape` 中的高度。该方法不改变权重。因此，对于零输入，新头为每个类提供 sigmoid 分数 σ(b)。此分数接近 5 ⁄ (nclasses(H ⁄ s)2)。

> **示例**
> 第一个尺度的步幅为 `8`。对于 `H = 256` 和三个类，新头的类分数接近 5 ⁄ (3⋅322)：

```pycon
>>> from torch import Size
>>> from luxonis_train.nodes import PrecisionBBoxHead
>>> sizes = [Size([1, 8, 32, 32]), Size([1, 16, 16, 16])]
>>> head = PrecisionBBoxHead(
...     n_heads=2,
...     n_classes=3,
...     input_shapes=[{"features": sizes}],
...     original_in_shape=Size([3, 256, 256]),
... )
>>> block = head.heads[0]
>>> block.regression_branch[-1].bias.unique().tolist()
[1.0]
>>> score = block.classification_branch[-1].bias.sigmoid()
>>> round(score[0].item(), 5), round(5 / (3 * 32**2), 5)
(0.00162, 0.00163)
```

参数

 * `method` (`str | None`): [BaseNode.initialize_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md) 的方法。`"yolo"` 更改批归一化和激活设置。其他值跳过该步骤。

#### 属性

##### dfl

##### export_output_names

导出模型的 `n_heads` 个输出的名称。

默认名称是 `output1_yolov8`、`output2_yolov8` 等。`export_output_names` 参数仅在它包含恰好 `n_heads` 个名称时才替换它们。每次它给出默认名称时，该头都会记录警告。该值从不为 `None`。

##### grid_cell_offset

##### grid_cell_size

##### heads

##### no

##### reg_max
