annotation
最后更新
luxonis_ml.ldf.annotationLuxonis 数据格式数据集使用的注释模式。此模块拥有 LuxonisDataset.add 接受并由特定格式解析器生成的记录和注释负载契约。这些模式以 pydantic 模型 的形式实现,因此输入字典在写入 LDF parquet 分片之前会经过验证和规范化。目录记录模型
"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",默认任务键以 "/" 开头。坐标和实例
instance_id,以便即使作为单独的记录生成,边界框、关键点和实例掩码也可以关联起来。警告
如果省略
instance_id 并且相关注释类型在单独的记录中生成,则关联将回退到插入顺序。这仅在每个记录都一致发出时才可靠。分类
Python
1{"class": "vehicle"}classification 任务类型。任何提供类名的检测都会贡献一个分类目标,即使同一检测也包含框、掩码、关键点、数组或元数据。加载时,类通常作为形状为 (C) 的独热向量返回。边界框
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}关键点
(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}分割
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}Python
1{
2 "class": "road",
3 "segmentation": {
4 "mask": binary_mask,
5 },
6}counts 值可以是未压缩的整数列表或压缩的字节字符串:Python
1{
2 "class": "road",
3 "segmentation": {
4 "height": 720,
5 "width": 1280,
6 "counts": [120, 8, 200, 12],
7 },
8}注意
Numpy 掩码在内部转换为 RLE。RLE 输入主要用于与已以该格式存储掩码的数据集兼容。
实例分割
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}数组
.npy 数据:Python
1{
2 "class": "embedding",
3 "array": {
4 "path": "path/to/embedding.npy",
5 },
6}元数据和类别
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}Python
1{
2 "metadata": {
3 "text": "ABC-123",
4 "color": Category("red"),
5 },
6}Python
1{
2 "metadata": {
3 "id": 42,
4 "color": Category("red"),
5 },
6}重要
元数据和数组没有通用的几何语义。内置增强功能可以丢弃与离开图像的框相关联的值,但除非自定义增强功能明确处理它们,否则任意值将保持不变。
类
Annotation
方法
combine_to_numpy
Python
1def combine_to_numpy(annotations: list[Annotation], classes: list[int], n_classes: int) -> np.ndarray: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: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
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
file 指向一个媒体源,或者通过 files 指向多个同步源,但不能同时指向两者——同时传递两者是错误的,以前 files 会被静默丢弃以支持 file。sample_metadata 存储记录级元数据。它由原生导入/导出保留,并由 LuxonisLoader 作为 LoaderOutput.metadata 返回。它有意与 Detection.metadata 分开,后者创建注释元数据标签任务。示例
JSON
1{
2 "file": "images/frame_001.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": "person",
13 "boundingbox": {
14 "x": 0.1,
15 "y": 0.2,
16 "w": 0.3,
17 "h": 0.4
18 }
19 }
20}方法
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]:- 注释数据行。
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
已弃用
自 0.9.0 版起已弃用:请改用
list(record.files.values())。annotation
file
ValueError: 如果数据集记录有零个或多个文件。
files
sample_metadata
task_name
Detection
scale_to_boxes 时,关键点将相对于边界框进行解释,并重新缩放到图像归一化坐标。示例
Pycon
1>>> detection = Detection(
2... class_name="person",
3... instance_id=1,
4... metadata={
5... "category": Category("adult"),
6... },
7... boundingbox={
8... "x": 0.1,
9... "y": 0.2,
10... "w": 0.3,
11... "h": 0.4,
12... },
13... instance_segmentation={
14... "mask": np.array([[0, 1], [1, 0]]),
15... },
16... sub_detections={
17... "face": {
18... "class_name": "face",
19... "boundingbox": {
20... "x": 0.2,
21... "y": 0.3,
22... "w": 0.1,
23... "h": 0.1,
24... },
25... "keypoints": {
26... "keypoints": [
27... (0.25, 0.35, 2), # 左眼
28... (0.3, 0.35, 2), # 右眼
29... ],
30... },
31... "metadata": {
32... "expression": Category("happy"),
33... "eye_color": Category("blue"),
34... },
35... },
36... },
37... )方法
get_task_types
Python
1def get_task_types(self) -> set[str]:示例
Pycon
1>>> detection = Detection(
2... class_name="cat",
3... boundingbox=BBoxAnnotation(x=0.1, y=0.2, w=0.3, h=0.4),
4... metadata={"color": "black"},
5... )
6>>> sorted(detection.get_task_types())
7['boundingbox', 'classification', 'metadata/color']set[str]: 注释任务类型和元数据键。
属性
array
boundingbox
class_name
"class" 别名。instance_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 }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
方法
combine_to_numpy
Python
1def combine_to_numpy(annotations: list[InstanceSegmentationAnnotation], classes: list[int] | None = None, n_classes: int | None = None) -> np.ndarray:注意
与语义分割相反,允许重叠注释,并且不以任何方式解决。一个像素可以属于多个实例,并且在它所属的每个实例掩码中都将被标记为 1。
annotations(list[InstanceSegmentationAnnotation]): 要组合的实例分割注释。classes(list[int] | None): 未使用的类 ID,为 API 兼容性保留。n_classes(int | None): 未使用的类计数,为 API 兼容性保留。
np.ndarray: 形状为 (N, H, W) 的组合实例分割掩码,其中 N 是实例的数量。
KeypointAnnotation
方法
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
- 直接作为计数列表或字节字符串的行程编码 (RLE)。
- 作为 numpy 数组或保存为
.npy或.png文件的二值掩码数组。 - 作为归一化点列表以及图像宽度和高度的多边形。
示例
Pycon
1>>> rle = SegmentationAnnotation(height=4, width=4, counts=b"11213ON0")
2>>> mask = SegmentationAnnotation(
3... mask=np.array(
4... [
5... [0, 1, 0, 0],
6... [1, 1, 0, 0],
7... [0, 0, 0, 0],
8... [0, 0, 1, 1],
9... ]
10... )
11... )
12>>> np.array_equal(rle.to_numpy(), mask.to_numpy())
13True注意
当将 RLE 作为计数列表而不是编码字节提供时,请确保计数遵循 FORTRAN(列主序)顺序,如 COCO RLE 格式所期望的那样。计数在背景运行和前景运行之间交替,第一个计数始终是背景运行。如果掩码以前景像素开头,则第一个计数为 0。
方法
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
- 0:不可见或未标记。
- 1:被遮挡。
- 2:可见。