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

本页目录

  • 概述
  • 输入位置
  • 支持的格式
  • 预期目录布局
  • COCO JSON
  • YOLOv8-v12
  • Ultralytics NDJSON
  • 分类目录
  • 分割掩码目录
  • 原生 LDF 导出
  • 拆分行为
  • 命令行界面
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

LuxonisParser

最后更新

概述

LuxonisParser 将支持的第三方数据集布局转换为 Luxonis 数据格式 (LDF)。它验证输入结构,在可能的情况下检测格式,转换其注释,并创建带有拆分定义的 LuxonisDataset。从公共数据包导入:
Python
1from luxonis_ml.data import LuxonisParser
2
3dataset = LuxonisParser(
4    "path/to/dataset",
5    dataset_name="my_dataset",
6).parse()
当检测不明确或相同目录布局可以表示不同任务时,传递 DatasetType:
Python
1from luxonis_ml.data import LuxonisParser
2from luxonis_ml.enums import DatasetType
3
4dataset = LuxonisParser(
5    "path/to/yolo_dataset",
6    dataset_name="people_pose",
7    dataset_type=DatasetType.YOLOV8KEYPOINTS,
8    task_name="pose",
9).parse()
task_name 还可以将类映射到任务组:
Python
1parser = LuxonisParser(
2    "path/to/dataset",
3    task_name={
4        "head": "head_pose",
5        "neck": "head_pose",
6        "torso": "body_pose",
7        "leg": "body_pose",
8    },
9)

输入位置

解析器接受:
  • 本地目录
  • 本地 ZIP 存档
  • Google Cloud Storage 中的 gs://... 或 gcs://... 路径
  • S3 兼容存储中的 s3://... 路径
  • roboflow://workspace/project/version/format 数据集引用
  • ultralytics://username/datasets/slug Ultralytics 平台引用
使用 ?v=<version> 选择特定的 Ultralytics 数据集版本:
Python
1dataset = LuxonisParser(
2    "ultralytics://username/datasets/people?v=3",
3    dataset_name="people",
4).parse()
Roboflow 源需要 ROBOFLOW_API_KEY;Ultralytics 平台源需要 ULTRALYTICS_API_KEY。Google Cloud Storage 和 S3 使用 LuxonisFileSystem 支持的凭据。使用 save_dir 选择远程源在解析前下载的位置。

支持的格式

格式DatasetType 值导入的注释
COCO JSON、FiftyOne 或 Roboflow 布局coco边界框、语义和实例分割、关键点
Pascal VOC XMLvoc边界框
YOLO Darknet TXTdarknet边界框
YOLOv4 PyTorch TXTyolov4边界框
MT YOLOv6yolov6边界框
YOLOv8-v12 边界框yolov8边界框
YOLOv8-v12 实例分割yolov8instancesegmentation实例分割
YOLOv8-v12 关键点yolov8keypoints关键点
Ultralytics NDJSON 检测ultralytics-ndjson边界框
Ultralytics NDJSON 实例分割ultralytics-ndjson-instancesegmentation实例分割
Ultralytics NDJSON 关键点ultralytics-ndjson-keypoints关键点
CreateML JSONcreateml边界框
TensorFlow 对象检测 CSVtfcsv边界框
Unity SOLOsolo边界框、语义和实例分割、关键点
分类目录clsdir分类
FiftyOne 分类fiftyone-classification分类
分割掩码目录segmask语义分割
原生 LDF 导出native原生解析器支持的 LDF 记录
包含类的注释也会填充相应的 LDF 分类目标。对于 YOLOv8-v12 数据,请明确选择边界框、实例分割或关键点数据集类型,因为这些变体可以共享相同的目录结构。

预期目录布局

解析器识别完整的数据集目录,并且对于支持的格式,识别单个拆分目录。验证拆分名称(例如 valid 和 validation)在生成的 LDF 数据集中标准化为 val。

COCO JSON

FiftyOne COCO 导出将媒体保存在 data/ 中,注释保存在 labels.json 中:
Plain Text
1dataset_dir/
2├── train/
3│   ├── data/
4│   │   ├── img1.jpg
5│   │   └── img2.jpg
6│   └── labels.json
7├── validation/
8│   ├── data/
9│   └── labels.json
10└── test/
11    ├── data/
12    └── labels.json
Roboflow COCO 导出将每个拆分的图像保存在 _annotations.coco.json 旁边:
Plain Text
1dataset_dir/
2├── train/
3│   ├── img1.jpg
4│   ├── img2.jpg
5│   └── _annotations.coco.json
6├── valid/
7└── test/

YOLOv8-v12

Roboflow 风格的导出在每个拆分中都使用 images/ 和 labels/:
Plain Text
1dataset_dir/
2├── train/
3│   ├── images/
4│   │   ├── img1.jpg
5│   │   └── img2.jpg
6│   └── labels/
7│       ├── img1.txt
8│       └── img2.txt
9├── valid/
10├── test/
11└── data.yaml
Ultralytics 布局将所有拆分目录分组到顶级 images/ 和 labels/ 目录下:
Plain Text
1dataset_dir/
2├── images/
3│   ├── train/
4│   ├── val/
5│   └── test/
6├── labels/
7│   ├── train/
8│   ├── val/
9│   └── test/
10└── data.yaml

Ultralytics NDJSON

NDJSON 数据集包含一个 .ndjson 清单。它的第一行是带有 class_names 的数据集头;随后的每一行描述一个图像及其拆分和注释。
Plain Text
1dataset_dir/
2├── dataset.ndjson
3├── train/
4├── val/
5└── test/
图像记录可以指向本地文件或远程 URL。仅包含远程图像引用的清单不需要图像目录,您可以将清单文件本身传递给 LuxonisParser。

分类目录

基于拆分的分类数据集为每个类使用一个目录:
Plain Text
1dataset_dir/
2├── train/
3│   ├── car/
4│   │   ├── img1.jpg
5│   │   └── img2.jpg
6│   └── motorcycle/
7├── valid/
8└── test/
扁平分类目录将类目录直接放置在数据集根目录下。解析器为此形式创建随机拆分。还可以存在可选的 info.json 文件。

分割掩码目录

每个 .jpg 图像都有一个匹配的 _mask.png 文件。_classes.csv 将灰度像素值映射到类名:
Plain Text
1dataset_dir/
2├── train/
3│   ├── img1.jpg
4│   ├── img1_mask.png
5│   └── _classes.csv
6├── valid/
7└── test/
Csv
1Pixel Value,Class
20,background
31,car
42,motorcycle

原生 LDF 导出

原生解析器读取 LuxonisDataset.export(..., dataset_type=DatasetType.NATIVE) 生成的布局:
Plain Text
1dataset_dir/
2├── metadata.json
3├── train/
4│   ├── annotations.json
5│   └── images/
6├── val/
7│   ├── annotations.json
8│   └── images/
9└── test/
10    ├── annotations.json
11    └── images/
有关 Pascal VOC、Darknet、YOLOv4、YOLOv6、CreateML、TensorFlow CSV、SOLO、FiftyOne 分类和原生记录的确切布局和解析器特定选项,请参阅 解析器 API 参考。

拆分行为

当源包含拆分目录且未提供覆盖时,其分配将保留。由一个拆分或扁平布局表示的源将使用默认的 80:10:10 比例分为 train、val 和 test。使用总和为 1.0 的浮点比例覆盖分配:
Python
1dataset = parser.parse(
2    split_ratios={"train": 0.7, "val": 0.2, "test": 0.1}
3)
基于比例的拆分会打乱并重新分配所有已解析的样本。整数值请求绝对计数。对于具有现有拆分目录的源,记录将从相应的原始拆分中采样,以便拆分边界保持不变:
Python
1dataset = parser.parse(
2    split_ratios={"train": 1000, "val": 100, "test": 50}
3)
当请求的计数超过该拆分中可用的记录时,将使用所有可用记录。

命令行界面

使用 luxonis_ml data parse 进行相同的工作流程:
Command Line
1luxonis_ml data parse path/to/dataset --name my_dataset
2luxonis_ml data parse path/to/yolo_dataset \
3    --name people_pose \
4    --type yolov8keypoints \
5    --task-name pose
6luxonis_ml data parse path/to/dataset \
7    --train 0.8 \
8    --val 0.1 \
9    --test 0.1
10luxonis_ml data parse path/to/dataset \
11    --train 1000 \
12    --val 100 \
13    --test 50
运行 luxonis_ml data parse --help 以获取存储选择、下载位置、格式选择、警告报告和删除选项。