# LuxonisLoader

## 概述

LuxonisLoader 提供了一种简单高效的方式来加载和遍历存储在 Luxonis 数据格式（LDF） 中的数据，并支持实时数据增强。由于它也与 LuxonisTrain 原生集成，因此能够实现流畅无缝的训练工作流。

## 数据集加载

要使用 LuxonisLoader 加载数据集，我们首先需要获取 LuxonisDataset 的一个实例。加载器使用数据集和我们要加载的数据集视图（即拆分）进行初始化。

```python
from luxonis_ml.data.datasets import LuxonisDataset
from luxonis_ml.data.loaders import LuxonisLoader

dataset_name: str = ... # 现有 LDF 数据集的名称，例如 "parking_lot"
dataset = LuxonisDataset(dataset_name)
loader = LuxonisLoader(dataset, view="train")
```

> `view`
> 可以是单个拆分，也可以是拆分列表。

可以使用简单的 for 循环来迭代数据：

```python
for images, labels in loader:
    ...
```

对于单源数据集，images 通常是一个单独的图像数组。对于多源数据集，它可以是一个以源或组件名称为键的字典。labels 输出按任务名称分组。

## 数据增强

数据增强是应用于数据以增加数据集多样性从而改进模型训练的变换。我们可以通过向 LuxonisLoader 构造函数的 augmentation_config 参数传递一个 Python 字典列表来定义它们，每个字典代表一个单独的增强操作：

```python
{
    "name": str,  # 增强操作的名称
    "params": dict  # 增强操作的参数
}
```

默认情况下，我们支持来自 albumentations 库的大部分增强操作。您可以在 [Albumentations 文档](https://albumentations.ai/docs/api_reference/augmentations/)
中找到完整的增强操作列表及其参数。此外，我们还提供了一些自定义的批量增强操作：

 * Mosaic4 - 使用 4 张图像的马赛克增强。将 4 张图像的裁剪部分组合成一张马赛克图案的图像。
 * MixUp - MixUp 增强。使用随机权重叠加两张图像。

每个增强条目还可以定义 use_for_resizing: true，当希望该变换显式处理大小调整时使用。

### 示例

以下示例演示了一个简单的增强流水线：

```python
[
  {
    'name': 'HueSaturationValue',
    'params': {
      'p': 0.5,
      'hue_shift_limit': 3,
      'sat_shift_limit': 70,
      'val_shift_limit': 40,
    }
  },
  {
    'name': 'Rotate',
    'params': {
      'p': 0.6,
      'limit': 30,
      'border_mode': 0,
      'value': [0, 0, 0]
    }
  },
  {
    'name': 'Perspective',
    'params': {
      'p': 0.5,
      'scale': [0.04, 0.08],
      'keep_size': True,
      'pad_mode': 0,
      'pad_val': 0,
      'mask_pad_val': 0,
      'fit_output': False,
      'interpolation': 1,
      'always_apply': False,
    }
  },
  {
    'name': 'Affine',
    'params': {
      'p': 0.4,
      'scale': None,
      'translate_percent': None,
      'translate_px': None,
      'rotate': None,
      'shear': 10,
      'interpolation': 1,
      'mask_interpolation': 0,
      'cval': 0,
      'cval_mask': 0,
      'mode': 0,
      'fit_output': False,
      'keep_ratio': False,
      'rotate_method': 'largest_box',
      'always_apply': False,
    }
  },
]
```

假设上面的增强列表存储在一个名为 augmentations.yaml 的 YAML 文件中。然后我们可以使用它来创建一个加载器：

```python
from luxonis_ml.data.datasets import LuxonisDataset
from luxonis_ml.data.loaders import LuxonisLoader

dataset_name: str = ...
dataset = LuxonisDataset(dataset_name)
loader = LuxonisLoader(
    dataset,
    view="train", 
    augmentation_config="augmentations.yaml", 
    augmentation_engine="albumentations",  # 默认
    height=256,
    width=320,
    keep_aspect_ratio=True, # 默认
    color_space="RGB",  # 默认，也可以是 BGR
)
for img, labels in loader:
    ...
```

> 增强操作
> **不一定**
> 按照列表中定义的顺序应用。相反，会根据增强操作的类型确定一个最优顺序，以最小化计算成本。

## 其他加载器选项

当前的加载器还支持一些在较大训练流水线中很重要的有用选项：

 * exclude_empty_annotations=True 从最终标签字典中删除空的标签条目
 * filter_task_names=[...] 仅从多任务数据集中加载选定的任务组
 * keep_categorical_as_strings=True 将分类元数据值保留为字符串而不是编码后的整数
 * color_space={...} 在处理多源数据集时按源设置色彩空间
 * update_mode="all" 或 "missing" 用于控制远程数据集的本地同步行为

有关完整的构造函数签名和返回类型，请参见 [API
参考](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/api-reference.md)。