# augmentations

Python API: `luxonis_ml.data.augmentations`

LDF 样本的增强引擎和自定义转换。

此包提供了
[LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
使用的增强接口。默认实现是
[AlbumentationsEngine](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)，它在转换前将
LDF 标签调整为 Albumentations 目标，并在转换后将其转换回来。

目录

 * [配置](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations.md)
 * [自定义转换](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations.md)
 * [引擎接口](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations.md)
 * [提示和技巧](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations.md)
   *
   [旋转边界框过大](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations.md)

## 配置

增强配置是记录列表。每条记录包含一个 `name`，用于标识 Albumentations 转换或在
[TRANSFORMATIONS](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom.md)
中注册的转换，可选的 `params`，可选的 `use_for_resizing`，以及通过 `apply_on_stages` 进行的阶段过滤。当省略 `apply_on_stages` 时，转换应用于 `"train"`。

```python
[
    {"name": "HorizontalFlip", "params": {"p": 0.5}},
    {
        "name": "Mosaic4",
        "params": {"height": 640, "width": 640, "p": 1.0},
    },
]
```

引擎根据行为而不是保留精确的输入顺序对转换进行分组：

 1. 批处理转换，例如
    [MixUp](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom/mixup.md)
    或
    [Mosaic4](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom/mosaic.md)。
 2. 空间转换，例如 Albumentations 双重转换。
 3. 自定义基本转换。
 4. 仅像素转换。

调整大小处理是引擎的一部分。标记为 `use_for_resizing` 的转换用作调整大小阶段；否则引擎会回退到常规调整大小或
[LetterboxResize](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom/letterbox_resize.md)，具体取决于加载器的宽高比设置。如果选定的调整大小转换的概率
`p < 1`，它会保留在调整大小阶段，剩余的概率质量由始终开启的 `OneOf` 中的默认调整大小填充。当缩小可以节省工作时，调整大小阶段在仅像素转换之前应用；当放大或保留大小时，在仅像素转换之后应用。

标准的 Albumentations 翻转转换，例如 `HorizontalFlip`、`VerticalFlip` 和 `Transpose`，会翻转关键点坐标，但不会交换语义上的左右关键点标签。对于对称关键点结构，请使用 Luxonis 自定义转换
[HorizontalSymmetricKeypointsFlip](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom/symmetric_keypoints_flip.md)、[VerticalSymmetricKeypointsFlip](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom/symmetric_keypoints_flip.md)
和
[TransposeSymmetricKeypoints](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom/symmetric_keypoints_flip.md)。

批处理转换会增加加载器所需的源样本数量。例如，包含
[MixUp](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom/mixup.md)
和
[Mosaic4](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom/mosaic.md)
的管道，每个增强输出需要 8 = 2⋅4 个样本。

可以通过继承
[AugmentationEngine](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/base_engine.md)
来添加自定义增强引擎。子类会自动注册到
[AUGMENTATION_ENGINES](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/base_engine.md)
中。

[LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
会为您构建引擎。将配置作为记录列表传递，或者作为包含相同列表的 YAML 或 JSON 文件的路径传递：

```python
from luxonis_ml.data import LuxonisDataset, LuxonisLoader

loader = LuxonisLoader(
    LuxonisDataset("parking_lot"),
    view="train",
    augmentation_engine="albumentations",
    augmentation_config="augmentations.yaml",
    height=256,
    width=320,
    keep_aspect_ratio=True,
    color_space="RGB",
)

for sample in loader:
    images = sample.images
    labels = sample.labels
```

## 自定义转换

自定义转换遵循 Albumentations 约定。继承适当的基类，例如 `DualTransform` 或 `ImageOnlyTransform`，实现标签所需的 target 方法，在
[luxonis_ml.data.augmentations.custom.TRANSFORMATIONS](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom.md)
中注册该类，并在加载器配置中引用类名。[Albumentations 指南](https://albumentations.ai/docs/4-advanced-guides/creating-custom-transforms/)解释了基类和 target
方法。

要将多个样本组合成一个，请继承
[BatchTransform](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/batch_transform.md)
而不是 Albumentations
基类。[CutMix](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom/cutmix.md)、[MixUp](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom/mixup.md)
和
[Mosaic4](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom/mosaic.md)
是内置示例。注册和配置方式相同。

```python
from albumentations import DualTransform
from luxonis_ml.data.augmentations.custom import TRANSFORMATIONS

class CustomTransform(DualTransform):
    def apply(self, image, **kwargs):
        return image

    def apply_to_mask(self, mask, **kwargs):
        return mask

    def apply_to_bboxes(self, bboxes, **kwargs):
        return bboxes

    def apply_to_keypoints(self, keypoints, **kwargs):
        return keypoints

TRANSFORMATIONS.register(module=CustomTransform)

augmentation_config = [
    {"name": "CustomTransform", "params": {"p": 1.0}},
]
```

## 引擎接口

自定义引擎应继承
[AugmentationEngine](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/base_engine.md)
并实现：

 * `__init__` 用于接收输出大小、类别计数、配置、宽高比行为、管道阶段和目标元数据；
 * `apply` 用于转换一批图像和标签并返回转换后的值；
 * `batch_size` 用于告诉
   [LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
   每个增强输出需要多少源样本。

引擎还可以重写
[AugmentationEngine.applied_augmentations](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/base_engine.md)
以报告其最新调用的配置路径和运行时参数。

## 提示和技巧

### 旋转边界框过大

`Affine`、`Rotate`、`SafeRotate` 和 `ShiftScaleRotate` 在旋转或剪切图像后，可能会使边界框远大于其中的对象。高大或宽阔的对象，例如站立的人，表现最为明显。

增强前的样本。

使用默认的 `rotate_method="largest_box"` 旋转。

使用 `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](https://arxiv.org/abs/2109.13488) 表明，过大的框可能会使检测器比完全不进行旋转训练更差。

```python
[
    {
        "name": "Affine",
        "params": {
            "rotate": [-30, 30],
            "shear": [-15, 15],
            "rotate_method": "ellipse",
        },
    },
]
```

在训练前检查增强的框：

```bash
luxonis_ml data inspect <dataset> --aug-config augmentations.yaml
```

添加 `--list-augmentations` 以打印每个 `Affine` 的采样旋转和比例。Albumentations 不报告采样的剪切。

## 子页面

 * [custom](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom.md)
 * [albumentations_engine](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
 * [base_engine](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/base_engine.md)
 * [batch_compose](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/batch_compose.md)
 * [batch_transform](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/batch_transform.md)
 * [utils](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/utils.md)
