# luxonis_loader

Python API: `luxonis_ml.data.loaders.luxonis_loader`

## 类

### LuxonisLoader

[LuxonisDataset](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
样本的索引加载器。

[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](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/typing.md)
保留了传统的元组行为：对于单源数据集，它产生 `(image, labels)`。对于多源数据集，它产生 `(images, labels)`，其中 `images` 将源名称映射到数组。

新代码优先使用属性访问：

```python
sample = loader[0]

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

`sample.metadata` 包含来自
[DatasetRecord.sample_metadata](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
的记录级元数据。当启用 `autopopulate_metadata` 时，加载器还会添加一个从源名称到文件基名的 `"filenames"` 映射。增强输出还包括一个从配置的转换路径到所选运行时参数的 `"augmentations"`
映射。两者都是保留键，永远不会覆盖存储在记录上的元数据。

标签键使用 `"task_name/task_type"`。如果数据集是在没有任务名称的情况下创建的，则默认任务名称为空，键看起来像 `"/boundingbox"` 或 `"/segmentation"`。

#### 方法

##### init

```python
def __init__(dataset: LuxonisDataset, view: str | list[str] = 'train', augmentation_engine: Literal['albumentations'] | str = 'albumentations', augmentation_config: list[Params] | PathType | None = None, height: int | None = None, width: int | None = None, keep_aspect_ratio: bool = True, exclude_empty_annotations: bool = False, color_space: dict[str, Literal['RGB', 'BGR', 'GRAY']] | Literal['RGB', 'BGR', 'GRAY'] | None = None, seed: int | None = None, min_bbox_visibility: float = 0.0, bbox_area_threshold: float = 0.0004, *, keep_categorical_as_strings: bool = False, update_mode: UpdateMode | Literal['all', 'missing'] = UpdateMode.ALL, filter_task_names: list[str] | None = None, autopopulate_metadata: bool = True):
```

为 Luxonis 数据集创建加载器。

> **示例**
> ```python
augmentation_config = [
    {
        "name": "Defocus",
        "params": {"p": 1},
    },
    {
        "name": "RandomCrop",
        "params": {"height": 512, "width": 512, "p": 1},
    },
    {
        "name": "Mosaic4",
        "params": {
            "height": 256,
            "width": 256,
            "p": 1.0,
        },
    },
]

loader = LuxonisLoader(
    dataset,
    view="train",
    augmentation_config=augmentation_config,
    height=640,
    width=640,
)
```

参数

 * `dataset` (`LuxonisDataset`): 要从中加载的数据集。
 * `view` (`str | list[str]`): 要加载的拆分名称或拆分名称列表。
 * `augmentation_engine` (`Literal['albumentations'] | str`): 增强引擎注册表名称。
 * `augmentation_config` (`list[Params] | PathType | None`): 可选的增强配置或配置文件路径。每个配置项包含 `name` 和可选的 `params` 键。
 * `height` (`int | None`): 可选的输出图像高度。启用增强时必需。
 * `width` (`int | None`): 可选的输出图像宽度。启用增强时必需。
 * `keep_aspect_ratio` (`bool`): 调整大小时是否保留图像宽高比。
 * `exclude_empty_annotations` (`bool`): 是否从返回的标签字典中省略空注释。
 * `color_space` (`dict[str, Literal['RGB', 'BGR', 'GRAY']] | Literal['RGB', 'BGR', 'GRAY'] | None`): 每个源的可选颜色空间。单个值适用于所有源；如果省略，所有源都使用 `"RGB"`。
 * `seed` (`int | None`): 增强的可选随机种子。
 * `min_bbox_visibility` (`float`): 增强后原始边界框必须保持可见的最小分数。
 * `bbox_area_threshold` (`float`): 边界框保持有效的最小归一化面积。默认值会移除非常小的框及其相关的关键点。
 * `keep_categorical_as_strings` (`bool`): 是否将分类元数据标签保留为字符串而不是将其转换为整数。
 * `update_mode` (`UpdateMode | Literal['all', 'missing']`): 远程数据集中媒体文件的同步模式。注释和元数据始终被覆盖。
 * `filter_task_names` (`list[str] | None`): 可选的任务名称以包含。如果省略，则包含所有任务。
 * `autopopulate_metadata` (`bool`): 是否添加自动样本元数据，例如源文件名。启用时，返回的元数据包含一个以源名称为键的 `"filenames"` 字典。设置为 `False` 以仅返回存储在 [DatasetRecord.sample_metadata](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md) 中的元数据。增强来源无论如何都会报告，因为它描述的是返回的数组而不是记录。

引发

 * `ValueError`: 如果 [color_space](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md) 既不是字符串也不是字典。
 * `ValueError`: 如果 [filter_task_names](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md) 包含数据集中不存在的任务名称。
 * `RuntimeError`: 如果缺少拆分元数据。

#### 属性

##### augmentations

可选的增强引擎。其应用的配置路径被添加到增强输出元数据中。

##### autopopulate_metadata

是否将自动元数据（例如源文件名）添加到 [LoaderOutput.metadata](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/typing.md)。

##### classes

每个任务的类名映射。

##### color_space

每个源的输出颜色空间。

##### dataset

正在加载的数据集。

##### df

加载器使用的记录数据帧。

##### exclude_empty_annotations

是否省略空注释。

##### filter_task_names

可选的任务名称允许列表。

##### height

可选的输出图像高度。

##### idx_to_df_row

从加载器索引到数据帧行索引的映射。

##### instances

选定视图中包含的组 ID。

##### keep_categorical_as_strings

分类元数据是否保留为字符串。

##### source_names

每个样本中预期的源名称。

##### sync_mode

数据集是否为远程并在加载前拉取。

##### tasks_without_background

未分配像素映射到背景类 0 的分割任务。

##### view

此加载器加载的拆分名称。

##### width

可选的输出图像宽度。
