概览硬件软件云平台
OAK 应用
DepthAI
AI
软件栈
故障排除

LuxonisDataset

概述

LuxonisDataset 类提供了一个简单的 API，用于在 Luxonis 数据格式 (LDF) 中创建和管理数据。它充当抽象层，并提供数据集的方法：
  • 初始化、
  • 数据摄取、
  • 分割、
  • 合并，以及
  • 导出、云同步和删除。
以下部分将指导您创建 LDF 数据集。我们准备了一个简单的玩具数据集，供您跟随示例操作（ParkingLot.zip）。该数据集包含停车场中汽车和摩托车的图像，每张图像都带有边界框、关键点和分割掩码的注释。

数据集初始化

数据集的创建过程从初始化 LuxonisDataset 对象开始：
Python
1from luxonis_ml.data.datasets import LuxonisDataset
2
3dataset_name: str = ... # 例如 "parking_lot"
4dataset = LuxonisDataset(dataset_name)
如果您需要对存储行为进行更多控制，构造函数还接受 team_id、bucket_type、bucket_storage 和 delete_remote 参数。当数据集应存储在共享或远程对象存储中（而非仅存储在本地机器上）时，这些参数非常有用。

添加数据

数据集初始化后，我们可以开始数据摄取。我们必须首先定义一个生成器函数，该函数逐个生成数据实例。每个数据实例存储图像的路径和单个注释（例如边界框）。因此，如果一张图像有多个注释，则必须分别生成多个数据实例。我们将数据实例定义为具有以下结构的 Python 字典：
Python
1{
2    "file": str,  # 图像文件的路径
3    "annotation": Optional[dict]  # 单个图像注释
4}
其中 annotation 字段的内容取决于任务类型。支持以下任务类型：下面我们提供一个停车数据集的示例生成器函数，用于生成边界框注释的数据实例。
Python
1import json
2from pathlib import Path
3
4# 数据集的路径，请根据您系统上的实际路径进行替换
5dataset_root = Path("data/parking_lot")
6
7def generator():
8    for annotation_dir in dataset_root.iterdir():
9        with open(annotation_dir / "annotations.json") as f:
10            data = json.load(f)
11
12        # 获取图像的宽度和高度
13        W = data["dimensions"]["width"]
14        H = data["dimensions"]["height"]
15
16        image_path = annotation_dir / data["filename"]
17
18        for instance_id, bbox in data["BoundingBoxAnnotation"].items():
19
20            # 获取未归一化的边界框坐标
21            x, y = bbox["origin"]
22            w, h = bbox["dimension"]
23
24            # 获取边界框的类别名称
25            class_ = bbox["labelName"]
26            yield {
27                "file": image_path,
28                "annotation": {
29                    "class": class_,
30                    # 归一化的边界框
31                    "boundingbox": {
32                        "x": x / W,
33                        "y": y / H,
34                        "w": w / W,
35                        "h": h / H,
36                    },
37                },
38            }
然后，将生成器传递给数据集的 add 方法。
Python
1dataset.add(generator())

元数据与来源

Luxonis 数据集不仅可以存储图像和标签。数据集元数据还记录：
  • 任务定义与类别映射
  • 关键点骨架
  • 分类元数据编码
  • 数据集来源结构
来源结构由 LuxonisSource 和 LuxonisComponent 表示，使得一个数据集可以描述多组件或多传感器输入。例如，一个来源可以包含多个图像组件，而不仅仅是单个 RGB 图像。有用的元数据相关方法包括：
  • set_tasks(...) 用于显式定义任务组
  • set_classes(...) 用于注册类别映射
  • get_source_names() 用于检查可用的数据集来源
  • update_source(...) 用于更新来源/组件元数据

定义划分

在向数据集添加数据后，我们可以定义其划分。 划分名称没有限制，但大多数情况下应使用 train、val 和 test 集合。 划分通过调用 LuxonisDataset 对象的 make_splits 方法并在其参数中传递所需的划分比例来实现 （默认情况下，数据按 80:10:10 的比例划分为 train、val 和 test 集合）。
Python
1dataset.make_splits({
2  "train": 0.7,
3  "val": 0.2,
4  "test": 0.1,
5})
为了更精细地控制划分，你可以传递一个字典，其中键为划分名称，值为文件名列表：
Python
1dataset.make_splits({
2  "train": ["file1.jpg", "file2.jpg", ...],
3  "val": ["file3.jpg", "file4.jpg", ...],
4  "test": ["file5.jpg", "file6.jpg", ...],
5})
一旦完成划分，再次调用 make_splits 方法将引发错误。 如果你想重新定义划分，请在方法调用中传递 redefine_splits=True。

云同步与数据集发现

对于远程工作流，LuxonisDataset 还可以：
  • 使用 LuxonisDataset.list_datasets(...) 列出数据集
  • 使用 pull_from_cloud(...) 将缺失或所有媒体拉取到本地
  • 使用 push_to_cloud(...) 将本地数据推送到远程对象存储
当同一数据集在训练机器或团队环境中共享时，这些方法尤其有用。

数据集克隆

你可以克隆现有数据集，以新名称创建副本。 这对于在不影响原始数据集的情况下测试更改非常有用。 克隆通过调用 LuxonisDataset 对象的 clone 方法并传递新数据集的所需名称来完成。
Python
1dataset_clone = dataset.clone(new_dataset_name="dataset_clone")

数据集合并

数据集也可以合并在一起。 这对于将多个数据集合并为一个更大、统一的数据集以进行全面训练或分析非常有益。 合并通过调用第一个 LuxonisDataset 对象的 merge_with 方法并将第二个数据集作为参数传递来完成。 你可以选择两种不同的合并模式：
  • inplace（原地合并）：第一个数据集被修改以包含第二个数据集的数据
  • out-of-place（非原地合并）：从两个现有数据集的组合中创建一个新数据集
Python
1# inplace merging
2dataset1.merge_with(dataset2, inplace=True)
3# OR out-of-place merging
4dataset_merge = dataset1.merge_with(dataset2, inplace=False, new_dataset_name="dataset_merge")

数据集导出

LuxonisDataset 可以将数据从 LDF 导出为常见的数据集格式。 当你希望在 LuxonisML 中准备数据，但在其他工具链中训练或检查数据时，这非常有用。
Python
1from luxonis_ml.enums import DatasetType
2
3dataset.export("exports/coco", dataset_type=DatasetType.COCO)
当前的导出器支持原生 LDF 导出以及多种标准格式，包括 COCO、Pascal VOC、Darknet、YOLOv4、YOLOv6、YOLOv8 任务特定导出器、TensorFlow CSV、CreateML、FiftyOne 分类、分类目录和分割掩码目录。

CLI 参考

luxonis_ml CLI 提供了一组用于管理数据集的各种有用命令。 这些命令可通过 luxonis_ml data 命令访问。可用的命令有：
  • luxonis_ml data ls - 列出所有数据集
  • luxonis_ml data info <dataset_name> - 打印数据集信息
  • luxonis_ml data inspect <dataset_name> - 使用 cv2 在屏幕上渲染数据集中的数据
  • luxonis_ml data delete <dataset_name> - 删除数据集
如需更多信息，请运行 luxonis_ml data --help 或向上述任何命令传递 --help 标志。