# efficient_bbox_head

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

YOLOv6 的解耦检测头。

## 类

### EfficientBBoxHead

高效目标检测头。

 * `输入:`: * `inputs` (`list[Tensor]`): 每个尺度的 [B, Ci, Hi, Wi]
 * `输出:`: * 训练: * `features` (`list[Tensor]`): 每个尺度的 [B, Ci, Hi, Wi]
       * `class_scores` (`Tensor`): [B, N, nclasses]
       * `distributions` (`Tensor`): [B, N, 4]，步幅单位的 `(l, t, r, b)`
    * 评估: * `features` (`list[Tensor]`): 每个尺度的 [B, Ci, Hi, Wi]
       * `class_scores` (`Tensor`): [B, N, nclasses]
       * `distributions` (`Tensor`): [B, N, 4]，步幅单位的 `(l, t, r, b)`
       * `boundingbox` (`list[Tensor]`): 每张图像的 [Mi, 6]，`[x1, y1, x2, y2, conf, class]`，像素
       * `detections_pre_nms` (`Tensor`): [B, N, 5 + nclasses]，仅在请求时
    * 导出: * `boundingbox` (`list[Tensor]`): 每个尺度的 [B, 5 + nclasses, Hi, Wi]，`(l, t, r, b)` 然后是分数

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

> **注意**
> 该头为每个尺度运行一个 [EfficientDecoupledBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)。在评估模式下，它解码锚点周围的距离到框中并运行 NMS。训练模式和导出模式跳过此步骤。

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

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

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

 * `兼容:`: * 所需标签: `boundingbox`
    * 使用者:
      [DetectionModel](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/config/predefined_models/detection/v1/model.md)
    * 损失:
      [AdaptiveDetectionLoss](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/losses/adaptive_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`
    * 预训练权重: 可通过 `weights: download` 获取

#### 方法

##### 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, bias_init_p: float = 0.01, **kwargs):
```

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

参数

 * `n_heads` (`Literal[2, 3, 4]`): 尺度数量。头读取输入节点的最后 `n_heads` 个输出。`attach_index`
   参数替换此选择。该值通常等于颈部输出的数量。当输入节点提供的输出较少时，头会记录警告并使用该数量。默认为 `3`。
 * `conf_thres` (`float`): NMS 仅保留最大类别分数高于此值的框。该值必须在 `[0, 1]` 之间。默认为 `0.25`。
 * `iou_thres` (`float`): 当与具有相同类别和更高分数的框的 IoU 高于此值时，NMS 会移除该框。该值必须在 `[0, 1]` 之间。默认为 `0.45`。
 * `max_det` (`int`): NMS 为每张图像保留的最大框数。默认为 `300`。
 * `bias_init_p` (`float`):
   每个锚点的初始类别分数。[initialize_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_bbox_head.md)
   从中设置类别偏差。默认为 `1e-2`。
 * `**kwargs`:
   [BaseNode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   的关键字参数，例如 `n_classes` 和 `input_shapes`。

##### forward

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

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

每个
[EfficientDecoupledBlock](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/blocks/blocks.md)
返回解码后的特征、类别 logits 和一个尺度的距离。头对类别 logits 应用 sigmoid。导出模式优先于训练模式。数据包取决于模式:

 * 导出模式: `"boundingbox"` 为每个尺度保存一个形状为 `[B, 5 + n_classes, H_i, W_i]` 的映射。其通道是距离 `(l, t, r, b)`、最大类别分数和类别分数。
 * 训练模式: `"features"` 为每个尺度保存形状为 `[B, C_i, H_i, W_i]` 的解码特征图。形状为 `[B, N, n_classes]` 的 `"class_scores"` 和形状为 `[B, N, 4]` 的
   `"distributions"` 保存所有 `N` 个锚点的类别分数和距离。距离 `(l, t, r, b)` 以步幅单位表示。`N` 是 `H_i * W_i` 的总和。
 * 评估模式: 训练键和 `"boundingbox"`。头将距离解码为像素框并运行 NMS。每张图像获得一个形状为 `[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` 和类别分数。

> **示例**
> ```pycon
>>> import torch
>>> from torch import Size
>>> from luxonis_train.nodes import EfficientBBoxHead
>>> sizes = [Size([1, 8, 32, 32]), Size([1, 16, 16, 16])]
>>> head = EfficientBBoxHead(
...     n_heads=2,
...     n_classes=3,
...     input_shapes=[{"features": sizes}],
...     original_in_shape=Size([3, 256, 256]),
... )
>>> out = head([torch.zeros(size) for size in sizes])
>>> out["class_scores"].shape, out["distributions"].shape
(torch.Size([1, 1280, 3]), torch.Size([1, 1280, 4]))
```

一个新的头给每个类别 `0.01` 的分数，这低于 `conf_thres`。在评估模式下，NMS 因此不保留任何框:

```pycon
>>> out = head.eval()([torch.zeros(size) for size in sizes])
>>> sorted(out)
['boundingbox', 'class_scores', 'distributions', 'features']
>>> out["boundingbox"][0].shape
torch.Size([0, 8])
```

参数

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

返回

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

##### 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` 作为每个尺度一个整数的列表。

##### get_weights_url

```python
def get_weights_url(self) -> str:
```

从输入通道中选择 COCO 检查点。

头没有变体。[RepPANNeck](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/necks/reppan_neck/reppan_neck.md) 的 `"n"`、`"s"` 和 `"l"` 变体的输入通道选择相同大小的检查点。检查点不包含类别分支，因此任何 `n_classes` 都可以加载它们。

引发

 * `NotImplementedError`: 当输入通道不是 `[32, 64, 128]`、`[64, 128, 256]` 或 `[128, 256, 512]` 时。

##### initialize_weights

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

初始化权重和最后一层的先验。

该方法首先调用 [BaseNode.initialize_weights](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)。然后，对于每个尺度，它将两个分支的最后一个卷积的权重设置为零。类别分支的偏差变为 − log((1 − p) ⁄ p)，其中 p 是 `bias_init_p`。回归分支的偏差变为 `1`。因此，一个新的头预测每个锚点和每个输入的类别分数 `bias_init_p` 和距离 `1`。

> **示例**
> 节点在构造后调用该方法，因此一个新的头已经给出这些输出:

```pycon
>>> import torch
>>> from torch import Size
>>> from luxonis_train.nodes import EfficientBBoxHead
>>> sizes = [Size([1, 8, 32, 32]), Size([1, 16, 16, 16])]
>>> head = EfficientBBoxHead(
...     n_heads=2,
...     n_classes=2,
...     input_shapes=[{"features": sizes}],
...     original_in_shape=Size([3, 256, 256]),
... )
>>> out = head([torch.zeros(size) for size in sizes])
>>> torch.allclose(out["class_scores"], torch.tensor(0.01))
True
>>> out["distributions"].unique().tolist()
[1.0]
```

参数

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

##### load_checkpoint

```python
def load_checkpoint(path: str | None = None, strict: bool = False):
```

默认情况下，以非严格键匹配加载检查点。

该方法将 `path` 作为 `ckpt` 传递给 [BaseNode.load_checkpoint](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)。此重写重命名了第一个参数并将 `strict` 的默认值设置为 `False`。

警告: 此重写没有 `ckpt` 参数。构造后，节点会为 `weights` URL 调用 `load_checkpoint(ckpt=...)`。因此，诸如 `EfficientBBoxHead(weights="https://...")` 之类的调用会引发 `TypeError`。

参数

 * `path` (`str | None`): `.ckpt` 文件的本地路径或 URL。[LuxonisLightningModule](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md) 也提供状态字典，并且基本方法直接加载它。`None` 或 `""` 从 [get_weights_url](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_bbox_head.md) 获取 URL。对于没有检查点的输入通道，该调用会失败。
 * `strict` (`bool`): 检查点的键是否必须与头的键完全匹配。默认为 `False`。

#### 属性

##### export_output_names

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

默认名称是 `output1_yolov6r2`、`output2_yolov6r2` 等。这些名称与 DepthAI 兼容。`export_output_names` 参数仅在它包含恰好 `n_heads` 个名称时才替换它们。头每次给出默认名称时都会记录警告。该值从不为 `None`。

##### grid_cell_offset

##### grid_cell_size

##### heads
