# albumentations_engine

Python API: `luxonis_ml.data.augmentations.albumentations_engine`

## 类

### AlbumentationConfigItem

[AlbumentationsEngine](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
的配置项。

#### 属性

##### apply_on_stages

应用此转换的管道阶段列表。有效阶段为 `"train"`、`"val"` 和 `"test"`。默认情况下，转换仅在 `"train"` 阶段应用。

##### name

转换的名称。必须是 [Albumentations](https://albumentations.ai/explore/) 转换的有效名称，或者是
[TRANSFORMATIONS](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom.md)
注册表中注册的自定义转换的名称。

##### params

转换的参数。

##### use_for_resizing

此转换是否可用于调整大小。

### AlbumentationsEngine

由 Albumentations 支持的增强引擎。

目录

 * [配置格式](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
 * [转换顺序](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
 * [支持的增强](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
   * [Albumentations
   增强](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
    * [批量增强](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
      *
      [CutMix](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
       * [MixUp](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
       * [Mosaic4](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
 * [增强不支持的类型](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
   *
   [分类](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
    * [元数据](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
    * [数组](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
    * [定向边界框](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
 * [自定义增强](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)

#### 配置格式

配置包含一个转换列表，每个转换都由其名称和可选参数指定，如
[AlbumentationConfigItem](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
模式中所述。

名称必须是 [Albumentations](https://albumentations.ai/explore/) 转换的有效名称，或者是
[TRANSFORMATIONS](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom.md)
注册表中注册的自定义转换的名称。

例如：

```python
[
    {
        "name": "Affine",
        "params": {
            "rotate": 30,
            "scale": 0.5,
            "p": 0.3,
        },
    },
    {
        "name": "MixUp",
        "params": {
            "alpha": [0.3, 0.7],
            "p": 0.5,
        },
    },
    {
        "name": "CustomResize",
        "use_for_resizing": True,
    },
]
```

#### 转换顺序

配置中提供的转换顺序不保证保留。转换分为以下几组，并按此顺序应用：

 1. 批量转换：[BatchTransform](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/batch_transform.md)
    的子类。
 2. 空间转换：[A.DualTransform](https://github.com/albumentations-team/albumentations/blob/66212d77a44927a29d6a0e81621d3c27afbd929c/albumentations/core/transforms_interface.py#L545)
    的子类。
 3. 自定义转换：[A.BasicTransform](https://github.com/albumentations-team/albumentations/blob/66212d77a44927a29d6a0e81621d3c27afbd929c/albumentations/core/transforms_interface.py#L49)
    的子类，但不是上述更具体基类的子类。
 4. 像素转换：[A.ImageOnlyTransform](https://github.com/albumentations-team/albumentations/blob/66212d77a44927a29d6a0e81621d3c27afbd929c/albumentations/core/transforms_interface.py#L756)
    的子类。这些转换仅作用于图像。

#### 支持的增强

#### Albumentations 增强

支持 Albumentations 库提供的所有增强。

#### 批量增强

这些需要同时处理多张图像，并且必须配置为顶级增强。将其嵌套在 `OneOf` 或 `Sequential` 等组合中会引发 `ValueError`。

#### CutMix

CutMix 是一种数据增强技术，它使用从 beta 分布混合系数中采样的矩形将一张源图像修补到另一张图像中。

第一张图像的边界框只要其在补丁外部的部分至少是其原始面积的 `bbox_min_visibility`，就会保留下来；补丁覆盖的超出此范围的边界框及其实例掩码、关键点和元数据都会被丢弃。第二张图像的边界框会被裁剪到补丁。

`occluded_bbox_strategy` 选择补丁部分覆盖的幸存者会发生什么。默认的 `"keep"` 会将其保留在其原始范围，因为对象仍然填充框并且只是被覆盖；`"clip"` 会将其缩小到补丁未到达的最大部分，因此没有框边缘会留在补丁顶部。

#### MixUp

MixUp 是一种数据增强技术，它使用权重系数 alpha 将 2 张源图像混合成一张图像。

#### Mosaic4

Mosaic4 转换通过将 4 张图像放置在 2×2 网格中，将它们组合成一张图像。

#### 增强不支持的类型

Albumentations 不原生支持 Luxonis Data Format 支持的所有标签类型。本节描述了如何处理不支持的类型。

请注意，以下内容仅适用于官方支持的增强。可以实现自定义增强来处理任意类型。

#### 分类

分类只能针对多标签任务进行正确增强，其中每个类都与一个边界框绑定。在这种情况下，属于图像外部边界框的类将被删除。在其他情况下，分类注释保持不变。

#### 元数据

元数据标签可以包含任意数据，其语义对增强引擎未知。因此，应用于元数据的唯一转换是丢弃与图像外部边界框关联的元数据。

#### 数组

数组的处理方式与元数据相同。应用于数组的唯一转换是丢弃与图像外部边界框关联的数组。

#### 定向边界框

（尚未实现）

定向边界框的形状为 (N, 5)，其中每行的最后一个元素包含边界框的角度。Albumentations 不支持此格式，但是，Albumentations
支持将角度作为关键点的一部分。因此，定向边界框被拆分为常规边界框和一组关键点，这些关键点表示边界框的中心并包含角度作为第三个坐标。

关键点和边界框都分别进行增强。最后，从关键点中提取角度并将其添加回边界框。关键点被丢弃。

#### 自定义增强

可以通过创建
[A.BasicTransform](https://github.com/albumentations-team/albumentations/blob/66212d77a44927a29d6a0e81621d3c27afbd929c/albumentations/core/transforms_interface.py#L49)
的子类并将其注册到
[TRANSFORMATIONS](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/custom.md)
注册表中来实现自定义增强。

增强可以接收的可能目标类型有：

 * `"image"`：> 图像。所有增强通常都应支持此目标。对于
   [A.ImageOnlyTransform](https://github.com/albumentations-team/albumentations/blob/66212d77a44927a29d6a0e81621d3c27afbd929c/albumentations/core/transforms_interface.py#L756)
   或
   [A.DualTransform](https://github.com/albumentations-team/albumentations/blob/66212d77a44927a29d6a0e81621d3c27afbd929c/albumentations/core/transforms_interface.py#L545)
   的子类，这意味着覆盖 `apply`。
 * `"bboxes"`：> 边界框。对于
   [A.DualTransform](https://github.com/albumentations-team/albumentations/blob/66212d77a44927a29d6a0e81621d3c27afbd929c/albumentations/core/transforms_interface.py#L545)
   的子类，这意味着覆盖 `apply_to_bboxes`。
 * `"keypoints"`：> 关键点。对于
   [A.DualTransform](https://github.com/albumentations-team/albumentations/blob/66212d77a44927a29d6a0e81621d3c27afbd929c/albumentations/core/transforms_interface.py#L545)
   的子类，这意味着覆盖 `apply_to_keypoints`。
 * `"mask"`：> 分割掩码。对于
   [A.DualTransform](https://github.com/albumentations-team/albumentations/blob/66212d77a44927a29d6a0e81621d3c27afbd929c/albumentations/core/transforms_interface.py#L545)
   的子类，这意味着覆盖 `apply_to_mask`。
 * `"instance_mask"`：> 实例分割掩码。对于
   [BatchTransform](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/batch_transform.md)
   的子类，这意味着覆盖 `apply_to_instance_mask`。
   > 
   > [A.DualTransform](https://github.com/albumentations-team/albumentations/blob/66212d77a44927a29d6a0e81621d3c27afbd929c/albumentations/core/transforms_interface.py#L545) 的子类不支持此目标；实例掩码被视为常规掩码。
   > 
   > 自定义增强可以通过实现自己的处理逻辑并覆盖 `targets` 属性以包含 `"instance_mask"` 目标来支持实例掩码。
 * `"array"`：> 任意数组。只能通过自定义增强通过实现自己的逻辑并将 `"array"` 目标添加到 `targets` 属性来支持。
 * `"metadata"`：> 元数据标签。与 `"array"` 类型相同。
 * `"classification"`：> 独热编码的多任务分类标签。与 `"array"` 类型相同。

例如：

```python
class CustomArrayAugmentation(A.BasicTransform):

    @property
    @override
    def targets(self):
        return {
            "image": self.apply,
            "array": self.apply_to_array,
        }

    @override
    def apply(self, image, **kwargs):
        ...

    def apply_to_array(
        self, array: np.ndarray, **kwargs
    ) -> np.ndarray:
        ...
```

#### 方法

##### init

```python
def __init__(height: int, width: int, targets: dict[str, str], n_classes: dict[str, int], source_names: list[str], config: Iterable[Params], keep_aspect_ratio: bool = True, is_validation_pipeline: bool | None = None, pipeline_stage: Literal['train', 'val', 'test'] | None = None, min_bbox_visibility: float = 0.0, seed: int | None = None, bbox_area_threshold: float = 0.0004):
```

创建基于 Albumentations 的增强管道。

参数

 * `height` (`int`)：目标输出图像高度。
 * `width` (`int`)：目标输出图像宽度。
 * `targets` (`dict[str, str]`)：任务名称映射到任务类型。支持的任务类型有
   `"array"`、`"classification"`、`"segmentation"`、`"instance_segmentation"`、`"boundingbox"`、`"keypoints"` 和元数据任务。
 * `n_classes` (`dict[str, int]`)：每个任务的类数。
 * `source_names` (`list[str]`)：应被视为图像目标的源名称。
 * `config` (`Iterable[Params]`)：增强配置字典的可迭代对象。
 * `keep_aspect_ratio` (`bool`)：默认调整大小转换是否应保留图像纵横比。
 * `is_validation_pipeline` (`bool | None`)： 可选的旧版标志，用于选择评估行为。> **已弃用**
   > 自 0.5.0 版起已弃用：请改用 `pipeline_stage`。
 * `pipeline_stage` (`Literal['train', 'val', 'test'] | None`)：可选的显式管道阶段。有效值为 `"train"`、`"val"` 和 `"test"`。
 * `min_bbox_visibility` (`float`)：增强后边界框的最小可见分数。
 * `seed` (`int | None`)：可选的随机种子。
 * `bbox_area_threshold` (`float`)：增强后保留的最小归一化边界框面积。

引发

 * `ValueError`：如果目标任务类型不受支持，同一任务组中存在多个边界框目标，多个转换被标记为调整大小，或者配置的转换不是 Albumentations 转换。
 * `TypeError`：如果调整大小转换的概率 `p` 为非数字。

##### apply

```python
def apply(input_batch: list[LoaderMultiOutput]) -> LoaderMultiOutput:
```

将增强管道应用于数据。

参数

 * `input_batch` (`list[LoaderMultiOutput]`)：要增强的加载器输出。项目数必须与引擎的批量大小匹配。

返回

 * `LoaderMultiOutput`：增强的加载器输出。

#### 属性

##### applied_augmentations

最新调用的配置路径和运行时参数。

##### batch_augmentation_indices

贡献于最新增强输出的输入位置。

##### batch_size

增强管道所需的批量大小。

批量大小是批量增强情况下增强管道请求的图像数量。

例如，如果增强管道包含 MixUp 增强，则批量大小应为 2。

如果管道需要 MixUp 和 Mosaic4 增强，则批量大小应为 8 = (2⋅4)。

## 属性

### ASSOCIATED_TARGET_TYPES

### Data

### LabelSpec

### TargetType
