datasets
最后更新
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)- 从生成器中生成 DatasetRecord-兼容字典。
- 将生成器传递给 LuxonisDataset.add。
- 调用 LuxonisDataset.make_splits 以定义拆分成员资格。
- 可选地通过 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})注意
尽管
"train"、"val" 和 "test" 是传统的拆分名称,但 LuxonisDataset.make_splits 在项目需要自定义视图时接受任意拆分名称。创建和追加模式
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 分片之前缓冲多少注释记录。对于远程数据集,相同的批处理边界还控制何时将媒体和注释分片推送到云存储。数据集记录
"file" 表示单个源,或使用 "files" 表示多个同步源。记录级字段| 字段 | 含义 |
|---|---|
file | 单个媒体源的路径。 |
files | 从源名称到同步媒体路径的映射。 |
task_name | 加载器和元数据使用的可选组名。 |
sample_metadata | 可选的记录级元数据,与样本一起保留,并由 LuxonisLoader 作为 LoaderOutput.metadata 返回。 |
annotation | 由 Detection 验证的可选注释负载。 |
{"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 是样本数据,而不是注释目标。另请参阅
DatasetRecord 用于记录验证,Detection 用于负载分组,以及 luxonis_ml.ldf.annotation 用于详细注释模式。
存储布局
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 列中。警告
删除标志独立控制本地和远程状态。要完全重新创建远程数据集,请传递
delete_local=True 和 delete_remote=True。要从现有远程数据集重建损坏的本地副本,请传递 delete_local=True 和 delete_remote=False。警告
本地路径不包含存储桶存储组件。因此,同名的本地数据集和远程数据集共享一个本地目录。请使用不同的名称,否则可能会相互覆盖本地状态。
克隆、合并和同步
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)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)重要
注释分片和元数据始终同步。媒体更新模式控制是传输所有媒体文件还是仅传输缺失的媒体文件。
类排序
Python
1dataset.set_class_order_per_task(
2 {
3 "vehicle_detection": ["car", "motorcycle"],
4 "color_segmentation": ["background", "red", "green", "blue"],
5 }
6)