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

本页目录

  • 记录模型
  • 坐标和实例
  • 分类
  • 边界框
  • 关键点
  • 分割
  • 实例分割
  • 数组
  • 元数据和类别
  • 类
  • Annotation
  • ArrayAnnotation
  • BBoxAnnotation
  • Category
  • ClassificationAnnotation
  • DatasetRecord
  • Detection
  • InstanceSegmentationAnnotation
  • KeypointAnnotation
  • SegmentationAnnotation
  • 函数
  • load_annotation
  • 属性
  • KeypointVisibility
  • NormalizedFloat
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
Python API: luxonis_ml.ldf.annotationLuxonis 数据格式数据集使用的注释模式。此模块拥有 LuxonisDataset.add 接受并由特定格式解析器生成的记录和注释负载契约。这些模式以 pydantic 模型 的形式实现,因此输入字典在写入 LDF parquet 分片之前会经过验证和规范化。目录

记录模型

数据集摄取从 DatasetRecord 开始。记录指向媒体,可选地分配任务名称,并可选地携带由 Detection 验证的注释负载。单源记录使用 "file":
JSON
1{
2  "file": "path/to/image.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": "car",
13    "boundingbox": {
14      "x": 0.1,
15      "y": 0.2,
16      "w": 0.3,
17      "h": 0.4
18    }
19  }
20}
多源记录使用 "files":
JSON
1{
2  "files": {
3    "rgb": "path/to/rgb.png",
4    "depth": "path/to/depth.png"
5  },
6  "task_name": "detection",
7
8  "sample_metadata": {
9    "sequence": "loading_dock_07",
10    "frame": 42
11  },
12
13  "annotation": {
14    "class": "person",
15    "boundingbox": {
16      "x": 0.1,
17      "y": 0.1,
18      "w": 0.3,
19      "h": 0.4
20    }
21  }
22}
记录级元数据位于 sample_metadata 中。它描述了整个样本:捕获 ID、UI 标签、源系统标识符、相机名称、帧号、时间戳或应随样本一起传输的其他值。LuxonisLoader 通过 LoaderOutput.metadata 公开它。注释元数据位于 Detection.metadata 中。它被转换为标签任务,例如 "detection/metadata/weather",旨在由训练代码作为注释标签使用。前端注意事项: sample_metadata 是样本数据,而不是注释目标。任务名称将应一起使用的注释分组。如果未提供 task_name,则使用空字符串 ""。因此,加载器标签键遵循 "task_name/task_type",默认任务键以 "/" 开头。

坐标和实例

空间注释使用图像归一化坐标。对于宽度为 W、高度为 H 的图像,绝对点 (x, y) 存储为 (x ⁄ W, y ⁄ H)。当多个注释类型描述同一物理对象时,使用相同的 instance_id,以便即使作为单独的记录生成,边界框、关键点和实例掩码也可以关联起来。Detection.scale_to_boxes 支持框相对注释。启用后,关键点将相对于边界框进行解释,并在存储前重新缩放到图像归一化坐标。

分类

分类将类分配给整个样本或实例:
Python
1{"class": "vehicle"}
分类在内部表示为 classification 任务类型。任何提供类名的检测都会贡献一个分类目标,即使同一检测也包含框、掩码、关键点、数组或元数据。加载时,类通常作为形状为 (C) 的独热向量返回。

边界框

BBoxAnnotation 存储归一化的 xywh 框,其中 x 和 y 是左上角,w 和 h 是宽度和高度:
Python
1{
2    "class": "car",
3    "instance_id": 17,
4    "boundingbox": {
5        "x": 0.20,
6        "y": 0.10,
7        "w": 0.35,
8        "h": 0.25,
9    },
10}
加载器输出将框组合成形状为 (N, 5) 的数组,行格式为 [c, x, y, w, h],其中 c 是类索引。

关键点

KeypointAnnotation 将关键点存储为 (x, y, visibility) 三元组。坐标已归一化,可见性遵循 COCO 约定:
  • 0:不可见或未标记。
  • 1:被遮挡。
  • 2:可见。
Python
1{
2    "class": "car",
3    "instance_id": 17,
4    "keypoints": {
5        "keypoints": [
6            (0.10, 0.20, 2),
7            (0.30, 0.40, 1),
8        ],
9    },
10}
对于 K 个关键点和 N 个实例,加载器输出使用形状 (N, 3⋅K)。

分割

SegmentationAnnotation 支持多边形、二值掩码和行程编码输入。折线分割存储归一化的多边形点。最后一个点隐式连接到第一个点:
Python
1{
2    "class": "road",
3    "segmentation": {
4        "height": 720,
5        "width": 1280,
6        "points": [
7            (0.10, 0.10),
8            (0.90, 0.10),
9            (0.80, 0.80),
10            (0.20, 0.80),
11        ],
12    },
13}
二值掩码是二维数组,其中前景像素为 1,背景像素为 0:
Python
1{
2    "class": "road",
3    "segmentation": {
4        "mask": binary_mask,
5    },
6}
行程编码掩码使用 COCO RLE。counts 值可以是未压缩的整数列表或压缩的字节字符串:
Python
1{
2    "class": "road",
3    "segmentation": {
4        "height": 720,
5        "width": 1280,
6        "counts": [120, 8, 200, 12],
7    },
8}
语义分割加载器输出使用通道优先掩码,形状为 (C, H, W)。

实例分割

InstanceSegmentationAnnotation 使用与语义分割相同的掩码编码,但每个实例存储一个掩码。检测可以同时包含边界框和实例掩码:
Python
1{
2    "class": "car",
3    "instance_id": 17,
4    "boundingbox": {"x": 0.20, "y": 0.10, "w": 0.35, "h": 0.25},
5    "instance_segmentation": {
6        "height": 720,
7        "width": 1280,
8        "points": [
9            (0.20, 0.10),
10            (0.55, 0.10),
11            (0.55, 0.35),
12            (0.20, 0.35),
13        ],
14    },
15}
实例掩码加载器输出使用形状 (N, H, W)。

数组

ArrayAnnotation 引用与样本同步的任意 .npy 数据:
Python
1{
2    "class": "embedding",
3    "array": {
4        "path": "path/to/embedding.npy",
5    },
6}
数组对于特定于模态的目标或应与数据集一起存储但不适合标准空间模式的辅助数据很有用。

元数据和类别

元数据存储灵活的键值对。使用 Category 将字符串标记为分类元数据而不是自由格式文本:
Python
1from luxonis_ml.ldf import Category
2
3{
4    "metadata": {
5        "text": "ABC-123",
6        "text_color": Category("white"),
7        "track_id": 42,
8    },
9}
分类元数据可以由 LuxonisLoader 编码为整数,或者在加载器配置请求时保留为字符串。OCR 注释通常存储识别的文本和分类视觉属性:
Python
1{
2    "metadata": {
3        "text": "ABC-123",
4        "color": Category("red"),
5    },
6}
LuxonisTrain 的 OCR 头 使用此元数据。嵌入和重识别数据集通常存储标识符或其他查找键:
Python
1{
2    "metadata": {
3        "id": 42,
4        "color": Category("red"),
5    },
6}
LuxonisTrain 的 嵌入头 使用此元数据。

类

Annotation

注释的基类。

方法

combine_to_numpy
Python
1def combine_to_numpy(annotations: list[Annotation], classes: list[int], n_classes: int) -> np.ndarray:
将多个注释组合成一个 numpy 数组。参数
  • annotations (list[Annotation]): 要组合的注释。
  • classes (list[int]): 与每个注释对应的类 ID。
  • n_classes (int): 类的总数。
返回
  • np.ndarray: 组合的注释表示。

ArrayAnnotation

由数组文件支持的自定义注释。此注释的所有实例必须具有相同的形状。

方法

combine_to_numpy
Python
1def combine_to_numpy(annotations: list[ArrayAnnotation], classes: list[int], n_classes: int) -> np.ndarray:
将数组注释组合成实例类索引数组。参数
  • annotations (list[ArrayAnnotation]): 要组合的数组注释。
  • classes (list[int]): 与注释关联的类 ID。
  • n_classes (int): 已知类的总数。
返回
  • np.ndarray: 形状为 (N, C, …) 的组合数组,其中 C 是类的数量,N 是实例的数量。
to_numpy
Python
1def to_numpy(self) -> np.ndarray:
从文件路径加载数组。

属性

path
保存为 .npy 文件的数组路径。

BBoxAnnotation

边界框注释。值根据图像大小进行归一化。

方法

combine_to_numpy
Python
1def combine_to_numpy(annotations: list[BBoxAnnotation], classes: list[int], n_classes: int | None = None) -> np.ndarray:
将边界框注释与类 ID 组合成行。参数
  • annotations (list[BBoxAnnotation]): 要组合的边界框注释。
  • classes (list[int]): 与注释关联的类 ID。
  • n_classes (int | None): 未使用的类计数,为 API 兼容性保留。
返回
  • np.ndarray: 形状为 (N, 5) 的数组,其中 N 是边界框注释的数量,每行格式为 [class_id, x, y, w, h]。
to_numpy
Python
1def to_numpy(class_id: int) -> np.ndarray:
将边界框注释转换为行格式。参数
  • class_id (int): 注释的数字类 ID。
返回
  • np.ndarray: 形状为 (5, ) 的数组,格式为 [class_id, x, y, w, h]。

属性

h
归一化的边界框高度。
w
归一化的边界框宽度。
x
归一化的左上角 x 坐标。
y
归一化的左上角 y 坐标。

Category

元数据值的类别标签。此类用于区分分类元数据值和自由格式字符串值。

ClassificationAnnotation

分类任务的虚拟包装注释。分类任务没有显式注释字段,而是将检测的类名解释为类标签,并解释为属于整个图像。多个分类注释被多热编码成一个向量,其长度等于类的总数。

方法

combine_to_numpy
Python
1def combine_to_numpy(annotations: list[ClassificationAnnotation], classes: list[int], n_classes: int) -> np.ndarray:
将分类注释组合成多热标签向量。参数
  • annotations (list[ClassificationAnnotation]): 要组合的分类注释。
  • classes (list[int]): 与注释关联的类 ID。
  • n_classes (int): 已知类的总数。
返回
  • np.ndarray: 形状为 (N, ) 的多热类标签向量,其中 N 是类的总数。

DatasetRecord

包含文件路径和可选注释的数据集记录。记录是 LuxonisDataset.add 的摄取单元。它可以通过 file 指向一个媒体源,或者通过 files 指向多个同步源,但不能同时指向两者——同时传递两者是错误的,以前 files 会被静默丢弃以支持 file。sample_metadata 存储记录级元数据。它由原生导入/导出保留,并由 LuxonisLoader 作为 LoaderOutput.metadata 返回。它有意与 Detection.metadata 分开,后者创建注释元数据标签任务。

方法

decode_metadata
Python
1def decode_metadata(value: Any) -> Params:
将序列化的记录元数据解码为字典。参数
  • value (Any): 元数据字典、序列化的 JSON 对象、空字符串或 None。
返回
  • Params: 当值为字典式 JSON 对象时解码的元数据;否则为空字典。
to_parquet_rows
Python
1def to_parquet_rows(self) -> Iterable[ParquetRecord]:
递归地将数据集记录及其所有注释和子注释转换为 parquet 行。生成
  • 注释数据行。
validate_files
Python
1def validate_files(values: Any) -> Any:
validate_task_name
Python
1def validate_task_name(values: Any) -> Any:
validate_task_name_valid_identifier
Python
1def validate_task_name_valid_identifier(self) -> Self:

属性

all_file_paths
与数据集记录关联的所有文件路径。
annotation
与数据集记录关联的可选检测。
file
数据集记录的文件路径。当数据集记录只有一个文件时,提供此属性是为了方便。引发
  • ValueError: 如果数据集记录有零个或多个文件。
files
按源名称键入的文件路径。
sample_metadata
整个样本的类似 JSON 的元数据。值应可 JSON 序列化。缺失的元数据默认为空字典。
task_name
记录所属任务的名称。

Detection

包含一个对象的注释和元数据的检测记录。它描述了图像中单个检测到的对象,并且可以包含各种类型的注释和元数据以及用于分层注释的嵌套子检测。当启用 scale_to_boxes 时,关键点将相对于边界框进行解释,并重新缩放到图像归一化坐标。

方法

get_task_types
Python
1def get_task_types(self) -> set[str]:
获取与此检测关联的所有任务类型。返回
  • set[str]: 注释任务类型和元数据键。

属性

array
可选数组注释。
boundingbox
可选边界框注释。
class_name
检测的可选类名。输入数据可以使用 "class" 别名。
instance_id
实例标识符。如果未提供,实例 ID 将对应于检测添加到数据集的顺序。请注意,如果单独添加单个检测类型并且在记录之间顺序不一致,这可能会导致实例注释的配对不正确:
Pycon
1# 如果不指定 `instance_id`,
2# 边界框和关键点注释将
3# 无法正确配对,因为它们是单独添加的
4# 检测,并且顺序不同。
5def generator():
6    yield {
7        "file": ...,
8        "annotation": {"boundingbox": bbox1},
9    }
10    yield {
11        "file": ...,
12        "annotation": {"keypoints": kpts2},
13    }
14    yield {
15        "file": ...,
16        "annotation": {"boundingbox": bbox2},
17    }
18    yield {
19        "file": ...,
20        "annotation": {"keypoints": kpts1},
21    }
建议尽可能提供实例 ID,并避免在单独的检测中单独生成注释:
Pycon
1# 这是正确的方法
2def generator():
3    yield {
4        "file": ...,
5        "annotation": {
6            "instance_id": 1,
7            "boundingbox": bbox1
8            "keypoints": kpts1,
9        },
10    }
11    yield {
12        "file": ...,
13        "annotation": {
14            "instance_id": 2,
15            "boundingbox": bbox2
16            "keypoints": kpts2,
17        },
18    }
instance_segmentation
可选实例分割注释。
keypoints
可选关键点注释。
metadata
按元数据名称键入的元数据值。
scale_to_boxes
关键点坐标是否应从边界框相对坐标重新缩放。
segmentation
可选语义分割注释。
sub_detections
按子检测名称键入的嵌套检测。

InstanceSegmentationAnnotation

实例分割注释。SegmentationAnnotation 的子类,用于区分实例分割注释和语义分割注释。单个实例分割注释的数组表示与语义分割注释的数组表示相同,但多个实例分割注释组合成形状为 (N, H, W) 的数组,其中前导维度 N 对应于实例注释的数量,而不是语义分割中的类数量。

方法

combine_to_numpy
Python
1def combine_to_numpy(annotations: list[InstanceSegmentationAnnotation], classes: list[int] | None = None, n_classes: int | None = None) -> np.ndarray:
将实例分割注释组合成实例掩码。参数
  • annotations (list[InstanceSegmentationAnnotation]): 要组合的实例分割注释。
  • classes (list[int] | None): 未使用的类 ID,为 API 兼容性保留。
  • n_classes (int | None): 未使用的类计数,为 API 兼容性保留。
返回
  • np.ndarray: 形状为 (N, H, W) 的组合实例分割掩码,其中 N 是实例的数量。

KeypointAnnotation

关键点注释。坐标根据图像大小归一化到 [0, 1] 范围。

方法

combine_to_numpy
Python
1def combine_to_numpy(annotations: list[KeypointAnnotation], classes: list[int] | None = None, n_classes: int | None = None) -> np.ndarray:
将关键点注释组合成扁平的关键点行。参数
  • annotations (list[KeypointAnnotation]): 要组合的关键点注释。
  • classes (list[int] | None): 未使用的类 ID,为 API 兼容性保留。
  • n_classes (int | None): 未使用的类计数,为 API 兼容性保留。
返回
  • np.ndarray: 形状为 (N, 3K) 的数组,其中 N 是关键点注释的数量,K 是每个注释的关键点数量。扁平的关键点行。每行包含关键点坐标和可见性,格式为 [x1, y1, v1, x2, y2, v2, …],其中 (xi, yi, vi) 是第 i 个关键点的坐标和可见性。
to_numpy
Python
1def to_numpy(self) -> np.ndarray:
将关键点注释转换为扁平的行格式。返回
  • np.ndarray: 形状为 (3K, ) 的数组,其中 K 是关键点的数量。数组的格式为 [x1, y1, v1, x2, y2, v2, …],其中 (xi, yi, vi) 是第 i 个关键点的坐标和可见性。

属性

keypoints
(x, y, visibility) 格式的关键点。可见性遵循 COCO 约定:
  • 0:不可见或未标记。
  • 1:被遮挡。
  • 2:可见。

SegmentationAnnotation

行程编码分割掩码。编码掩码使用 COCO 风格的 行程编码。此类支持从多种输入格式解析分割掩码:
  • 直接作为计数列表或字节字符串的行程编码 (RLE)。
  • 作为 numpy 数组或保存为 .npy 或 .png 文件的二值掩码数组。
  • 作为归一化点列表以及图像宽度和高度的多边形。

方法

combine_to_numpy
Python
1def combine_to_numpy(annotations: list[SegmentationAnnotation], classes: list[int], n_classes: int) -> np.ndarray:
将分割注释组合成类掩码。参数
  • annotations (list[SegmentationAnnotation]): 要组合的分割注释。
  • classes (list[int]): 与注释关联的类 ID。
  • n_classes (int): 已知类的总数。
返回
  • np.ndarray: 形状为 (C, H, W) 的组合语义分割掩码。
to_numpy
Python
1def to_numpy(self) -> np.ndarray:
将分割注释转换为二值掩码。返回
  • np.ndarray: 形状为 (H, W) 的二值掩码。

属性

counts
行程编码掩码数据。
height
分割掩码的高度。
width
分割掩码的宽度。

函数

load_annotation

Python
1def load_annotation(task_type: Literal['classification', 'boundingbox', 'keypoints', 'segmentation', 'instance_segmentation', 'array'], data: Mapping[str, Any]) -> Annotation:
从序列化数据加载注释。参数
  • task_type (Literal['classification', 'boundingbox', 'keypoints', 'segmentation', 'instance_segmentation', 'array']): 注释任务的类型。
  • data (Mapping[str, Any]): 序列化的注释数据。
返回
  • Annotation: 根据任务类型,适当的 Annotation 子类的实例。
引发
  • ValueError: 如果任务类型未知。

属性

KeypointVisibility

遵循 COCO 约定的关键点可见性。这些值表示图像中关键点的可见性:
  • 0:不可见或未标记。
  • 1:被遮挡。
  • 2:可见。

NormalizedFloat

归一化到 [0, 1] 范围的浮点值。