Visualize Expression

Variadic image renderer driven by a Python expression. {{param:expression}} is evaluated via asteval with the variadic inputs bound to x0, x1, ... and helpers from NumPy / OpenCV / scikit-image / Matplotlib in scope. When {{param:icons}} is true the optional icons file slot is auto-scanned (PNG / JPG / JPEG / BMP / WEBP / SVG) and exposed as an icons dict keyed by filename stem. The result is coerced to a uint8 ndarray and emitted as an {{type:Image}} in {{param:output_color_model}}.

How it fits

{{type:t}} ($ts ...) -> {{component:visualize_expression}} -> {{type:Image}}
                          |
                          +-- bind the variadic inputs as `x0`, `x1`, ... in the asteval environment
                          +-- when {{param:icons}} is true, scan the `icons` file slot and expose `icons[<stem>]` for each supported image file
                          +-- evaluate {{param:expression}} in a sandboxed environment with `np`, `cv2`, `skimage`, `plt`, and `overlay_icon`
                          +-- COERCE the result to a `uint8` ndarray; reject mismatches with the requested {{param:output_color_model}}
                          +-- when {{param:output_color_model}} is `auto`, copy the colour model from the FIRST {{type:Image}} input; otherwise force the conversion at output

Pick this for one-off custom visualisations without building a dedicated worker. For dedicated detection overlays prefer {{component:visualize}}; for non-image transforms use {{component:evaluate_expression}}.

Typical backends

• Custom detection overlay: {{component:input_camera}} + {{component:detect_objects_triton}} -> {{component:visualize_expression}} -> {{component:output_browser_stream}}.
• PPE icon overlay: {{component:input_camera}} + {{component:summarize_tracked_ppe}} -> {{component:visualize_expression}} ({{param:expression}} = overlay_icon(x0, icons['helmet_green'], ...)).
• Inline plot: {{component:input_camera}} + telemetry -> {{component:visualize_expression}} ({{param:expression}} = fig2bgr(...)) -> {{component:output_video_file}}.

Caveats

• Output MUST be a uint8 ndarray that matches {{param:output_color_model}}. There is NO auto-conversion of dtype or channel count — float, int16, or wrongly-shaped arrays raise.
• The asteval sandbox BLOCKS lambdas, getattr, and string-literal .format(...). Disk and network I/O from inside the expression are also blocked.
• A throwing {{param:expression}} PAUSES the input stream until you push a fixed expression via the mutable config update. Validate offline before deploying.
• Per-pixel Python loops are slow inside the sandbox. Prefer vectorised NumPy / OpenCV operations.
• {{param:icons}} true auto-scans the slot ONCE at startup; adding new files at runtime requires a worker restart.
• {{param:output_color_model}} accepts auto, BGR, RGB, GRAY, BGRA, RGBA. auto copies the colour model from the FIRST input that happens to be an {{type:Image}}; with no {{type:Image}} input the worker defaults to RGB.
• {{param:expression}} is mutable: true and re-read every call via config.sync(). {{param:icons}} and {{param:output_color_model}} are captured ONCE at module import.