# annotation

Python API: `luxonis_ml.ldf.annotation`

Luxonis 数据格式数据集使用的注释模式。

此模块拥有
[LuxonisDataset.add](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
接受并由特定格式解析器生成的记录和注释负载契约。这些模式以 [pydantic 模型](https://pydantic.dev/docs/validation/latest/concepts/models/) 的形式实现，因此输入字典在写入 LDF
parquet 分片之前会经过验证和规范化。

目录

 * [记录模型](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
 * [坐标和实例](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
 * [分类](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
 * [边界框](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
 * [关键点](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
 * [分割](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
 * [实例分割](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
 * [数组](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
 * [元数据和类别](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)

## 记录模型

数据集摄取从
[DatasetRecord](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
开始。记录指向媒体，可选地分配任务名称，并可选地携带由
[Detection](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
验证的注释负载。

单源记录使用 `"file"`：

```json
{
  "file": "path/to/image.jpg",
  "task_name": "detection",

  "sample_metadata": {
    "record_id": 123,
    "camera": "left",
    "tags": ["night", "warehouse"]
  },

  "annotation": {
    "class": "car",
    "boundingbox": {
      "x": 0.1,
      "y": 0.2,
      "w": 0.3,
      "h": 0.4
    }
  }
}
```

多源记录使用 `"files"`：

```json
{
  "files": {
    "rgb": "path/to/rgb.png",
    "depth": "path/to/depth.png"
  },
  "task_name": "detection",

  "sample_metadata": {
    "sequence": "loading_dock_07",
    "frame": 42
  },

  "annotation": {
    "class": "person",
    "boundingbox": {
      "x": 0.1,
      "y": 0.1,
      "w": 0.3,
      "h": 0.4
    }
  }
}
```

记录级元数据位于 `sample_metadata` 中。它描述了整个样本：捕获 ID、UI
标签、源系统标识符、相机名称、帧号、时间戳或应随样本一起传输的其他值。[LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
通过
[LoaderOutput.metadata](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/typing.md)
公开它。

注释元数据位于
[Detection.metadata](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
中。它被转换为标签任务，例如 `"detection/metadata/weather"`，旨在由训练代码作为注释标签使用。

前端注意事项： `sample_metadata` 是样本数据，而不是注释目标。

任务名称将应一起使用的注释分组。如果未提供 `task_name`，则使用空字符串 `""`。因此，加载器标签键遵循 `"task_name/task_type"`，默认任务键以 `"/"` 开头。

## 坐标和实例

空间注释使用图像归一化坐标。对于宽度为 W、高度为 H 的图像，绝对点 (x, y) 存储为 (x ⁄ W, y ⁄ H)。

当多个注释类型描述同一物理对象时，使用相同的 `instance_id`，以便即使作为单独的记录生成，边界框、关键点和实例掩码也可以关联起来。

> **警告**
> 如果省略 `instance_id` 并且相关注释类型在单独的记录中生成，则关联将回退到插入顺序。这仅在每个记录都一致发出时才可靠。

[Detection.scale_to_boxes](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
支持框相对注释。启用后，关键点将相对于边界框进行解释，并在存储前重新缩放到图像归一化坐标。

## 分类

分类将类分配给整个样本或实例：

```python
{"class": "vehicle"}
```

分类在内部表示为 `classification` 任务类型。任何提供类名的检测都会贡献一个分类目标，即使同一检测也包含框、掩码、关键点、数组或元数据。加载时，类通常作为形状为 (C) 的独热向量返回。

## 边界框

[BBoxAnnotation](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
存储归一化的 `xywh` 框，其中 `x` 和 `y` 是左上角，`w` 和 `h` 是宽度和高度：

```python
{
    "class": "car",
    "instance_id": 17,
    "boundingbox": {
        "x": 0.20,
        "y": 0.10,
        "w": 0.35,
        "h": 0.25,
    },
}
```

加载器输出将框组合成形状为 (N, 5) 的数组，行格式为 [c, x, y, w, h]，其中 c 是类索引。

## 关键点

[KeypointAnnotation](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
将关键点存储为 `(x, y, visibility)` 三元组。坐标已归一化，可见性遵循 COCO 约定：

 * 0：不可见或未标记。
 * 1：被遮挡。
 * 2：可见。

```python
{
    "class": "car",
    "instance_id": 17,
    "keypoints": {
        "keypoints": [
            (0.10, 0.20, 2),
            (0.30, 0.40, 1),
        ],
    },
}
```

对于 K 个关键点和 N 个实例，加载器输出使用形状 (N, 3⋅K)。

## 分割

[SegmentationAnnotation](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
支持多边形、二值掩码和行程编码输入。

折线分割存储归一化的多边形点。最后一个点隐式连接到第一个点：

```python
{
    "class": "road",
    "segmentation": {
        "height": 720,
        "width": 1280,
        "points": [
            (0.10, 0.10),
            (0.90, 0.10),
            (0.80, 0.80),
            (0.20, 0.80),
        ],
    },
}
```

二值掩码是二维数组，其中前景像素为 1，背景像素为 0：

```python
{
    "class": "road",
    "segmentation": {
        "mask": binary_mask,
    },
}
```

行程编码掩码使用 COCO RLE。`counts` 值可以是未压缩的整数列表或压缩的字节字符串：

```python
{
    "class": "road",
    "segmentation": {
        "height": 720,
        "width": 1280,
        "counts": [120, 8, 200, 12],
    },
}
```

> **注意**
> Numpy 掩码在内部转换为 RLE。RLE 输入主要用于与已以该格式存储掩码的数据集兼容。

语义分割加载器输出使用通道优先掩码，形状为 (C, H, W)。

## 实例分割

[InstanceSegmentationAnnotation](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
使用与语义分割相同的掩码编码，但每个实例存储一个掩码。检测可以同时包含边界框和实例掩码：

```python
{
    "class": "car",
    "instance_id": 17,
    "boundingbox": {"x": 0.20, "y": 0.10, "w": 0.35, "h": 0.25},
    "instance_segmentation": {
        "height": 720,
        "width": 1280,
        "points": [
            (0.20, 0.10),
            (0.55, 0.10),
            (0.55, 0.35),
            (0.20, 0.35),
        ],
    },
}
```

实例掩码加载器输出使用形状 (N, H, W)。

## 数组

[ArrayAnnotation](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
引用与样本同步的任意 `.npy` 数据：

```python
{
    "class": "embedding",
    "array": {
        "path": "path/to/embedding.npy",
    },
}
```

数组对于特定于模态的目标或应与数据集一起存储但不适合标准空间模式的辅助数据很有用。

## 元数据和类别

元数据存储灵活的键值对。使用
[Category](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
将字符串标记为分类元数据而不是自由格式文本：

```python
from luxonis_ml.ldf import Category

{
    "metadata": {
        "text": "ABC-123",
        "text_color": Category("white"),
        "track_id": 42,
    },
}
```

分类元数据可以由
[LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
编码为整数，或者在加载器配置请求时保留为字符串。

OCR 注释通常存储识别的文本和分类视觉属性：

```python
{
    "metadata": {
        "text": "ABC-123",
        "color": Category("red"),
    },
}
```

LuxonisTrain 的 [OCR 头](https://github.com/luxonis/luxonis-train/tree/main/luxonis_train/nodes#ocr-heads) 使用此元数据。

嵌入和重识别数据集通常存储标识符或其他查找键：

```python
{
    "metadata": {
        "id": 42,
        "color": Category("red"),
    },
}
```

LuxonisTrain 的 [嵌入头](https://github.com/luxonis/luxonis-train/tree/main/luxonis_train/nodes#embedding-heads) 使用此元数据。

> **重要**
> 元数据和数组没有通用的几何语义。内置增强功能可以丢弃与离开图像的框相关联的值，但除非自定义增强功能明确处理它们，否则任意值将保持不变。

## 类

### Annotation

注释的基类。

#### 方法

##### combine_to_numpy

```python
def 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
def 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
def to_numpy(self) -> np.ndarray:
```

从文件路径加载数组。

#### 属性

##### path

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

### BBoxAnnotation

边界框注释。

值根据图像大小进行归一化。

#### 方法

##### combine_to_numpy

```python
def 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
def 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
def 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](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
的摄取单元。它可以通过 `file` 指向一个媒体源，或者通过 `files` 指向多个同步源，但不能同时指向两者——同时传递两者是错误的，以前 `files` 会被静默丢弃以支持 `file`。

`sample_metadata` 存储记录级元数据。它由原生导入/导出保留，并由
[LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
作为
[LoaderOutput.metadata](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/typing.md)
返回。它有意与
[Detection.metadata](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
分开，后者创建注释元数据标签任务。

> **示例**
> ```json
{
  "file": "images/frame_001.jpg",
  "task_name": "detection",

  "sample_metadata": {
    "record_id": 123,
    "camera": "left",
    "tags": ["night", "warehouse"]
  },

  "annotation": {
    "class": "person",
    "boundingbox": {
      "x": 0.1,
      "y": 0.2,
      "w": 0.3,
      "h": 0.4
    }
  }
}
```

#### 方法

##### decode_metadata

```python
def decode_metadata(value: Any) -> Params:
```

将序列化的记录元数据解码为字典。

参数

 * `value` (`Any`): 元数据字典、序列化的 JSON 对象、空字符串或 `None`。

返回

 * `Params`: 当值为字典式 JSON 对象时解码的元数据；否则为空字典。

##### to_parquet_rows

```python
def to_parquet_rows(self) -> Iterable[ParquetRecord]:
```

递归地将数据集记录及其所有注释和子注释转换为 parquet 行。

生成

 * 注释数据行。

##### validate_files

```python
def validate_files(values: Any) -> Any:
```

##### validate_task_name

```python
def validate_task_name(values: Any) -> Any:
```

##### validate_task_name_valid_identifier

```python
def validate_task_name_valid_identifier(self) -> Self:
```

#### 属性

##### all_file_paths

与数据集记录关联的所有文件路径。

> **已弃用**
> 自 0.9.0 版起已弃用：请改用 `list(record.files.values())`。

##### annotation

与数据集记录关联的可选检测。

##### file

数据集记录的文件路径。

当数据集记录只有一个文件时，提供此属性是为了方便。

引发

 * `ValueError`: 如果数据集记录有零个或多个文件。

##### files

按源名称键入的文件路径。

##### sample_metadata

整个样本的类似 JSON 的元数据。值应可 JSON 序列化。缺失的元数据默认为空字典。

##### task_name

记录所属任务的名称。

### Detection

包含一个对象的注释和元数据的检测记录。

它描述了图像中单个检测到的对象，并且可以包含各种类型的注释和元数据以及用于分层注释的嵌套子检测。

当启用 `scale_to_boxes` 时，关键点将相对于边界框进行解释，并重新缩放到图像归一化坐标。

> **示例**
> ```pycon
>>> detection = Detection(
...     class_name="person",
...     instance_id=1,
...     metadata={
...         "category": Category("adult"),
...     },
...     boundingbox={
...         "x": 0.1,
...         "y": 0.2,
...         "w": 0.3,
...         "h": 0.4,
...     },
...     instance_segmentation={
...         "mask": np.array([[0, 1], [1, 0]]),
...     },
...     sub_detections={
...         "face": {
...             "class_name": "face",
...             "boundingbox": {
...                 "x": 0.2,
...                 "y": 0.3,
...                 "w": 0.1,
...                 "h": 0.1,
...             },
...             "keypoints": {
...                 "keypoints": [
...                     (0.25, 0.35, 2),  # 左眼
...                     (0.3, 0.35, 2),  # 右眼
...                 ],
...             },
...             "metadata": {
...                 "expression": Category("happy"),
...                 "eye_color": Category("blue"),
...             },
...         },
...     },
... )
```

#### 方法

##### get_task_types

```python
def get_task_types(self) -> set[str]:
```

获取与此检测关联的所有任务类型。

> **示例**
> ```pycon
>>> detection = Detection(
...     class_name="cat",
...     boundingbox=BBoxAnnotation(x=0.1, y=0.2, w=0.3, h=0.4),
...     metadata={"color": "black"},
... )
>>> sorted(detection.get_task_types())
['boundingbox', 'classification', 'metadata/color']
```

返回

 * `set[str]`: 注释任务类型和元数据键。

#### 属性

##### array

可选数组注释。

##### boundingbox

可选边界框注释。

##### class_name

检测的可选类名。输入数据可以使用 `"class"` 别名。

##### instance_id

实例标识符。如果未提供，实例 ID 将对应于检测添加到数据集的顺序。请注意，如果单独添加单个检测类型并且在记录之间顺序不一致，这可能会导致实例注释的配对不正确：

```pycon
# 如果不指定 `instance_id`，
# 边界框和关键点注释将
# 无法正确配对，因为它们是单独添加的
# 检测，并且顺序不同。
def generator():
    yield {
        "file": ...,
        "annotation": {"boundingbox": bbox1},
    }
    yield {
        "file": ...,
        "annotation": {"keypoints": kpts2},
    }
    yield {
        "file": ...,
        "annotation": {"boundingbox": bbox2},
    }
    yield {
        "file": ...,
        "annotation": {"keypoints": kpts1},
    }
```

建议尽可能提供实例 ID，并避免在单独的检测中单独生成注释：

```pycon
# 这是正确的方法
def generator():
    yield {
        "file": ...,
        "annotation": {
            "instance_id": 1,
            "boundingbox": bbox1
            "keypoints": kpts1,
        },
    }
    yield {
        "file": ...,
        "annotation": {
            "instance_id": 2,
            "boundingbox": bbox2
            "keypoints": kpts2,
        },
    }
```

##### instance_segmentation

可选实例分割注释。

##### keypoints

可选关键点注释。

##### metadata

按元数据名称键入的元数据值。

##### scale_to_boxes

关键点坐标是否应从边界框相对坐标重新缩放。

##### segmentation

可选语义分割注释。

##### sub_detections

按子检测名称键入的嵌套检测。

### InstanceSegmentationAnnotation

实例分割注释。

[SegmentationAnnotation](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md) 的子类，用于区分实例分割注释和语义分割注释。

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

#### 方法

##### combine_to_numpy

```python
def 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

关键点注释。

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

#### 方法

##### combine_to_numpy

```python
def 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
def 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 风格的 [行程编码](https://en.wikipedia.org/wiki/Run-length_encoding)。

此类支持从多种输入格式解析分割掩码：

 * 直接作为计数列表或字节字符串的行程编码 (RLE)。
 * 作为 numpy 数组或保存为 `.npy` 或 `.png` 文件的二值掩码数组。
 * 作为归一化点列表以及图像宽度和高度的多边形。

> **示例**
> ```pycon
>>> rle = SegmentationAnnotation(height=4, width=4, counts=b"11213ON0")
>>> mask = SegmentationAnnotation(
...     mask=np.array(
...         [
...             [0, 1, 0, 0],
...             [1, 1, 0, 0],
...             [0, 0, 0, 0],
...             [0, 0, 1, 1],
...         ]
...     )
... )
>>> np.array_equal(rle.to_numpy(), mask.to_numpy())
True
```

> **注意**
> 当将 RLE 作为计数列表而不是编码字节提供时，请确保计数遵循 FORTRAN（列主序）顺序，如 COCO RLE 格式所期望的那样。

计数在背景运行和前景运行之间交替，第一个计数始终是背景运行。如果掩码以前景像素开头，则第一个计数为 0。

#### 方法

##### combine_to_numpy

```python
def 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
def to_numpy(self) -> np.ndarray:
```

将分割注释转换为二值掩码。

返回

 * `np.ndarray`: 形状为 (H, W) 的二值掩码。

#### 属性

##### counts

行程编码掩码数据。

##### height

分割掩码的高度。

##### width

分割掩码的宽度。

## 函数

### load_annotation

```python
def 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](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
   子类的实例。

引发

 * `ValueError`: 如果任务类型未知。

## 属性

### KeypointVisibility

遵循 COCO 约定的关键点可见性。

这些值表示图像中关键点的可见性：

 * 0：不可见或未标记。
 * 1：被遮挡。
 * 2：可见。

### NormalizedFloat

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