# utils

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

用于将 LDF 注释适配到 Albumentations 的实用程序。

增强引擎接收 Luxonis 数据格式 (LDF) 的注释，在空间变换之前将其转换为 Albumentations 兼容的数组，并在之后将其转换回来。此模块将这些边界转换集中管理。

布局转换

| 目标 | LDF 布局 | Albumentations 布局 |
| --- | --- | --- |
| 掩码 | (C, H, W) 或 (N, H, W) | (H, W, C) 或 (H, W, N) |
| 边界框 | [c, x, y, w, h] | [xmin, ymin, xmax, ymax, c, i] |
| 关键点 | (N, 3K) 归一化行 | (NK, 3) 像素空间行 |

附加的 bbox 索引 i 是 bbox
相关标签（例如实例掩码和关键点）中的位置，用于使它们与在增强和过滤后保留的边界框对齐。它对于上次写入它的阶段是本地的：[BatchCompose](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/batch_compose.md)
在每次批处理转换后重新标记它，因此它在整个管道中不稳定。

## 函数

### instance_count

```python
def instance_count(array: np.ndarray, target_type: str, n_keypoints: int = 0) -> int:
```

计算 Albumentations 布局目标描述的实例数。

每个实例目标类型将其实例存储在不同的轴上，因此不能仅从 `len(array)` 读取计数。

> **示例**
> ```pycon
>>> instance_count(np.zeros((8, 8, 3)), "instance_mask")
3
>>> instance_count(np.zeros((6, 3)), "keypoints", n_keypoints=2)
3
>>> instance_count(np.zeros((4, 5)), "metadata")
4
```

参数

 * `array` (`np.ndarray`): Albumentations 布局中的目标。
 * `target_type` (`str`): 数组持有的目标类型，例如 `"instance_mask"` 或 `"keypoints"`。
 * `n_keypoints` (`int`): 每个实例的关键点数 K。仅用于关键点目标，每个实例存储 K 行。

返回

 * `int`: `array` 中的实例数。

引发

 * `ValueError`: 如果 `target_type` 是 `"keypoints"` 且 `n_keypoints` 不是正数。

### pad_empty_entries

```python
def pad_empty_entries(batch: list[np.ndarray], n_columns: int = 6) -> list[np.ndarray]:
```

调整每个空条目的形状，以便可以连接批次。

不带框或关键点的样本以变换留下的任何形状返回，包括一维 `np.array([])`，它不会与填充的样本连接。这些条目被替换为形状正确的空行。

宽度从填充的条目中读取，因为管道的可选字段决定了这些行的宽度。空但仍为二维的条目具有相同的宽度，并在没有条目填充时使用。

> **示例**
> ```pycon
>>> batch = [np.array([]), np.zeros((2, 7))]
>>> [array.shape for array in pad_empty_entries(batch)]
[(0, 7), (2, 7)]
>>> [array.shape for array in pad_empty_entries([np.array([])])]
[(0, 6)]
```

参数

 * `batch` (`list[np.ndarray]`): 每个样本的数组，其中一些可能为空。
 * `n_columns` (`int`): 当没有条目带有宽度时回退的宽度。bbox 行 [xmin, ymin, xmax, ymax, c, i] 和关键点行都是六列宽。

返回

 * `list[np.ndarray]`: 批次，每个空条目的形状为 (0, n)。

### postprocess_bboxes

```python
def postprocess_bboxes(bboxes: np.ndarray, area_threshold: float = 0.0004) -> tuple[np.ndarray, np.ndarray]:
```

将增强的边界框转换回 LDF 格式。

小于 `area_threshold` 的边界框将被丢弃。附加的 bbox 索引与框一起返回，以便与框绑定的标签（例如实例掩码、关键点、数组和元数据）可以以相同的方式进行过滤。

> **示例**
> ```pycon
>>> bboxes = np.array([[0.1, 0.2, 0.4, 0.6, 2, 5]], dtype=float)
>>> out_bboxes, ordering = postprocess_bboxes(bboxes)
>>> np.round(out_bboxes, 2).tolist()
[[2.0, 0.1, 0.2, 0.3, 0.4]]
>>> ordering.tolist()
[5]
>>> tiny = np.array([[0.0, 0.0, 0.01, 0.01, 1, 3]], dtype=float)
>>> postprocess_bboxes(tiny, area_threshold=0.1)[0].shape
(0, 5)
>>> postprocess_bboxes(np.empty((0, 6)), area_threshold=0.1)[0].shape
(0, 5)
```

参数

 * `bboxes` (`np.ndarray`): 形状为 (N, 6) 的增强边界框，格式为 [xmin, ymin, xmax, ymax, c, i]，其中 c 是类别 ID，i 是 bbox 索引。
 * `area_threshold` (`float`): 框保持有效所需的最小归一化框面积 w⋅h。

返回

 * `一个包含以下内容的元组`: * 形状为 (M, 5) 的边界框，格式为 [c, x, y, w, h]，其中 M ≤ N 且 c 是类别 ID。
    * 形状为 (M) 的整数索引，用于标识哪些原始 bbox 相关标签在过滤后保留。

### postprocess_keypoints

```python
def postprocess_keypoints(keypoints: np.ndarray, bboxes_ordering: np.ndarray, image_height: int, image_width: int, n_keypoints:
int) -> np.ndarray:
```

将增强的关键点转换回归一化的 LDF 行。

输入包含 Albumentations 应用空间变换后的像素空间关键点。此函数恢复原始注释分组，仅保留与保留的边界框相关的注释，将图像外的关键点标记为不可见，将坐标裁剪到图像范围，并将坐标归一化回 [0, 1]。

> **示例**
> ```pycon
>>> keypoints = np.array([[5, 5, 2], [12, -1, 2]], dtype=float)
>>> out = postprocess_keypoints(keypoints, np.array([0]), 10, 10, 2)
>>> np.round(out, 2).tolist()
[[0.5, 0.5, 2.0, 1.0, 0.0, 0.0]]
>>> keypoints = np.array([[1, 1, 2], [9, 9, 1]], dtype=float)
>>> postprocess_keypoints(
...     keypoints, np.array([1, 0]), 10, 10, 1
... ).tolist()
[[0.9, 0.9, 1.0], [0.1, 0.1, 2.0]]
```

参数

 * `keypoints` (`np.ndarray`): 形状为 (NK, D) 的增强关键点，其中每个注释的前 3K 个值是 (x, y, v) 三元组，任何额外的列都将被丢弃。
 * `bboxes_ordering` (`np.ndarray`): 在 bbox 后处理中保留的 bbox 相关注释的索引。
 * `image_height` (`int`): 用于归一化 y 坐标的增强图像的高度。
 * `image_width` (`int`): 用于归一化 x 坐标的增强图像的宽度。
 * `n_keypoints` (`int`): 每个注释中的关键点数 K。

返回

 * `np.ndarray`: 形状为 (M, 3K) 的关键点，其中 M 是保留注释的数量。每行都采用归一化的 LDF 格式 [x1, y1, v1, x2, y2, v2, …]。

### postprocess_mask

```python
def postprocess_mask(mask: np.ndarray) -> np.ndarray:
```

将增强的掩码转换回 LDF 布局。

> **示例**
> ```pycon
>>> postprocess_mask(np.array([[1, 0], [0, 1]])).shape
(1, 2, 2)
>>> mask = np.array([[[1, 5], [2, 6]], [[3, 7], [4, 8]]])
>>> postprocess_mask(mask).tolist()
[[[1, 2], [3, 4]], [[5, 6], [7, 8]]]
```

参数

 * `mask` (`np.ndarray`): 增强的掩码。二维输入被解释为形状为 (H, W) 的单个掩码。三维输入应具有形状 (H, W, C) 或 (H, W, N)。

返回

 * `np.ndarray`: LDF 通道优先布局中的掩码数组。二维输入变为 (1, H, W)，三维输入变为 (C, H, W) 或 (N, H, W)。

### preprocess_bboxes

```python
def preprocess_bboxes(bboxes: np.ndarray) -> np.ndarray:
```

将 LDF 边界框转换为 Albumentations 格式。

LDF 将边界框存储为归一化的 [c, x, y, w, h] 行，其中 c 是类别 ID，x 和 y 是左上角。Albumentations 期望归一化的 [xmin, ymin, xmax, ymax, c] 行。此函数还附加一个每框索引，用于在增强后使 bbox 相关标签与在过滤后保留的框对齐。

> **示例**
> ```pycon
>>> bboxes = np.array([[2, 0.1, 0.2, 0.3, 0.4]])
>>> out = preprocess_bboxes(bboxes)
>>> np.round(out[:, :4], 4).tolist()
[[0.1, 0.2, 0.4, 0.6]]
>>> out[:, 4:].astype(int).tolist()
[[2, 0]]
```

参数

 * `bboxes` (`np.ndarray`): 形状为 (N, 5) 的边界框，格式为 [c, x, y, w, h]。

返回

 * `np.ndarray`: 形状为 (N, 6) 的边界框，格式为 [xmin, ymin, xmax, ymax, c, i]，其中 i 是 bbox 索引。

### preprocess_keypoints

```python
def preprocess_keypoints(keypoints: np.ndarray, height: int, width: int) -> np.ndarray:
```

将归一化的 LDF 关键点转换为绝对坐标。

LDF 将关键点存储为归一化的 (x, y, v) 三元组的扁平行。Albumentations 期望每行一个关键点，并使用像素空间坐标进行空间变换。

> **示例**
> ```pycon
>>> keypoints = np.array([[0.5, 0.25, 2, 1.0, 0.0, 1]])
>>> preprocess_keypoints(keypoints, height=8, width=4).tolist()
[[2.0, 2.0, 2.0], [4.0, 0.0, 1.0]]
>>> preprocess_keypoints(np.empty((0, 3)), 8, 4).shape
(0, 3)
```

参数

 * `keypoints` (`np.ndarray`): 形状为 (N, 3K) 的关键点，其中 N 是注释的数量，K 是每个注释的关键点数量。每行都采用格式 [x1, y1, v1, x2, y2, v2, …]。
 * `height` (`int`): 用于缩放归一化 y 坐标的图像高度。
 * `width` (`int`): 用于缩放归一化 x 坐标的图像宽度。

返回

 * `np.ndarray`: 形状为 (NK, 3) 的关键点，采用像素空间 [x, y, v] 格式。

### preprocess_mask

```python
def preprocess_mask(seg: np.ndarray) -> np.ndarray:
```

将 LDF 掩码转换为 Albumentations 掩码布局。

Luxonis 数据格式将语义掩码存储为 (C, H, W)，将实例掩码存储为 (N, H, W)。Albumentations 期望空间维度在前，因此此函数将通道或实例维度移动到末尾。

> **示例**
> ```pycon
>>> seg = np.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])
>>> preprocess_mask(seg).shape
(2, 2, 2)
>>> preprocess_mask(seg).tolist()
[[[1, 5], [2, 6]], [[3, 7], [4, 8]]]
```

参数

 * `seg` (`np.ndarray`): 形状为 (C, H, W) 或 (N, H, W) 的掩码数组。

返回

 * `np.ndarray`: 形状为 (H, W, C) 或 (H, W, N) 的掩码数组。

### yield_batches

```python
def yield_batches(data_batch: list[dict[str, T]], batch_size: int) -> Iterator[dict[str, list[T]]]:
```

生成固定大小的样本字典块。

> **示例**
> ```pycon
>>> samples = [
...     {"image": "a", "label": 1},
...     {"image": "b", "label": 2},
...     {"image": "c", "label": 3},
... ]
>>> list(yield_batches(samples, 2))
[{'image': ['a', 'b'], 'label': [1, 2]}, {'image': ['c'], 'label': [3]}]
>>> next(yield_batches(samples, 10))["label"]
[1, 2, 3]
```

参数

 * `data_batch` (`list[dict[str, T]]`): 包含每个样本数据的字典。所有字典都应公开相同的键。
 * `batch_size` (`int`): 每个生成的批次中的最大样本数。

返回

 * `Iterator[dict[str, list[T]]]`: 按键分组的字典迭代器。对于 B 个样本的输入块，每个生成的值将每个键映射到 B 个值的列表。

## 属性

### T
