# annotate_utils

Python API: `luxonis_train.core.utils.annotate_utils`

使用训练好的模型对图像目录进行预标注，并将其转换为新的数据集。

## 函数

### annotate_from_directory

```python
def annotate_from_directory(model: lxt.LuxonisModel, img_paths: Iterable[PathType], dataset_name: str, bucket_storage: Literal['local', 'gcs'] = 'local', delete_local: bool = True, delete_remote: bool = True, team_id: str | None = None) -> LuxonisDataset:
```

使用模型对图像文件进行标注，并将其转换为新的数据集。

该函数执行以下步骤：

 * 它使用
   [create_loader_from_directory](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/infer_utils.md)
   在 `img_paths` 上构建一个加载器，批处理大小为 `1`。该函数会替换名为 `infer_from_directory` 的本地数据集。
 * 它创建数据集 `dataset_name` 并将
   [annotated_dataset_generator](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/annotate_utils.md)
   的记录添加到其中。
 * 它将非空数据集按 0.8、0.1 和 0.1 的比例拆分为 `train`、`val` 和 `test`。对于空数据集，它会记录警告。
 * 它删除名为 `infer_from_directory` 的数据集的本地副本。

该函数不加载权重。[LuxonisModel.annotate](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
在调用之前加载它们。

参数

 * `model` (`lxt.LuxonisModel`): 预测标注的模型。加载器应用其 `trainer.preprocessing`。
 * `img_paths` (`Iterable[PathType]`): 要标注的图像文件。
 * `dataset_name` (`str`): 新数据集的名称。
 * `bucket_storage` (`Literal['local', 'gcs']`): 新数据集的存储后端。
 * `delete_local` (`bool`): 在函数创建新数据集之前，删除名为 `dataset_name` 的现有数据集的本地文件。如果为 `False` 且存储为 `"local"`，则记录将进入现有数据集。
 * `delete_remote` (`bool`): 删除名为 `dataset_name` 的现有数据集的远程文件。该值仅在存储为 `"gcs"` 时有效。
 * `team_id` (`str | None`): 拥有数据集的团队。`None` 从环境中读取 `LUXONISML_TEAM_ID`。

返回

 * `LuxonisDataset`: 带有标注的新数据集。

### annotated_dataset_generator

```python
def annotated_dataset_generator(model: lxt.LuxonisModel, loader: torch_data.DataLoader) -> DatasetIterator:
```

生成模型头部预测的数据集记录。

生成器将 `model` 的 Lightning 模块置于评估模式。对于 `loader` 的每个批次，它在没有梯度的情况下运行
[LuxonisLightningModule.full_forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)。对于每个作为
[BaseHead](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/base_head.md)
的输出节点，它调用
[BaseHead.annotate](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/nodes/heads/base_head.md)。该调用获取头部的输出、来自
`"path"` 样本元数据的图像路径以及配置的 `trainer.preprocessing`。生成器跳过其他输出节点。

来自 `annotate` 的字典记录成为 `DatasetRecord`。当记录的唯一验证错误是边界框超出裁剪范围时，生成器会跳过该记录并记录调试消息。

参数

 * `model` (`lxt.LuxonisModel`): 预测标注的模型。
 * `loader` (`torch_data.DataLoader`): 一个加载器，其批次包含输入、标签以及每个样本的元数据列表，如
   [create_loader_from_directory](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/infer_utils.md)
   使用 `return_sample_metadata=True` 构建。

返回

 * `DatasetIterator`

生成

 * 头部为图像提供的记录。

引发

 * `ValidationError`: 当记录因其他原因未能通过 `DatasetRecord` 的验证时。
