VISION & ROBOTICS / RUNTIME APP
LumiScan
Script Runner
Your HALCON expertise. Connected to LumiScan.
LumiScan Script Runner runs your own MVTec HALCON procedures in LumiScan Keryx – with the same connection to cameras, PLCs and robots as every other LumiScan app.
For the vision tasks only you know.
The LumiScan Vision Suite apps solve standard tasks without vision expertise. Script Runner is for the other end: HALCON experts who need full control for their hardest cases. Both run side by side in Keryx.
Reuse your expertise
Existing HDevelop procedures run unchanged once they follow the script contract. You keep writing HALCON – Script Runner handles the connection, the handshake and operation.
Connect consistently
PLCs, robots, Cockpit and other LumiScan apps see your script like any other LumiScan app: the same Keryx nodes, the same data types, the same trigger handshake.
Robust in production
Every script runs in its own worker process with a watchdog. A faulty script reports an error and restarts – Keryx and the other apps keep running.
How it works
From HDevelop to production.
Write
Write the procedure lumiscan_process in HDevelop or adapt an existing one: a list of images and a list of values in, a list of images and a list of values out.
Upload
Upload the procedure as .hdvp or from a .hdpl library. Script Runner checks its name, parameters and HALCON classes before activation and keeps the previous version for rollback.
Run
On every trigger, HDevEngine executes the procedure JIT-compiled. Results, cycle time and status are available in Keryx immediately.
The script contract.
One fixed interface for every script, so no procedure needs its own integration code.
procedure lumiscan_process (Images : ImagesOut : Values : ValuesOut)| Parameter | HALCON class | Direction | Content |
|---|---|---|---|
Images | Iconic object tuple | Input | 0…n images, in the order of the Keryx input list |
Values | Control tuple | Input | 0…n values (integer, real, string) |
ImagesOut | Iconic object tuple | Output | 0…n result images, e.g. masks, overlays, rectified images |
ValuesOut | Control tuple | Output | 0…n result values, e.g. measurements, OK/NOK flags, counts, strings |
- The entry procedure name is fixed; support procedures in the same library may have any name.
- All four parameters must exist, even if unused. An empty list is valid.
- You define the meaning of each value position as the script author.
- Result images must be HALCON images; convert regions and XLDs in the script, e.g. with region_to_bin or paint_region.
- No global variables, no file access to fixed paths; dev_* operators are ignored at runtime.
- Raise errors as normal HALCON exceptions – Script Runner reports them in Keryx with procedure and line.
procedure lumiscan_process (Images : ImagesOut : Values : ValuesOut)
* Values[0] = minimum area, Values[1] = maximum area
gen_empty_obj (ImagesOut)
ValuesOut := []
count_obj (Images, NumImages)
for I := 1 to NumImages by 1
select_obj (Images, Image, I)
threshold (Image, Region, 128, 255)
connection (Region, Parts)
select_shape (Parts, Selected, 'area', 'and', Values[0], Values[1])
count_obj (Selected, NumParts)
ValuesOut := [ValuesOut, NumParts]
get_image_size (Image, Width, Height)
region_to_bin (Selected, Mask, 255, 0, Width, Height)
concat_obj (ImagesOut, Mask, ImagesOut)
endfor
return ()The Keryx interface.
Each Script Runner instance gets its own subtree in LumiScan Keryx. Several instances with different scripts run in parallel.
lumiscan/scriptrunner/<instance>/| Node | Type | Access | Meaning |
|---|---|---|---|
config/script | string | read/write | Active script (library + version) |
config/timeout_ms | int32 | read/write | Maximum execution time per call |
input/image_refs | array of string | read/write | Node paths of the source images, e.g. LumiScan Cam Driver image nodes |
input/images | array of image | read/write | Alternative: write images directly |
input/values | array of variant | read/write | Input values in contract order |
output/images | array of image | read | Result images in contract order |
output/values | array of variant | read | Result values in contract order |
control/trigger | bool | read/write | Starts a cycle |
control/done | bool | read | Cycle finished, outputs valid |
status/state | int32 | read | 0 Idle · 1 Busy · 2 Done · 3 Error · 4 Not ready |
status/error_code | int32 | read | Error code (see below) |
status/error_text | string | read | HALCON error message with procedure and line |
status/cycle_time_ms | double | read | Execution time of the last call |
status/cycle_counter | int64 | read | Number of completed calls |
status/script_version | string | read | Version and hash of the loaded script |
Handshake
- The PLC or client writes input/* and sets control/trigger.
- Script Runner sets status/state to Busy and calls lumiscan_process with the images and values.
- Script Runner writes output/* and status/* completely, then sets control/done = true and the state Done or Error.
- The PLC reads output/* and resets control/trigger.
- Script Runner sets control/done = false and the state Idle – the next cycle can start.
Data types
| Keryx | HALCON | Back to Keryx |
|---|---|---|
| bool | integer 0 / 1 | integer |
| int32, int64 | integer | int64 |
| float, double | real | double |
| string | string | string |
| image (mono 8/16 bit, RGB 8 bit) | image (byte / uint2 / 3-channel byte) | image of the same type |
Error codes
| Code | Meaning | Behaviour |
|---|---|---|
| 0 | OK | – |
| 1 | HALCON exception in the script | Outputs empty, error text set, ready for the next trigger |
| 2 | Timeout exceeded | Worker restarted, script reloaded |
| 3 | No valid script loaded or contract violated | Not ready until a valid script is activated |
| 4 | Input error (missing image reference, unsupported type) | Script not called |
| 5 | Worker crashed | Worker restarted, script reloaded |
| 6 | Licence error (LumiScan or HALCON runtime) | Not ready |
At a glance.
Platforms, connectivity and licensing.
- Execution
- One HALCON procedure (.hdvp or from a .hdpl library) per instance, JIT-compiled through HDevEngine on every trigger.
- Instances
- Several instances in parallel, each with its own script and its own Keryx subtree.
- Platforms
- Windows 11 and Ubuntu 24.04 with LumiScan Keryx. ctrlX OS is in preparation – with the same node layout and handshake through the ctrlX Data Layer.
- Connectivity
- Image and value lists through Keryx; images directly from LumiScan Cam Driver, status in LumiScan Cockpit, PLC and robot connection as with every LumiScan app.
- Know-how protection
- Password-protected HALCON procedures run without exposing their source code.
- Operation
- Isolated worker process, configurable timeout, versioning with rollback, cycle-time and error counters, structured log.
- Licensing
- LumiScan Key (CodeMeter). Every installation is supplied with the complete MVTec HALCON runtime licence.
HALCON and HDevelop are trademarks of MVTec Software GmbH.
Frequently asked questions
Which HALCON procedures can Script Runner run?
Any procedure that follows the script contract lumiscan_process(Images : ImagesOut : Values : ValuesOut), saved as .hdvp or in a .hdpl library. Support procedures from the same library may be called.
Do we need our own HALCON licence?
No. Every installation is supplied with the complete MVTec HALCON runtime licence; Script Runner itself is licensed with the LumiScan Key.
Can we protect our know-how?
Yes. Password-protected HALCON procedures run without exposing their source code.
What happens if a script fails?
Each script runs in its own worker process. A HALCON exception is reported in Keryx with procedure and line; on a timeout or crash the worker restarts and reloads the script, while Keryx and the other apps keep running.
Which platforms are supported?
Windows 11 and Ubuntu 24.04 with LumiScan Keryx. ctrlX OS is in preparation, with the same node layout and handshake.
Already working with HALCON?
Tell us about your application, the number of instances and your target platform – we will send you a quote.