# base_detection_head

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

预测边界框的头的基类。

它保留了 NMS 设置和尺度的步幅。它还选择了导出输出的名称。每个子类在评估模式下自行运行 NMS。

## 类

### BaseDetectionHead

具有多个尺度的 YOLO 样检测头的基类。

头读取输入节点的最后 `n_heads` 个输出，每个尺度一个特征图。对于此选择，构造函数将 `attach_index` 设置为 `(-n_heads - 1, -1)`。节点 `params` 中的 `attach_index` 会替换此值。

子类将每个尺度的块存储在 `heads` 中。在评估模式下，它使用 `conf_thres`、`iou_thres` 和 `max_det` 运行 NMS。在调用
[request_detections_pre_nms](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/base_detection_head.md)
后，它还会将 NMS 输入保留在其数据包中。

> **示例**
> [EfficientBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/efficient_bbox_head.md) 是一个检测头。它有两个尺度，读取三个特征图中的最后两个：

```pycon
>>> from torch import Size
>>> from luxonis_train.nodes import EfficientBBoxHead
>>> sizes = [
...     Size([1, 4, 64, 64]),
...     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]),
... )
>>> head.attach_index, head.in_channels, head.stride.tolist()
((-3, -1), [8, 16], [8, 16])
```

#### 方法

##### init

```python
def __init__(n_heads: int, conf_thres: float, iou_thres: float, max_det: int, **kwargs):
```

设置 NMS 设置、附加索引和步幅。

构造函数读取
[BaseNode.in_channels](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)、[BaseNode.in_sizes](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
和
[BaseNode.original_in_shape](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)。因此
`kwargs` 必须包含 `original_in_shape`，以及 `input_shapes` 或 `in_sizes`。当头获得的特征图少于 `n_heads` 时，构造函数会记录警告并将 `n_heads` 设置为该数字。在 `kwargs`
中没有 `attach_index` 的情况下，此检查会计算输入节点的所有输出。

参数

 * `n_heads` (`int`): 尺度数量。头读取输入节点的最后 `n_heads` 个输出。
 * `conf_thres` (`float`): NMS 的置信度阈值，范围为 `[0, 1]`。
 * `iou_thres` (`float`): NMS 的 IoU 阈值，范围为 `[0, 1]`。
 * `max_det` (`int`): NMS 为每张图像保留的最大框数。
 * `**kwargs`:
   [BaseNode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   的关键字参数。其中的 `attach_index` 会替换默认的最后 `n_heads` 个输出的选择。它必须选择一个范围或 `"all"`。整数索引会导致构造函数失败。此类将 `in_channels` 注释为 `list[int]`，因此
   [BaseNode](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   会引发
   [IncompatibleError](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/exceptions.md)。具有自己类注释的子类会隐藏此注释，例如
   [PrecisionSegmentBBoxHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/precision_seg_bbox_head.md)。对于此类子类，构造函数会引发
   `TypeError`。

##### fit_stride_to_heads

```python
def fit_stride_to_heads(self) -> Tensor:
```

根据输入大小计算每个尺度的步幅。

尺度 i 的步幅为 si = round(H ⁄ Hi)，其中 H 是模型输入的高度，Hi 是特征图的高度。该方法从
[BaseNode.in_sizes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
的前 `n_heads` 个大小中读取。它从每个大小的索引 `2` 中获取 Hi，因此大小必须具有 `[B, C, H, W]` 的形式。构造函数将结果存储在 `stride` 中。类示例显示了结果。

返回

 * `Tensor`: 形状为 `[n_heads]` 的 `int32` 张量。

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

##### get_output_names

```python
def get_output_names(default: list[str]) -> list[str]:
```

返回导出输出名称或 `default` 名称。

子类在其 `export_output_names` 属性中调用此方法。该方法通过
[BaseNode.export_output_names](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
读取 `export_output_names` 构造函数参数。它不读取调用此方法的子类的属性。当构造函数参数的名称数量为 `n_heads` 时，它返回这些名称。否则，它会记录警告并返回 `default`。当参数为 `None` 时，它也会记录警告。

警告： 该方法将名称数量与 `n_heads` 进行比较，而不是与 `default` 的长度进行比较。因此，具有多于 `n_heads` 个输出的子类永远无法从参数中获取所有输出的名称。

> **示例**
> ```pycon
>>> from torch import Size
>>> from luxonis_train.nodes import EfficientBBoxHead
>>> sizes = [Size([1, 8, 32, 32]), Size([1, 16, 16, 16])]
>>> def build_head(names):
...     return EfficientBBoxHead(
...         n_heads=2,
...         n_classes=3,
...         input_shapes=[{"features": sizes}],
...         original_in_shape=Size([3, 256, 256]),
...         export_output_names=names,
...     )
>>> build_head(["small", "large"]).get_output_names(["a", "b"])
['small', 'large']
```

两个尺度一个名称会给出默认名称。示例关闭了日志记录器，因此不会显示警告：

```pycon
>>> from loguru import logger
>>> logger.disable("luxonis_train")
>>> build_head(["boxes"]).get_output_names(["a", "b"])
['a', 'b']
>>> logger.enable("luxonis_train")
```

参数

 * `default` (`list[str]`): 当构造函数参数为 `None` 或长度错误时返回的名称。子类给出 DepthAI 接受的名称。

返回

 * `list[str]`: 构造函数参数的名称，或 `default`。

##### request_detections_pre_nms

```python
def request_detections_pre_nms(self):
```

使头将其 NMS 前的候选框添加到其数据包中。

调用后，子类的评估数据包也包含 `"detections_pre_nms"` 键。其值为 NMS 输入：形状为 `[B, N, 5 + n_classes]` 的张量，其中 `N` 个锚点中的每个锚点对应一行。每行包含像素坐标中的 `xyxy` 框、一个常量 `1` 和类别分数。如果头保留了每个框的更多值，例如关键点或掩码系数，则会在类别分数之后添加列。该张量可能会占用大量内存，因此头仅在请求时才保留它。[PrecisionRecallCurve](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/attached_modules/metrics/precision_recall_curve.md) 在其构造函数中调用此方法。

> **示例**
> ```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]),
... )
>>> head.keep_detections_pre_nms
False
>>> head.request_detections_pre_nms()
>>> out = head.eval()([torch.zeros(size) for size in sizes])
>>> out["detections_pre_nms"].shape
torch.Size([1, 1280, 8])
```

#### 属性

##### attach_index

##### in_channels

附加输入的通道数。

它是
[in_sizes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
从末尾开始的第三个维度，因此带或不带批处理维度的形状会给出相同的值。大小列表会给出通道计数列表。

引发

 * `RuntimeError`: 当
   [in_sizes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   找不到输入大小时。
 * `ValueError`: 当
   [attach_index](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
   不适合大小时。

##### in_sizes

附加输入的大小。

该属性使用适用的第一个规则：

 1. `in_sizes` 构造函数参数，如果已设置。
 2. 唯一输入数据包的 `"features"` 条目。
 3. 该数据包的唯一条目。
 4. 该数据包中键与 `forward` 参数名称匹配的条目。它们的大小必须相等，并且该属性使用第一个。

规则 2 到 4 通过
[get_attached](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
传递条目。结果是整数
[attach_index](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)
的单个大小，以及 `"all"` 或范围的大小列表。具有多个输入或形状不符合规则的节点必须改为读取
[input_shapes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md)。

> **示例**
> ```pycon
>>> from torch import Size, Tensor
>>> from luxonis_train.nodes import BaseNode
>>> class Node(BaseNode, register=False):
...     def forward(self, x: list[Tensor]) -> list[Tensor]:
...         return x
>>> shapes = [
...     {"features": [Size([2, 8, 64, 64]), Size([2, 16, 32, 32])]}
... ]
>>> node = Node(input_shapes=shapes)
>>> node.attach_index
'all'
>>> node.in_sizes
[torch.Size([2, 8, 64, 64]), torch.Size([2, 16, 32, 32])]
>>> node.in_channels, node.in_height, node.in_width
([8, 16], [64, 32], [64, 32])
```

引发

 * `RuntimeError`: 当 `input_shapes` 缺失或不包含恰好一个数据包时。当没有键与 `forward` 参数匹配，或者匹配的大小不同时。当 [attach_index](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md) 为 `None` 且条目为列表时。
 * `ValueError`: 当 [attach_index](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/base_node.md) 不适合大小时。

##### iou_thres

NMS 的 IoU 阈值。

##### keep_detections_pre_nms

头是否将其 NMS 前的候选框添加到其数据包中。

在调用 [request_detections_pre_nms](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/base_detection_head.md) 之前，它为 `False`。当它为 `True` 时，子类的评估数据包也包含 `"detections_pre_nms"` 键。

##### max_det

NMS 为每张图像保留的最大框数。

##### parser

导出解析器，`"YOLO"`。子类可以替换它。

##### stride

每个尺度的步幅，形状为 `[n_heads]` 的 `int32` 张量。[fit_stride_to_heads](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/base_detection_head.md) 计算它。
