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

本页目录

  • 基本用法
  • 构造函数选项
  • 标签键
  • 输出布局
  • 样本元数据
  • 运行时选项
  • 子页面
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
Python API: luxonis_ml.data.loadersLDF 样本的数据集加载器。此包负责运行时样本访问。LuxonisLoader 读取一个或多个数据集拆分,解析媒体路径,按任务键组装标签,可选地应用增强功能,并以适合训练管道的形状返回数据。目录

基本用法

Python
1from luxonis_ml.data import LuxonisDataset, LuxonisLoader
2
3dataset = LuxonisDataset("parking_lot")
4loader = LuxonisLoader(dataset, view="train")
5
6sample = loader[0]
7
8images = sample.images
9labels = sample.labels
10metadata = sample.metadata
LuxonisLoader 实现了索引访问和迭代。返回的值始终是 LoaderOutput。LoaderOutput.images 将源名称映射到数组。单源数据集使用常规的 "image" 源名称;多源数据集保留记录 "files" 映射中的名称。LoaderOutput.metadata 包含来自 DatasetRecord.sample_metadata 的记录级元数据。默认情况下,它还包括一个从源名称到加载文件基本名称的 "filenames" 映射。当代码只需要输入和标签时,传统的两值解包仍然有效:
Python
1image_or_images, labels = loader[0]
元数据不会通过元组解包产生。通过 loader[0].metadata 访问它。

构造函数选项

LuxonisLoader 在运行时配置,不改变存储的数据集状态。常见选项包括:
  • view 用于加载一个拆分或拆分列表。
  • augmentation_engine 和 augmentation_config 用于启用增强功能。
  • height、width 和 keep_aspect_ratio 用于定义增强引擎所需的调整大小行为。
  • color_space 用于请求全局或按源名称请求 "RGB"、"BGR" 或 "GRAY" 输出。
  • seed 用于可重现的随机增强。
  • exclude_empty_annotations 用于省略空标签。
  • keep_categorical_as_strings 用于保留分类元数据值。
  • update_mode 用于控制远程数据集的媒体同步。
  • filter_task_names 用于仅加载选定的任务组。
  • autopopulate_metadata 用于在 LoaderOutput.metadata 中包含自动元数据,例如源文件名。
加载远程数据集时,注释和元数据会刷新。媒体文件根据 UpdateMode 下载:ALL 覆盖本地媒体,MISSING 仅下载本地无法解析的媒体。

标签键

labels 字典以 "task_name/task_type" 为键。如果数据集是在没有任务名称的情况下创建的,则默认任务名称为空字符串,键以 "/" 开头。元数据标签使用 "task_name/metadata/key",因此每个元数据字段都可以独立使用。样本元数据不使用标签键。它通过 LoaderOutput.metadata 单独返回:
Python
1sample = loader[0]
2print(sample.metadata)
3
4# {
5#     "filenames": {"image": "frame_001.jpg"},
6#     "record_id": 123,
7#     "camera": "left",
8# }
传递 autopopulate_metadata=False 以仅返回存储的元数据:
Python
1loader = LuxonisLoader(dataset, autopopulate_metadata=False)
2metadata = loader[0].metadata
增强输出还带有一个 "augmentations" 映射,从配置的增强路径到引擎选择的运行时参数。与 "filenames" 不同,无论 autopopulate_metadata 如何,它都会被添加,因为它描述的是返回的数组而不是数据集记录:
Python
1{
2    "record_id": 123,
3    "augmentations": {
4        "HorizontalFlip": {},
5        "OneOf/RandomBrightnessContrast": {"alpha": 1.02, "beta": -0.03},
6    },
7}
这两个键都是保留的。定义其中一个的记录保留其自己的值,加载器会发出警告而不是覆盖它。当批处理增强组合多个样本时,输入样本的元数据会保留在 "batch_augmentation_metadata" 中:
Python
1{
2    "record_id": 123,
3
4    "batch_augmentation_metadata": [
5        {
6            "input_index": 0,
7            "sample_metadata": {"record_id": 123},
8        },
9        {
10            "input_index": 1,
11            "sample_metadata": {"record_id": 456},
12        },
13    ],
14}
注释元数据不同: annotation["metadata"] 下的值被转换为标签任务,例如 "detection/metadata/weather"。

输出布局

常见标签布局
任务类型形状或结构含义
classification(C)独热类向量。
boundingbox(N, 5)行是 [c, x, y, w, h]。
segmentation(C, H, W)通道优先布局的独热语义掩码。
instance_segmentation(N, H, W)每个实例一个二进制掩码。
keypoints(N, 3K)展平的 (x, y, v) 关键点三元组。
metadata原始值结构。按元数据字段名称键入的值。

样本元数据

记录级元数据 来自 DatasetRecord.sample_metadata,并作为 LoaderOutput.metadata 提供。
Python
1sample = loader[0]
2
3sample.metadata
4# {
5#     "filenames": {"image": "frame_001.jpg"},
6#     "record_id": 123,
7#     "camera": "left",
8# }
传递 autopopulate_metadata=False 以仅返回存储的元数据:
Python
1loader = LuxonisLoader(dataset, autopopulate_metadata=False)
2metadata = loader[0].metadata
增强输出还带有一个 "augmentations" 映射,从配置的增强路径到引擎选择的运行时参数。与 "filenames" 不同,无论 autopopulate_metadata 如何,它都会被添加,因为它描述的是返回的数组而不是数据集记录:
Python
1{
2    "record_id": 123,
3    "augmentations": {
4        "HorizontalFlip": {},
5        "OneOf/RandomBrightnessContrast": {"alpha": 1.02, "beta": -0.03},
6    },
7}
这两个键都是保留的。定义其中一个的记录保留其自己的值,加载器会发出警告而不是覆盖它。当批处理增强组合多个样本时,输入样本的元数据会保留在 "batch_augmentation_metadata" 中:
Python
1{
2    "record_id": 123,
3
4    "batch_augmentation_metadata": [
5        {
6            "input_index": 0,
7            "sample_metadata": {"record_id": 123},
8        },
9        {
10            "input_index": 1,
11            "sample_metadata": {"record_id": 456},
12        },
13    ],
14}
注释元数据不同: annotation["metadata"] 下的值被转换为标签任务,例如 "detection/metadata/weather"。

运行时选项

LuxonisLoader 拥有与数据集存储有意分离的运行时关注点:
  • 通过 view 选择的视图;
  • 通过 color_space 进行颜色空间转换;
  • 通过 height 和 width 进行可选调整大小;
  • 通过 keep_aspect_ratio 保持纵横比;
  • 通过 augmentation_engine 和 augmentation_config 构建增强引擎;
  • 通过 update_mode 进行远程媒体同步;
  • 通过 exclude_empty_annotations 过滤空注释;
  • 通过 keep_categorical_as_strings 进行元数据类别编码;
  • 通过 filter_task_names 进行任务过滤。
Python
1loader = LuxonisLoader(
2    dataset,
3    view=["train", "val"],
4    height=640,
5    width=640,
6    keep_aspect_ratio=True,
7    color_space="RGB",
8    filter_task_names=["detection"],
9    exclude_empty_annotations=True,
10)

子页面