# infer_utils

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

对图像、视频、目录或数据集视图进行推理。

[LuxonisModel.infer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
调用这些辅助函数。它们运行模型，将其可视化工具的图像转换为 OpenCV
数组，并保存数组或在窗口中显示它们。[LuxonisModel.annotate](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
也通过
[create_loader_from_directory](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/infer_utils.md)
读取其图像。

`VIDEO_FORMATS` 包含
[LuxonisModel.infer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
读取为视频的小写文件扩展名。`IMAGE_FORMATS` 包含
[LuxonisModel.infer](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
和
[LuxonisModel.annotate](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/core.md)
在目录中选择的图像的小写文件扩展名。[LuxonisLoaderPerlinNoise](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/luxonis_perlin_loader_torch.md)
也用它选择其异常源图像。

## 函数

### create_loader_from_directory

```python
def create_loader_from_directory(img_paths: Iterable[PathType], model: lxt.LuxonisModel, batch_size: int | None = None, return_sample_metadata: bool = False) -> torch_data.DataLoader:
```

构建一个基于图像文件的 `DataLoader`。

该函数在删除名为 `infer_from_directory` 的本地 `LuxonisDataset` 后，创建一个名为 `infer_from_directory` 的本地 `LuxonisDataset`。它将每个图像与样本元数据 `{"path":
<image path>}` 添加，并将所有图像放入 `test` 分割中。它将数据集包装在
[LuxonisLoaderTorch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/luxonis_loader_torch.md)
中，并使用 `test` 视图。加载器应用 `model` 的 `trainer.preprocessing` 的这些设置：训练图像大小、活动增强、色彩空间和 `keep_aspect_ratio`。

加载器不保留 `img_paths` 的顺序。使用 `"path"`
元数据将样本与其文件匹配。该函数不删除数据集。[infer_from_directory](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/infer_utils.md)
和
[annotate_from_directory](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/annotate_utils.md)
在使用后删除它。

参数

 * `img_paths` (`Iterable[PathType]`): 图像文件。
 * `model` (`lxt.LuxonisModel`): 加载器应用其预处理的模型。
 * `batch_size` (`int | None`): 批处理大小。`None` 选择 `model` 配置的 `trainer.batch_size`。
 * `return_sample_metadata` (`bool`): 也返回每个样本的元数据。每个批次都是输入、标签和包含每个样本元数据字典的列表的元组，每个字典都有 `"path"` 键。

返回

 * `torch_data.DataLoader`: 加载器，`pin_memory` 开启且不打乱。如果没有 `return_sample_metadata`，每个批次都是输入和标签的列表。输入是一个形状为 `[B, C, H, W]` 的
   `Tensor`。标签是一个空字典，因为数据集没有注释。

### infer_from_dataset

```python
def infer_from_dataset(model: lxt.LuxonisModel, view: Literal['train', 'val', 'test'], save_dir: PathType | None):
```

在其数据集的一个视图上运行模型。

该函数读取 `model.pytorch_loaders[view]`。当配置的 `trainer.overfit_batches` 大于 `0` 且 `view` 为 `"train"` 时，它只读取那么多批次并记录警告。然后它运行
[infer_from_loader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/infer_utils.md)，不带图像路径，因此保存的渲染被命名为
`<node>_<visualizer>_<n>.png`。

参数

 * `model` (`lxt.LuxonisModel`): 要运行的模型。
 * `view` (`Literal['train', 'val', 'test']`): 要读取的数据集视图。
 * `save_dir` (`PathType | None`): PNG 文件的目录。`None` 则在屏幕上显示渲染。

### infer_from_directory

```python
def infer_from_directory(model: lxt.LuxonisModel, img_paths: Iterable[PathType], save_dir: Path | None):
```

在图像文件上运行模型。

该函数使用
[create_loader_from_directory](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/infer_utils.md)
构建一个加载器，并在其上运行
[infer_from_loader](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/infer_utils.md)。它按给定顺序传递
`img_paths` 以命名保存的渲染。加载器不保留该顺序，因此当有两个或更多图像时，保存的渲染可能会获得不同图像的名称。最后，该函数删除临时本地数据集 `infer_from_directory`。

参数

 * `model` (`lxt.LuxonisModel`): 要运行的模型。
 * `img_paths` (`Iterable[PathType]`): 图像文件。
 * `save_dir` (`Path | None`): PNG 文件的目录。`None` 则在屏幕上显示渲染。

### infer_from_loader

```python
def infer_from_loader(model: lxt.LuxonisModel, loader: torch_data.DataLoader, save_dir: PathType | None, img_paths: list[PathType] | None = None):
```

在加载器上运行训练器的预测循环并渲染可视化。

该函数使用 `model.lightning_module` 在 `loader` 上运行 `model.pl_trainer.predict`，因此每个批次都通过
[LuxonisLightningModule.predict_step](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)。

使用 `save_dir` 时，一个临时的 `BasePredictionWriter` 回调将每个批次的渲染保存为 PNG 文件，如下所示：

 * 当给定 `img_paths` 时，为 `<save_dir>/<image stem>_<node>_<visualizer>.png`。回调按加载器顺序为每个样本获取下一个路径。
 * 否则为 `<save_dir>/<node>_<visualizer>_<n>.png`，其中 `<n>` 从 `0` 开始计数写入的文件。

文件名中的 `/` 变为 `-`。

如果没有 `save_dir`，该函数首先收集所有预测。然后它在名为 `<node>/<visualizer>` 的 OpenCV 窗口中显示每个样本的每个渲染。它在每个样本后等待按键。`Esc` 或 `q` 停止循环。最后，该函数关闭窗口。

参数

 * `model` (`lxt.LuxonisModel`): 要运行的模型。
 * `loader` (`torch_data.DataLoader`): 要运行的批次。
 * `save_dir` (`PathType | None`): PNG 文件的目录。`None` 则在屏幕上显示渲染。
 * `img_paths` (`list[PathType] | None`): 每个样本的源路径，按加载器顺序。它命名保存的文件。如果没有 `save_dir`，则不读取它。

### infer_from_video

```python
def infer_from_video(model: lxt.LuxonisModel, video_path: PathType, save_dir: Path | None):
```

在视频的每一帧上运行模型，一次一帧。

该函数使用 `cv2.VideoCapture` 读取帧。当配置的 `trainer.preprocessing.color_space` 为 `"RGB"` 时，它首先将每帧从 BGR 转换为 RGB。然后它在输入名称 `"image"` 下对帧运行
[prepare_and_infer_image](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/infer_utils.md)，并使用
[process_visualizations](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/core/utils/infer_utils.md)
渲染可视化。当 OpenCV 无法打开 `video_path` 时，该函数不读取帧也不写入任何内容。

使用 `save_dir` 时，该函数将每个可视化工具的渲染写入 `<save_dir>/<node>_<visualizer>.mp4`。视频获取 `mp4v` 编解码器、源视频的帧速率和第一个渲染的大小。如果没有 `save_dir`，该函数在名为
`<node>/<visualizer>` 的 OpenCV 窗口中显示每个可视化工具的渲染。然后它在每帧后等待按键。`Esc` 或 `q` 停止循环。最后，该函数释放捕获和写入器，并关闭窗口。

参数

 * `model` (`lxt.LuxonisModel`): 要运行的模型。
 * `video_path` (`PathType`): 视频文件。
 * `save_dir` (`Path | None`): 输出视频的目录。`None` 则在屏幕上显示渲染。

### prepare_and_infer_image

```python
def prepare_and_infer_image(model: lxt.LuxonisModel, images: dict[str, Tensor]) -> LuxonisOutput:
```

使用 `val` 加载器预处理一个原始图像并在其上运行模型。

该函数将 `images` 传递给 `model` 的 `val` 加载器的 `augment_test_image`。该方法返回一个形状为 `[H, W, C]`
的图像。[LuxonisLoaderTorch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/luxonis_loader_torch.md)
在那里应用其增强，例如调整大小和归一化。没有高度或宽度的
[LuxonisLoaderTorch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/luxonis_loader_torch.md)
返回未更改的图像。未覆盖该方法的加载器会引发 `NotImplementedError`。该函数添加批次维度，将通道移到前面，并转换为 `torch.float32`。然后它在模块的 `image_source` 名称下，对这个批次运行
[LuxonisLightningModule.full_forward](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_lightning.md)。可视化工具在去归一化图像上绘制。该函数不提供标签，因此不运行损失和指标。

参数

 * `model` (`lxt.LuxonisModel`): 要运行的模型。
 * `images` (`dict[str, Tensor]`): 形状为 `[H, W, C]` 的原始图像，以加载器的输入名称为键。

返回

 * `LuxonisOutput`: `outputs` 包含每个输出节点的包。`visualizations` 包含每个可视化工具的图像批次，批次大小为 `1`。`losses` 和 `metrics` 为空。

### process_visualizations

```python
def process_visualizations(visualizations: dict[str, dict[str, Tensor]]) -> dict[tuple[str, str], list[np.ndarray]]:
```

将可视化工具的图像转换为 OpenCV 数组。

该函数获取
[LuxonisOutput](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_output.md)
的 `visualizations`，并将每个批次的每个图像转换为 NumPy 数组。它分离每个图像，将其移动到 CPU，并将其从 `[C, H, W]` 转置为 `[H, W, C]`。然后它使用 `cv2.cvtColor` 将通道从 RGB 转换为
BGR，因为 OpenCV 写入和显示 BGR。具有四个通道的图像会丢失其第四个通道。

> **示例**
> ```pycon
>>> import torch
>>> image = torch.zeros(2, 3, 4, 5, dtype=torch.uint8)
>>> image[:, 0] = 255  # RGB 中的红色
>>> renders = process_visualizations({"head": {"boxes": image}})
>>> sorted(renders)
[('head', 'boxes')]
>>> [render.shape for render in renders["head", "boxes"]]
[(4, 5, 3), (4, 5, 3)]
>>> renders["head", "boxes"][0][0, 0].tolist()
[0, 0, 255]
```

参数

 * `visualizations` (`dict[str, dict[str, Tensor]]`): 每个可视化工具的图像批次，形状为 `[B, C, H, W]`，以节点名称和可视化工具名称为键。

返回

 * `dict[tuple[str, str], list[np.ndarray]]`: 每个可视化工具的 `B` 个图像，每个图像形状为 `[H, W, 3]`（BGR 格式），以节点名称和可视化工具名称对为键。结果是一个 `defaultdict`，因此缺失的键会返回一个空列表。

### window_closed

```python
def window_closed() -> bool:
```

在 OpenCV 窗口中等待按键并报告停止请求。

该函数在 `cv2.waitKey` 中阻塞，直到用户按下按键。

返回

 * `bool`: 当按键为 `Esc` 或 `q` 时为 `True`。

## 属性

### IMAGE_FORMATS

### VIDEO_FORMATS
