# frame_cropper

Python API: `depthai_nodes.node.frame_cropper`

## Classes

### FrameCropper

A host node that crops detection regions from frames and outputs one cropped `dai.ImgFrame` per region.

`FrameCropper` is a convenience wrapper around an internal `dai.node.ImageManip` configured for cropping + resizing. It supports
two input modes:

 * fromImgDetections: Provide `dai.ImgDetections` and the node will generate `dai.ImageManipConfig` messages for each detection
   via a `dai.node.Script` node. Each config is paired with the corresponding input frame, producing one cropped output frame per
   detection.
 * fromManipConfigs: Provide an upstream stream of cropping configs packed in `dai.MessageGroup` messages. An on-device
   `dai.node.Script` node pairs each config with the current frame and forwards them to the internal `dai.node.ImageManip`.

Configuration is provided via `fromImgDetections` or `fromManipConfigs`. The pipeline nodes are constructed only once `build` is
called.

> **Note**
> * Exactly one configuration path must be selected: only one of `fromImgDetections` and `fromManipConfigs` can be used.
 * Output frames are always resized to `outputSize` using the provided `resizeMode` (default: `CENTER_CROP`).
 * In `fromImgDetections` mode, a `dai.node.Script` node drives the cropping by emitting one `dai.ImageManipConfig` per detection.
 * In `fromManipConfigs` mode, the `inputManipConfigs` stream must output `dai.MessageGroup` messages where each value is a
   `dai.ImageManipConfig`. Key naming is arbitrary.

Use `fromImgDetections(padding=0.0)` to set optional padding around each detection region. `build(outputSize, resizeMode)` sets
the crop size and resize mode.

Outputs:

 * `out : dai.Node.Output`: Stream of cropped `dai.ImgFrame` messages. One output frame is produced per crop configuration (per
   detection in `fromImgDetections` mode; per config in the received `MessageGroup` in `fromManipConfigs` mode).

See also:

 * `dai.node.ImageManip`: Node used to perform cropping and resizing.
 * `dai.ImageManipConfig`: Cropping configuration messages forwarded to ImageManip.
 * `dai.ImgDetections`: Detection message type used in `fromImgDetections` mode.
 * `dai.MessageGroup`: Message type expected by `fromManipConfigs`.

#### Methods

##### init

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

Initialize logging and the platform-specific output image format.

Raises

 * `ValueError`: If the pipeline device platform has no configured image-frame format.

##### build

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

Connect image input and construct the configured crop pipeline.

Parameters

 * `inputImage` (`dai.Node.Output`): Image stream to crop. Call `fromImgDetections()` or `fromManipConfigs()` first.

Returns

 * `FrameCropper`: This node, with cropped frames available on `out`.

Raises

 * `RuntimeError`: If no crop configuration mode has been selected.

##### 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:
```

Select detection-driven cropping before calling `build()`.

> **Note**
> Produces one crop per detection. The image stream is connected later by `build()`.

Parameters

 * `inputImgDetections` (`dai.Node.Output`): Output stream of `dai.ImgDetections` to synchronize with image frames.
 * `outputSize` (`tuple[int, int]`): Crop output size as `(width, height)` pixels.
 * `resizeMode` (`dai.ImageManipConfig.ResizeMode`): ImageManip resize policy applied to each crop.
 * `padding` (`float`): Normalized padding added to each side of the detection region.
 * `syncThreshold` (`timedelta`): Maximum timestamp difference used to synchronize detections and frames.

Returns

 * `FrameCropper`: This node for fluent configuration.

Raises

 * `RuntimeError`: If either crop configuration mode was already selected.

##### fromManipConfigs

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

Select cropping from groups of ImageManip configuration messages.

Parameters

 * `inputManipConfigs` (`dai.Node.Output`): Stream of `dai.MessageGroup` objects whose values are `dai.ImageManipConfig` messages.
   Group keys are arbitrary.
 * `maxOutputFrameSize` (`int`): Maximum output image buffer size in bytes.
 * `waitForConfig` (`bool`): If true, synchronize each frame with a configuration group. Otherwise, reuse the latest group for
   subsequent frames.
 * `syncThreshold` (`timedelta | None`): Optional timestamp tolerance. May only be set when `waitForConfig` is true.

Returns

 * `FrameCropper`: This node for fluent configuration.

Raises

 * `RuntimeError`: If a configuration mode was already selected, or a sync threshold is supplied without waiting for
   configuration.

##### run

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

No-op because cropping is driven entirely by on-device Script nodes.

#### Attributes

##### IMG_DETECTIONS_SCRIPT_CONTENT

##### MANIP_CONFIGS_SCRIPT_CONTENT

##### out

Return the cropped frame output stream.

##### SYNCED_MANIP_CONFIGS_SCRIPT_CONTENT