refactor(halcon): single-skill plugin layout → invoke as /halcon (not /halcon:halcon)
Move SKILL.md + references/ scripts/ evals/ from skills/halcon/ up to the plugin root. Per Claude Code plugins-reference, a plugin with SKILL.md at its root and no skills/ subdir is auto-loaded as a single-skill plugin (v2.1.142+), so the invocation name = frontmatter name = halcon → clean /halcon. Bump plugin.json 2.0.0 → 2.0.1 so existing installs receive the update. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,173 @@
|
||||
---
|
||||
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` |
|
||||
Reference in New Issue
Block a user