halcon-extension-developer

name	halcon-extension-developer
description	The ultimate expert guidance for HALCON Extension Package development (C). Combines low-level implementation rules, mandatory error handling patterns, systematic debugging, and implementation contracts.

Ultimate HALCON Extension Developer Skill

This skill provides the comprehensive technical knowledge required to extend HALCON's core functionality. It merges legacy best practices with modern MCP-based retrieval to ensure production-grade stability, memory integrity, and localized clarity.

When to use this skill

• Use this when implementing, debugging, or optimizing C HALCON Extension Packages.
• Use this to define new operators in .def files with strict slot and bilingual requirements.
• Use this to ensure absolute memory integrity using HALCON's internal allocators and pointer safety rules.
• Use this to implement the mandatory 33000-offset error handling pattern.

How to use it

1. Unified Search Strategy

Always use the search_halcon_knowledge tool with domain="extension_package_development".

Multi-Version Strategy:

• Version Compatibility: If an extension package builds in one version but fails in another (e.g., a header HAlloc behavior change between 23.11 and 24.05), perform parallel searches for both versions.
• Specific Versioning: Use the halcon_version parameter (e.g., halcon_version="24.11") to isolate macros, headers, and rules for a specific target environment.
• Active Version: By default, the search prioritizes your current HALCONROOT version but will fallback to others if no results are found.

Optimal Workflow:

1. Headers First (The Contract): Search source_type="header" for exact C signatures (e.g., HGetCPar, HPGetPElemD) and macro definitions.
2. Implementation Pattern: Search source_type="example" and language="c" to see Hproc_handle orchestration.
3. Rule Verification: Search source_type="documentation" for memory ownership and parallelization rules in the "Extension Package Manual".
4. Types & Errors: Simply search for the C type or error code using the general search tool.

2. Mandatory Implementation Patterns

Clean C Coding & Memory Management

• Allocators: NEVER use standard malloc/free. ALWAYS use HAlloc and HFree. Use deallocators immediately when scope ends.
• Safety: Always check for NULL pointers after every allocation or parameter retrieval.
• Naming: Use snake_case for all C functions and variables. External operators must have descriptive names without suffixes (e.g. my_op not my_op_c).
• Simplicity: Write small, testable functions. Avoid global state; keep variables locally scoped.
• Include Guards: Ensure #ifndef, #define, #endif guards are present in all .h files.
• Doxygen: Use /** ... */ blocks for all public functions/structs. Define @param[in/out], @brief, and @return.

The Supply & Action Pattern

• Supply Procedure (CIP...):
  • The entry point called by HALCON. Signature: Herror CIPMyOp(Hproc_handle proc_handle).
  • Contract: Accepts exactly one Hproc_handle.
  • Tasks: Retrieve parameters (HGetCPar, HGetObj), handle tuples (HAllSegm), validate types, call the Action Procedure, and return results (HNewRegion, HPutObj).
• Action Procedure (IPB...):
  • Performs core logic on raw types (e.g., Hrlregion, Himage, Hlong*).
  • Tasks: Independent of parameter buffers.

Unit Test-First Strategy

Before implementing any C logic, you MUST create a verification script.

1. Activate Skill: Use halcon-developer skill.
2. Create Test: Write a .hdev test in extensions/container/test/ using synthetic data (e.g., gen_image_const) to ensure portability.
3. Headless Compliance: Use try/catch, avoid stop(), and use buffer windows for rendering.
4. Strict Compilation Before Testing: ALWAYS fully compile and deploy the extension (.\scripts\build.ps1 -Install -Test) before executing unit tests to guarantee you are not validating against a stale .dll.

3. Error Handling: The 33000 Offset Pattern

Descriptive error messages are mandatory. Standard codes (1-1000) are reserved; use the 33000 offset for custom validation.

1. Dynamic Message: Use snprintf to format a context-rich string.
2. Register: Call HSetErrText(msg).
3. Return: Return (Standard Code + 33000).

Search for standard codes in headers (e.g., H_ERR_WRP) to find their base values.

4. Systematic Debugging & Stubs

Avoid "silent crashes" with this diagnostic workflow:

• Minimal Diagnostic Stub: Implement only parameter retrieval (HPGetPElemD, HPGetPElemS, etc.) and return HAllocOutpCtrl with a simple constant to verify integration first.
• FFlush: Use fflush(stdout) after every printf to ensure output is captured before a potential crash.
• Bounds Check: Always verify n_values > 0 before indexing.
• Conversion: Use CONV_CAST in HPGetPElem to handle both INT and REAL tuples.
• Crash Isolation: Comment out the algorithmic loop and re-enable line-by-line.
• OpenMP: If a crash occurs, temporarily disable #pragma OpenMP blocks to rule out race conditions.

5. Build System & Operator Database (.def)

• CMake: Use CMake for builds. Support HALCON XL via cmake -DHALCON_XL=1.
• DEF Files: Must include English and German documentation.
  • Use halcon-doc-specialist skill to write an optimal .def file.
  • Mandatory slots: short, module (before abstract), abstract, result_state, parameter descriptions.
  • Localize German: Use ä, ö, ü, ß. Never ASCII equivalents.
• Environment: Add package root to HALCONEXTENSIONS and bin/<ARCH> to PATH.

MCP Tool Interface

search_halcon_knowledge

• domain: "extension_package_development".
• source_type: "header", "documentation", or "example".
• language: "c", "def", or "cmake".
• fast_search: Set to true for exact name searches or macro lookups to skip the reranker and get results faster.