skills-market/plugins/halcon/SKILL.md

---
name: halcon
description: >-
  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.
metadata:
  author: agent-studio
  skill_version: "2.0"
  halcon_version: "24.11.1.1 Windows (local) + 24.11.1 Linux (remote MCP)"
  environments: "local: WSL -> Windows HALCON + uv venv | remote: halcon-remote MCP -> headless Linux server"
compatibility: >-
  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` |