# Streams Gizmos

{% hint style="info" %}
This API Reference is based on DeGirum Tools version 1.2.0.
{% endhint %}

## Classes <a href="#classes" id="classes"></a>

## VideoSourceGizmo <a href="#videosourcegizmo" id="videosourcegizmo"></a>

`VideoSourceGizmo`

Bases: `Gizmo`

Video source gizmo with OpenCV and GStreamer support.

Captures frames from a video source (camera, video file, etc.) and outputs them as [StreamData](https://docs.degirum.com/degirum-tools/streams_base#streamdata) into the pipeline. Supports both OpenCV and GStreamer backends for maximum compatibility and performance.

Example:

{% code overflow="wrap" %}

```
# Using enum (recommended)
source = VideoSourceGizmo("video.mp4", source_type=VideoSourceType.GSTREAMER)
# Using string (backward compatible)
source = VideoSourceGizmo("video.mp4", source_type="gstream")
# Auto-detect best backend (default)
source = VideoSourceGizmo("video.mp4")
```

{% endcode %}

### VideoSourceGizmo Methods <a href="#videosourcegizmo-methods" id="videosourcegizmo-methods"></a>

#### \_\_del\_\_ <a href="#del" id="del"></a>

`__del__()`

Destructor to ensure video source is released.

#### \_\_init\_\_(video\_source=None, ...) <a href="#init" id="init"></a>

`__init__(video_source=None, *, source_type=VideoSourceType.AUTO, stop_composition_on_end=False, retry_on_error=False, fps_override=None, resolution_override=None)`

Constructor.

Parameters:

| Name                      | Type                          | Description                                                                                                                                                                                                                     | Default |
| ------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `video_source`            | `int or str`                  | A cv2.VideoCapture-compatible video source (device index as int, or file path/URL as str). Defaults to None.                                                                                                                    | `None`  |
| `source_type`             | `Union[str, VideoSourceType]` | Video backend to use. Options: - VideoSourceType.AUTO or "auto": Automatically choose best backend - VideoSourceType.GSTREAMER or "gstream": Force GStreamer backend - VideoSourceType.OPENCV or "opencv": Force OpenCV backend | `AUTO`  |
| `stop_composition_on_end` | `bool`                        | If True, stop the [Composition](https://docs.degirum.com/degirum-tools/streams_base#composition) when the video source is over. Defaults to False.                                                                              | `False` |
| `retry_on_error`          | `bool`                        | If True, retry opening the video source on error after some time. Defaults to False.                                                                                                                                            | `False` |
| `fps_override`            | `float`                       | If provided, overrides the FPS value reported by source (some IP cameras report 100FPS). Defaults to None.                                                                                                                      | `None`  |
| `resolution_override`     | `Tuple[int, int]`             | If provided, overrides the resolution (width, height) reported by source. Defaults to None.                                                                                                                                     | `None`  |

#### get\_tags <a href="#get_tags" id="get_tags"></a>

`get_tags()`

Get list of tags assigned to this gizmo.

Returns:

| Type        | Description                                                   |
| ----------- | ------------------------------------------------------------- |
| `List[str]` | List\[str]: Tags for this gizmo (its name and the video tag). |

#### run <a href="#run" id="run"></a>

`run()`

Run the video capture loop.

Continuously reads frames from the video source and sends each frame (with metadata) downstream until the source is exhausted or abort is signaled.

## IteratorSourceGizmo <a href="#iteratorsourcegizmo" id="iteratorsourcegizmo"></a>

`IteratorSourceGizmo`

Bases: `Gizmo`

Iterator-based source gizmo.

Takes an iterator that yields images in various formats (file paths, numpy arrays, or PIL images) and outputs them as StreamData into the pipeline, similar to VideoSourceGizmo but for static images.

### IteratorSourceGizmo Methods <a href="#iteratorsourcegizmo-methods" id="iteratorsourcegizmo-methods"></a>

#### \_\_init\_\_(iterator, ...) <a href="#init" id="init"></a>

`__init__(iterator, *, fps=0.0)`

Constructor.

Parameters:

| Name       | Type       | Description                                                                                                                                                | Default    |
| ---------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `iterator` | `Iterator` | An iterator that yields images. Each yielded item can be: - str: path to an image file - numpy.ndarray: image as numpy array - PIL.Image: PIL image object | *required* |
| `fps`      | `float`    | Optional FPS value to include in metadata (default 0.0, meaning not applicable)                                                                            | `0.0`      |

#### get\_tags <a href="#get_tags" id="get_tags"></a>

`get_tags()`

Get list of tags assigned to this gizmo.

Returns:

| Type        | Description                                                   |
| ----------- | ------------------------------------------------------------- |
| `List[str]` | List\[str]: Tags for this gizmo (its name and the video tag). |

#### run <a href="#run" id="run"></a>

`run()`

Run the iterator source loop.

Iterates over the iterator, converts each item to a numpy array image, creates appropriate metadata (similar to VideoSourceGizmo), and sends the results downstream.

## FPSStabilizingGizmo <a href="#fpsstabilizinggizmo" id="fpsstabilizinggizmo"></a>

`FPSStabilizingGizmo`

Bases: `Gizmo`

FPS stabilizing gizmo that maintains stable frame rate by sending fake frames when input is empty.

When the input queue has frames available, they are sent through as-is. When the input queue is empty, fake frames are generated by gradually shading the last genuine frame to maintain the target FPS derived from video metadata.

### FPSStabilizingGizmo Methods <a href="#fpsstabilizinggizmo-methods" id="fpsstabilizinggizmo-methods"></a>

#### \_\_init\_\_(\*, ...) <a href="#init" id="init"></a>

`__init__(*, stream_depth=10, allow_drop=False)`

Constructor.

Parameters:

| Name           | Type   | Description                                                                   | Default |
| -------------- | ------ | ----------------------------------------------------------------------------- | ------- |
| `stream_depth` | `int`  | Depth of the input frame queue. Defaults to 10.                               | `10`    |
| `allow_drop`   | `bool` | If True, allow dropping frames if the input queue is full. Defaults to False. | `False` |

#### require\_tags(inp) <a href="#require_tags" id="require_tags"></a>

`require_tags(inp)`

Get the list of meta tags this gizmo requires in upstream meta for a specific input.

Returns:

| Type | Description                                                                       |
| ---- | --------------------------------------------------------------------------------- |
|      | List\[str]: Tags required by this gizmo in upstream meta for the specified input. |

#### run <a href="#run" id="run"></a>

`run()`

Run the FPS stabilizing loop.

Continuously reads frames from input queue and sends them downstream. When the input queue is empty, generates fake frames by gradually shading the last genuine frame to maintain stable FPS derived from video metadata.

## VideoDisplayGizmo <a href="#videodisplaygizmo" id="videodisplaygizmo"></a>

`VideoDisplayGizmo`

Bases: `Gizmo`

OpenCV-based video display gizmo.

Displays incoming frames in one or more OpenCV windows.

### VideoDisplayGizmo Methods <a href="#videodisplaygizmo-methods" id="videodisplaygizmo-methods"></a>

#### \_\_init\_\_(window\_titles='Display', ...) <a href="#init" id="init"></a>

`__init__(window_titles='Display', *, show_ai_overlay=False, show_fps=False, stream_depth=10, allow_drop=False, multiplex=False)`

Constructor.

Parameters:

| Name              | Type               | Description                                                                                                                                                                   | Default     |
| ----------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `window_titles`   | `str or List[str]` | Title or list of titles for the display window(s). If a list is provided, multiple windows are opened (one per title). Defaults to "Display".                                 | `'Display'` |
| `show_ai_overlay` | `bool`             | If True, overlay AI inference results on the displayed frame (when available). Defaults to False.                                                                             | `False`     |
| `show_fps`        | `bool`             | If True, show the FPS on the display window(s). Defaults to False.                                                                                                            | `False`     |
| `stream_depth`    | `int`              | Depth of the input frame queue. Defaults to 10.                                                                                                                               | `10`        |
| `allow_drop`      | `bool`             | If True, allow dropping frames if the input queue is full. Defaults to False.                                                                                                 | `False`     |
| `multiplex`       | `bool`             | If True, use a single input stream and display frames in a round-robin across multiple windows; if False, each window corresponds to its own input stream. Defaults to False. | `False`     |

Raises:

| Type        | Description                                                                      |
| ----------- | -------------------------------------------------------------------------------- |
| `Exception` | If multiplex is True while allow\_drop is also True (unsupported configuration). |

#### run <a href="#run" id="run"></a>

`run()`

Run the video display loop.

Fetches frames from the input stream(s) and shows them in the window(s) (with optional overlays and FPS display) until all inputs are exhausted or aborted.

## VideoSaverGizmo <a href="#videosavergizmo" id="videosavergizmo"></a>

`VideoSaverGizmo`

Bases: `Gizmo`

Video saving gizmo.

Writes incoming frames to an output video file.

### VideoSaverGizmo Methods <a href="#videosavergizmo-methods" id="videosavergizmo-methods"></a>

#### \_\_init\_\_(filename, ...) <a href="#init" id="init"></a>

`__init__(filename, *, show_ai_overlay=False, stream_depth=10, allow_drop=False)`

Constructor.

Parameters:

| Name              | Type   | Description                                                                                        | Default    |
| ----------------- | ------ | -------------------------------------------------------------------------------------------------- | ---------- |
| `filename`        | `str`  | Path to the output video file.                                                                     | *required* |
| `show_ai_overlay` | `bool` | If True, overlay AI inference results on frames before saving (when available). Defaults to False. | `False`    |
| `stream_depth`    | `int`  | Depth of the input frame queue. Defaults to 10.                                                    | `10`       |
| `allow_drop`      | `bool` | If True, allow dropping frames if the input queue is full. Defaults to False.                      | `False`    |

#### run <a href="#run" id="run"></a>

`run()`

Run the video saving loop.

Reads frames from the input stream and writes them to the output file until the stream is exhausted or aborted.

## VideoStreamerGizmo <a href="#videostreamergizmo" id="videostreamergizmo"></a>

`VideoStreamerGizmo`

Bases: `Gizmo`

Video streaming gizmo.

Streams incoming frames to RTSP/RTMP stream using ffmpeg. `MediaServer` must be running to accept the stream.

### VideoStreamerGizmo Methods <a href="#videostreamergizmo-methods" id="videostreamergizmo-methods"></a>

#### \_\_init\_\_(stream\_url, ...) <a href="#init" id="init"></a>

`__init__(stream_url, *, fps=0, show_ai_overlay=False, stream_depth=10, allow_drop=False)`

Constructor.

Parameters:

| Name              | Type    | Description                                                                                                                                                                                                        | Default    |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `stream_url`      | `str`   | RTMP/RTSP URL to stream to (e.g., 'rtsp\://user:password\@hostname:port/stream'). Typically you use `MediaServer` class to start media server and then use its RTMP/RTSP URL like `rtsp://localhost:8554/mystream` | *required* |
| `fps`             | `float` | Frames per second for the stream. Defaults to 0, meaning to deduce from upstream video source.                                                                                                                     | `0`        |
| `show_ai_overlay` | `bool`  | If True, overlay AI inference results on frames before saving (when available). Defaults to False.                                                                                                                 | `False`    |
| `stream_depth`    | `int`   | Depth of the input frame queue. Defaults to 10.                                                                                                                                                                    | `10`       |
| `allow_drop`      | `bool`  | If True, allow dropping frames if the input queue is full. Defaults to False.                                                                                                                                      | `False`    |

#### run <a href="#run" id="run"></a>

`run()`

Run the video saving loop.

Reads frames from the input stream and writes them to the output file until the stream is exhausted or aborted.

## ResizingGizmo <a href="#resizinggizmo" id="resizinggizmo"></a>

`ResizingGizmo`

Bases: `Gizmo`

OpenCV-based image resizing/padding gizmo.

Resizes incoming images to a specified width and height, using the chosen padding or cropping method.

### ResizingGizmo Methods <a href="#resizinggizmo-methods" id="resizinggizmo-methods"></a>

#### \_\_init\_\_(w, ...) <a href="#init" id="init"></a>

`__init__(w, h, pad_method='letterbox', resize_method='bilinear', stream_depth=10, allow_drop=False)`

Constructor.

Parameters:

| Name            | Type   | Description                                                                                             | Default       |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------- | ------------- |
| `w`             | `int`  | Target width for output images.                                                                         | *required*    |
| `h`             | `int`  | Target height for output images.                                                                        | *required*    |
| `pad_method`    | `str`  | Padding method to use ("stretch", "letterbox", "crop-first", "crop-last"). Defaults to "letterbox".     | `'letterbox'` |
| `resize_method` | `str`  | Resampling method to use ("nearest", "bilinear", "area", "bicubic", "lanczos"). Defaults to "bilinear". | `'bilinear'`  |
| `stream_depth`  | `int`  | Depth of the input frame queue. Defaults to 10.                                                         | `10`          |
| `allow_drop`    | `bool` | If True, allow dropping frames if the input queue is full. Defaults to False.                           | `False`       |

#### get\_tags <a href="#get_tags" id="get_tags"></a>

`get_tags()`

Get list of tags assigned to this gizmo.

Returns:

| Type        | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| `List[str]` | List\[str]: Tags for this gizmo (its name and the resize tag). |

#### run <a href="#run" id="run"></a>

`run()`

Run the resizing loop.

Resizes each input image according to the configured width, height, padding, and resizing method, then sends the result with updated metadata downstream.

## AiGizmoBase <a href="#aigizmobase" id="aigizmobase"></a>

`AiGizmoBase`

Bases: `Gizmo`

Base class for AI model inference gizmos.

Handles loading the model and iterating over input data for inference in a background thread.

### AiGizmoBase Methods <a href="#aigizmobase-methods" id="aigizmobase-methods"></a>

#### \_\_init\_\_(model, ...) <a href="#init" id="init"></a>

`__init__(model, *, analyzers=None, non_blocking_batch_predict_timeout_s=0.01, stream_depth=10, allow_drop=False, inp_cnt=1, **kwargs)`

Constructor.

Parameters:

| Name                                   | Type           | Description                                                                                                                                               | Default    |
| -------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `model`                                | `Model or str` | A DeGirum model object or model name string to load. If a string is provided, the model will be loaded via `degirum.load_model()` using the given kwargs. | *required* |
| `analyzers`                            | `list`         | List of analyzer objects to apply to inference results (e.g., EventDetector, EventNotifier instances). Defaults to None.                                  | `None`     |
| `non_blocking_batch_predict_timeout_s` | `float`        | Input queue get timeout for non-blocking batch prediction mode. Defaults to 0.001 seconds.                                                                | `0.01`     |
| `stream_depth`                         | `int`          | Depth of the input stream queue. Defaults to 10.                                                                                                          | `10`       |
| `allow_drop`                           | `bool`         | If True, allow dropping frames on input overflow. Defaults to False.                                                                                      | `False`    |
| `inp_cnt`                              | `int`          | Number of input streams (for models requiring multiple inputs). Defaults to 1.                                                                            | `1`        |
| `**kwargs`                             | `any`          | Additional parameters to pass to `degirum.load_model()` when loading the model (if model is given as a name).                                             | `{}`       |

#### get\_tags <a href="#get_tags" id="get_tags"></a>

`get_tags()`

Get list of tags assigned to this gizmo.

Returns:

| Type        | Description                                                       |
| ----------- | ----------------------------------------------------------------- |
| `List[str]` | List\[str]: Tags for this gizmo (its name and the inference tag). |

#### on\_result(result) <a href="#on_result" id="on_result"></a>

`on_result(result)`

`abstractmethod`

Handle a single inference result (to be implemented by subclasses).

Parameters:

| Name     | Type                                                                                                                             | Description                                 | Default    |
| -------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ---------- |
| `result` | [InferenceResults](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.inferenceresults) | The inference result object from the model. | *required* |

#### run <a href="#run" id="run"></a>

`run()`

Run the model inference loop.

Internally feeds data from the input stream(s) into the model and yields results, invoking `on_result` for each inference result.

## AiSimpleGizmo <a href="#aisimplegizmo" id="aisimplegizmo"></a>

`AiSimpleGizmo`

Bases: `AiGizmoBase`

AI inference gizmo with no custom result processing.

Passes through input frames and attaches the raw inference results to each frame's metadata.

### AiSimpleGizmo Methods <a href="#aisimplegizmo-methods" id="aisimplegizmo-methods"></a>

#### on\_result(result) <a href="#on_result" id="on_result"></a>

`on_result(result)`

Append the inference result to the input frame's metadata and send it downstream.

Parameters:

| Name     | Type                                                                                                                             | Description                                 | Default    |
| -------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ---------- |
| `result` | [InferenceResults](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.inferenceresults) | The inference result for the current frame. | *required* |

## AiObjectDetectionCroppingGizmo <a href="#aiobjectdetectioncroppinggizmo" id="aiobjectdetectioncroppinggizmo"></a>

`AiObjectDetectionCroppingGizmo`

Bases: `Gizmo`

Gizmo that crops detected objects from frames of an object detection model.

Each input frame with object detection results yields one or more cropped images as output.

Output

* **Image**: The cropped portion of the original image corresponding to a detected object.
* **Meta-info**: A dictionary containing:
  * `original_result`: Reference to the original detection result ([InferenceResults](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.inferenceresults)) for the frame.
  * `cropped_result`: The detection result entry for this specific crop.
  * `cropped_index`: The index of this object in the original results list.
  * `is_last_crop`: True if this crop is the last one for the frame.

Note

`cropped_index` and `is_last_crop` are only present if at least one object is detected in the frame.

The `validate_bbox()` method can be overridden in subclasses to filter out undesirable detections.

### AiObjectDetectionCroppingGizmo Methods <a href="#aiobjectdetectioncroppinggizmo-methods" id="aiobjectdetectioncroppinggizmo-methods"></a>

#### \_\_init\_\_(labels, ...) <a href="#init" id="init"></a>

`__init__(labels, *, send_original_on_no_objects=True, crop_extent=0.0, crop_extent_option=CropExtentOptions.ASPECT_RATIO_NO_ADJUSTMENT, crop_aspect_ratio=1.0, stream_depth=10, allow_drop=False)`

Constructor.

Parameters:

| Name                          | Type                | Description                                                                                                                       | Default                      |
| ----------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `labels`                      | `List[str]`         | List of class labels to process. Only objects whose class is in this list will be cropped.                                        | *required*                   |
| `send_original_on_no_objects` | `bool`              | If True, when no objects are detected in a frame, the original frame is sent through. Defaults to True.                           | `True`                       |
| `crop_extent`                 | `float`             | Extra padding around the bounding box, as a percentage of the bbox size. Defaults to 0.0.                                         | `0.0`                        |
| `crop_extent_option`          | `CropExtentOptions` | Method for applying the crop extent (e.g., aspect ratio adjustment). Defaults to CropExtentOptions.ASPECT\_RATIO\_NO\_ADJUSTMENT. | `ASPECT_RATIO_NO_ADJUSTMENT` |
| `crop_aspect_ratio`           | `float`             | Desired aspect ratio (W/H) for the cropped images. Defaults to 1.0.                                                               | `1.0`                        |
| `stream_depth`                | `int`               | Depth of the input frame queue. Defaults to 10.                                                                                   | `10`                         |
| `allow_drop`                  | `bool`              | If True, allow dropping frames on overflow. Defaults to False.                                                                    | `False`                      |

#### get\_tags <a href="#get_tags" id="get_tags"></a>

`get_tags()`

Get list of tags assigned to this gizmo.

Returns:

| Type        | Description                                                  |
| ----------- | ------------------------------------------------------------ |
| `List[str]` | List\[str]: Tags for this gizmo (its name and the crop tag). |

#### require\_tags(inp) <a href="#require_tags" id="require_tags"></a>

`require_tags(inp)`

Get the list of meta tags this gizmo requires in upstream meta for a specific input.

Returns:

| Type        | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| `List[str]` | List\[str]: Tags required by this gizmo in upstream meta for the specified input. |

#### run <a href="#run" id="run"></a>

`run()`

Run the object cropping loop.

For each input frame, finds all detected objects (matching the specified labels and passing validation) and sends out a cropped image for each. If no objects are detected and `send_original_on_no_objects` is True, the original frame is forwarded.

#### validate\_bbox(result, ...) <a href="#validate_bbox" id="validate_bbox"></a>

`validate_bbox(result, idx)`

Decide whether a detected object should be cropped (can be overridden in subclasses).

Parameters:

| Name     | Type                                                                                                                             | Description                                              | Default    |
| -------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------- |
| `result` | [InferenceResults](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.inferenceresults) | The detection result for the frame.                      | *required* |
| `idx`    | `int`                                                                                                                            | The index of the object in `result.results` to validate. | *required* |

Returns:

| Name   | Type   | Description                                                          |
| ------ | ------ | -------------------------------------------------------------------- |
| `bool` | `bool` | True if the object should be cropped; False if it should be skipped. |

## CropCombiningGizmo <a href="#cropcombininggizmo" id="cropcombininggizmo"></a>

`CropCombiningGizmo`

Bases: `Gizmo`

Gizmo to combine original frames with their after-crop results.

Expects N+1 inputs: one input stream of original frames (index 0), and N input streams of inference results from cropped images. This gizmo synchronizes and attaches the after-crop inference results back to each original frame's metadata.

### CropCombiningGizmo Methods <a href="#cropcombininggizmo-methods" id="cropcombininggizmo-methods"></a>

#### \_\_init\_\_(crop\_inputs\_num=1, ...) <a href="#init" id="init"></a>

`__init__(crop_inputs_num=1, *, stream_depth=10)`

Constructor.

Parameters:

| Name              | Type  | Description                                                                               | Default |
| ----------------- | ----- | ----------------------------------------------------------------------------------------- | ------- |
| `crop_inputs_num` | `int` | Number of crop result input streams (excluding the original frame stream). Defaults to 1. | `1`     |
| `stream_depth`    | `int` | Depth for each crop input stream's queue. Defaults to 10.                                 | `10`    |

#### require\_tags(inp) <a href="#require_tags" id="require_tags"></a>

`require_tags(inp)`

Get the list of meta tags this gizmo requires in upstream meta for a specific input.

Returns:

| Type        | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| `List[str]` | List\[str]: Tags required by this gizmo in upstream meta for the specified input. |

#### run <a href="#run" id="run"></a>

`run()`

Run the crop combining loop.

Synchronizes original frames with their corresponding after-crop result streams, merges the inference results from crops back into the original frame's metadata, and sends the updated frame downstream.

## AiResultCombiningGizmo <a href="#airesultcombininggizmo" id="airesultcombininggizmo"></a>

`AiResultCombiningGizmo`

Bases: `Gizmo`

Gizmo to combine inference results from multiple AI gizmos of the same type.

### AiResultCombiningGizmo Methods <a href="#airesultcombininggizmo-methods" id="airesultcombininggizmo-methods"></a>

#### \_\_init\_\_(inp\_cnt, ...) <a href="#init" id="init"></a>

`__init__(inp_cnt, *, stream_depth=10)`

Constructor.

Parameters:

| Name           | Type  | Description                                         | Default    |
| -------------- | ----- | --------------------------------------------------- | ---------- |
| `inp_cnt`      | `int` | Number of input result streams to combine.          | *required* |
| `stream_depth` | `int` | Depth of each input stream's queue. Defaults to 10. | `10`       |

#### get\_tags <a href="#get_tags" id="get_tags"></a>

`get_tags()`

Get list of tags assigned to this gizmo.

Returns:

| Type        | Description                                                       |
| ----------- | ----------------------------------------------------------------- |
| `List[str]` | List\[str]: Tags for this gizmo (its name and the inference tag). |

#### require\_tags(inp) <a href="#require_tags" id="require_tags"></a>

`require_tags(inp)`

Get the list of meta tags this gizmo requires in upstream meta for a specific input.

Returns:

| Type        | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| `List[str]` | List\[str]: Tags required by this gizmo in upstream meta for the specified input. |

#### run <a href="#run" id="run"></a>

`run()`

Run the result combining loop.

Collects inference results from all input streams, merges their results into a single combined result, and sends it downstream.

## AiPreprocessGizmo <a href="#aipreprocessgizmo" id="aipreprocessgizmo"></a>

`AiPreprocessGizmo`

Bases: `Gizmo`

Preprocessing gizmo that applies a model's preprocessor to input images.

It generates preprocessed image data to be fed into the model.

Output

* **Data**: Preprocessed image bytes ready for model input.
* **Meta-info**: Dictionary including:
  * `image_input`: The original input image.
  * `converter`: A function to convert coordinates from model output back to the original image.
  * `image_result`: The preprocessed image (present only if the model is configured to provide it).

Attributes:

| Name               | Type  | Description                                          |
| ------------------ | ----- | ---------------------------------------------------- |
| `key_image_input`  | `str` | Metadata key for the original input image.           |
| `key_converter`    | `str` | Metadata key for the coordinate conversion function. |
| `key_image_result` | `str` | Metadata key for the preprocessed image.             |

### AiPreprocessGizmo Methods <a href="#aipreprocessgizmo-methods" id="aipreprocessgizmo-methods"></a>

#### \_\_init\_\_(model, ...) <a href="#init" id="init"></a>

`__init__(model, *, stream_depth=10, allow_drop=False)`

Constructor.

Parameters:

| Name           | Type    | Description                                                     | Default    |
| -------------- | ------- | --------------------------------------------------------------- | ---------- |
| `model`        | `Model` | The model object (PySDK model) whose preprocessor will be used. | *required* |
| `stream_depth` | `int`   | Depth of the input frame queue. Defaults to 10.                 | `10`       |
| `allow_drop`   | `bool`  | If True, allow dropping frames on overflow. Defaults to False.  | `False`    |

#### get\_tags <a href="#get_tags" id="get_tags"></a>

`get_tags()`

Get list of tags assigned to this gizmo.

Returns:

| Type        | Description                                                        |
| ----------- | ------------------------------------------------------------------ |
| `List[str]` | List\[str]: Tags for this gizmo (its name and the preprocess tag). |

#### run <a href="#run" id="run"></a>

`run()`

Run the preprocessing loop.

Applies the model's preprocessor to each input frame and sends the resulting data (and updated meta-info) downstream.

## AiAnalyzerGizmo <a href="#aianalyzergizmo" id="aianalyzergizmo"></a>

`AiAnalyzerGizmo`

Bases: `Gizmo`

Gizmo to apply a chain of analyzers to an inference result, with optional filtering.

Each analyzer (e.g., EventDetector, EventNotifier) processes the inference result and may add events or notifications. If filters are provided, only results that contain at least one of the specified events/notifications are passed through.

### AiAnalyzerGizmo Methods <a href="#aianalyzergizmo-methods" id="aianalyzergizmo-methods"></a>

#### \_\_init\_\_(analyzers, ...) <a href="#init" id="init"></a>

`__init__(analyzers, *, filters=None, stream_depth=10, allow_drop=False)`

Constructor.

Parameters:

| Name           | Type   | Description                                                                                                                                                                                                 | Default    |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `analyzers`    | `List` | List of analyzer objects to apply (e.g., EventDetector, EventNotifier instances).                                                                                                                           | *required* |
| `filters`      | `set`  | A set of event names or notification names to filter results. Only results that have at least one of these events or notifications will be forwarded (others are dropped). Defaults to None (no filtering). | `None`     |
| `stream_depth` | `int`  | Depth of the input frame queue. Defaults to 10.                                                                                                                                                             | `10`       |
| `allow_drop`   | `bool` | If True, allow dropping frames on overflow. Defaults to False.                                                                                                                                              | `False`    |

#### get\_tags <a href="#get_tags" id="get_tags"></a>

`get_tags()`

Get list of tags assigned to this gizmo.

Returns:

| Type        | Description                                                                          |
| ----------- | ------------------------------------------------------------------------------------ |
| `List[str]` | List\[str]: Tags for this gizmo (its name, the inference tag, and the analyzer tag). |

#### require\_tags(inp) <a href="#require_tags" id="require_tags"></a>

`require_tags(inp)`

Get the list of meta tags this gizmo requires in upstream meta for a specific input.

Returns:

| Type        | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| `List[str]` | List\[str]: Tags required by this gizmo in upstream meta for the specified input. |

#### run <a href="#run" id="run"></a>

`run()`

Run the analyzer processing loop.

For each input frame, clones its inference result and runs all analyzers on it (which may add events/notifications). If filters are specified, the result is dropped unless it contains at least one of the specified events or notifications. The possibly modified inference result is appended to the frame's metadata and sent downstream. After processing all frames, all analyzers are finalized.

## SinkGizmo <a href="#sinkgizmo" id="sinkgizmo"></a>

`SinkGizmo`

Bases: `Gizmo`

Sink gizmo that receives results and accumulates them in an internal queue.

This gizmo does not send data further down the pipeline. Instead, it stores all incoming results so they can be retrieved (for example, by iterating over the gizmo's output in the main thread).

### SinkGizmo Methods <a href="#sinkgizmo-methods" id="sinkgizmo-methods"></a>

#### \_\_call\_\_ <a href="#call" id="call"></a>

`__call__()`

Retrieve the internal queue for iteration.

Returns:

| Name     | Type     | Description                                                                                  |
| -------- | -------- | -------------------------------------------------------------------------------------------- |
| `Stream` | `Stream` | The input Stream (queue) of this sink gizmo, which can be iterated to get collected results. |

#### \_\_init\_\_(\*, ...) <a href="#init" id="init"></a>

`__init__(*, stream_depth=10, allow_drop=False)`

Constructor.

Parameters:

| Name           | Type   | Description                                                    | Default |
| -------------- | ------ | -------------------------------------------------------------- | ------- |
| `stream_depth` | `int`  | Depth of the input queue. Defaults to 10.                      | `10`    |
| `allow_drop`   | `bool` | If True, allow dropping frames on overflow. Defaults to False. | `False` |

#### run <a href="#run" id="run"></a>

`run()`

Run gizmo (no operation).

Immediately returns, as the sink simply collects incoming data without processing.