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

本页目录

  • 概述
  • 加载器输出
  • 标签键和形状
  • 样本元数据
  • 调整大小和颜色空间
  • 增强
  • 内置转换
  • 运行时过滤和远程数据集
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

LuxonisLoader

最后更新

概述

LuxonisLoader 提供对 LuxonisDataset 的一个或多个拆分的索引和可迭代访问。它解析媒体,按任务组装标签,可选地调整图像和标签的大小并进行增强,并为每个样本返回一个 LoaderOutput。在创建加载器之前,数据集必须有拆分。有关拆分创建,请参阅 LuxonisDataset。
Python
1from luxonis_ml.data import LuxonisDataset, LuxonisLoader
2
3dataset = LuxonisDataset("parking_lot")
4loader = LuxonisLoader(dataset, view="train")
5
6sample = loader[0]
7images = sample.images
8labels = sample.labels
9metadata = sample.metadata
view 接受一个拆分名称或一个拆分名称列表:
Python
1loader = LuxonisLoader(dataset, view=["train", "val"])

加载器输出

每个项目都是一个具有三个属性的 LoaderOutput:
属性内容
images将源名称映射到 NumPy 数组的字典。
labels将 "task_name/task_type" 键映射到 NumPy 数组的字典。
metadata存储的样本元数据以及可选的加载器生成的元数据。
单源数据集使用 "image" 作为其源名称。直接使用 sample.image 访问其第一个图像:
Python
1for sample in loader:
2    image = sample.image
3    boxes = sample.labels["detection/boundingbox"]
当不需要元数据时,也可以进行两值解包:
Python
1image_or_images, labels = loader[0]
对于多源记录,image_or_images 是完整的源字典。对于单源记录,它是第一个图像数组。元数据仍然可以通过 loader[0].metadata 获得。

标签键和形状

标签键结合了任务组和注释类型。具有 task_name="detection" 的记录会生成诸如 "detection/boundingbox" 之类的键。如果未提供任务名称,则键以 / 开头,例如 "/classification"。
任务类型输出形状内容
classification(C,)多热类向量。
boundingbox(N, 5)[class, x, y, w, h] 形式的行。
segmentation(C, H, W)通道优先的独热语义掩码。
instance_segmentation(N, H, W)每个实例一个二进制掩码。
keypoints(N, 3 * K)展平的 (x, y, visibility) 三元组。
metadata/<key>值相关一个字段的注释元数据。
设置 exclude_empty_annotations=True 以省略特定样本没有注释的标签键。否则,加载器会为已知数据集任务添加正确形状的空数组。

样本元数据

存储在记录的 sample_metadata 中的值通过 sample.metadata 返回。默认情况下,当 autopopulate_metadata=True 时,加载器还会添加一个 filenames 映射:
Python
1sample.metadata
2# {
3#     "filenames": {"image": "frame_001.jpg"},
4#     "camera": "left",
5#     "frame_id": 1,
6# }
仅返回存储的样本元数据:
Python
1loader = LuxonisLoader(dataset, autopopulate_metadata=False)
启用增强功能时,元数据还包括一个 augmentations 映射,其中包含影响输出的转换及其选定的运行时参数。批处理转换保留有关 batch_augmentation_metadata 下所有贡献样本的信息。

调整大小和颜色空间

传递 height 和 width 以调整每个加载源的大小。keep_aspect_ratio=True 使用信箱调整大小;将其设置为 False 以进行直接调整大小。
Python
1loader = LuxonisLoader(
2    dataset,
3    view="train",
4    height=640,
5    width=640,
6    keep_aspect_ratio=True,
7    color_space="RGB",
8)
color_space 接受 "RGB"、"BGR" 或 "GRAY",默认为 "RGB"。单个值适用于每个源,或者字典可以单独配置源:
Python
1loader = LuxonisLoader(
2    dataset,
3    color_space={
4        "rgb": "RGB",
5        "depth": "GRAY",
6    },
7)

增强

默认的增强引擎使用 Albumentations。传递配置字典列表或包含该列表的 YAML 或 JSON 文件的路径。每个项目支持:
字段描述
nameAlbumentations 转换名称或注册的 Luxonis 转换名称。
params转换构造函数参数。
use_for_resizing将此转换用作管道的调整大小阶段。最多一个项目可以启用它。
apply_on_stagestrain、val 和 test 中的任何一个;默认为 train。
Python
1augmentation_config = [
2    {
3        "name": "HorizontalFlip",
4        "params": {"p": 0.5},
5    },
6    {
7        "name": "RandomBrightnessContrast",
8        "params": {
9            "brightness_limit": 0.15,
10            "contrast_limit": 0.15,
11            "p": 0.3,
12        },
13    },
14    {
15        "name": "Mosaic4",
16        "params": {
17            "height": 640,
18            "width": 640,
19            "p": 0.2,
20        },
21        "apply_on_stages": ["train"],
22    },
23]
24
25loader = LuxonisLoader(
26    dataset,
27    view="train",
28    augmentation_config=augmentation_config,
29    height=640,
30    width=640,
31    seed=42,
32)
当没有转换具有 use_for_resizing 时,引擎会根据 keep_aspect_ratio 插入直接或信箱调整大小。当概率调整大小转换未应用时,它会回退到默认调整大小。转换按行为分组并按此顺序应用:
  1. 批处理转换
  2. 空间转换
  3. 其他自定义转换
  4. 仅像素转换
因此,配置列表顺序不能保证在这些组之间。

内置转换

LuxonisML 为 Albumentations 引擎添加了几个转换:
  • LetterboxResize 用于保持宽高比的调整大小和填充
  • CutMix 用于将两个样本修补在一起
  • MixUp 用于混合两个样本
  • Mosaic4 用于以 2x2 马赛克形式组合四个样本
  • HorizontalSymmetricKeypointsFlip、VerticalSymmetricKeypointsFlip 和 TransposeSymmetricKeypoints 用于同时交换语义关键点对的转换
批处理转换增加了生成一个输出所需的源样本数量。例如,MixUp 使用两个样本,Mosaic4 使用四个。将它们组合起来,每个增强输出需要八个源样本。有关自定义转换注册、目标处理、转换参数和增强来源,请参阅 增强 API 参考。

运行时过滤和远程数据集

常见的加载器选项包括:
  • filter_task_names=[...] 以包含选定的任务组
  • keep_categorical_as_strings=True 以保留分类元数据而不是使用其整数编码
  • min_bbox_visibility 以要求增强后框的可见部分
  • bbox_area_threshold 以丢弃非常小的归一化框及其相关标签
  • seed 以使随机增强选择可重现
  • update_mode="all" 或 "missing" 以控制远程媒体同步
Python
1loader = LuxonisLoader(
2    dataset,
3    view="train",
4    filter_task_names=["detection"],
5    exclude_empty_annotations=True,
6    keep_categorical_as_strings=True,
7    update_mode="missing",
8)
对于远程数据集,加载器初始化时会刷新注释和元数据。update_mode 默认为 "all";将其设置为 "missing" 以仅下载无法在本地解析的媒体。有关完整的构造函数和输出契约,请参阅 加载器 API 参考。