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

本页目录

  • 数据集生命周期
  • 创建和追加模式
  • 数据集记录
  • 存储布局
  • 克隆、合并和同步
  • 类排序
  • 子页面
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
Python API: luxonis_ml.data.datasetsLDF 的数据集句柄、记录、元数据和存储抽象。此包拥有持久的 Luxonis 数据格式 (LDF) 数据集契约。主要入口点是 LuxonisDataset,它创建或打开数据集,并提供添加记录、定义拆分、设置类顺序和关键点骨架、合并或克隆数据集、导出数据集以及同步远程媒体的方法。确切的注释负载模式位于 luxonis_ml.ldf.annotation 中。此包级文档侧重于数据集生命周期和存储。目录

数据集生命周期

数据集由 dataset_name 和可选的存储设置标识。构建 LuxonisDataset 会在数据集存在时打开现有数据集,或者在没有匹配数据集时初始化新数据集。
Python
1from luxonis_ml.data import BucketStorage, LuxonisDataset
2
3dataset = LuxonisDataset(
4    "parking_lot",
5    bucket_storage=BucketStorage.LOCAL,
6)
典型的修改流程:
  1. 从生成器中生成 DatasetRecord-兼容字典。
  2. 将生成器传递给 LuxonisDataset.add。
  3. 调用 LuxonisDataset.make_splits 以定义拆分成员资格。
  4. 可选地通过 LuxonisDataset 方法或 CLI 克隆、合并、导出、推送、拉取、检查、清理或删除。
Python
1def records():
2    yield {
3        "file": "path/to/image.jpg",
4        "task_name": "detection",
5        "annotation": {
6            "class": "car",
7            "boundingbox": {
8                "x": 0.1,
9                "y": 0.2,
10                "w": 0.3,
11                "h": 0.4,
12            },
13        },
14    }
15
16dataset.add(records())
17dataset.make_splits({"train": 0.8, "val": 0.1, "test": 0.1})

创建和追加模式

LuxonisDataset 默认创建本地数据集。传递 bucket_storage=BucketStorage.GCS、BucketStorage.S3 或其他受支持的存储后端以创建远程支持的数据集。远程数据集保留与本地数据集相同的本地元数据结构,而媒体文件与对象存储同步。打开同名现有数据集会重用它。要强制使用干净的本地数据集,请传递 delete_local=True。要强制使用干净的远程数据集,请在添加记录之前使用 delete_local=True 和 delete_remote=True 删除两侧。
Python
1dataset = LuxonisDataset(
2    "parking_lot",
3    bucket_storage=BucketStorage.LOCAL,
4    delete_local=True,
5)
6dataset.add(records(), batch_size=100_000_000)
7dataset.make_splits((0.8, 0.1, 0.1))
要追加新数据,请使用 delete_local=False 打开数据集并再次调用 LuxonisDataset.add。新的注释记录将被追加,而具有相同信息 UUID 的媒体记录将替换该媒体项的先前注释。LuxonisDataset.add batch_size 控制在写入 Parquet 分片之前缓冲多少注释记录。对于远程数据集,相同的批处理边界还控制何时将媒体和注释分片推送到云存储。

数据集记录

LuxonisDataset.add 接受 DatasetRecord-兼容项的迭代器。记录可以使用 "file" 表示单个源,或使用 "files" 表示多个同步源。记录级字段
字段含义
file单个媒体源的路径。
files从源名称到同步媒体路径的映射。
task_name加载器和元数据使用的可选组名。
sample_metadata可选的记录级元数据,与样本一起保留,并由 LuxonisLoader 作为 LoaderOutput.metadata 返回。
annotation由 Detection 验证的可选注释负载。
多源记录保留 LuxonisLoader 的源名称,允许训练代码接收诸如 {"rgb": ..., "depth": ...} 之类的字典。记录级元数据与注释元数据是分开的:sample_metadata 描述样本,而 annotation["metadata"] 创建元数据标签任务。
JSON
1{
2  "file": "images/frame_001.jpg",
3  "task_name": "detection",
4
5  "sample_metadata": {
6    "record_id": 123,
7    "camera": "left",
8    "tags": ["night", "warehouse"]
9  },
10
11  "annotation": {
12    "class": "person",
13    "boundingbox": {
14      "x": 0.1,
15      "y": 0.2,
16      "w": 0.3,
17      "h": 0.4
18    }
19  }
20}
前端注意事项: sample_metadata 是样本数据,而不是注释目标。

存储布局

默认情况下,本地数据集位于 LUXONISML_BASE_PATH / data / LUXONISML_TEAM_ID / datasets / dataset_name 下。默认基本路径是 Path.home() / "luxonis_ml",默认团队标识符是 "offline"。数据集存储布局
路径内容
annotations/*.parquet包含媒体路径、源名称、任务名称、类名称、实例 ID、任务类型、序列化注释负载、序列化 sample_metadata JSON 和 UUID 的 Parquet 分片。
media/远程媒体的本地副本,命名为 <uuid><suffix>。仅限本地的数据集可以保持此目录为空并继续引用原始文件。
metadata/metadata.json数据集元数据、源描述符、类映射、任务元数据、分类编码、骨架定义和 LDF 版本元数据。
metadata/splits.json从拆分名称到数据集样本标识符的映射。
远程数据集使用相同的本地元数据结构,并与配置的对象存储同步媒体和注释状态。在存储桶中,数据集位于 <bucket_storage>://<bucket>/<team_id>/datasets/<dataset_name>/,并保留相同的 annotations/、media/ 和 metadata/ 子文件夹。数组注释添加第四个 arrays/ 子文件夹。远程数据集会重命名其媒体对象。每个文件都变为 <uuid><original suffix>,其中 UUID 来自文件内容。原始文件名保留在 Parquet 分片的 file 列中。

克隆、合并和同步

LuxonisDataset.clone 在新数据集名称下创建副本。 LuxonisDataset.merge_with 将两个数据集合并到原地或合并到新数据集。
Python
1clone = dataset.clone(new_dataset_name="parking_lot_clone")
2
3dataset1.merge_with(dataset2, inplace=True)
4
5merged = dataset1.merge_with(
6    dataset2,
7    inplace=False,
8    new_dataset_name="parking_lot_merged",
9)
远程同步是显式的,由 UpdateMode 控制:
Python
1from luxonis_ml.data import BucketStorage, UpdateMode
2
3dataset.pull_from_cloud(update_mode=UpdateMode.MISSING)
4dataset.push_to_cloud(
5    bucket_storage=BucketStorage.GCS,
6    update_mode=UpdateMode.ALL,
7)

类排序

LuxonisDataset.set_class_order_per_task 为每个任务应用视图时间类顺序,而无需重写存储的元数据。提供的映射必须使用数据集中已有的确切任务名称和确切类名称。
Python
1dataset.set_class_order_per_task(
2    {
3        "vehicle_detection": ["car", "motorcycle"],
4        "color_segmentation": ["background", "red", "green", "blue"],
5    }
6)
在构建 LuxonisLoader 之前调用此函数,因为加载器初始化使用数据集的活动类排序。如果后续添加引入新类,请再次使用完整的所需顺序调用 set_class_order_per_task。

子页面