Overlay Drawing

helios.overlay draws shapes and text and displays image, animation, text, and controller assets. CV C++ provides the same features under Helios::Overlay.

Draw primitives inside process(frame). Load reusable assets during worker setup and show or hide them as needed.

Targets

The default target is BOTH, so a drawing appears on the processed frame and the Fuser output. Set FRAME or FUSER explicitly when only one output should receive it.

Python Example

from helios import overlay


class CVWorker:
    def __init__(self, width, height):
        pass

    def process(self, frame):
        overlay.rect(
            100, 100, 300, 220,
            color=(0, 255, 0),
            thickness=2,
            target=overlay.BOTH,
        )
        overlay.circle(
            200, 160, 18,
            color=(255, 0, 0),
            filled=True,
        )
        overlay.text(
            "TARGET",
            200, 90,
            color=(255, 255, 255),
            background_color=(0, 0, 0),
            background_alpha=140,
            padding=5,
            anchor=overlay.BOTTOM_CENTER,
        )

Overlay colors use RGB order. A four-value color tuple may include alpha, and an explicit alpha= value takes priority.

Primitives

overlay.line(x1, y1, x2, y2, color=(255, 255, 255),
             thickness=1, target=overlay.BOTH, alpha=None,
             space=overlay.PIXELS)

overlay.rect(x1, y1, x2, y2, color=(255, 255, 255),
             thickness=1, target=overlay.BOTH, alpha=None,
             filled=False, space=overlay.PIXELS)

overlay.circle(x, y, radius, color=(255, 255, 255),
               thickness=1, target=overlay.BOTH, alpha=None,
               filled=False, space=overlay.PIXELS)

overlay.text(value, x, y, color=(255, 255, 255), scale=2,
             target=overlay.BOTH, alpha=None,
             background_color=(0, 0, 0), background_alpha=None,
             padding=0, anchor=overlay.TOP_LEFT,
             space=overlay.PIXELS)

overlay.rectangle(...) is an alias for overlay.rect(...). A rectangle or circle is filled when filled=True or its thickness is zero or negative.

Coordinates and Text Anchors

overlay.PIXELS uses the current frame's pixel coordinates. overlay.DESIGN_1080P lets a fixed HUD layout scale from a 1920×1080 design.

Text anchors are:

• TOP_LEFT, TOP_CENTER, TOP_RIGHT
• CENTER_LEFT, CENTER, CENTER_RIGHT
• BOTTOM_LEFT, BOTTOM_CENTER, BOTTOM_RIGHT

Primitive text has a black background with alpha 128 by default. Pass background_color=None or zero background alpha to remove it. On the Fuser output, a text background appears as an opaque box so it remains visible. This differs from load_text(), whose asset background defaults to none.

Images, Animations, Text, and Controller Overlays

Load assets once, then show or hide them without loading them again every frame:

from helios import overlay


class CVWorker:
    def __init__(self, width, height):
        self.label = overlay.load_text(
            "Preview", size=32, background=(16, 16, 16, 160), padding=8
        )
        self.label.show(16, 16, anchor="top_left")
        self.controller = overlay.load_controller(
            "xbox", height=max(1, height // 4), source="report"
        )
        self.controller.show(16, 16, anchor="bottom_right")

    def process(self, frame):
        pass

Relative image paths resolve beside the Python script. Specify image dimensions to reduce a large animation before displaying it. A text asset supports update(value); update only when the text changes and use a fixed width/height if changing text must fit a stable canvas.

Every asset supports:

asset.show(x=0, y=0, anchor="top_left", opacity=1.0,
           duration_ms=0, loop=True, fade_in_ms=0,
           fade_out_ms=0, target=overlay.BOTH)
asset.hide()
asset.unload()

Asset anchors are top_left, top, top_right, left, center, right, bottom_left, bottom, and bottom_right. Offsets move inward from the selected anchor in actual frame pixels. Opacity accepts 0..1. Duration 0 keeps an asset visible until hidden; loop=False plays an animation once and hides it. A fade-out needs a bounded display duration or a one-shot animation.

Calling show() again while an asset remains active updates its placement without restarting its animation or timer. Call hide() first to restart it. Assets appear on the selected output, including the processed frame after the script callback. Loaded assets are released when the script session ends. Do not use an asset after unloading it.

C++

Helios::Overlay::rect(
    100, 100, 300, 220,
    Helios::Overlay::Color{0, 255, 0},
    2,
    Helios::Overlay::Target::Both);

Helios::Overlay::text(
    200, 90,
    "TARGET",
    Helios::Overlay::Color{255, 255, 255},
    2,
    Helios::Overlay::Target::Fuser,
    Helios::Overlay::TextAnchor::BottomCenter);

C++ also provides line, circle, coordinate-space selection, alpha colors, text backgrounds, and OpenCV convenience overloads. Helios::Overlay::Color uses RGB; OpenCV cv::Scalar overloads use their usual BGR order.

For reusable assets, the packaged SDK provides loadImageFile(...), loadImage(...) for encoded bytes, loadText(...), updateText(...), loadController(...), showImage(...), hideImage(...), and unloadImage(...). Use TextStyle and Placement from HeliosCVSDK.h for text and placement options. C++ placement opacity uses 0..255. The corresponding public C declarations are in HeliosOverlayImageABI.h; use those headers directly when writing another native language binding.

Use OpenCV drawing when a script needs OpenCV-specific fonts, contours, polygons, ellipses, or line styles.

Raw Video Preview

Enable Preferences → Other → Video Display → Disable Overlay Drawing when you need to inspect the unannotated video. Helios continues script, inference, and OCR processing and still produces results, but skips their drawing and reusable overlay assets on both the frame and Fuser outputs.