# base_loader

Python API: `luxonis_train.loaders.base_loader`

每个加载器都继承的基类，以及一个样本的类型。

[LuxonisLoaderTorchOutput](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md)
是一个样本的类型。它是一对输入和标签。输入是形状为 `[C, H, W]` 的图像，或者是一个将每个输入名称映射到其图像的字典。标签将每个 `"<task_name>/<label>"` 键映射到一个张量。

## 类

### BaseLoaderTorch

训练管道加载器的基类。

子类在
[luxonis_train.registry.LOADERS](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/registry.md)
中以其类名注册，因此配置的 `loader.name` 字段可以命名它。子类必须实现
[input_shapes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md)、`__len__`、`__getitem__`
和
[get_classes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md)。带有关键点标签的加载器还必须重写
[get_n_keypoints](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md)。

#### 方法

##### init

```python
def __init__(view: list[str], height: int | None = None, width: int | None = None, augmentation_engine: str = 'albumentations', augmentation_config: list[AugmentationConfig] | None = None, image_source: str = 'image', keep_aspect_ratio: bool = True, color_space: Literal['RGB', 'BGR', 'GRAY'] = 'RGB', seed: int | None = None):
```

存储每个加载器共享的设置。

参数

 * `view` (`list[str]`): 构成视图的拆分。列表通常包含一个拆分，例如 `["train"]`。数据集也可以组合拆分，例如 `["train_synthetic", "train_real"]`。
 * `height` (`int | None`): 输出图像的高度。如果为 `None`，则
   [height](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md)
   属性会引发 `ValueError`。
 * `width` (`int | None`): 输出图像的宽度。如果为 `None`，则
   [width](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md)
   属性会引发 `ValueError`。
 * `augmentation_engine` (`str`): 增强引擎的名称，例如 `"albumentations"`。
 * `augmentation_config` (`list[AugmentationConfig] | None`): 增强。每个项目都有一个 `name` 和一个 `params` 字典。如果为 `None`，则
   [augmentation_config](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md)
   属性会引发 `ValueError`。
 * `image_source` (`str`): 主图像源的名称。对于具有多个源（例如 `"left"` 和 `"right"`）的数据集，可视化使用此源。
 * `keep_aspect_ratio` (`bool`): 调整大小是否保持图像的纵横比。
 * `color_space` (`Literal['RGB', 'BGR', 'GRAY']`): 输出图像的颜色空间。
 * `seed` (`int | None`): 增强的随机种子，或 `None`。

##### augment_test_image

```python
def augment_test_image(img: dict[str, Tensor] | Tensor) -> Tensor:
```

将加载器的增强应用于一个原始图像。

推理调用此方法来准备像视图样本一样的图像。基本实现只引发异常。支持原始图像推理的加载器必须重写它。[LuxonisLoaderTorch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/luxonis_loader_torch.md)
重写了它。

参数

 * `img` (`dict[str, Tensor] | Tensor`): 形状为 `[H, W, C]` 的原始图像。字典将每个源名称映射到其图像。

返回

 * `Tensor`: 重写返回形状为 `[H, W, C]` 的增强图像。

引发

 * `NotImplementedError`: 始终在基本实现中。

##### collate_fn

```python
def collate_fn(batch: list[LuxonisLoaderTorchOutput]) -> tuple[dict[str, Tensor] | Tensor, Labels]:
```

将样本列表合并为一个批次。

该方法沿新的第一维堆叠输入。对于字典输入，它单独堆叠每个输入名称。它通过标签类型合并第一个样本的每个标签：

 * `boundingbox` 和 `keypoints`: 该方法将样本索引添加为新的第一列，并连接所有样本的行。`[N, 5]` 框标签变为 `[N, 6]`。
 * `instance_segmentation`: 该方法沿第一维连接所有样本的掩码。
 * `metadata/text`: 该方法用零填充每个样本的字符代码到最长的文本。结果是形状为 `[B, S]` 的 `torch.int32` 张量。
 * 其他 `metadata/<name>` 标签: 该方法沿第一维连接所有样本的值。
 * 其他标签，例如 `classification` 和 `segmentation`: 该方法沿新的第一维堆叠它们。

参数

 * `batch` (`list[LuxonisLoaderTorchOutput]`): 样本。所有样本必须具有第一个样本的标签键。

返回

 * `tuple[dict[str, Tensor] | Tensor, Labels]`: 批处理的输入和批处理的标签，带有第一个样本的键。

引发

 * `TypeError`: 如果批次混合了张量输入和字典输入。

##### dict_numpy_to_torch

```python
def dict_numpy_to_torch(numpy_dictionary: dict[str, np.ndarray]) -> dict[str, Tensor]:
```

将 NumPy 数组字典转换为 `torch.float32` 张量。

字符串数组变为其第一个字符串的字符代码。该方法也将代码转换为 `torch.float32`。

参数

 * `numpy_dictionary` (`dict[str, np.ndarray]`): 数组，例如一个样本的标签。

返回

 * `dict[str, Tensor]`: 一个新字典，具有相同的键和每个数组的一个张量。

##### get_categorical_encodings

```python
def get_categorical_encodings(self) -> dict[str, dict[str, int]]:
```

返回每个元数据标签的每个类别的整数代码。

基本实现返回一个空字典，这意味着加载器没有分类元数据标签。

返回

 * `dict[str, dict[str, int]]`: 每个分类元数据标签的类别到代码映射，以标签名称为键。

##### get_classes

```python
def get_classes(self) -> dict[str, dict[str, int]]:
```

返回每个任务的类名和类 ID。

返回

 * `dict[str, dict[str, int]]`: 每个任务的类名到类 ID 映射，以任务名称为键。

##### get_metadata_types

```python
def get_metadata_types(self) -> dict[str, type[int] | type[Category] | type[float] | type[str]]:
```

返回每个元数据标签的 Python 类型。

基本实现返回一个空字典，这意味着加载器没有元数据标签。[DatasetMetadata](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/dataset_metadata.md)
读取结果。

返回

 * `dict[str, type[int] | type[Category] | type[float] | type[str]]`: 每个元数据标签的类型，以标签名称为键，例如 `"task_name/metadata/color"`。

##### get_n_keypoints

```python
def get_n_keypoints(self) -> dict[str, int] | None:
```

返回每个任务的关键点数量。

基本实现返回 `None`。带有关键点标签的加载器必须重写它。

返回

 * `dict[str, int] | None`: 关键点数量，以任务名称为键，或者当加载器没有关键点时为 `None`。

##### img_numpy_to_torch

```python
def img_numpy_to_torch(img: np.ndarray) -> Tensor:
```

将 NumPy 图像转换为 `torch.float32` 张量。

该方法首先移动 3D 图像的通道。2D 图像保持其形状。

> **示例**
> ```pycon
>>> import numpy as np
>>> image = np.zeros((4, 6, 3), dtype=np.uint8)
>>> BaseLoaderTorch.img_numpy_to_torch(image).shape
torch.Size([3, 4, 6])
>>> gray = np.zeros((4, 6), dtype=np.uint8)
>>> BaseLoaderTorch.img_numpy_to_torch(gray).shape
torch.Size([4, 6])
```

参数

 * `img` (`np.ndarray`): 形状为 `[H, W, C]` 或 `[H, W]` 的图像。

返回

 * `Tensor`: 形状为 `[C, H, W]` 或 `[H, W]` 的图像。

##### read_image

```python
def read_image(path: str) -> npt.NDArray[np.uint8]:
```

将图像文件读取为未归一化的 NumPy 数组。

OpenCV 将文件读取为 BGR 彩色图像。然后该方法将其转换为 [color_space](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md)。

参数

 * `path` (`str`): 图像文件的路径。

返回

 * `npt.NDArray[np.uint8]`: 形状为 `[H, W, 3]` 的图像，或者对于 `"GRAY"` 颜色空间为 `[H, W]`。

引发

 * `ValueError`: 如果 OpenCV 无法读取文件。

#### 属性

##### augmentation_config

加载器的增强。

当构造函数获得 `None` 时，该属性会引发 `ValueError`。

##### augmentation_engine

增强引擎的名称。

##### color_space

输出图像的颜色空间。

值为 `"RGB"`、`"BGR"` 或 `"GRAY"`。

##### height

输出图像的高度。

当构造函数获得 `None` 时，该属性会引发 `ValueError`。

##### image_source

主图像源的名称，例如 `"image"`。

##### input_shape

[image_source](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md) 输入的形状 `[C, H, W]`。

形状来自 [input_shapes](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md) 并且没有批次维度。

##### input_shapes

一个样本的每个输入的形状，以输入名称为键。

实现返回每个输入的一个形状，不带批次维度。图像的形状为 `[C, H, W]`。结果必须包含 [image_source](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md) 键，因为 [input_shape](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md) 读取它。

> **示例**
> 一个图像的加载器：

```python
{
    "image": torch.Size([3, 224, 224]),
}
```

一个图像和一个分割输入的加载器：

```python
{
    "image": torch.Size([3, 224, 224]),
    "segmentation": torch.Size([1, 224, 224]),
}
```

一个左图像、一个右图像和一个视差图的加载器：

```python
{
    "left": torch.Size([3, 224, 224]),
    "right": torch.Size([3, 224, 224]),
    "disparity": torch.Size([1, 224, 224]),
}
```

一个图像、关键点和点云的加载器：

```python
{
    "image": torch.Size([3, 224, 224]),
    "keypoints": torch.Size([17, 2]),
    "point_cloud": torch.Size([20000, 3]),
}
```

##### keep_aspect_ratio

调整大小是否保持图像的纵横比。

##### seed

增强的随机种子，或 `None`。

##### view

构成视图的拆分，例如 `["train"]`。

##### width

输出图像的宽度。

当构造函数获得 `None` 时，该属性会引发 `ValueError`。

## 属性

### LuxonisLoaderTorchOutput

### MIXED_INPUT_TYPES_ERROR
