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

本页目录

  • 基本用法
  • 支持的格式
  • 预期目录布局
  • COCO JSON
  • YOLOv8-v12 和 Ultralytics
  • Ultralytics NDJSON
  • Pascal VOC XML
  • YOLO Darknet TXT
  • YOLOv4 PyTorch TXT
  • MT YOLOv6
  • CreateML JSON
  • TensorFlow 对象检测 CSV
  • SOLO
  • 分类目录
  • FiftyOne 分类
  • 分割掩码目录
  • 原生 LDF
  • 拆分比例模式
  • COCO 关键点
  • 评估数据集注意事项
  • COCO-2017
  • ImageNet 示例
  • ImageNet-2012
  • 子页面
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
Python API: luxonis_ml.data.parsers将外部数据集格式转换为 LDF 的解析器。此包拥有支持的导入格式列表。此处应记录对解析器支持的添加或更改,以及实现它们的解析器类。高级 LuxonisParser 调度程序接受本地目录、LuxonisFileSystem 支持的远程路径、ZIP 存档和 roboflow://workspace/project/version/format 形式的 Roboflow URL。它可以自动检测支持的布局或使用显式 DatasetType,然后委托给匹配的解析器实现。目录

基本用法

Python
1from luxonis_ml.data import LuxonisParser
2from luxonis_ml.enums import DatasetType
3
4parser = LuxonisParser(
5    "path/to/dataset",
6    dataset_name="parking_lot",
7    dataset_type=DatasetType.COCO,
8    task_name="detection",
9)
10
11dataset = parser.parse()
当省略 dataset_type 时,LuxonisParser 尝试从目录结构推断数据集格式。task_name 可以是用于所有记录的单个字符串,也可以是从类名到任务名的映射。
Python
1parser = LuxonisParser(
2    "path/to/person_dataset",
3    task_name={
4        "head": "head_pose",
5        "neck": "head_pose",
6        "torso": "body_pose",
7        "leg": "body_pose",
8    },
9)

支持的格式

支持的解析器格式
格式数据集类型解析器典型注释
FiftyOne 布局或 Roboflow 布局中的 COCO JSONDatasetType.COCOCOCOParser边界框、分割、实例分割、关键点。
Pascal VOC XMLDatasetType.VOCVOCParser边界框。
YOLO Darknet TXTDatasetType.DARKNETDarknetParser边界框。
YOLOv4 PyTorch TXTDatasetType.YOLOV4YoloV4Parser边界框。
MT YOLOv6DatasetType.YOLOV6YoloV6Parser边界框。
YOLOv8 边界框DatasetType.YOLOV8BOUNDINGBOXYOLOv8Parser边界框。
YOLOv8 实例分割DatasetType.YOLOV8INSTANCESEGMENTATIONYOLOv8Parser实例分割。
YOLOv8 关键点DatasetType.YOLOV8KEYPOINTSYOLOv8Parser关键点。
Ultralytics NDJSON 检测DatasetType.ULTRALYTICSNDJSONUltralyticsNDJSONParser检测记录,包括本地路径或远程图像 URL。
Ultralytics NDJSON 实例分割DatasetType.ULTRALYTICSNDJSONINSTANCESEGMENTATIONUltralyticsNDJSONParser分割记录。
Ultralytics NDJSON 关键点DatasetType.ULTRALYTICSNDJSONKEYPOINTSUltralyticsNDJSONParser姿态记录。
CreateML JSONDatasetType.CREATEMLCreateMLParser边界框。
TensorFlow 对象检测 CSVDatasetType.TFCSVTensorflowCSVParser边界框。
SOLODatasetType.SOLOSOLOParser带有框、掩码、关键点和分割的合成数据。
分类目录DatasetType.CLSDIRClassificationDirectoryParser按目录名编码的类标签。
FiftyOne 分类DatasetType.FIFTYONECLSFiftyOneClassificationParser来自 labels.json 的类标签。
分割掩码目录DatasetType.SEGMASKSegmentationMaskDirectoryParser带有 _classes.csv 中类映射的灰度掩码。
原生 LDFDatasetType.NATIVENativeParser现有的 Luxonis 原生导出,包括 sample_metadata 记录。

预期目录布局

调度程序可以解析完整的数据集目录、支持它的解析器类型的单个拆分目录、提取根目录包含支持布局的 ZIP 存档、LuxonisFileSystem 处理的远程路径、roboflow://workspace/project/version/format 形式的 Roboflow URL 以及 ultralytics://username/datasets/slug 形式的 Ultralytics 格式 URL。下面的每棵树都完整地显示了一个拆分。其他拆分重复相同的结构。Roboflow 导出将第二个拆分命名为 valid,FiftyOne 导出将其命名为 validation。

COCO JSON

FiftyOne 布局将图像保存在 data 目录中,并将注释保存在 labels.json 中:
JSON
1dataset_dir/
2├── train/
3│   ├── data/
4│   │   ├── img1.jpg
5│   │   ├── img2.jpg
6│   │   └── ...
7│   └── labels.json
8├── validation/
9│   ├── data/
10│   └── labels.json
11└── test/
12    ├── data/
13    └── labels.json
Roboflow 布局将图像与 _annotations.coco.json 放在一起:
Text
1dataset_dir/
2├── train/
3│   ├── img1.jpg
4│   ├── img2.jpg
5│   ├── ...
6│   └── _annotations.coco.json
7├── valid/
8└── test/

YOLOv8-v12 和 Ultralytics

Roboflow 布局为每个拆分提供了自己的 images 和 labels 目录:
JSON
1dataset_dir/
2├── train/
3│   ├── images/
4│   │   ├── img1.jpg
5│   │   ├── img2.jpg
6│   │   └── ...
7│   └── labels/
8│       ├── img1.txt
9│       ├── img2.txt
10│       └── ...
11├── valid/
12├── test/
13└── *.yaml
Ultralytics 布局 将拆分目录放在一个 images 目录和一个 labels 目录下:
JSON
1dataset_dir/
2├── images/
3│   ├── train/
4│   │   ├── img1.jpg
5│   │   ├── img2.jpg
6│   │   └── ...
7│   ├── val/
8│   └── test/
9├── labels/
10│   ├── train/
11│   │   ├── img1.txt
12│   │   ├── img2.txt
13│   │   └── ...
14│   ├── val/
15│   └── test/
16└── *.yaml

Ultralytics NDJSON

目录中只包含一个 .ndjson 清单。清单的第一行是标题记录。它包含 "type": "dataset" 和 class_names。后面的每条记录描述一个图像:
Pycon
1dataset_dir/
2├── dataset.ndjson
3├── train/
4├── val/
5└── test/
记录通过 file 命名本地图像。记录通过 url 命名远程图像,然后 file 给出本地缓存文件的名称。您还可以给出清单本身的路径。仅包含远程图像的清单不需要图像目录:
Command Line
1dataset.ndjson

Pascal VOC XML

每个拆分都包含图像和匹配的 .xml 文件:
Python
1dataset_dir/
2├── train/
3│   ├── img1.jpg
4│   ├── img1.xml
5│   └── ...
6├── valid/
7└── test/

YOLO Darknet TXT

每个拆分都包含图像和 .txt 对,以及 _darknet.labels:
Command Line
1dataset_dir/
2├── train/
3│   ├── img1.jpg
4│   ├── img1.txt
5│   ├── ...
6│   └── _darknet.labels
7├── valid/
8└── test/

YOLOv4 PyTorch TXT

每个拆分都包含 _annotations.txt 和 _classes.txt:
Command Line
1dataset_dir/
2├── train/
3│   ├── img1.jpg
4│   ├── img2.jpg
5│   ├── ...
6│   ├── _annotations.txt
7│   └── _classes.txt
8├── valid/
9└── test/

MT YOLOv6

拆分目录位于一个 images 目录和一个 labels 目录下,旁边是 data.yaml:
Text
1dataset_dir/
2├── images/
3│   ├── train/
4│   │   ├── img1.jpg
5│   │   ├── img2.jpg
6│   │   └── ...
7│   ├── valid/
8│   └── test/
9├── labels/
10│   ├── train/
11│   │   ├── img1.txt
12│   │   ├── img2.txt
13│   │   └── ...
14│   ├── valid/
15│   └── test/
16└── data.yaml

CreateML JSON

每个拆分都包含 _annotations.createml.json:
Text
1dataset_dir/
2├── train/
3│   ├── img1.jpg
4│   ├── img2.jpg
5│   ├── ...
6│   └── _annotations.createml.json
7├── valid/
8└── test/

TensorFlow 对象检测 CSV

每个拆分都包含 _annotations.csv:
Text
1dataset_dir/
2├── train/
3│   ├── img1.jpg
4│   ├── img2.jpg
5│   ├── ...
6│   └── _annotations.csv
7├── valid/
8└── test/

SOLO

每个拆分都包含 Unity Perception 定义文件和每个序列的一个目录:
Text
1dataset_dir/
2├── train/
3│   ├── metadata.json
4│   ├── sensor_definitions.json
5│   ├── annotation_definitions.json
6│   ├── metric_definitions.json
7│   └── sequence.<SequenceNUM>/
8│       ├── step<StepNUM>.camera.jpg
9│       ├── step<StepNUM>.frame_data.json
10│       └── step<StepNUM>.camera.semantic segmentation.jpg
11├── valid/
12└── test/
语义分割图像是可选的。metadata.json 声明 totalSequences,当序列目录的数量与它不匹配时,解析器会发出警告。

分类目录

一个目录包含一个类的图像。拆分布局将类目录保存在拆分目录中:
Text
1dataset_dir/
2├── train/
3│   ├── class1/
4│   │   ├── img1.jpg
5│   │   ├── img2.jpg
6│   │   └── ...
7│   ├── class2/
8│   └── ...
9├── valid/
10└── test/
平面布局将类目录放在根目录中。然后解析器进行随机拆分:
Text
1dataset_dir/
2├── class1/
3│   ├── img1.jpg
4│   └── ...
5├── class2/
6│   └── ...
7└── info.json
info.json 是可选的。它是平面布局根目录中唯一可以包含的文件。

FiftyOne 分类

图像放在 data 目录中,标签放在 labels.json 中。拆分布局为每个拆分提供了自己的对:
Text
1dataset_dir/
2├── train/
3│   ├── data/
4│   │   ├── img1.jpg
5│   │   └── ...
6│   └── labels.json
7├── validation/
8│   ├── data/
9│   └── labels.json
10└── test/
11    ├── data/
12    └── labels.json
平面布局包含一对,然后解析器进行随机拆分:
Text
1dataset_dir/
2├── data/
3│   ├── img1.jpg
4│   └── ...
5└── labels.json
labels.json 包含类名列表和从图像词干到其类索引的映射:
Pycon
1{
2  "classes": ["class1", "class2"],
3  "labels": {
4    "img1": 0,
5    "img2": 1
6  }
7}

分割掩码目录

每个拆分都包含图像、匹配的掩码和 _classes.csv:
Text
1dataset_dir/
2├── train/
3│   ├── img1.jpg
4│   ├── img1_mask.png
5│   ├── ...
6│   └── _classes.csv
7├── valid/
8└── test/
img1.jpg 的掩码是 img1_mask.png。解析器需要每个掩码的 .jpg 图像。显式 DatasetType.SEGMASK 不会改变此规则。掩码是灰度图像,每个像素值都是一个类。_classes.csv 将像素值映射到类名:
Pycon
1Pixel Value, Class
20, background
31, class1
42, class2
解析器不会从类名中删除空格。行 0, background 给出类名 " background",带有前导空格。

原生 LDF

DatasetType.NATIVE 读取 LuxonisDataset.export 使用 --type native 写入的内容。使用它在机器之间移动数据集,或在没有 LuxonisParser 的情况下读取 LDF 导出:
Text
1dataset_dir/
2├── metadata.json
3├── train/
4│   ├── annotations.json
5│   └── images/
6│       ├── 0.jpg
7│       ├── 1.jpg
8│       └── ...
9├── val/
10│   ├── annotations.json
11│   └── images/
12└── test/
13    ├── annotations.json
14    └── images/
metadata.json 包含导出的 LDF 版本,例如 {"ldf_version": "2.1.0"}。它是可选的,解析器只读取它以警告来自较新版本的导出。大于 max_partition_size_gb 的导出将写入为 <name>_part0、<name>_part1 等,每个部分重复此布局。annotations.json 包含记录列表。每条记录都使用 LuxonisDataset.add 接受的相同形状,因此您可以在没有 LuxonisParser 的情况下读取它:
Pycon
1[
2  {
3    "file": "images/0.jpg",
4    "task_name": "detection",
5    "sample_metadata": {
6      "camera": "left"
7    },
8    "annotation": {
9      "instance_id": 0,
10      "class": "person",
11      "boundingbox": {
12        "x": 0.1,
13        "y": 0.2,
14        "w": 0.3,
15        "h": 0.4
16      }
17    }
18  }
19]
记录的键是:
  • file 包含一个图像的路径,相对于 annotations.json。具有多个同步源的记录使用 files 代替,它将每个源名称映射到路径。
  • task_name 命名注释的任务组。
  • sample_metadata 包含记录级元数据,例如相机名称或帧号。它不是注释标签。
  • annotation 包含一个检测。导出为每个检测写入一条记录,因此多条记录可以共享同一个 file。
检测包含 class、instance_id 及其有效负载键。有效负载键是 boundingbox、keypoints、segmentation、instance_segmentation 或 metadata。导出在每条记录中最多写入一个有效负载键,但手写检测可以同时包含多个。框和关键点使用图像归一化坐标。掩码以 COCO RLE 形式写入,具有 height、width 和压缩的 counts 字符串:
Pycon
1{
2  "instance_id": 1,
3  "class": "road",
4  "segmentation": {
5    "height": 720,
6    "width": 1280,
7    "counts": "b14<000000000^3"
8  }
9}

拆分比例模式

解析器拆分比例支持两种模式:
  • 浮点值,例如 0.8、0.1 和 0.1,重新分配和打乱样本。值应总和为 1.0。
  • 整数计数,例如 1000、100 和 50,从相应的原始拆分中提取并保留拆分边界。如果请求的计数超过可用样本,则使用该拆分中的所有可用样本。
Pycon
1luxonis_ml data parse ./dataset --name parking_lot --type coco
2luxonis_ml data parse ./dataset --train 0.8 --val 0.1 --test 0.1
3luxonis_ml data parse ./dataset --train 1000 --val 100 --test 50
为 --train、--val 和 --test 各自赋予一个值。如果您只设置其中一些,则剩余的拆分将平均分配剩余的记录。这仅适用于比例,不适用于计数。较旧的 --split-ratio 选项接受一个包含三个值的 Python 列表文字,例如 --split-ratio "[0.8, 0.1, 0.1]"。不带括号的逗号分隔值会引发 ValueError。该选项已弃用。请改用 --train、--val 和 --test。

COCO 关键点

对于 COCO-2017 风格的 FiftyOne 导出,边界框和分割通常来自实例注释文件,而人物关键点则位于专用的 person_keypoints_*.json 文件中。使用 Python API 解析时,请使用 use_keypoint_ann=True:
Pycon
1parser = LuxonisParser("coco-2017", dataset_name="coco_keypoints")
2dataset = parser.parse(
3    use_keypoint_ann=True,
4    split_ratios={"train": 0.5, "val": 0.4, "test": 0.1},
5)
解析期间跳过或恢复的解析器问题将报告为 ParserIssueMessage 实例,并按 ParserIssue 分类。

评估数据集注意事项

COCO-2017

FiftyOne 布局是 fiftyone 包写入的。安装它,然后一次下载一个拆分:
Pycon
1fiftyone zoo datasets load coco-2017 \
2    --splits validation \
3    --kwargs max_samples=1000
COCO 解析处理 FiftyOne 和 Roboflow 布局。边界框相对于图像尺寸进行归一化;多边形或 RLE 分割存储为 RLE;实例分割从相同的分割源发出;关键点进行归一化和裁剪;类别标识符映射到类名。对于 FiftyOne COCO 导出,标准 labels.json 通常包含 80 个 COCO 类别的实例注释,但不包含人物关键点。使用 Python API 读取专用 raw/person_keypoints_train2017.json 和 raw/person_keypoints_val2017.json 文件时,请使用 use_keypoint_ann=True。如果缺少测试关键点,split_val_to_test=True 会将验证样本拆分为验证集和测试集。Roboflow COCO 布局会忽略关键点特定选项。COCO 解析器还会过滤已知的损坏 COCO-2017 训练图像,并在源元数据需要修复时写入清理后的注释文件。

ImageNet 示例

ImageNet-sample 数据集包含 1,000 张图像,涵盖 1,000 个 ImageNet 类别,用于图像分类。使用 fiftyone 包下载它:
Pycon
1fiftyone zoo datasets load imagenet-sample
ImageNet-sample 解析器处理 FiftyOne 图像分类导出,可以是平面 data/ 加 labels.json 形式,也可以是基于拆分的 train/validation/test 目录。上面的命令写入平面形式。解析器在解析时随机拆分平面布局。已知的 ImageNet-sample 标签问题会自动清理:重复的 "crane" 和 "maillot" 类名会进行消歧,并纠正图像 006742 和 031933 的已知错误索引标签。labels_fixed.json 文件会保存在原始标签旁边。

ImageNet-2012

原始 ImageNet-2012 存档布局不直接解析。提取训练和验证存档,按类别对训练图像进行分组,使用开发工具包元数据将验证图像映射到类别标签,将验证图像移动到类别文件夹中,然后将结果解析为 DatasetType.CLSDIR。

子页面