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:
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_FORMATfor the maximum format). The actual format of an image can be extracted from the structureHimage(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 withtype_list(seetype_list). An operator should reject all images that it can not process by returningH_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
HAllRegandHAllSegmdescribed in Loop macros orHAllObj). 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 (seeHAllComp). - All procedures should only work within the imageβs area of definition, especially when performing feature extraction, filter or segmentation tasks.