Skip to content

Programming guidelinesπŸ”—

The following sections contain recommendations for implementing new HALCON operators. They aim on portable code that should be easy to understand for other HALCON programmers. One of the major topics is the memory management discussed in Managing memory in extension packages.

Basic numeric data typesπŸ”—

Since C made no assumption about the size of integers prior to the introduction of the C99 standard, HALCON versions 20.11 and earlier define the following types:

Type name C99 type name Size/range of values
INT1 int8_t one byte with sign
HBYTE uint8_t one byte, unsigned
UINT1 uint8_t the same as HBYTE
INT2 int16_t two bytes with sign (generally short)
UINT2 uint16_t two bytes, unsigned
INT4 int32_t four bytes with sign
UINT4 uint32_t four bytes, unsigned
INT4_8 four (on 32 bit systems) or eight (on 64 bit systems) bytes with sign
UINT4_8 four (on 32 bit systems) or eight (on 64 bit systems) bytes, unsigned
HINT int At least two, maximal eight bytes with sign
HUINT unsigned At least two, maximal eight bytes, unsigned

Using these types ensures the portability of HALCON operators. If the extension package does not need to be compilable for HALCON 20.11 or earlier versions, the C99 data types (defined in the stdint.h header file) should be used where applicable.

Note

C99 does not define any types that exactly match the INT4_8 or UINT4_8 types.

Attributes of iconic parametersπŸ”—

To use operators in HALCON and HALCON XL, the following types have been introduced. With a compiler define (see Creating and using HALCON package), they are mapped to the suitable basic types for the corresponding image size.

#if !defined(HC_LARGE_IMAGES)
typedef int32_t HIMGDIM;  /* Image dimension, e.g., width and height     */
typedef int16_t HIMGCOOR; /* Image coordinates, e.g, row and column      */
typedef int32_t HLINCOOR; /* Linearized image coordinates                */
typedef int32_t HIMGCNT;  /* Number of pixels, e.g., area or buffer size */
typedef int32_t HITEMCNT; /* Number of elements (contours or runlengths) */
typedef float   HSUBCOOR; /* Sub-pixel precise coordinates               */
typedef float   HSUBATTR; /* Sub-pixel precise attributes of contours    */
#else
typedef int32_t HIMGDIM;
typedef int32_t HIMGCOOR;
typedef INT4_8  HLINCOOR;
typedef INT4_8  HIMGCNT;
typedef INT4_8  HITEMCNT;
typedef double  HSUBCOOR;
typedef double  HSUBATTR;
#endif

Examples for their use can be found in About HALCON data types.

Local variables / temporary resultsπŸ”—

Types and sizes for local variables (no arrays) should be handled as follows:

Type Size C-data type
Integer 1 byte
2 byte
int (HINT) or unsigned (HUINT)
Integer 3 byte
4 byte
INT4_8 or UINT4_8
Floating-point number double

Procedure parametersπŸ”—

Parameters of procedures should be of the following types within HALCON:

Type Size C-data type
Integer 1 byte
2 byte
HINT
Integer 3 byte
4 byte
INT4_8
Floating-point number double
Structure pointer

ArraysπŸ”—

For arrays or structures (i.e., larger sets), always the smallest possible data type should be used.

Type Size C-data type
Integer 1 byte int8_t
Integer 2 byte int16_t or uint16_t
Integer 3 byte
4 byte
int32_t or uint32_t
Floating-point number 4 byte float
Floating-point number 8 byte double
Structure pointer

Structuring programsπŸ”—

HALCON operators are typically implemented by at least two routines: one procedure (supply procedure) receives/unpacks all input data and checks its consistency. Afterward, it calls the action procedure, which performs the image processing.
In some cases, it can be convenient to implement several action procedures dependent on special parameter values or pixel types of image data. Generally, these steps are performed within a loop over all input iconic objects that may include further loops over different parameter values and over all image channels. The results are collected and finally returned to the HALCON interface to the application.

Supply procedures are of type Herror and have only one parameter (a handle of type Hproc_handle for instances of HALCON operators or HALCON threads). Do not forget to return an appropriate value at the end of every supply procedure (standard value: H_MSG_TRUE) and every action procedure (standard value: H_MSG_OK).

Typically, action procedures perform the image processing itself. They should return an error code of type Herror as well. It is convenient to implement an action procedure for each pixel type of image data.

Extension package initializationπŸ”—

To initialize an extension package, the following optional function may be defined:

extern HUserExport Herror HXPkgMain(Hproc_handle)

If defined, HALCON will call this function upon loading the extension package. For example, this mechanism is useful to initialize synchronization objects (for example, mutexes) that will be used in the extension package.

Name conventions for proceduresπŸ”—

To ease the interpretation of program code, HALCON introduces some conventions for procedure names. The most important ones are summarized in the following section.

The names of action procedures typically begin with β€œIP” (image processing procedure), β€œIO” (input/output procedure), or β€œDB” (data base procedure). The rest of the name describes the task performed by the procedure (in English language, beginning with a capital letter). In case of filters, an additional token might be inserted between these two parts of the name encoding the pixel type(s) of images to be processed, for example, β€œB” (HBYTE), β€œI4” (INT4) or β€œF” (float).

Example

IPBLowpas
IPI4Threshold
IODispRegion
DBGetTuple

Basic routines performing a small task that might be used by many other routines should start with β€œH” (for Help). The leading β€œH” should be followed by a string encoding the data the routine works on, for example, β€œRL” for an auxiliary routine processing region data, or β€œXLD” for routines working on XLDs.

Example

HRLUnion
HXLDContLen
HXLDContRegress

Names of supply procedures start with β€œC” (this stands for Core). The rest is determined by the name of the underlying action procedure (if there is only one). If there are several action procedures with names differing only by the symbols for different pixel types, the pixel type is left out in the name of the supply procedure.

Example

CIPLowpas
CIPThreshold
CIOOpenWindow

Input / outputπŸ”—

Except explicit IO routines HALCON procedures should not contain any input/output commands, especially no print commands. Any interaction should be done either via parameters or via Extension Package Interface input/output procedures. Error messages should be encoded by proper error code returned by the procedure (see Handling errors in extension packages).

Notes on image processing operatorsπŸ”—

  • HALCON images are variable in their size (format). Therefore, no constants should be used for image formats (except MAX_FORMAT for the maximum format). The actual format of an image can be extracted from the structure Himage (see Data type Himage for images).
  • Notice that more than one pixel type may occur, when performing gray value operations. An operator should be able to work on all of them, see also the discussion in HAllFilter. If an operator can only process a reduced set of types, this can be specified in the DEF file with type_list (see type_list). An operator should reject all images that it can not process by returning H_ERR_WIT – wrong image type.
  • In many cases, an operator might receive more than one iconic object as input, i.e. the supply procedure must contain a loop over all iconic objects (for example, using HAllReg and HAllSegm described in Loop macros or HAllObj). This is true for regions as well as images or XLDs. Furthermore, images may contain more than one channel. Hence, a second loop over all channels (components) within an image is needed (see HAllComp).
  • All procedures should only work within the image’s area of definition, especially when performing feature extraction, filter or segmentation tasks.