Overview

We provide the DeGirum Tools Python module to aid development of AI applications with PySDK. In this group, we'll outline main concepts of DeGirum Tools and provide the API Reference Guide.

This overview was written for DeGirum Tools version 0.16.5.

Core Concepts

DeGirum Tools extends PySDK with a kit for building multi-threaded, low-latency media pipelines. Where PySDK focuses on running a single model well, DeGirum Tools focuses on everything around it: video ingest, pre-and post-processing, multi-model fusion, result annotation, stream routing, and more.

In one sentence:

DeGirum Tools is a flow-based mini-framework that lets you prototype complex AI applications in a few dozen lines of Python.

Streams

The flow behind DeGirum Tools is supported by the Streams subsystem. There are three constituent Python submodules: streams.py, streams_base.py, and streams_gizmos.py. In this subsystem, the two most important concepts to understand in streams are gizmos and compositions.

Gizmos

A Gizmo is a worker that:

1

Consumes from one or more input streams.

2

Runs its custom run() loop (decode, resize, infer, etc.).

3

Pushes new StreamData to any number of output streams. StreamData is described in more detail in streams.py.

Because every gizmo lives in its own thread, pipelines scale across CPU cores with almost no user code.

Gizmo families built into DeGirum Tools include:

Family	Example Classes	Typical Use
Video IO	VideoSourceGizmo, VideoDisplayGizmo, VideoSaverGizmo	Capture, live preview, archival
Transform	ResizingGizmo	Pre-process frames (letterbox, crop, pad)
AI Inference	AiSimpleGizmo, AiObjectDetectionCroppingGizmo	Run models, cascade detectors & classifiers
Post-fusion	CropCombiningGizmo, AiResultCombiningGizmo	Merge multi-crop or multi-model outputs
Utility	SinkGizmo	Collect results in the main thread

Gizmos pass data around by using the Stream class. A stream is an iterable queue that moves StreamData objects between threads. Each queue may be bounded (with optional drop policy) to prevent bottlenecks, and it automatically propagates a poison pill sentinel to shut the pipeline down cleanly.

Compositions

A Composition collects any connected gizmos and controls their life-cycle:

• start() – spawn threads

• stop() – signal abort & join

• wait() – block until completion

• get_bottlenecks() – diagnose dropped-frame hotspots

Use it as a context-manager so everything shuts down even on exceptions.

Compound Models

Compound models wrap two PySDK models into a singlepredict() / predict_batch() interface. Some compound models classes we provide in DeGirum Tools include:

Class	What it Does
CombiningCompoundModel	Runs two models in parallel on the same image and concatenates results.
CroppingAndClassifyingCompoundModel	Detector → crops → classifier (adds labels back).
CroppingAndDetectingCompoundModel	Detector → crops → refined detector (with optional NMS).

Use compound models exactly how you would use normal models:

compound = CroppingAndClassifyingCompoundModel(detector, classifier)
for res in compound.predict_batch(my_images):
    ...

Analyzers

Analyzers allow for advanced processing of inference results such as object tracking, line cross counting, in-zone counting, and more.

A ResultAnalyzerBase subclass can:

• analyze() – append extra fields, run business logic

• annotate() – draw overlays on the image

• Clean up in finalize().

Any number of analyzers can be attached to regular PySDK models and compound models:

attach_analyzers(my_model, [MyTracker(), MyNotifier()])

When used inside a gizmo pipeline, an analyzer can filter or decorate results in-flight.

Inference Support Utilities

The inference_support helpers smooth the edges between PySDK and your application. Inference Support utilities include:

• connect_model_zoo() – one-liner to pick AI Hub, AI Server, or local inference.
• predict_stream() / annotate_video() – quick video loops when a full gizmo graph is overkill.
• model_time_profile() – benchmark a model in <10 LOC.