# luxonis_loader_torch

Python API: `luxonis_train.loaders.luxonis_loader_torch`

默认加载器，读取 `LuxonisDataset`。

[LuxonisLoaderTorch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/luxonis_loader_torch.md)
打开一个现有数据集，或将目录解析为新数据集。

## 类

### LuxonisLoaderTorch

默认加载器，读取 `LuxonisDataset`。

该加载器封装了 `luxonis_ml` 中的 `LuxonisLoader`。`LuxonisLoader` 读取视图中分割的图像和标签，并应用增强。此类将数组转换为张量。它还可以更改每个任务的类顺序和关键点顺序。

> **示例**
> 读取现有数据集的配置的 `loader` 部分：

```yaml
loader:
  name: LuxonisLoaderTorch
  params:
    dataset_name: coco_test
```

将目录解析为新数据集的配置的 `loader` 部分：

```yaml
loader:
  name: LuxonisLoaderTorch
  params:
    dataset_dir: data/my_dataset
    dataset_name: my_dataset
```

#### 方法

##### init

```python
def __init__(dataset_name: str | None = None, dataset_dir: str | None = None, dataset_type: DatasetType | None = None, team_id: str | None = None, bucket_type: Literal['internal', 'external'] = 'internal', bucket_storage: Literal['local', 's3', 'gcs', 'azure'] = 'local', update_mode: Literal['all', 'missing'] = 'all', delete_existing: bool = True, filter_task_names: list[str] | None = None, min_bbox_visibility: float = 0.0, bbox_area_threshold: float = 0.0004, class_order_per_task: dict[str, list[str]] | None = None, kpts_mapping_per_task: dict[str, list[int]] | None = None, return_sample_metadata: bool = False, **kwargs):
```

初始化数据集和 `LuxonisLoader`。

使用 `dataset_dir`，加载器将目录解析为新数据集，或打开现有本地数据集，请参阅 `delete_existing`。不使用 `dataset_dir`，加载器打开数据集 `dataset_name`。`LuxonisLoader`
在启动时下载远程数据集。

参数

 * `dataset_name` (`str | None`): 数据集的名称。不使用 `dataset_dir`，加载器打开此数据集。使用 `dataset_dir`，解析后的数据集将获得此名称；`None` 使用目录名称。
 * `dataset_dir` (`str | None`): 要解析的目录，格式为 `LuxonisParser` 可识别的格式。它可以是本地路径、远程 URL 或 ZIP 文件。解析器将远程目录下载到工作目录中的 `data/`。
 * `dataset_type` (`DatasetType | None`): `dataset_dir` 的格式。`None` 让解析器检测它。
 * `team_id` (`str | None`): 数据集的团队 ID。它选择其本地和远程位置。`None` 使用 `luxonis_ml` 的 `LUXONISML_TEAM_ID` 设置。
 * `bucket_type` (`Literal['internal', 'external']`): 远程数据集的存储桶类型。加载器仅在不使用 `dataset_dir` 时使用它。
 * `bucket_storage` (`Literal['local', 's3', 'gcs', 'azure']`): 数据集的存储后端。
 * `update_mode` (`Literal['all', 'missing']`): 远程数据集媒体文件的同步模式。`"all"` 再次下载所有媒体文件。`"missing"`
   仅下载本地不存在的媒体文件。对于远程数据集，`LuxonisLoader` 始终下载注释和元数据。
 * `delete_existing` (`bool`): 当设置了 `dataset_dir` 并且存在同名本地数据集时该怎么做。`True` 记录警告，删除现有数据集，并再次解析目录。`False` 打开现有数据集而不进行解析。
 * `filter_task_names` (`list[str] | None`): 要加载的任务名称。`None` 加载所有任务。数据集中不存在的名称会使 `LuxonisLoader` 引发 `ValueError`。
 * `min_bbox_visibility` (`float`): 增强后必须保持可见的框的最小分数。
 * `bbox_area_threshold` (`float`): 框的最小面积，相对于图像面积，范围为 `[0, 1]`。增强会移除较小的框及其实例的标签，例如关键点和实例掩码。
 * `class_order_per_task` (`dict[str, list[str]] | None`): 每个任务的类名及其所需顺序。每个列表必须包含其任务的精确类。`None` 保持数据集顺序。
 * `kpts_mapping_per_task` (`dict[str, list[int]] | None`): 每个任务的新关键点顺序。对于列表 `m`，位置 `j` 处的关键点是原始关键点
   `m[j]`。每个列表必须映射其任务的每个关键点。`None` 保持原始顺序。
 * `return_sample_metadata` (`bool`): `__getitem__` 是否将样本元数据作为第三个元素返回。
 * `**kwargs`:
   [BaseLoaderTorch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md)
   的参数，例如 `view`、`height` 和 `width`。此加载器需要 `view`，以及 `height`、`width` 和 `augmentation_config` 的非 `None` 值。

引发

 * `ValueError`: 如果 `dataset_dir` 和 `dataset_name` 都为 `None`，或者 `height`、`width` 或 `augmentation_config` 为 `None`。
 * `KeyError`: 如果 `kpts_mapping_per_task` 包含数据集中不存在的任务，或者没有关键点标签的任务。

##### augment_test_image

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

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

推理调用此方法以准备图像，使其像视图的样本一样。增强获取一个没有标签的样本。它们包括将大小调整为 `height` 和 `width`。

参数

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

返回

 * `Tensor`: 形状为 `[height, width, C]` 的增强图像。对于具有多个源的字典，它是增强字典的第一个图像。当 `LuxonisLoader` 没有增强时，该方法返回没有更改的 `image_source`
   图像。`__init__` 构建的 `LuxonisLoader` 始终具有增强。

##### get_categorical_encodings

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

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

代码来自数据集元数据。加载器的标签包含这些代码而不是类别名称。

返回

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

##### get_classes

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

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

映射来自 `LuxonisLoader`。使用 `filter_task_names`，它只包含这些任务。它具有 `class_order_per_task` 中的类顺序。

当所有这些都为真时，`LuxonisLoader` 会向分割任务添加一个 ID 为 `0` 的 `"background"` 类：

 * 视图的样本具有任务的掩码，并且掩码不覆盖整个图像。
 * 任务具有多个类。
 * 任务没有 `"background"` 类。

其他类的 ID 随后增加 `1`。因此，两个视图的加载器可以返回不同的映射。

返回

 * `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 类型。

数据集存储类型的名称。该方法将 `"float"`、`"int"` 和 `"str"` 映射到该名称的类型。它将 `"Category"` 映射到 `int`，因为加载器的标签包含类别的整数代码。

返回

 * `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]:
```

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

计数是任务骨架中关键点名称的数量，来自数据集元数据。没有骨架的任务不在结果中。

返回

 * `dict[str, int]`: 关键点数量，以任务名称为键。

#### 属性

##### dataset

##### input_shapes

输入图像的形状 `[C, H, W]`，以 `image_source` 为键。

字典只有 `image_source` 键，即使对于具有多个图像源的数据集也是如此。每次访问都会加载第一个样本，并进行增强。

##### kpts_mapping_per_task

##### loader
