# loaders

Python API: `luxonis_ml.data.loaders`

LDF 样本的数据集加载器。

此包负责运行时样本访问。[LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
读取一个或多个数据集拆分，解析媒体路径，按任务键组装标签，可选地应用增强功能，并以适合训练管道的形状返回数据。

目录

 * [基本用法](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders.md)
 * [构造函数选项](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders.md)
 * [标签键](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders.md)
 * [输出布局](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders.md)
 * [样本元数据](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders.md)
 * [运行时选项](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders.md)

## 基本用法

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

dataset = LuxonisDataset("parking_lot")
loader = LuxonisLoader(dataset, view="train")

sample = loader[0]

images = sample.images
labels = sample.labels
metadata = sample.metadata
```

[LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
实现了索引访问和迭代。返回的值始终是
[LoaderOutput](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/typing.md)。

[LoaderOutput.images](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/typing.md)
将源名称映射到数组。单源数据集使用常规的 `"image"` 源名称；多源数据集保留记录 `"files"` 映射中的名称。

[LoaderOutput.metadata](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/typing.md)
包含来自 `DatasetRecord.sample_metadata` 的记录级元数据。默认情况下，它还包括一个从源名称到加载文件基本名称的 `"filenames"` 映射。

当代码只需要输入和标签时，传统的两值解包仍然有效：

```python
image_or_images, labels = loader[0]
```

元数据不会通过元组解包产生。通过 `loader[0].metadata` 访问它。

## 构造函数选项

[LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
在运行时配置，不改变存储的数据集状态。常见选项包括：

 * `view` 用于加载一个拆分或拆分列表。
 * `augmentation_engine` 和 `augmentation_config` 用于启用增强功能。
 * `height`、`width` 和 `keep_aspect_ratio` 用于定义增强引擎所需的调整大小行为。
 * `color_space` 用于请求全局或按源名称请求 `"RGB"`、`"BGR"` 或 `"GRAY"` 输出。
 * `seed` 用于可重现的随机增强。
 * `exclude_empty_annotations` 用于省略空标签。
 * `keep_categorical_as_strings` 用于保留分类元数据值。
 * `update_mode` 用于控制远程数据集的媒体同步。
 * `filter_task_names` 用于仅加载选定的任务组。
 * `autopopulate_metadata` 用于在
   [LoaderOutput.metadata](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/typing.md)
   中包含自动元数据，例如源文件名。

加载远程数据集时，注释和元数据会刷新。媒体文件根据
[UpdateMode](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/enums.md)
下载：`ALL` 覆盖本地媒体，`MISSING` 仅下载本地无法解析的媒体。

## 标签键

`labels` 字典以 `"task_name/task_type"` 为键。如果数据集是在没有任务名称的情况下创建的，则默认任务名称为空字符串，键以 `"/"` 开头。

> **示例**
> ```pycon
>>> task_name = "detection"
>>> task_type = "boundingbox"
>>> f"{task_name}/{task_type}"
'detection/boundingbox'
>>> f"{''}/metadata/camera_angle"
'/metadata/camera_angle'
```

元数据标签使用 `"task_name/metadata/key"`，因此每个元数据字段都可以独立使用。

样本元数据不使用标签键。它通过 [LoaderOutput.metadata](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/typing.md) 单独返回：

```python
sample = loader[0]
print(sample.metadata)

# {
#     "filenames": {"image": "frame_001.jpg"},
#     "record_id": 123,
#     "camera": "left",
# }
```

传递 `autopopulate_metadata=False` 以仅返回存储的元数据：

```python
loader = LuxonisLoader(dataset, autopopulate_metadata=False)
metadata = loader[0].metadata
```

增强输出还带有一个 `"augmentations"` 映射，从配置的增强路径到引擎选择的运行时参数。与 `"filenames"` 不同，无论 `autopopulate_metadata` 如何，它都会被添加，因为它描述的是返回的数组而不是数据集记录：

```python
{
    "record_id": 123,
    "augmentations": {
        "HorizontalFlip": {},
        "OneOf/RandomBrightnessContrast": {"alpha": 1.02, "beta": -0.03},
    },
}
```

这两个键都是保留的。定义其中一个的记录保留其自己的值，加载器会发出警告而不是覆盖它。

当批处理增强组合多个样本时，输入样本的元数据会保留在 `"batch_augmentation_metadata"` 中：

```python
{
    "record_id": 123,

    "batch_augmentation_metadata": [
        {
            "input_index": 0,
            "sample_metadata": {"record_id": 123},
        },
        {
            "input_index": 1,
            "sample_metadata": {"record_id": 456},
        },
    ],
}
```

注释元数据不同： `annotation["metadata"]` 下的值被转换为标签任务，例如 `"detection/metadata/weather"`。

## 输出布局

常见标签布局

| 任务类型 | 形状或结构 | 含义 |
| --- | --- | --- |
| `classification` | (C) | 独热类向量。 |
| `boundingbox` | (N, 5) | 行是 [c, x, y, w, h]。 |
| `segmentation` | (C, H, W) | 通道优先布局的独热语义掩码。 |
| `instance_segmentation` | (N, H, W) | 每个实例一个二进制掩码。 |
| `keypoints` | (N, 3K) | 展平的 (x, y, v) 关键点三元组。 |
| `metadata` | 原始值结构。 | 按元数据字段名称键入的值。 |

> **另请参阅**
> [luxonis_ml.ldf.annotation](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md) 用于转换为这些加载器输出的摄取模式。

## 样本元数据

记录级元数据 来自 `DatasetRecord.sample_metadata`，并作为 [LoaderOutput.metadata](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/typing.md) 提供。

```python
sample = loader[0]

sample.metadata
# {
#     "filenames": {"image": "frame_001.jpg"},
#     "record_id": 123,
#     "camera": "left",
# }
```

传递 `autopopulate_metadata=False` 以仅返回存储的元数据：

```python
loader = LuxonisLoader(dataset, autopopulate_metadata=False)
metadata = loader[0].metadata
```

增强输出还带有一个 `"augmentations"` 映射，从配置的增强路径到引擎选择的运行时参数。与 `"filenames"` 不同，无论 `autopopulate_metadata` 如何，它都会被添加，因为它描述的是返回的数组而不是数据集记录：

```python
{
    "record_id": 123,
    "augmentations": {
        "HorizontalFlip": {},
        "OneOf/RandomBrightnessContrast": {"alpha": 1.02, "beta": -0.03},
    },
}
```

这两个键都是保留的。定义其中一个的记录保留其自己的值，加载器会发出警告而不是覆盖它。

当批处理增强组合多个样本时，输入样本的元数据会保留在 `"batch_augmentation_metadata"` 中：

```python
{
    "record_id": 123,

    "batch_augmentation_metadata": [
        {
            "input_index": 0,
            "sample_metadata": {"record_id": 123},
        },
        {
            "input_index": 1,
            "sample_metadata": {"record_id": 456},
        },
    ],
}
```

注释元数据不同： `annotation["metadata"]` 下的值被转换为标签任务，例如 `"detection/metadata/weather"`。

## 运行时选项

[LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md) 拥有与数据集存储有意分离的运行时关注点：

 * 通过 `view` 选择的视图；
 * 通过 `color_space` 进行颜色空间转换；
 * 通过 `height` 和 `width` 进行可选调整大小；
 * 通过 `keep_aspect_ratio` 保持纵横比；
 * 通过 `augmentation_engine` 和 `augmentation_config` 构建增强引擎；
 * 通过 `update_mode` 进行远程媒体同步；
 * 通过 `exclude_empty_annotations` 过滤空注释；
 * 通过 `keep_categorical_as_strings` 进行元数据类别编码；
 * 通过 `filter_task_names` 进行任务过滤。

```python
loader = LuxonisLoader(
    dataset,
    view=["train", "val"],
    height=640,
    width=640,
    keep_aspect_ratio=True,
    color_space="RGB",
    filter_task_names=["detection"],
    exclude_empty_annotations=True,
)
```

> **重要**
> 增强功能需要输出 `height` 和 `width`，以便加载器可以构建确定性调整大小阶段。

> **另请参阅**
> [luxonis_ml.data.augmentations](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations.md) 用于增强配置和目标转换详细信息。

## 子页面

 * [base_loader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/base_loader.md)
 * [luxonis_loader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
