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

本页目录

  • 概述
  • 添加记录
  • 多源记录
  • 注释类型
  • 定义拆分
  • 克隆和合并数据集
  • 导出数据集
  • 命令行界面
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

LuxonisDataset

最后更新

概述

LuxonisDataset 是用于存储在 Luxonis 数据格式 (LDF) 中的数据集的高级 API。它管理记录、注释、任务和类元数据、拆分、本地或远程存储、克隆、合并、验证和导出。安装数据依赖项并从公共 luxonis_ml.data 包导入类:
Command Line
1python -m pip install "luxonis-ml[data]"
Python
1from luxonis_ml.data import LuxonisDataset
2
3dataset = LuxonisDataset("parking_lot")
构造 LuxonisDataset 会在数据集存在时打开匹配的数据集,或者在数据集不存在时对其进行初始化。本地数据集默认存储在 ~/luxonis_ml 下。设置 LUXONISML_BASE_PATH 以使用其他基本目录。要使用相同的名称重新创建本地数据集,请在初始化期间明确删除其本地状态:
Python
1dataset = LuxonisDataset("parking_lot", delete_local=True)

添加记录

dataset.add(...) 接受任何 DatasetRecord 对象或兼容字典的可迭代对象。对于大型数据集,生成器很方便,因为它可以避免将每个记录都保存在内存中。每个记录包含:
字段描述
file一个媒体文件的路径。
files同步多源样本的源名称到路径映射。使用 file 或 files。
task_name可选任务组。默认值为空字符串。
annotation可选分类、空间、数组或注释元数据负载。
sample_metadata完整样本的可选 JSON 可序列化元数据。
以下生成器添加归一化的边界框:
Python
1from pathlib import Path
2
3from luxonis_ml.data import LuxonisDataset
4
5image_dir = Path("data/parking_lot/images")
6
7
8def records():
9    yield {
10        "file": image_dir / "frame_001.jpg",
11        "task_name": "detection",
12        "sample_metadata": {
13            "camera": "left",
14            "frame_id": 1,
15        },
16        "annotation": {
17            "class": "car",
18            "instance_id": 17,
19            "boundingbox": {
20                "x": 0.10,
21                "y": 0.20,
22                "w": 0.30,
23                "h": 0.40,
24            },
25        },
26    }
27
28
29dataset = LuxonisDataset("parking_lot")
30dataset.add(records())
边界框坐标使用归一化的 xywh:x 和 y 标识左上角,所有四个值都相对于图像尺寸。

多源记录

将 files 用于同步输入,例如 RGB 和深度图像:
Python
1def records():
2    yield {
3        "files": {
4            "rgb": "data/rgb/frame_001.png",
5            "depth": "data/depth/frame_001.png",
6        },
7        "task_name": "detection",
8        "annotation": {
9            "class": "person",
10            "boundingbox": {"x": 0.1, "y": 0.1, "w": 0.3, "h": 0.4},
11        },
12    }
源名称成为 LuxonisLoader 的 sample.images 字典中的键。

注释类型

LDF 支持:
  • 通过 class 进行分类
  • 通过 boundingbox 进行归一化的 xywh 边界框
  • 通过 keypoints 进行归一化的 (x, y, visibility) 关键点三元组
  • 通过 segmentation 进行语义分割
  • 通过 instance_segmentation 进行实例分割
  • 通过 array 进行任意 .npy 目标
  • 通过 metadata 进行灵活的注释标签
分割输入可以是多边形、二进制掩码或 COCO 游程编码掩码。当多个记录描述同一个物理对象时,分配相同的 instance_id 以可靠地关联其边界框、关键点和实例掩码。有关每个接受的有效负载形状和掩码编码,请参阅 LDF 注释 API 参考。

定义拆分

LuxonisLoader 需要拆分定义。不带参数调用 make_splits() 会使用 80:10:10 的比例创建 train、val 和 test 拆分:
Python
1dataset.make_splits()
传递任何总和为 1.0 的命名比例:
Python
1dataset.make_splits({"train": 0.7, "val": 0.2, "test": 0.1})
您还可以分配确切的文件:
Python
1dataset.make_splits(
2    {
3        "train": [image_dir / "frame_001.jpg", image_dir / "frame_002.jpg"],
4        "val": [image_dir / "frame_003.jpg"],
5        "test": [image_dir / "frame_004.jpg"],
6    }
7)
拆分名称不限于 train、val 和 test。默认情况下,后续调用仅分配尚未在拆分中的记录。使用以下命令替换完整的拆分定义:
Python
1dataset.make_splits(
2    {"train": 0.8, "val": 0.1, "test": 0.1},
3    replace_old_splits=True,
4)

克隆和合并数据集

克隆完整数据集或选定的拆分并使用新名称:
Python
1clone = dataset.clone(
2    new_dataset_name="parking_lot_clone",
3    push_to_cloud=False,
4)
5
6train_clone = dataset.clone(
7    new_dataset_name="parking_lot_train",
8    push_to_cloud=False,
9    splits_to_clone=["train"],
10)
将另一个数据集合并到当前数据集:
Python
1dataset.merge_with(other_dataset, inplace=True)
或者创建一个单独的合并数据集:
Python
1merged = dataset.merge_with(
2    other_dataset,
3    inplace=False,
4    new_dataset_name="parking_lot_merged",
5)
两个数据集必须使用相同的存储桶存储类型才能进行异地合并。使用 splits_to_merge 将传入数据限制为选定的拆分。

导出数据集

使用 DatasetType 将 LDF 导出为受支持的第三方格式:
Python
1from luxonis_ml.enums import DatasetType
2
3output = dataset.export(
4    "exports/parking_lot_coco",
5    dataset_type=DatasetType.COCO,
6)
支持的导出系列包括:
  • 本机 LDF
  • COCO 和 Pascal VOC
  • Darknet、YOLOv4、YOLOv6 和 YOLOv8 边界框
  • YOLOv8 实例分割和关键点
  • Ultralytics NDJSON 检测、实例分割和关键点
  • CreateML 和 TensorFlow 对象检测 CSV
  • 分类目录和 FiftyOne 分类
  • 分割掩码目录
除了 Unity SOLO,LuxonisParser 支持的每种格式也可用作导出目标。具有多个特定于任务的变体(例如 YOLOv8 和 Ultralytics NDJSON)的格式使用单独的 DatasetType 值用于边界框、实例分割和关键点。输出路径不得已存在。设置 zip_output=True 以创建存档,或设置 max_partition_size_gb 以将大型导出分成多个部分。

命令行界面

luxonis_ml data 命令涵盖了完整的数据集生命周期:
Command Line
1luxonis_ml data ls
2luxonis_ml data info parking_lot
3luxonis_ml data inspect parking_lot
4luxonis_ml data health parking_lot
5luxonis_ml data sanitize parking_lot
6luxonis_ml data export parking_lot --type coco
7luxonis_ml data clone parking_lot parking_lot_clone
8luxonis_ml data merge source_dataset target_dataset
9luxonis_ml data push parking_lot --bucket-storage gcs
10luxonis_ml data pull parking_lot --bucket-storage gcs
11luxonis_ml data delete parking_lot --local
运行 luxonis_ml data <command> --help 以获取所有选项,包括拆分选择、远程存储、分区导出和非交互式删除。