precision_bbox_head
最后更新
luxonis_train.nodes.heads.precision_bbox_headYOLOv8 检测头,它回归距离 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],logitsboundingbox(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 和 YOLOv6: A Single-Stage Object Detection Framework for Industrial Applications。
- 许可证:Apache-2.0 (本项目)
注意事项
该头为每个尺度运行一个 PreciseDecoupledBlock。回归分支预测框的每一侧在
reg_max 个距离 bin 上的分布。DFL 将每个分布转换为预期的距离,以步幅单位表示。在评估模式下,该头将锚点周围的距离解码为框并运行 NMS。训练模式跳过此步骤,并且它优先于导出模式。导出模式提供每个尺度的距离和 sigmoid 类分数,不进行 NMS。变体:: 无。通过params配置节点。
示例
配置中
model.nodes 部分的节点条目:Yaml
1- name: PrecisionBBoxHead
2 inputs: [RepPANNeck]兼容::- 必需标签:
boundingbox - 损失: PrecisionDFLDetectionLoss
- 指标:
- 可视化工具: BBoxVisualizer
- 导出解析器:
YOLO
- 必需标签:
方法
init
Python
1def __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 从节点读取这两个值。参数n_heads(Literal[2, 3, 4]): 尺度数量。该头读取输入节点的最后n_heads个输出。attach_index参数替换此选择。当该头获得的输出较少时,它会记录警告并使用该数量。当attach_index选择更多输出时,该头为每个输出构建一个块,但只保留n_heads个步幅。然后构建失败,因为 initialize_weights 引发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 将 bin 转换为距离。当值为1时,该头直接使用回归输出作为距离。**kwargs: BaseNode 的关键字参数。它们必须包含original_in_shape、通过input_shapes或in_sizes输入的大小,以及通过n_classes或dataset_metadata的类计数。
forward
Python
1def forward(inputs: list[Tensor]) -> Packet[Tensor]:- 训练模式:
"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 解码距离。分数是 sigmoid 概率。 - 评估模式:
"features"与训练模式相同,以及 NMS 结果"boundingbox"。该头将锚点周围的距离解码为像素中的框,并且不将其裁剪到图像。每张图像获得一个形状为[M_i, 6]的张量,行格式为[x1, y1, x2, y2, score, class]。没有框的图像获得一个形状为[0, 5 + n_classes]的张量。调用 BaseDetectionHead.request_detections_pre_nms 后,数据包还包含"detections_pre_nms"。这是形状为[B, N, 5 + n_classes]的 NMS 输入:像素中的xyxy框、一个常量1和类分数。N是H_i * W_i的总和。
示例
一个新的头处于训练模式:对于零输入,新头为每个类提供低于 导出模式为每个尺度提供一个映射:
Pycon
1>>> import torch
2>>> from torch import Size
3>>> from luxonis_train.nodes import PrecisionBBoxHead
4>>> sizes = [Size([1, 8, 32, 32]), Size([1, 16, 16, 16])]
5>>> head = PrecisionBBoxHead(
6... n_heads=2,
7... n_classes=3,
8... input_shapes=[{"features": sizes}],
9... original_in_shape=Size([3, 256, 256]),
10... )
11>>> inputs = [torch.zeros(size) for size in sizes]
12>>> [f.shape for f in head(inputs)["features"]]
13[torch.Size([1, 67, 32, 32]), torch.Size([1, 67, 16, 16])]conf_thres 的分数。因此,在评估模式下,NMS 不保留任何框:Pycon
1>>> out = head.eval()(inputs)
2>>> sorted(out), out["boundingbox"][0].shape
3(['boundingbox', 'features'], torch.Size([0, 8]))Pycon
1>>> head.export = True
2>>> [b.shape for b in head(inputs)["boundingbox"]]
3[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
1def forward_heads(inputs: list[Tensor]) -> tuple[list[Tensor], list[Tensor], list[Tensor]]:inputs 配对。它不应用 sigmoid,因此所有输出都是 logits。PrecisionSegmentBBoxHead 也调用此方法。示例
Pycon
1>>> import torch
2>>> from torch import Size
3>>> from luxonis_train.nodes import PrecisionBBoxHead
4>>> sizes = [Size([1, 8, 32, 32]), Size([1, 16, 16, 16])]
5>>> head = PrecisionBBoxHead(
6... n_heads=2,
7... n_classes=3,
8... reg_max=4,
9... input_shapes=[{"features": sizes}],
10... original_in_shape=Size([3, 256, 256]),
11... )
12>>> inputs = [torch.zeros(size) for size in sizes]
13>>> features, classes, regressions = head.forward_heads(inputs)
14>>> features[1].shape
15torch.Size([1, 19, 16, 16])
16>>> classes[1].shape[1], regressions[1].shape[1]
17(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]。
- 特征,沿通道轴连接距离 bin logits 和类 logits,形状为
get_custom_head_config
Python
1def get_custom_head_config(self) -> Params:"subtype"。返回Params: 一个字典,包含键"iou_threshold"、"conf_threshold"、"max_det"和"strides"。它们分别包含iou_thres、conf_thres、max_det和stride,其中stride是一个列表,每个尺度一个整数。
initialize_weights
Python
1def initialize_weights(method: str | None = None):method 调用 BaseNode.initialize_weights。然后,对于步幅为 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
1>>> from torch import Size
2>>> from luxonis_train.nodes import PrecisionBBoxHead
3>>> sizes = [Size([1, 8, 32, 32]), Size([1, 16, 16, 16])]
4>>> head = PrecisionBBoxHead(
5... n_heads=2,
6... n_classes=3,
7... input_shapes=[{"features": sizes}],
8... original_in_shape=Size([3, 256, 256]),
9... )
10>>> block = head.heads[0]
11>>> block.regression_branch[-1].bias.unique().tolist()
12[1.0]
13>>> score = block.classification_branch[-1].bias.sigmoid()
14>>> round(score[0].item(), 5), round(5 / (3 * 32**2), 5)
15(0.00162, 0.00163)method(str | None): BaseNode.initialize_weights 的方法。"yolo"更改批归一化和激活设置。其他值跳过该步骤。
属性
dfl
export_output_names
n_heads 个输出的名称。默认名称是 output1_yolov8、output2_yolov8 等。export_output_names 参数仅在它包含恰好 n_heads 个名称时才替换它们。每次它给出默认名称时,该头都会记录警告。该值从不为 None。