skills-market/plugins/halcon/SKILL.md

name, description, metadata, compatibility

name	description	metadata	compatibility
halcon	Runs and orchestrates MVTec HALCON machine-vision tasks two ways: the local Windows-side HALCON 24.11 (driven from WSL via uv, HDevEngine, hrun, or the HDevelop GUI), or a remote HALCON compute service over MCP (server `halcon-remote`) that needs no local HALCON. Use whenever the work touches HALCON, HDevelop, .hdev/.hdvp scripts, HDevEngine, or a machine-vision goal it can solve: blob analysis, thresholding/segmentation, edge and contour (XLD) extraction, circle/line/shape fitting, 1D/2D/3D measuring and metrology, 2D/3D and surface-based matching, camera calibration, stereo/depth, bar code and 2D data code reading (QR, DataMatrix, PDF417), OCR/Deep OCR, classification, D2W overlay/bullseye alignment metrology, or looking up a HALCON operator — even when the user only states the vision goal (e.g. "measure these circles", "find the mark centers", "read this DataMatrix", "no HALCON on my machine") without naming HALCON.	author skill_version halcon_version environments agent-studio 2.0 24.11.1.1 Windows (local) + 24.11.1 Linux (remote MCP) local: WSL -> Windows HALCON + uv venv | remote: halcon-remote MCP -> headless Linux server	Local path: this machine only (Windows HALCON + Windows uv.exe + project venv mvtec-halcon==24111.0.0 + monthly license). Remote path (halcon-remote MCP): any machine with network access + a bearer token; no local HALCON needed.

HALCON on this machine

MVTec HALCON is a machine-vision library (operators for imaging, measuring, matching, calibration, code reading, OCR, deep learning). This skill is about driving the HALCON that is installed here and orchestrating vision pipelines with it. It does not re-teach general vision theory — for operator details and worked examples, read the bundled manuals on demand (see references/doc-map.md).

Two runtimes — pick one

A. Local (Windows HALCON, this machine). Everything below in this file (Environment, the three execution methods, ROI teaching, gotchas) is the local path. Use it when you are on this WSL/Windows box.

B. Remote over MCP (halcon-remote) — no local HALCON. A HALCON 24.11 compute service reachable over the public internet; the client needs only network + a bearer token (no HALCON install, no minio creds, no VPN/tailnet). Prefer this when there is no local HALCON (MacOS, plain Linux, a colleague's machine), or for turnkey D2W overlay / find-circles jobs and large batches (zip → process → CSV). Tools, image-in/result-out model, the zip batch pattern, D2W conventions, and examples: read references/remote-mcp.md before using the remote tools. Quick self-check: call mcp__halcon-remote__halcon_get_env.

⚠️ Environment (LOCAL path) — read this first (it overrides assumptions)

• HALCON lives on the Windows side only. Install: C:\Users\NAURA\AppData\Local\Programs\MVTec\HALCON-24.11-Progress-Steady, bin\x64-win64 on the Windows PATH. WSL has no Linux HALCON runtime — you must dispatch every execution to Windows binaries or the Windows venv. Do not pip install halcon inside WSL and do not try to run it Linux-side.
• Python is managed by uv, never called directly. uv is not on the WSL PATH; use the full path /mnt/c/Users/NAURA/.local/bin/uv.exe. From the project dir it auto-detects .venv: uv.exe run python <script.py> [args]. The venv has mvtec-halcon==24111.0.0. (See references/invocation.md for the exact, tested commands.)
• License is a monthly evaluation .dat in <install>\license\, refreshed manually by the user. If operators fail with a license error, the current month's .dat is likely missing/expired — tell the user; don't work around it.

Smoke-test the environment before real work: uv.exe run python .claude/skills/halcon/scripts/check_env.py — prints the HALCON version and runs a trivial operator (exercises the license).

Three ways to execute — pick by task

1. HDevEngine from Python (preferred for automation). Load an external procedure (.hdvp) or a program (.hdev), set inputs, execute, read outputs back as native Python values, and drive the loop in Python. Use the generic runners:
   • scripts/run_procedure.py — call one .hdvp with input/output params.
   • scripts/run_program.py — run a whole .hdev and read control vars.
2. hrun.exe (headless batch). Runs a .hdev unattended; the script must write its own output files. Gotchas: hrun does not auto-open a graphics window (add dev_open_window if the script draws), and relative paths resolve from the working dir. See references/invocation.md.
3. HDevelop GUI (hdevelop -run, or start_debug_server + remote debug). For interactive inspection/debugging. Not for unattended runs — there is no run-and-exit; the window stays open.

Full flags, encoding handling, and copy-paste commands: references/invocation.md.

The human-in-the-loop seam: teach ROI once, reuse headless

Interactive operators (draw_rectangle1, draw_circle, draw_region) cannot run unattended. The clean pattern is:

1. Teach once (human draws): scripts/teach_roi.py opens a viewer on a representative image, the operator boxes the region, and write_region persists it to a .hobj file. For the common rectangle case it's an interactive matplotlib picker — left-drag = box, right-drag = pan, scroll wheel = zoom — which stays smooth on multi-megapixel images (it downsamples the display but keeps full-resolution box coordinates). circle and region fall back to HALCON's native draw_* window. Add --box r1,c1,r2,c2 to write a rectangle headless (no GUI). Needs matplotlib + numpy in the venv (uv.exe pip install matplotlib numpy). The same thing is exposed as the MCP tool halcon_teach_roi (see references/mcp-server.md), which runs the picker in a subprocess and returns the saved bbox.
2. Reuse forever (headless): downstream procedures read_region the .hobj and reduce_domain with it — no human needed.

Re-teach only when the fixture, camera, or dataset changes. Draw the ROI tightly around the target features: too large an ROI captures extra contours and downstream count checks (e.g. "expected 16 circles") fail.

A complete, tested example of this pattern is bundled in references/examples/ and is worth reading before building a new pipeline: teach_roi.py, find_circles.hdvp (edge-fit and metrology-model circle finding in one procedure), and run_compare.py (HDevEngine driver over a folder of images).

Top gotchas (this environment)

• Never route Chinese/Unicode paths through cmd.exe. Its GBK code page corrupts them into "syntax incorrect" errors. Call the .exe (or uv.exe) directly from WSL so argv is passed as UTF-16.
• Console output is GBK. Pipe through iconv -f GBK -t UTF-8 to restore Chinese text from HALCON/hrun stdout.
• hdevelop.exe is a GUI app — its stdout is NOT captured from WSL. For conversion/export/batch, always write results to a file, never rely on stdout.
• Relative paths resolve from the current working directory. cd into the script's dir before hrun, or pass absolute paths (HDevEngine: always absolute).
• hrun opens no graphics window. A script using dev_get_window / draw_* must call dev_open_window first (HDevelop supplies one implicitly, hrun does not).
• clip_region defaults to true and clips regions to ~128×128. Building a region from full-resolution coordinates (gen_rectangle1(2000, 2400, …)) silently yields an empty region, so a saved .hobj reads back with bbox 0,0,0,0. Call set_system('clip_region', 'false') before generating/reading regions with large coordinates (clamp to image bounds yourself instead). The ROI scripts already do this.

How to find the right operator / method

Fastest: the operator index under references/operator-ref/ (HALCON 24.11, 2387 operators). To find or confirm an operator, grep -i <keyword> references/operator-ref/operators.txt (e.g. circle, measure, datacode); browse the chapter tree in categories.md; then open any operator's online reference at https://www.mvtec.com/doc/halcon/2411/en/<operator>.html. This beats opening PDFs when you just need the right operator name/signature.

For depth, the 20 official manuals are bundled under references/pdf/. Do not read them wholesale — references/doc-map.md maps each guide to its topics and exact page ranges, so you open just the right pages with the Read tool (pages: parameter). For distilled, ready-to-adapt pipelines per task type (measuring, matching, code reading, calibration, …) read references/task-recipes.md first; it points into the PDFs for depth.

Where to look — quick index

Need	Read
Use HALCON remotely (no local install) — remote MCP tools, image I/O, zip batch, D2W overlay	references/remote-mcp.md
Find/confirm a HALCON operator (name → doc URL), browse by category	references/operator-ref/ (grep operators.txt, categories.md)
Call local HALCON as MCP tools (enhance/match/find-circles/metrology/teach-roi/run scripts)	references/mcp-server.md
Run/convert/export HALCON here; flags, encoding, license	references/invocation.md
Which manual + pages cover topic X	references/doc-map.md
A step-by-step pipeline for a task type	references/task-recipes.md
Generic HDevEngine procedure runner	scripts/run_procedure.py
Generic HDevEngine program runner	scripts/run_program.py
Teach an ROI interactively	scripts/teach_roi.py
Verify the environment works	scripts/check_env.py