Analyzers

DeGirum Tools API Reference Guide. Abstract base for result analyzers and overlays.

This API Reference is based on DeGirum Tools version 0.25.1.

Result Analyzer Base Module Overview

This module provides a base class (ResultAnalyzerBase) for performing custom post-processing and image annotation on DeGirum PySDK inference results. These analyzers can be used with compound models, streaming gizmos, and regular models to add advanced data processing and annotation steps to inference pipelines.

Key Concepts

• Analysis: By overriding the analyze() method, child classes can read and augment the InferenceResults (e.g., by adding extra keys to the internal results list).

• Annotation: By overriding the annotate() method, child classes can draw additional overlays on the original input image (e.g., bounding boxes, text labels, or any custom markings).

• Integration: Analyzers can be attached to a model or a compound model via the attach_analyzers() method, so their analysis and annotation is automatically applied to each inference result.

Typical Usage Example

1. Create a custom analyzer subclass:

   from degirum_tools import ResultAnalyzerBase

   class MyCustomAnalyzer(ResultAnalyzerBase):
       def analyze(self, result):
           # E.g., add custom fields to each detection
           for r in result.results:
               r["custom_info"] = "my_data"

       def annotate(self, result, image):
           # E.g., draw text or bounding boxes on the image
           # Return the annotated image
           return image

1. Attach it to a model or compound model:

   model.attach_analyzers(MyCustomAnalyzer())

1. Run inference. Each InferenceResults object will be passed through your analyzer, optionally modifying the result data and providing a new overlay.

Functions

image_overlay_substitute(result, ...)

image_overlay_substitute(result, analyzers)

Substitute the image_overlay property of the given inference result object so that future calls to result.image_overlay automatically apply the analyzers' annotate() methods.

This method creates a new class that inherits from the original result class and overrides the image_overlay property. The new class does the following:

1. Calls the base class's image_overlay property to get the image annotated by original result class.

2. Applies each analyzer's annotate() method to the image, in order.

Parameters:

Name	Type	Description	Default
result	InferenceResults	The inference result whose image_overlay property will be replaced.	required
analyzers	List[ResultAnalyzerBase]	A list of analyzer objects to apply for annotation.	required

clone_result(result)

clone_result(result)

Create a shallow clone of a DeGirum PySDK inference result object, duplicating the internal inference results list but reusing references to the original image.

This is useful when you want to create a separate copy of the result for further modifications without altering the original.

Parameters:

Name	Type	Description	Default
result	InferenceResults	The inference result object to clone.	required

Returns:

Type	Description
InferenceResults	A cloned result object with result._inference_results deep-copied.

Classes

ResultAnalyzerBase

ResultAnalyzerBase

Bases: ABC

Base class for result analyzers which can modify or extend the content of inference results and optionally annotate images with new data.

Subclasses should override

• analyze(result): to augment or inspect the inference result.

• annotate(result, image): to draw additional overlays or text onto the provided image.

ResultAnalyzerBase Methods

__del__

__del__()

Called when the analyzer object is about to be destroyed.

Invokes finalize() to ensure any open resources are cleaned up.

analyze(result)

analyze(result)

abstractmethod

Analyze and optionally modify a DeGirum PySDK inference result.

This method should access and potentially modify result.results (the list of detections, classifications, or similar structures) to add any custom fields. These modifications will then appear in downstream processes or when the result is displayed/serialized.

Parameters:

Name	Type	Description	Default
result	InferenceResults	The inference result object to analyze. Subclasses can read and/or modify the internal results list or other properties.	required

analyze_and_annotate(result, ...)

analyze_and_annotate(result, image)

Helper method to perform both analysis and annotation in one step.

1. Calls self.analyze(result).

2. Calls self.annotate(result, image).

Parameters:

Name	Type	Description	Default
result	InferenceResults	The inference result object to process.	required
image	ndarray	The image to annotate.	required

Returns:

Type	Description
ndarray	numpy.ndarray: The annotated image after analysis.

annotate(result, ...)

annotate(result, image)

Annotate an image with additional data derived from the analysis step.

Called after analyze() has been invoked on result. This method is typically used to draw bounding boxes, text, or other graphical elements representing the analysis data.

Parameters:

Name	Type	Description	Default
result	InferenceResults	The (already analyzed) inference result object.	required
image	ndarray	The original (or base) image to annotate.	required

Returns:

Type	Description
ndarray	numpy.ndarray: The annotated image. By default, this base implementation returns the image unchanged. Subclasses should override to perform custom drawing.

finalize

finalize()

Perform any finalization or cleanup actions before the analyzer is discarded.

This can be useful for analyzers that accumulate state (e.g., for multi-frame analysis). By default, this does nothing.