概览硬件软件云平台
此页面由 AI 自动翻译。查看英文原版
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# 原地合并
2dataset1.merge_with(dataset2, inplace=True)
3# 或非原地合并
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 Classification、Classification Directory 和 Segmentation Mask Directory。

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 标志传递给上述任何命令。