# frame_cropper

Python API: `depthai_nodes.node.frame_cropper`

## 类

### FrameCropper

一个主机节点，用于从帧中裁剪检测区域，并为每个区域输出一个裁剪后的 `dai.ImgFrame`。

`FrameCropper` 是一个方便的包装器，它封装了一个内部的 `dai.node.ImageManip`，该 `ImageManip` 配置用于裁剪 + 调整大小。它支持两种输入模式：

 * fromImgDetections：提供 `dai.ImgDetections`，节点将通过 `dai.node.Script` 节点为每个检测生成 `dai.ImageManipConfig`
   消息。每个配置都与相应的输入帧配对，为每个检测生成一个裁剪后的输出帧。
 * fromManipConfigs：提供一个由 `dai.MessageGroup` 消息中打包的裁剪配置组成的上游流。一个设备上的 `dai.node.Script` 节点将每个配置与当前帧配对，并将它们转发到内部的
   `dai.node.ImageManip`。

配置通过 `fromImgDetections` 或 `fromManipConfigs` 提供。只有在调用 `build` 后，才会构建管道节点。

> **Note**
> * 必须且只能选择一个配置路径：`fromImgDetections` 和 `fromManipConfigs` 只能使用其中一个。
 * 输出帧始终使用提供的 `resizeMode`（默认值：`CENTER_CROP`）调整为 `outputSize`。
 * 在 `fromImgDetections` 模式下，`dai.node.Script` 节点通过为每个检测发出一个 `dai.ImageManipConfig` 来驱动裁剪。
 * 在 `fromManipConfigs` 模式下，`inputManipConfigs` 流必须输出 `dai.MessageGroup` 消息，其中每个值都是 `dai.ImageManipConfig`。键名是任意的。

使用 `fromImgDetections(padding=0.0)` 为每个检测区域添加可选的填充。`build(outputSize, resizeMode)` 设置裁剪大小和调整大小模式。

输出：

 * `out : dai.Node.Output`：裁剪后的 `dai.ImgFrame` 消息流。每个裁剪配置（在 `fromImgDetections` 模式下为每个检测；在 `fromManipConfigs` 模式下为收到的
   `MessageGroup` 中的每个配置）都会生成一个输出帧。

另请参阅：

 * `dai.node.ImageManip`：用于执行裁剪和调整大小的节点。
 * `dai.ImageManipConfig`：转发到 ImageManip 的裁剪配置消息。
 * `dai.ImgDetections`：`fromImgDetections` 模式中使用的检测消息类型。
 * `dai.MessageGroup`：`fromManipConfigs` 期望的消息类型。

#### 方法

##### init

```python
def __init__(self):
```

初始化日志记录和特定于平台的输出图像格式。

引发

 * `ValueError`：如果管道设备平台没有配置图像帧格式。

##### build

```python
def build(inputImage: dai.Node.Output) -> FrameCropper:
```

连接图像输入并构建配置的裁剪管道。

参数

 * `inputImage` (`dai.Node.Output`)：要裁剪的图像流。首先调用 `fromImgDetections()` 或 `fromManipConfigs()`。

返回

 * `FrameCropper`：此节点，裁剪后的帧可在 `out` 上获得。

引发

 * `RuntimeError`：如果未选择裁剪配置模式。

##### fromImgDetections

```python
def fromImgDetections(inputImgDetections: dai.Node.Output, outputSize: tuple[int, int], resizeMode: dai.ImageManipConfig.ResizeMode = dai.ImageManipConfig.ResizeMode.CENTER_CROP, padding: float = 0.0, syncThreshold: timedelta = timedelta(milliseconds=10)) -> FrameCropper:
```

在调用 `build()` 之前选择检测驱动的裁剪。

> **Note**
> 为每个检测生成一个裁剪。图像流稍后由 `build()` 连接。

参数

 * `inputImgDetections` (`dai.Node.Output`)：要与图像帧同步的 `dai.ImgDetections` 输出流。
 * `outputSize` (`tuple[int, int]`)：裁剪输出大小，格式为 `(宽度, 高度)` 像素。
 * `resizeMode` (`dai.ImageManipConfig.ResizeMode`)：应用于每个裁剪的 ImageManip 调整大小策略。
 * `padding` (`float`)：添加到检测区域每侧的归一化填充。
 * `syncThreshold` (`timedelta`)：用于同步检测和帧的最大时间戳差异。

返回

 * `FrameCropper`：用于流畅配置的此节点。

引发

 * `RuntimeError`：如果已选择任一裁剪配置模式。

##### fromManipConfigs

```python
def fromManipConfigs(inputManipConfigs: dai.Node.Output, maxOutputFrameSize: int, waitForConfig: bool, syncThreshold: timedelta | None = None) -> FrameCropper:
```

从 ImageManip 配置消息组中选择裁剪。

参数

 * `inputManipConfigs` (`dai.Node.Output`)：`dai.MessageGroup` 对象流，其值是 `dai.ImageManipConfig` 消息。组键是任意的。
 * `maxOutputFrameSize` (`int`)：最大输出图像缓冲区大小（以字节为单位）。
 * `waitForConfig` (`bool`)：如果为 true，则将每个帧与配置组同步。否则，将最新组用于后续帧。
 * `syncThreshold` (`timedelta | None`)：可选时间戳容差。仅当 `waitForConfig` 为 true 时才能设置。

返回

 * `FrameCropper`：用于流畅配置的此节点。

引发

 * `RuntimeError`：如果已选择配置模式，或者在不等待配置的情况下提供了同步阈值。

##### run

```python
def run(self):
```

无操作，因为裁剪完全由设备上的 Script 节点驱动。

#### 属性

##### IMG_DETECTIONS_SCRIPT_CONTENT

##### MANIP_CONFIGS_SCRIPT_CONTENT

##### out

返回裁剪后的帧输出流。

##### SYNCED_MANIP_CONFIGS_SCRIPT_CONTENT
