skills-market/plugins/halcon/references/invocation.md

Invoking HALCON on this machine

Everything here is specific to this install. Read SKILL.md first for the one-paragraph environment summary; this file is the detailed, copy-paste reference.

Fixed paths

What	Path
HALCON install	C:\Users\NAURA\AppData\Local\Programs\MVTec\HALCON-24.11-Progress-Steady
Windows binaries	<install>\bin\x64-win64 (on Windows PATH: hrun.exe, hdevelop.exe, hhostid.exe)
License dir	<install>\license\ — monthly license_eval_halcon_progress_YYYY_MM.dat
Project	C:\workspace\agent-studio\halcon-001 (WSL: /mnt/c/workspace/agent-studio/halcon-001)
venv	C:\workspace\agent-studio\halcon-001\.venv (mvtec-halcon==24111.0.0)
venv python (direct)	C:\workspace\agent-studio\halcon-001\.venv\Scripts\python.exe
uv (use this)	/mnt/c/Users/NAURA/.local/bin/uv.exe

WSL has no Linux HALCON runtime. Every path above is Windows-side; drive it from WSL by calling the Windows .exe directly.

Running Python (always via uv)

uv is not on the WSL PATH — call it by full path. Run from the project directory so uv auto-detects .venv (there is no pyproject.toml; uv picks up the local .venv):

cd /mnt/c/workspace/agent-studio/halcon-001
/mnt/c/Users/NAURA/.local/bin/uv.exe run python <script.py> [args...]

Tested: uv.exe run python -c "import halcon as ha; print(ha.get_system('version'))" → ['24.11']. If you prefer a shorter command, alias it: alias uv=/mnt/c/Users/NAURA/.local/bin/uv.exe (session-local).

Do not call python/python3 directly (user rule). Use uv run. Direct .venv\Scripts\python.exe also works but uv is preferred.

Method 1 — HDevEngine from Python (preferred for automation)

HDevEngine runs the exact .hdev/.hdvp logic HDevelop would, from Python, so you can pass inputs in and read variables back. Interactive draw_* operators are not supported here — supply those inputs as parameters (see ROI seam).

Imports (ground truth from the tested project)

from halcon.hdevengine import (
    HDevEngine, HDevProcedure, HDevProcedureCall,
    HDevProgram, HDevProgramCall, HDevEngineError,
)
import halcon as ha          # plain operators: read_image, list_files, tuple_*, ...

External procedure (.hdvp)

eng = HDevEngine()
eng.set_procedure_path(r"C:\workspace\agent-studio\halcon-001")   # dir holding the .hdvp
proc = HDevProcedure.load_external("find_circles")                 # base name, no extension
call = HDevProcedureCall(proc)

call.reset()                                                       # before each iteration
call.set_input_control_param_by_name("ImageFile", r"C:\data\a.png")
call.set_input_control_param_by_name("RoiFile",  r"C:\...\roi.hobj")
call.execute()
fit_row = call.get_output_control_param_by_name("FitRow")         # -> native list/scalar

Wrap call.execute() in try/except HDevEngineError to skip bad images (the tested find_circles.hdvp throws when the circle count != 16; the Python driver catches it and continues). Helper: values come back as scalars or lists — normalize with list(v) if isinstance(v,(list,tuple)) else [v].

Use the generic runner instead of hand-writing this:

uv.exe run python .claude/skills/halcon/scripts/run_procedure.py \
  --proc-path C:/workspace/agent-studio/halcon-001 \
  --proc find_circles \
  --set ImageFile=C:/data/a.png --set RoiFile=C:/workspace/agent-studio/halcon-001/roi.hobj \
  --get FitRow --get FitCol --get MetroRow --get MetroCol
# prints a JSON object of the requested outputs

Whole program (.hdev)

program = HDevProgram(r"C:\...\demo_prog.hdev")
call = HDevProgramCall(program)
call.execute()
total = call.get_control_var_by_name("Total")     # any control var by name

Generic runner: scripts/run_program.py --program <path.hdev> --get Total --get Area.

Method 2 — hrun.exe (headless batch)

Runs a .hdev to completion without the GUI. The script must persist its own results (write to file). Launch from WSL with the working dir set so relative paths resolve:

cd /path/to/script/dir
"/mnt/c/Users/NAURA/AppData/Local/Programs/MVTec/HALCON-24.11-Progress-Steady/bin/x64-win64/hrun.exe" \
  script.hdev | iconv -f GBK -t UTF-8

Useful flags:

Flag	Meaning
-c <var>	after the run, check a variable; nonzero/true = success
-D name=value	preset a global control variable
-d	dump all control variable values after the run
-j	run procedures JIT-compiled

Gotchas: no graphics window is opened — if the script uses dev_get_window/draw_*, add dev_open_window first. Keep an hrun-runnable copy of interactive scripts (the project convention is a *_hrun.hdev variant with dev_open_window added and stop()/draw_* removed).

Method 3 — HDevelop GUI (hdevelop.exe)

For interactive runs / inspection. There is no run-and-exit; the window stays open until closed. hdevelop.exe is a GUI app, so its stdout is not captured from WSL — for any batch/convert/export use file outputs.

• hdevelop -run <prog.hdev> — open GUI and auto-run.
• -override_stop <n> — replace every stop() with wait_seconds(n) (use 0).
• -override_wait <n> — override all wait_seconds() durations.
• -external_proc_path "<dir1;dir2>" — external procedure search path.

Remote debugging: a running application calls start_debug_server (HALCON) / enables the debug server, then HDevelop attaches to it. See hdevelop_users_guide.pdf ch. 9 (Remote Debugging, p299).

Convert / export (batch, no interaction — write to a FILE)

• Convert: hdevelop -convert <src> <dst> — target type from <dst> extension (.hdev/.dev/.hdvp/.dvp/.hdpl/.c/.cpp/.cs/.vb/.txt). Add -no_msg_box to suppress GUI error dialogs in batch; -external_procs_only_interfaces for interface-only export.
• Export project: hdevelop -export_project for a CMake C++/C# project. -namespace is REQUIRED — omitting it fails silently and writes nothing. Prefer absolute paths for input and output folder.

Command-line reference: hdevelop_users_guide.pdf Appendix C (p323 HDevelop, p326 Hrun).

The ROI seam (teach once → reuse headless)

• Teach: scripts/teach_roi.py — shows a representative image, human drags a shape, write_region saves roi.hobj. Draw tightly (loose ROI → extra contours → count checks fail).
• Reuse: in a procedure/program, read_region(Roi, RoiFile) then reduce_domain(Image, Roi, ImageReduced). This is what unattended runs call instead of draw_*.

Encoding & path gotchas (recap with fixes)

• Chinese/Unicode paths: call the .exe/uv.exe directly from WSL (UTF-16 argv). Never wrap in cmd.exe /c (GBK → "syntax incorrect").
• Restore Chinese console output: ... | iconv -f GBK -t UTF-8.
• HALCON internally uses UTF-8 for strings since 18.11 (see technical_updates.pdf); the GBK issue is the Windows console/cmd layer, not HALCON itself.
• HDevEngine: always pass absolute paths — no cwd ambiguity.

License

Monthly evaluation .dat in <install>\license\, updated manually by the user. Stale/expired .dat files may linger; HALCON auto-selects a valid one. If you hit a license error, the current month's file is probably missing — surface this to the user, don't attempt to bypass it. Host id for a new license: run hhostid.exe (also a quick "can the binaries execute?" check). License details: installation_guide.pdf ch. 5 (p25).