# Image overlay

*Estimated read time: 4 minutes*

The rendered image you see comes from the result's `image_overlay`—your original frame with detections, keypoints, and (if applicable) segments drawn on top. Overlay settings affect only visualization; they do not change predictions, scores, or NMS behavior. The appearance is controlled by the properties below.

## What you can change

The examples below show seven overlay presets applied to the same frame.

{% tabs %}
{% tab title="Labels only" %}

<figure><img src="https://1657109811-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaQsuJ8iXkszyOgIpNy8w%2Fuploads%2Fgit-blob-3dbd91702d64044cbe24f67995cefbbfa1f309b5%2Fhailo-cookbook--image-overlay--labels-only.png?alt=media" alt="Detection overlay showing default labels without scores or color changes."><figcaption><p>Baseline overlay: labels on, probabilities hidden.</p></figcaption></figure>
{% endtab %}

{% tab title="Labels hidden" %}

<figure><img src="https://1657109811-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaQsuJ8iXkszyOgIpNy8w%2Fuploads%2Fgit-blob-af70495649a0dc0f7b0d2696f5a4b5ea7628cc3e%2Fhailo-cookbook--image-overlay--labels-hidden.png?alt=media" alt="Detection overlay with bounding boxes but no text labels."><figcaption><p>Label text removed for a low-clutter view.</p></figcaption></figure>
{% endtab %}

{% tab title="Cyan palette" %}

<figure><img src="https://1657109811-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaQsuJ8iXkszyOgIpNy8w%2Fuploads%2Fgit-blob-d0558467b1c288c9b91e7cf30e30d8105e583e4f%2Fhailo-cookbook--image-overlay--cyan-palette.png?alt=media" alt="Detection overlay recolored to a cyan palette with translucent fills."><figcaption><p>Custom cyan color palette with semi-transparent fills.</p></figcaption></figure>
{% endtab %}

{% tab title="Selective blur" %}

<figure><img src="https://1657109811-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaQsuJ8iXkszyOgIpNy8w%2Fuploads%2Fgit-blob-51f372024fa241de0e9854ed026bfdc48658209f%2Fhailo-cookbook--image-overlay--person-blur.png?alt=media" alt="Detection overlay with the person class blurred for privacy."><figcaption><p>Selective blur hides <code>person</code> detections.</p></figcaption></figure>
{% endtab %}

{% tab title="Scores shown" %}

<figure><img src="https://1657109811-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaQsuJ8iXkszyOgIpNy8w%2Fuploads%2Fgit-blob-9434e79a236140902dd74cc8333071f17b7f288b%2Fhailo-cookbook--image-overlay--scores-visible.png?alt=media" alt="Detection overlay displaying probability scores next to each label."><figcaption><p>Probability scores displayed alongside labels.</p></figcaption></figure>
{% endtab %}

{% tab title="Large labels" %}

<figure><img src="https://1657109811-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaQsuJ8iXkszyOgIpNy8w%2Fuploads%2Fgit-blob-172afce792c724071435330e39fed1724f7c966b%2Fhailo-cookbook--image-overlay--large-labels.png?alt=media" alt="Detection overlay with double-sized label text."><figcaption><p>Font scale doubled for large-format screens.</p></figcaption></figure>
{% endtab %}

{% tab title="Thick boxes" %}

<figure><img src="https://1657109811-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaQsuJ8iXkszyOgIpNy8w%2Fuploads%2Fgit-blob-db258f4bb917e0901edc72199ff3e9667527f710%2Fhailo-cookbook--image-overlay--thick-boxes.png?alt=media" alt="Detection overlay with wider bounding box outlines."><figcaption><p>Bounding boxes drawn with thicker lines.</p></figcaption></figure>
{% endtab %}
{% endtabs %}

* `overlay_show_labels` **(bool)**: Show or hide class names.
  * Use `False` for low-clutter dashboards.
* `overlay_show_probabilities` **(bool)**: Show or hide scores next to labels.
  * Hide in demos to reduce visual noise.
* `overlay_line_width` **(int)**: Thickness of boxes and lines.
  * **Typical range**: 1–4. Increase for high-res or bright scenes.
* `overlay_font_scale` **(float)**: Label text size.
  * **Typical range**: 0.5–0.9. Scale with your stream resolution.
* `overlay_alpha` **(float 0–1)**: Box fill opacity.
  * **Typical range**: 0.2–0.5. Lower values make more background visible.
* `overlay_color` **(RGB tuple or list of RGB tuples, writable)**: Colors used for overlay elements.
  * **Single tuple**: One color for everything (points, boxes, labels, segments).
  * **List of tuples**: Behavior depends on model type:
    * **Classification**: Different label colors per class.
    * **Detection**: Different box/label colors per class.
    * **Pose**: Different keypoint colors per person.
    * **Segmentation**: Different segment colors per class.
  * If the list is shorter than the number of classes, colors are cycled.
  * **Defaults**:
    * **Most models**: Single yellow RGB tuple.
    * **Segmentation models**: Auto-generated palette (one color per class).
  * Use `label_dictionary` to inspect class names.
* `overlay_blur` **(writable)**: Blur policy for the overlay.
  * `None`: No blur.
  * `"all"`: Blur all detected objects.
  * **A class label or list of labels**: Blur only those classes (from `label_dictionary`).

## Minimal Inspection

Run this quick check to confirm the overlay configuration your model exposes.

{% code overflow="wrap" %}

```python
from degirum_tools import ModelSpec, remote_assets

spec = ModelSpec(
    model_name="yolov8n_coco--640x640_quant_hailort_multidevice_1",
    zoo_url="degirum/hailo",
    inference_host_address="@local",
    model_properties={
        "device_type": ["HAILORT/HAILO8L", "HAILORT/HAILO8"],
    },
)
model = spec.load_model()
model(remote_assets.urban_picnic_elephants)

print("labels:", model.overlay_show_labels)
print("probs:", model.overlay_show_probabilities)
print("line width:", model.overlay_line_width)
print("font scale:", model.overlay_font_scale)
print("alpha:", model.overlay_alpha)
print("color:", model.overlay_color)
print("blur:", getattr(model, "overlay_blur", None))
```

{% endcode %}

Example output:

{% code overflow="wrap" %}

```bash
labels: True
probs: False
line width: 3
font scale: 1.0
alpha: auto
color: [(255, 255, 0), (0, 128, 0), (0, 128, 128), (128, 0, 0), (128, 0, 128), (128, 128, 0), (128, 128, 128), (0, 0, 64), (0, 0, 192), (0, 128, 64), (0, 128, 192), (128, 0, 64), (128, 0, 192), (128, 128, 64), (128, 128, 192), (0, 64, 0), (0, 64, 128), (0, 192, 0), (0, 192, 128), (128, 64, 0), (128, 64, 128), (128, 192, 0), (128, 192, 128), (0, 64, 64), (0, 64, 192), (0, 192, 64), (0, 192, 192), (128, 64, 64), (128, 64, 192), (128, 192, 64), (128, 192, 192), (64, 0, 0), (64, 0, 128), (64, 128, 0), (64, 128, 128), (192, 0, 0), (192, 0, 128), (192, 128, 0), (192, 128, 128), (64, 0, 64), (64, 0, 192), (64, 128, 64), (64, 128, 192), (192, 0, 64), (192, 0, 192), (192, 128, 64), (192, 128, 192), (64, 64, 0), (64, 64, 128), (64, 192, 0), (64, 192, 128), (192, 64, 0), (192, 64, 128), (192, 192, 0), (192, 192, 128), (64, 64, 64), (64, 64, 192), (64, 192, 64), (64, 192, 192), (192, 64, 64), (192, 64, 192), (192, 192, 64), (192, 192, 192), (0, 0, 32), (0, 0, 160), (0, 128, 32), (0, 128, 160), (128, 0, 32), (128, 0, 160), (128, 128, 32), (128, 128, 160), (0, 0, 96), (0, 0, 224), (0, 128, 96), (0, 128, 224), (128, 0, 96), (128, 0, 224), (128, 128, 96), (128, 128, 224), (0, 64, 32)]
blur: None
```

{% endcode %}