此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 配置
  • 自定义转换
  • 引擎接口
  • 提示和技巧
  • 旋转边界框过大
  • 子页面
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

augmentations

最后更新
Python API: luxonis_ml.data.augmentationsLDF 样本的增强引擎和自定义转换。此包提供了 LuxonisLoader 使用的增强接口。默认实现是 AlbumentationsEngine,它在转换前将 LDF 标签调整为 Albumentations 目标,并在转换后将其转换回来。目录

配置

增强配置是记录列表。每条记录包含一个 name,用于标识 Albumentations 转换或在 TRANSFORMATIONS 中注册的转换,可选的 params,可选的 use_for_resizing,以及通过 apply_on_stages 进行的阶段过滤。当省略 apply_on_stages 时,转换应用于 "train"。
Python
1[
2    {"name": "HorizontalFlip", "params": {"p": 0.5}},
3    {
4        "name": "Mosaic4",
5        "params": {"height": 640, "width": 640, "p": 1.0},
6    },
7]
引擎根据行为而不是保留精确的输入顺序对转换进行分组:
  1. 批处理转换,例如 MixUp 或 Mosaic4。
  2. 空间转换,例如 Albumentations 双重转换。
  3. 自定义基本转换。
  4. 仅像素转换。
调整大小处理是引擎的一部分。标记为 use_for_resizing 的转换用作调整大小阶段;否则引擎会回退到常规调整大小或 LetterboxResize,具体取决于加载器的宽高比设置。如果选定的调整大小转换的概率 p < 1,它会保留在调整大小阶段,剩余的概率质量由始终开启的 OneOf 中的默认调整大小填充。当缩小可以节省工作时,调整大小阶段在仅像素转换之前应用;当放大或保留大小时,在仅像素转换之后应用。标准的 Albumentations 翻转转换,例如 HorizontalFlip、VerticalFlip 和 Transpose,会翻转关键点坐标,但不会交换语义上的左右关键点标签。对于对称关键点结构,请使用 Luxonis 自定义转换 HorizontalSymmetricKeypointsFlip、VerticalSymmetricKeypointsFlip 和 TransposeSymmetricKeypoints。批处理转换会增加加载器所需的源样本数量。例如,包含 MixUp 和 Mosaic4 的管道,每个增强输出需要 8 = 2⋅4 个样本。可以通过继承 AugmentationEngine 来添加自定义增强引擎。子类会自动注册到 AUGMENTATION_ENGINES 中。LuxonisLoader 会为您构建引擎。将配置作为记录列表传递,或者作为包含相同列表的 YAML 或 JSON 文件的路径传递:
Python
1from luxonis_ml.data import LuxonisDataset, LuxonisLoader
2
3loader = LuxonisLoader(
4    LuxonisDataset("parking_lot"),
5    view="train",
6    augmentation_engine="albumentations",
7    augmentation_config="augmentations.yaml",
8    height=256,
9    width=320,
10    keep_aspect_ratio=True,
11    color_space="RGB",
12)
13
14for sample in loader:
15    images = sample.images
16    labels = sample.labels

自定义转换

自定义转换遵循 Albumentations 约定。继承适当的基类,例如 DualTransform 或 ImageOnlyTransform,实现标签所需的 target 方法,在 luxonis_ml.data.augmentations.custom.TRANSFORMATIONS 中注册该类,并在加载器配置中引用类名。Albumentations 指南解释了基类和 target 方法。要将多个样本组合成一个,请继承 BatchTransform 而不是 Albumentations 基类。CutMix、MixUp 和 Mosaic4 是内置示例。注册和配置方式相同。
Python
1from albumentations import DualTransform
2from luxonis_ml.data.augmentations.custom import TRANSFORMATIONS
3
4class CustomTransform(DualTransform):
5    def apply(self, image, **kwargs):
6        return image
7
8    def apply_to_mask(self, mask, **kwargs):
9        return mask
10
11    def apply_to_bboxes(self, bboxes, **kwargs):
12        return bboxes
13
14    def apply_to_keypoints(self, keypoints, **kwargs):
15        return keypoints
16
17TRANSFORMATIONS.register(module=CustomTransform)
18
19augmentation_config = [
20    {"name": "CustomTransform", "params": {"p": 1.0}},
21]

引擎接口

自定义引擎应继承 AugmentationEngine 并实现:
  • __init__ 用于接收输出大小、类别计数、配置、宽高比行为、管道阶段和目标元数据;
  • apply 用于转换一批图像和标签并返回转换后的值;
  • batch_size 用于告诉 LuxonisLoader 每个增强输出需要多少源样本。
引擎还可以重写 AugmentationEngine.applied_augmentations 以报告其最新调用的配置路径和运行时参数。

提示和技巧

旋转边界框过大

Affine、Rotate、SafeRotate 和 ShiftScaleRotate 在旋转或剪切图像后,可能会使边界框远大于其中的对象。高大或宽阔的对象,例如站立的人,表现最为明显。
https://raw.githubusercontent.com/luxonis/luxonis-ml/30a7530c1725538e1e9816b3d188e9df400db636/luxonis_ml/data/augmentations/media/bbox_rotation_original.png
增强前的样本。
https://raw.githubusercontent.com/luxonis/luxonis-ml/30a7530c1725538e1e9816b3d188e9df400db636/luxonis_ml/data/augmentations/media/bbox_rotation_largest_box.png
使用默认的 rotate_method="largest_box" 旋转。
https://raw.githubusercontent.com/luxonis/luxonis-ml/30a7530c1725538e1e9816b3d188e9df400db636/luxonis_ml/data/augmentations/media/bbox_rotation_ellipse.png
使用 rotate_method="ellipse" 进行相同的旋转。框无法说明其中对象的形状,因此在旋转或剪切后,Albumentations 必须猜测新的框。这些转换的 rotate_method 参数选择猜测方式:
  • "largest_box"(默认):围绕四个变换后的角取框,就像对象填充了整个框一样。框永远不会太小,但通常会太大。一个 w×h 的框旋转 θ 后,宽度变为 w|cosθ| + h|sinθ|。
  • "ellipse":围绕框中内切的变换后的椭圆取框。框更紧凑,但会切掉填充框的对象角。相同的框宽度变为 √(w2cos2θ + h2sin2θ)。
一个 120×315 的人物框旋转 20° 后,使用 "largest_box" 宽度变为 221 像素,使用 "ellipse" 宽度变为 156 像素。一个正方形对象旋转 45° 后跨度为 1.41w,但 "ellipse" 给出 w。在没有旋转或剪切的情况下,两种方法给出相同的框。当对象未达到其框的角时,例如人物或动物,请使用 "ellipse"。对于汽车或屏幕等矩形对象,请保留 "largest_box"。Towards Rotation Invariance in Object Detection 表明,过大的框可能会使检测器比完全不进行旋转训练更差。
Python
1[
2    {
3        "name": "Affine",
4        "params": {
5            "rotate": [-30, 30],
6            "shear": [-15, 15],
7            "rotate_method": "ellipse",
8        },
9    },
10]
在训练前检查增强的框:
Command Line
1luxonis_ml data inspect <dataset> --aug-config augmentations.yaml
添加 --list-augmentations 以打印每个 Affine 的采样旋转和比例。Albumentations 不报告采样的剪切。

子页面