# Analyzers

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

## Result Analyzer Base Module Overview <a href="#result-analyzer-base-module-overview" id="result-analyzer-base-module-overview"></a>

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 <a href="#key-concepts" id="key-concepts"></a>

* **Analysis**: By overriding the `analyze()` method, child classes can read and augment the [InferenceResults](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.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 <a href="#typical-usage-example" id="typical-usage-example"></a>

1. Create a custom analyzer subclass:

{% code overflow="wrap" %}

```python
   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
```

{% endcode %}

2. Attach it to a model or compound model:

{% code overflow="wrap" %}

```
   model.attach_analyzers(MyCustomAnalyzer())
```

{% endcode %}

3. Run inference. Each [InferenceResults](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.inferenceresults) object will be passed through your analyzer, optionally modifying the result data and providing a new overlay.

## Functions <a href="#functions" id="functions"></a>

#### image\_overlay\_substitute(result, ...) <a href="#image_overlay_substitute" id="image_overlay_substitute"></a>

`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](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.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) <a href="#clone_result" id="clone_result"></a>

`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](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.inferenceresults) | The inference result object to clone. | *required* |

Returns:

| Type                                                                                                                             | Description                                                          |
| -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [InferenceResults](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.inferenceresults) | A cloned result object with `result._inference_results` deep-copied. |

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

## ResultAnalyzerBase <a href="#resultanalyzerbase" id="resultanalyzerbase"></a>

`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 <a href="#resultanalyzerbase-methods" id="resultanalyzerbase-methods"></a>

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

`__del__()`

Called when the analyzer object is about to be destroyed.

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

#### analyze(result) <a href="#analyze" id="analyze"></a>

`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](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.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, ...) <a href="#analyze_and_annotate" id="analyze_and_annotate"></a>

`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](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.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, ...) <a href="#annotate" id="annotate"></a>

`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](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.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 <a href="#finalize" id="finalize"></a>

`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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.degirum.com/degirum-tools/analyzers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.