此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 核心工作流
  • 教程数据集
  • 记录、任务和标签
  • 使用生成器添加记录
  • 定义拆分
  • 注释负载
  • 命令行界面
  • 扩展点
  • 子页面
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
Python API: luxonis_ml.dataLuxonis 数据格式工作流的公共入口点。luxonis_ml.data 包汇集了用于创建、转换、加载和增强 Luxonis 数据格式 (LDF) 数据集的高级 API。LDF 是 Luxonis 训练堆栈中用于视觉数据集的数据集表示,具有一个或多个媒体源、任务组、注释类型、元数据字段、本地文件和远程对象存储。此模块有意作为包的映射,而不是每个详细合同的规范主页。详细信息位于拥有它们的实现旁边:目录

核心工作流

大多数数据管道遵循相同的序列:
  1. 创建或打开一个 LuxonisDataset。
  2. 从可迭代对象添加记录或使用 LuxonisParser 解析外部数据集。
  3. 定义数据集拆分。
  4. 使用 LuxonisLoader 加载一个或多个拆分。
  5. 可选地通过 AlbumentationsEngine 应用增强。
  6. 可选地克隆、合并、导出、推送、拉取、检查、清理或删除数据集。
高级 API
API何时使用更多细节
LuxonisDataset创建、修改、拆分、克隆、合并、导出、同步或删除 LDF 数据集。luxonis_ml.data.datasets
LuxonisParser将支持的外部数据集布局转换为 LDF。luxonis_ml.data.parsers
LuxonisLoader从一个或多个数据集拆分迭代图像类输入、标签和样本元数据。luxonis_ml.data.loaders
AlbumentationsEngine在加载样本时应用运行时图像和标签增强。luxonis_ml.data.augmentations

教程数据集

数据包中的大多数示例都使用一个小型 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 获取。

记录、任务和标签

数据集摄取是基于记录的。记录指向一个文件或多个同步文件,可选地分配任务名称,并可选地提供注释负载。任务名称将应由模型或加载器一起使用的注释分组。加载器标签键使用 "task_name/task_type"。如果未提供任务名称,则任务名称为空字符串,键以 "/" 开头。

使用生成器添加记录

LuxonisDataset.add 接受记录的迭代器。生成器函数是通常的选择,因为您不会在内存中构建完整的记录列表。下面的生成器为每个目录读取一个注释文件。它在共享的 instance_id 下生成一个对象的边界框和关键点。它在单独的任务名称下生成每个分割掩码。
Python
1import json
2from pathlib import Path
3
4import cv2
5import numpy as np
6
7from luxonis_ml.data import LuxonisDataset
8
9dataset_root = Path("data/parking_lot")
10
11
12def generator():
13    for annotation_file in dataset_root.rglob("annotations.json"):
14        data = json.loads(annotation_file.read_text())
15        width = data["dimensions"]["width"]
16        height = data["dimensions"]["height"]
17        image = str(annotation_file.parent / data["filename"])
18
19        for instance_id, box in data["BoundingBoxAnnotation"].items():
20            x, y = box["origin"]
21            w, h = box["dimension"]
22            yield {
23                "file": image,
24                "task_name": f"instance_keypoints_{box['labelName']}",
25                "annotation": {
26                    "class": box["labelName"],
27                    "instance_id": int(instance_id),
28                    "boundingbox": {
29                        "x": x / width,
30                        "y": y / height,
31                        "w": w / width,
32                        "h": h / height,
33                    },
34                },
35            }
36
37        for instance_id, pose in data["KeypointsAnnotation"].items():
38            yield {
39                "file": image,
40                "task_name": f"instance_keypoints_{pose['labelName']}",
41                "annotation": {
42                    "instance_id": int(instance_id),
43                    "keypoints": {
44                        "keypoints": [
45                            (
46                                keypoint["location"][0] / width,
47                                keypoint["location"][1] / height,
48                                keypoint["visibility"],
49                            )
50                            for keypoint in pose["keypoints"]
51                        ]
52                    },
53                },
54            }
55
56        masks = data["VehicleTypeSegmentation"]
57        mask_path = annotation_file.parent / masks["filename"]
58        mask = cv2.cvtColor(cv2.imread(str(mask_path)), cv2.COLOR_BGR2RGB)
59
60        for instance in masks["instances"]:
61            color = np.array(instance["pixelValue"], dtype=np.uint8)
62            yield {
63                "file": image,
64                "task_name": "segmentation",
65                "annotation": {
66                    "class": instance["labelName"],
67                    "segmentation": {
68                        "mask": (mask == color)
69                        .all(axis=-1)
70                        .astype(np.uint8)
71                    },
72                },
73            }
74
75
76dataset = LuxonisDataset("parking_lot")
77dataset.add(generator())

定义拆分

LuxonisDataset.make_splits 将记录分配给命名拆分。传递拆分的比率,或传递每个拆分的精确文件。
Python
1dataset.make_splits({"train": 0.7, "val": 0.2, "test": 0.1})
2
3dataset.make_splits(
4    {
5        "train": ["image_1.jpg", "image_2.jpg"],
6        "val": ["image_3.jpg"],
7        "test": ["image_4.jpg"],
8    }
9)
不带参数的调用将拆分为 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 data 提供数据集操作。CLI 镜像了用于解析、列出、检查、验证、清理、导出、同步、克隆、合并和删除数据集的 Python API。
Command Line
1luxonis_ml data --help
2luxonis_ml data parse --help
3luxonis_ml data parse <data_directory>
4luxonis_ml data ls
5luxonis_ml data info <dataset_name>
6luxonis_ml data inspect <dataset_name>
7luxonis_ml data health <dataset_name>
8luxonis_ml data sanitize <dataset_name>
9luxonis_ml data export <dataset_name> --type native
10luxonis_ml data export <dataset_name> --type coco
11luxonis_ml data export <dataset_name> --type ultralyticsndjson
12luxonis_ml data push <dataset_name>
13luxonis_ml data pull <dataset_name>
14luxonis_ml data clone <dataset_name> <new_name>
15luxonis_ml data merge <source_name> <target_name>
16luxonis_ml data delete <dataset_name>

扩展点

数据集和加载器是注册表支持的。第三方包可以在 dataset_plugins 和 loader_plugins 组中公开入口点。此模块在导入时加载这些插件,并将它们注册到 DATASETS_REGISTRY 和 LOADERS_REGISTRY 中。

子页面