# cutmix

Python API: `luxonis_ml.data.augmentations.custom.cutmix`

## 类

### CutMix

基于批次的增强，将一个图像修补到另一个图像中。

CutMix 从第二个图像中采样一个矩形区域并将其粘贴到第一个图像中。矩形区域的大小由从 Beta(α, α) 采样的混合系数得出。

如果图像大小不同，则在复制补丁之前，第二个图像及其标签会调整大小以匹配第一个图像。

第一个图像中的边界框如果其可见区域（原始区域减去与补丁的交集）至少是其原始区域的 `bbox_min_visibility` 倍，则保留；`occluded_bbox_strategy`
决定幸存者是保留其完整范围还是被裁剪到补丁未触及的部分。第二个图像中的边界框被裁剪到补丁区域。第一个图像中落在补丁内的关键点被标记为不可见，而第二个图像中落在补丁外的关键点被标记为不可见。

> **另请参阅**
> [CutMix: Regularization Strategy to Train Strong Classifiers with Localizable Features](https://arxiv.org/abs/1905.04899)。

#### 方法

##### init

```python
def __init__(alpha: float = 1.0, keep_aspect_ratio: bool = True, bbox_min_visibility: float = 0.5, occluded_bbox_strategy: Literal['keep', 'clip'] = 'keep', p: float = 0.5):
```

创建一个 CutMix 增强。

参数

 * `alpha` (`float`): 对称 Beta(α, α) 分布的正形状参数，用于确定补丁大小。`1.0` 均匀采样；小于 `1.0` 的值倾向于非常小或非常大的补丁，而大于 `1.0` 的值倾向于中等大小的补丁。
 * `keep_aspect_ratio` (`bool`): 调整大小时是否保留第二个图像的纵横比。
 * `bbox_min_visibility` (`float`): 第一个图像边界框必须保持可见（在补丁之外）的最小分数，以便保留该框。必须在 [0, 1] 之间。
 * `occluded_bbox_strategy` (`Literal['keep', 'clip']`): 如何处理补丁部分覆盖但未隐藏超过 `bbox_min_visibility` 的第一个图像框。 * `"keep"`
   将它们保留在其原始范围，理由是对象仍然占据整个框并且只是被覆盖。这是参考实现所做的。
    * `"clip"` 将它们缩小到补丁未触及的最大部分，以便没有框边缘位于补丁之上。将框一分为二的补丁保留两个剩余边中较大的一个。 无论哪种方式，哪个框幸存都由 `bbox_min_visibility`
      决定；这只会改变幸存者的范围。请注意，`"clip"` 可能会使可见关键点超出其自身现在较小的框。
 * `p` (`float`): 应用转换的概率。

引发

 * `ValueError`: 如果 `alpha` 不是有限正数，`bbox_min_visibility` 超出 [0, 1]，或者 `occluded_bbox_strategy` 不是 `"keep"` 和 `"clip"` 之一。

##### apply

```python
def apply(image_batch: list[np.ndarray], image_shapes: list[tuple[int, int]], x1: int, y1: int, x2: int, y2: int, **_) -> np.ndarray:
```

将 CutMix 应用于一批图像。

参数

 * `image_batch` (`list[np.ndarray]`): 要转换的图像。每个图像的形状应为 (H, W, C) 或 (H, W)。
 * `image_shapes` (`list[tuple[int, int]]`): 原始图像的形状。
 * `x1` (`int`): 第一个图像中补丁的左边缘。
 * `y1` (`int`): 第一个图像中补丁的上边缘。
 * `x2` (`int`): 第一个图像中补丁的右边缘。
 * `y2` (`int`): 第一个图像中补丁的下边缘。
 * `**_`

返回

 * `np.ndarray`: 形状为 (Hout, Wout, C) 或 (Hout, Wout) 的单个图像，其中矩形 [y1 : y2, x1 : x2] 被替换为第二个（调整大小的）图像的相应区域。

##### apply_to_array

```python
def apply_to_array(array_batch: list[np.ndarray], x1: int, y1: int, x2: int, y2: int, **_) -> np.ndarray:
```

将 CutMix 应用于任意数组。

##### apply_to_bboxes

```python
def apply_to_bboxes(bboxes_batch: list[np.ndarray], image_shapes: list[tuple[int, int]], x1: int, y1: int, x2: int, y2: int, **_) -> np.ndarray:
```

将 CutMix 应用于边界框。

当第一个图像中的边界框的可见区域（原始区域减去与补丁的交集）至少是原始区域的 `bbox_min_visibility` 时，保留该边界框。第二个图像中的边界框被裁剪到补丁区域。

未幸存的框被折叠为零面积而不是被移除，以便返回的行与实例掩码、关键点和元数据保持对齐。[BatchCompose](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/batch_compose.md)
在批次合并后，将折叠的行及其关联的标签一起丢弃。

参数

 * `bboxes_batch` (`list[np.ndarray]`): 要转换的边界框，采用归一化的 Albumentations 格式。
 * `image_shapes` (`list[tuple[int, int]]`): 原始图像形状。
 * `x1` (`int`): 第一个图像中补丁的左边缘。
 * `y1` (`int`): 第一个图像中补丁的上边缘。
 * `x2` (`int`): 第一个图像中补丁的右边缘。
 * `y2` (`int`): 第一个图像中补丁的下边缘。
 * `**_`

返回

 * `np.ndarray`: 来自两个图像的连接边界框。

##### apply_to_classification

```python
def apply_to_classification(classification_batch: list[np.ndarray], x1: int, y1: int, x2: int, y2: int, **_) -> np.ndarray:
```

将 CutMix 应用于分类标签。

##### apply_to_instance_mask

```python
def apply_to_instance_mask(masks_batch: list[np.ndarray], image_shapes: list[tuple[int, int]], x1: int, y1: int, x2: int, y2: int, **_) -> np.ndarray:
```

将 CutMix 应用于实例分割掩码。

参数

 * `masks_batch` (`list[np.ndarray]`): 要转换的掩码。每个掩码的形状应为 (H, W, N)，其中 N 是实例数。
 * `image_shapes` (`list[tuple[int, int]]`): 原始图像的形状。
 * `x1` (`int`): 第一个图像中补丁的左边缘。
 * `y1` (`int`): 第一个图像中补丁的上边缘。
 * `x2` (`int`): 第一个图像中补丁的右边缘。
 * `y2` (`int`): 第一个图像中补丁的下边缘。
 * `**_`

返回

 * `np.ndarray`: 形状为 (Hout, Wout, N1 + N2) 的连接实例掩码。第一个图像实例的补丁区域被清除；第二个图像实例的补丁外部的所有内容被清除。

##### apply_to_keypoints

```python
def apply_to_keypoints(keypoints_batch: list[np.ndarray], image_shapes: list[tuple[int, int]], x1: int, y1: int, x2: int, y2: int, **_) -> np.ndarray:
```

将 CutMix 应用于关键点。

第一个图像中落在补丁内的关键点被标记为不可见；第二个图像中落在补丁外的关键点被标记为不可见。

参数

 * `keypoints_batch` (`list[np.ndarray]`): 要转换的关键点。
 * `image_shapes` (`list[tuple[int, int]]`): 原始图像形状。
 * `x1` (`int`): 第一个图像中补丁的左边缘。
 * `y1` (`int`): 第一个图像中补丁的上边缘。
 * `x2` (`int`): 第一个图像中补丁的右边缘。
 * `y2` (`int`): 第一个图像中补丁的下边缘。
 * `**_`

返回

 * `np.ndarray`: 来自两个图像的连接关键点，可见性标志根据其相对于补丁的位置进行更新。

##### apply_to_mask

```python
def apply_to_mask(masks_batch: list[np.ndarray], image_shapes: list[tuple[int, int]], x1: int, y1: int, x2: int, y2: int, **_) -> np.ndarray:
```

将 CutMix 应用于语义分割掩码。

参数

 * `masks_batch` (`list[np.ndarray]`): 要转换的掩码。每个掩码的形状应为 (H, W, C) 或 (H, W)。
 * `image_shapes` (`list[tuple[int, int]]`): 原始图像的形状。
 * `x1` (`int`): 第一个图像中补丁的左边缘。
 * `y1` (`int`): 第一个图像中补丁的上边缘。
 * `x2` (`int`): 第一个图像中补丁的右边缘。
 * `y2` (`int`): 第一个图像中补丁的下边缘。
 * `**_`

返回

 * `np.ndarray`: 形状为 (Hout, Wout, C) 的单个语义分割掩码，其中补丁区域来自第二个（调整大小的）掩码，其余部分来自第一个掩码。

##### apply_to_metadata

```python
def apply_to_metadata(metadata_batch: list[np.ndarray], x1: int, y1: int, x2: int, y2: int, **_) -> np.ndarray:
```

将 CutMix 应用于元数据数组。

##### get_params

```python
def get_params(self) -> dict[str, Any]:
```

采样 CutMix 混合系数。

##### get_params_dependent_on_data

```python
def get_params_dependent_on_data(params: dict[str, Any], data: dict[str, Any]) -> dict[str, Any]:
```

从第一个图像形状中采样一个 CutMix 矩形。
