Script API Reference

Helios provides an MCP server for local automation, a server API for trusted Online Resources integrations, and CV APIs for scripts that read input state, analyze images, run models, read text, draw overlays, and publish compact data.

Use these pages after installing and selecting either CV Python or CV C++. For controller-only scripts, use the GPC 3 reference.

Choose a Reference

Python Worker

Helios creates CVWorker with the capture size and calls process(frame) for each frame. The frame is an HxWx3 uint8 BGR image.

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

    def process(self, frame):
        pass

    def close(self):
        pass  # Optional cleanup before unload or restart

Process the borrowed frame in place and do not retain it across callbacks. Put model creation and other one-time setup in __init__, not in the per-frame method. Use helios.controls.send_cvdata() to publish compact bytes. Define close() only when the worker owns resources that need cleanup.

Persistent Script Data

Use the script data directory for settings or calibration results that should survive downloads and updates. Obtain the path once during worker initialization, then use normal file I/O:

from helios import storage

data_dir = storage.data_directory()  # pathlib.Path
settings_file = data_dir / "settings.json"

In C++, include <helios/HeliosStorageSDK.hpp> and call Helios::Storage::dataDirectory() for a std::filesystem::path; HeliosCVSDK.h also includes it. Obtain it from the worker, not DllMain.

The folder is under %LOCALAPPDATA%\HeliosProject\Helios\ScriptData, named for the script filename without its final extension. Moving or updating the same-named script reuses its data. Renaming it selects a different folder. Python and C++ scripts with the same basename share data, even if they come from different authors, so choose a distinctive filename and keep your own files clearly named.

App updates, deleting the script, and clearing caches do not erase this data. Users can remove it explicitly when they want a reset. Handle ordinary file errors and avoid writing on every frame.

Look Latency Calibration

Calibration measures output submission to captured horizontal scene motion. It includes the selected output path, application response, and capture delay; it is not physical button-to-display latency. Frame timing limits its accuracy. No inference model is required.

Start video capture and a ready controller-output destination. Stand still, face a textured scene, and release controls before starting. Calibration temporarily takes control of participating outputs and moves the view with short horizontal pulses. Normal forwarding resumes when it finishes or is cancelled.

Keep one session per CV host and close it before creating another. Poll without blocking the frame callback. Only accept the result when busy is false, phase is "complete", and restored is true. Failed or cancelled batches can contain partial samples and must not be treated as completed calibration. Results include millisecond samples, average, median, minimum/maximum, and observed timing bounds.

By default, all ready outputs supporting controller input participate. Pass plugin to select one exact output name. Optional x_axis and y_axis use 0=right_x, 1=right_y, 2=left_x, 3=left_y; defaults are 0 and 1. Set invert_x to match the application’s horizontal inversion. held_input can hold controller buttons, keyboard keys/modifiers, or mouse buttons for the measurement; it cannot hold stick axes, mouse movement, or scrolling. See the packaged SDK for complete options.

For C++, include <helios/HeliosCalibrationSDK.hpp> and keep a Helios::Calibration::Client in the worker. Call start(10) or start(options), read changed snapshots with readIfChanged(HeliosCalibrationStatus&), and use cancel() to stop. Accept only a non-busy status with phase == HELIOS_CALIBRATION_COMPLETE and restored != 0. The current C++ API uses typed status structures; rebuild older JSON-based calibration code with the current SDK.

An MCP client can use helios_calibration without loading a CV or GPC script. See MCP Server.

If a measurement fails, check capture continuity, output readiness, scene texture, and horizontal inversion. Avoid moving controls or changing capture during the batch. Repeat measurements under the same conditions before using their median.

Common Workflow

The Compute GPU selected in Helios Preferences is used for inference, OCR, and other accelerated vision work.