# data

Python API: `luxonis_ml.data`

Luxonis 数据格式工作流的公共入口点。

luxonis_ml.data 包汇集了用于创建、转换、加载和增强 Luxonis 数据格式 (LDF) 数据集的高级 API。LDF 是 Luxonis
训练堆栈中用于视觉数据集的数据集表示，具有一个或多个媒体源、任务组、注释类型、元数据字段、本地文件和远程对象存储。

此模块有意作为包的映射，而不是每个详细合同的规范主页。详细信息位于拥有它们的实现旁边：

 * [luxonis_ml.data.datasets](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets.md)
   记录数据集生命周期、存储布局、拆分、克隆、合并、远程同步和数据集插件。
 * [luxonis_ml.ldf.annotation](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
   记录
   [DatasetRecord](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)、[Detection](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)、[Category](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
   和所有注释负载模式。
 * [luxonis_ml.data.parsers](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers.md)
   记录
   [LuxonisParser](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers/luxonis_parser.md)、支持的外部格式、每个格式预期的目录布局、原生
   LDF 布局、拆分比率模式和解析器特定注意事项。
 * [luxonis_ml.data.loaders](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders.md)
   记录
   [LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)、加载器输出、标签键约定、颜色空间、过滤和预处理。
 * [luxonis_ml.data.augmentations](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations.md)
   记录
   [AlbumentationsEngine](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)、转换顺序、调整大小、批量转换和自定义转换。

目录

 * [核心工作流](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data.md)
 * [教程数据集](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data.md)
 * [记录、任务和标签](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data.md)
 * [使用生成器添加记录](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data.md)
 * [定义拆分](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data.md)
 * [注释负载](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data.md)
 * [命令行界面](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data.md)
 * [扩展点](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data.md)

## 核心工作流

大多数数据管道遵循相同的序列：

 1. 创建或打开一个
    [LuxonisDataset](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)。
 2. 从可迭代对象添加记录或使用
    [LuxonisParser](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers/luxonis_parser.md)
    解析外部数据集。
 3. 定义数据集拆分。
 4. 使用
    [LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
    加载一个或多个拆分。
 5. 可选地通过
    [AlbumentationsEngine](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
    应用增强。
 6. 可选地克隆、合并、导出、推送、拉取、检查、清理或删除数据集。

高级 API

| API | 何时使用 | 更多细节 |
| --- | --- | --- |
|
[LuxonisDataset](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
| 创建、修改、拆分、克隆、合并、导出、同步或删除 LDF 数据集。 |
[luxonis_ml.data.datasets](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets.md)
|
|
[LuxonisParser](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers/luxonis_parser.md)
| 将支持的外部数据集布局转换为 LDF。 |
[luxonis_ml.data.parsers](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers.md)
|
|
[LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
| 从一个或多个数据集拆分迭代图像类输入、标签和样本元数据。 |
[luxonis_ml.data.loaders](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders.md)
|
|
[AlbumentationsEngine](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations/albumentations_engine.md)
| 在加载样本时应用运行时图像和标签增强。 |
[luxonis_ml.data.augmentations](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations.md)
|

> **示例**
> 最小流从数据集开始，然后构建加载器。

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

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

for sample in loader:
    images = sample.images
    labels = sample.labels
    metadata = sample.metadata
```

> **注意**
> 从 luxonis_ml.data 导入是常见工作流推荐的公共 API。当您需要特定于实现的模型（例如注释模式、解析器类或加载器基类）时，从较低模块导入。

## 教程数据集

数据包中的大多数示例都使用一个小型 `parking_lot` 数据集，其中包含汽车和摩托车。它包含对象检测框、实例关键点、用于颜色/类型/品牌/二进制车辆类别的语义分割掩码，以及适用于尝试完整 LDF 工作流的元数据。

该数据集可用于练习任务命名约定：

 * 具有不同骨架的类别的关键点注释应分为任务组，例如 `"instance_keypoints_car"` 和 `"instance_keypoints_motorbike"`；
 * 语义分割通常放置在其自己的任务组中，例如 `"segmentation"`，因为加载器会为分割任务添加背景类。

用于准备和与 LuxonisML 数据集交互的动手笔记本和脚本保存在 Luxonis AI 教程存储库中：`https://github.com/luxonis/ai-tutorials/tree/main/training`。

这些示例使用的原始 `parking_lot` 样本存档可在 `https://drive.google.com/uc?export=download&id=1OAuLlL_4wRSzZ33BuxM6Uw2QYYgv_19N` 获取。

## 记录、任务和标签

数据集摄取是基于记录的。记录指向一个文件或多个同步文件，可选地分配任务名称，并可选地提供注释负载。

> **示例**
> 两种支持的媒体键样式易于区分。

```pycon
>>> single_source = {"file": "image.jpg", "annotation": None}
>>> multi_source = {"files": {"rgb": "rgb.png", "depth": "depth.png"}}
>>> "file" in single_source, "files" in multi_source
(True, True)
```

任务名称将应由模型或加载器一起使用的注释分组。加载器标签键使用 `"task_name/task_type"`。如果未提供任务名称，则任务名称为空字符串，键以 `"/"` 开头。

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

> **另请参阅**
> [luxonis_ml.ldf.annotation](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md) 用于精确的记录模型、注释负载模式、标准化坐标约定、元数据类别和实例关联规则。

## 使用生成器添加记录

[LuxonisDataset.add](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md) 接受记录的迭代器。生成器函数是通常的选择，因为您不会在内存中构建完整的记录列表。

下面的生成器为每个目录读取一个注释文件。它在共享的 `instance_id` 下生成一个对象的边界框和关键点。它在单独的任务名称下生成每个分割掩码。

```python
import json
from pathlib import Path

import cv2
import numpy as np

from luxonis_ml.data import LuxonisDataset

dataset_root = Path("data/parking_lot")

def generator():
    for annotation_file in dataset_root.rglob("annotations.json"):
        data = json.loads(annotation_file.read_text())
        width = data["dimensions"]["width"]
        height = data["dimensions"]["height"]
        image = str(annotation_file.parent / data["filename"])

        for instance_id, box in data["BoundingBoxAnnotation"].items():
            x, y = box["origin"]
            w, h = box["dimension"]
            yield {
                "file": image,
                "task_name": f"instance_keypoints_{box['labelName']}",
                "annotation": {
                    "class": box["labelName"],
                    "instance_id": int(instance_id),
                    "boundingbox": {
                        "x": x / width,
                        "y": y / height,
                        "w": w / width,
                        "h": h / height,
                    },
                },
            }

        for instance_id, pose in data["KeypointsAnnotation"].items():
            yield {
                "file": image,
                "task_name": f"instance_keypoints_{pose['labelName']}",
                "annotation": {
                    "instance_id": int(instance_id),
                    "keypoints": {
                        "keypoints": [
                            (
                                keypoint["location"][0] / width,
                                keypoint["location"][1] / height,
                                keypoint["visibility"],
                            )
                            for keypoint in pose["keypoints"]
                        ]
                    },
                },
            }

        masks = data["VehicleTypeSegmentation"]
        mask_path = annotation_file.parent / masks["filename"]
        mask = cv2.cvtColor(cv2.imread(str(mask_path)), cv2.COLOR_BGR2RGB)

        for instance in masks["instances"]:
            color = np.array(instance["pixelValue"], dtype=np.uint8)
            yield {
                "file": image,
                "task_name": "segmentation",
                "annotation": {
                    "class": instance["labelName"],
                    "segmentation": {
                        "mask": (mask == color)
                        .all(axis=-1)
                        .astype(np.uint8)
                    },
                },
            }

dataset = LuxonisDataset("parking_lot")
dataset.add(generator())
```

> **注意**
> 共享的 `instance_id` 将一个对象的框和关键点链接起来。为每个类的关键点提供单独的任务名称，因为加载器将一个任务的关键点堆叠到一个数组中。

## 定义拆分

[LuxonisDataset.make_splits](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md) 将记录分配给命名拆分。传递拆分的比率，或传递每个拆分的精确文件。

```python
dataset.make_splits({"train": 0.7, "val": 0.2, "test": 0.1})

dataset.make_splits(
    {
        "train": ["image_1.jpg", "image_2.jpg"],
        "val": ["image_3.jpg"],
        "test": ["image_4.jpg"],
    }
)
```

不带参数的调用将拆分为 80/10/10。比率是 0 到 1 之间的数字，比率之和必须为 1。

按比率拆分仅使用尚未被任何拆分持有的记录。因此，第二次按比率调用需要新记录，否则会引发错误。使用显式文件列表的调用仅添加尚未被任何拆分持有的文件。如果没有命名文件是新的，则调用会记录警告并保留旧拆分。因此，您可以解析相同的数据两次。

传递 `replace_old_splits=True` 以删除旧拆分。稍后按比率调用将再次拆分每条记录。稍后按文件列表调用仅拆分您命名的文件。

## 注释负载

LDF 支持一小组注释负载系列：

 * 通过 `"class"` 值进行分类；
 * 通过 `"boundingbox"` 进行归一化 `xywh` 边界框；
 * 通过 `"keypoints"` 进行归一化 `(x, y, visibility)` 关键点三元组；
 * 通过多边形点、二进制掩码或 `"segmentation"` 下的 COCO RLE 值进行语义分割掩码；
 * 通过 `"instance_segmentation"` 下的相同掩码编码进行实例分割掩码；
 * 通过 `"array"` 进行任意 `.npy` 数组目标；
 * 通过 `"metadata"` 进行灵活的元数据值。

任何带有类的注释都会贡献一个分类目标。当单独的记录描述相同的物理对象时，使用相同的 `instance_id`，以便可以可靠地关联框、关键点和实例掩码。

> **另请参阅**
> [luxonis_ml.ldf.annotation](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md) 用于示例、精确的字段名称、掩码编码细节、元数据类别和加载器输出形状。

## 命令行界面

数据包还通过 `luxonis_ml data` 提供数据集操作。CLI 镜像了用于解析、列出、检查、验证、清理、导出、同步、克隆、合并和删除数据集的 Python API。

```bash
luxonis_ml data --help
luxonis_ml data parse --help
luxonis_ml data parse <data_directory>
luxonis_ml data ls
luxonis_ml data info <dataset_name>
luxonis_ml data inspect <dataset_name>
luxonis_ml data health <dataset_name>
luxonis_ml data sanitize <dataset_name>
luxonis_ml data export <dataset_name> --type native
luxonis_ml data export <dataset_name> --type coco
luxonis_ml data export <dataset_name> --type ultralyticsndjson
luxonis_ml data push <dataset_name>
luxonis_ml data pull <dataset_name>
luxonis_ml data clone <dataset_name> <new_name>
luxonis_ml data merge <source_name> <target_name>
luxonis_ml data delete <dataset_name>
```

> **另请参阅**
> [luxonis_ml.data.main](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/__main__.md) 用于命令实现细节，以及 [luxonis_ml.data.parsers](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers.md) 用于每个支持格式的目录布局，包括 `--type native` 写入的本机 LDF 布局。

## 扩展点

数据集和加载器是注册表支持的。第三方包可以在 `dataset_plugins` 和 `loader_plugins` 组中公开入口点。此模块在导入时加载这些插件，并将它们注册到 [DATASETS_REGISTRY](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/base_dataset.md) 和 [LOADERS_REGISTRY](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/base_loader.md) 中。

> **另请参阅**
> [BaseDataset](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/base_dataset.md)、[BaseLoader](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/base_loader.md)、[DatasetIterator](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/base_dataset.md)、[DATASETS_REGISTRY](https://docs.luxonis.com/zh/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/base_dataset.md) 和 [LOADERS_REGISTRY](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/base_loader.md)。

## 子页面

 * [增强](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/augmentations.md)
 * [数据集](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets.md)
 * [导出器](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/exporters.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/parsers.md)
 * [工具](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils.md)
 * [数据 CLI](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/__main__.md)
