Halcon Extension Developer

• 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 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.

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.