Streams Gizmos
Classes
VideoSourceGizmo
VideoSourceGizmo
Bases: Gizmo
OpenCV-based video source gizmo.
Captures frames from a video source (camera, video file, etc.) and outputs them as StreamData into the pipeline.
Functions
__init__(video_source=None, ...)
__init__(video_source=None, *, stop_composition_on_end=False)
Constructor.
Parameters:
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
stop_composition_on_end
bool
If True, stop the Composition when the video source is over. Defaults to False.
False
run
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.
VideoDisplayGizmo
VideoDisplayGizmo
Bases: Gizmo
OpenCV-based video display gizmo.
Displays incoming frames in one or more OpenCV windows.
Functions
__init__(window_titles='Display', ...)
__init__(window_titles='Display', *, show_ai_overlay=False, show_fps=False, stream_depth=10, allow_drop=False, multiplex=False)
Constructor.
Parameters:
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:
Exception
If multiplex is True while allow_drop is also True (unsupported configuration).
run
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
VideoSaverGizmo
Bases: Gizmo
OpenCV-based video saving gizmo.
Writes incoming frames to an output video file.
Functions
__init__(filename, ...)
__init__(filename, *, show_ai_overlay=False, stream_depth=10, allow_drop=False)
Constructor.
Parameters:
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
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
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.
Functions
__init__(w, ...)
__init__(w, h, pad_method='letterbox', resize_method='bilinear', stream_depth=10, allow_drop=False)
Constructor.
Parameters:
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
run
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
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.
Functions
__init__(model, ...)
__init__(model, *, stream_depth=10, allow_drop=False, inp_cnt=1, **kwargs)
Constructor.
Parameters:
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
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).
{}
on_result(result)
on_result(result)abstractmethod
Handle a single inference result (to be implemented by subclasses).
Parameters:
result
InferenceResults
The inference result object from the model.
required
run
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
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.
Functions
on_result(result)
on_result(result)
Append the inference result to the input frame's metadata and send it downstream.
Parameters:
result
InferenceResults
The inference result for the current frame.
required
AiObjectDetectionCroppingGizmo
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) 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.
Functions
__init__(labels, ...)
__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:
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
run
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, ...)
validate_bbox(result, idx)
Decide whether a detected object should be cropped (can be overridden in subclasses).
Parameters:
result
InferenceResults
The detection result for the frame.
required
idx
int
The index of the object in result.results to validate.
required
Returns:
bool
bool
True if the object should be cropped; False if it should be skipped.
CropCombiningGizmo
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.
Functions
__init__(crop_inputs_num=1, ...)
__init__(crop_inputs_num=1, *, stream_depth=10)
Constructor.
Parameters:
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
_adjust_results(orig_result, ...)
_adjust_results(orig_result, bbox_idx, cropped_results)
Adjust inference results from a crop to the original image's coordinate space.
This converts the coordinates (e.g., bounding boxes, landmarks) of inference results obtained on a cropped image back to the coordinate system of the original image.
Parameters:
orig_result
InferenceResults
The original detection result (InferenceResults) for the full frame.
required
bbox_idx
int
The index of the object in the original result list.
required
cropped_results
list
A list of InferenceResults from the cropped image's inference.
required
Returns:
list
list
A list of adjusted InferenceResults corresponding to the original image coordinates.
_clone_result(result)
_clone_result(result)
Clone an inference result, deep-copying its _inference_results list.
Parameters:
result
InferenceResults
The inference result to clone.
required
Returns:
InferenceResults
A cloned inference result with a deep-copied results list.
run
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
AiResultCombiningGizmo
Bases: Gizmo
Gizmo to combine inference results from multiple AI gizmos of the same type.
Functions
__init__(inp_cnt, ...)
__init__(inp_cnt, *, stream_depth=10)
Constructor.
Parameters:
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
run
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
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:
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.
Functions
__init__(model, ...)
__init__(model, *, stream_depth=10, allow_drop=False)
Constructor.
Parameters:
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
run
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
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.
Functions
__init__(analyzers, ...)
__init__(analyzers, *, filters=None, stream_depth=10, allow_drop=False)
Constructor.
Parameters:
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
run
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
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).
Functions
__call__
__call__()
Retrieve the internal queue for iteration.
Returns:
Stream
The input Stream (queue) of this sink gizmo, which can be iterated to get collected results.
__init__(*, ...)
__init__(*, stream_depth=10, allow_drop=False)
Constructor.
Parameters:
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
run()
Run gizmo (no operation).
Immediately returns, as the sink simply collects incoming data without processing.
Last updated
Was this helpful?