About HALCON data typesđź”—
The HALCON Extension Package Interface provides special data types to handle iconic objects.
All iconic objects in the application layer are represented by a key referring to the HALCON database of iconic objects.
The internal structure is hidden from the HALCON user.
However, using the Extension Package Interface it is possible to work directly on the data structures for images, regions, and XLDs.
Special macros can be used to access the internal representation of such an iconic object.
Furthermore, data structures for control parameters are provided.
All data types described in the following sections are defined in the files %HALCONROOT%\include\IPType.h and %HALCONROOT%\include\HBase.h.
Pixel data (Himage)đź”—
Gray value images are represented by a rectangular image matrix.
Several matrices (called channels) can be combined to a multi-channel image.
Each channel can be accessed separately, i.e. the channels are not interleaved.
The structure Himage contains size, pixel type, and pixel data of one channel.
Furthermore, a time-stamp is included.
Data type Himage for images shows the corresponding type declaration.
typedef union {
uint8_t* b; /* 0..255 (BYTE_IMAGE) */
uint8_t* z; /* 0..255 mod 256 (CYCLIC_IMAGE) */
uint8_t* d; /* orientation 0..180 (DIR_IMAGE) */
int8_t* i; /* -128..127 (INT1_IMAGE) */
int32_t* l; /* 4 byte integer (LONG_IMAGE) */
int64_t* i8; /* 8 byte integer (INT8_IMAGE) */
float* f; /* 4 byte real (FLOAT_IMAGE) */
HVFPixel* vf; /* vector field (VF_IMAGE) */
HComplexPixel* c; /* complex image (COMPLEX_IMAGE) */
HInt2Pixel s; /* 2 bytes with sign (INT2_IMAGE) */
HUInt2Pixel u; /* 2 bytes without sign (UINT2_IMAGE) */
} HPixelImage;
typedef struct {
int kind; /* pixel type */
HPixelImage pixel; /* pixel data */
HIMGDIM width; /* image width */
HIMGDIM height; /* image height */
HImageFreeProc free_proc; /* function for deallocating image data */
bool free; /* free image data when deleting image */
/* time of creation of image */
uint16_t msec; /* milliseconds 0..999 */
uint8_t sec; /* seconds 0..59 */
uint8_t min; /* minutes 0.59 */
uint8_t hour; /* 0..23 */
uint8_t day; /* 1..31 */
uint16_t yday; /* 1..366 */
uint8_t mon; /* 1..12 */
uint16_t year; /* 19xx */
} Himage;
The maximum for width and height, which describe the image size, is determined with MAX_FORMAT (HALCON: 32 768, HALCON XL: 1 073 741 824).
The origin of an image matrix is at position (0, 0).
Row coordinates range from 0 to height - 1, column coordinates from 0 to width - 1.
The image pointer (HPixelImage) refers to the first pixel of the matrix (index: 0,0).
Different pixel types are supported.
They are distinguished by a selector (kind), see Definitions of pixel types.
The pixel types include basic types like uint8_t, int8_t, int32_t, and float as well as composed types.
Their definitions can be seen in Data types for Himage.
#define BYTE_IMAGE (int)1 /* 1 byte per pixel (0..255) */
#define INT4_IMAGE (int)2 /* Type: 4 bytes per pixel (int32_t) */
#define LONG_IMAGE (int)2 /* 4 byte per pixel (int32_t) */
#define FLOAT_IMAGE (int)4 /* 4 byte per pixel (float) */
#define DIR_IMAGE (int)8 /* edge orientation 0..180 */
#define CYCLIC_IMAGE (int)16 /* 0..255 cyclic */
#define INT1_IMAGE (int)32 /* -128..127 */
#define COMPLEX_IMAGE (int)128 /* 2 float images */
#define INT2_IMAGE (int)512 /* 2 bytes with sign */
#define UINT2_IMAGE (int)1024 /* Type: 2 bytes (unsigned short) */
#define VF_IMAGE (int)2048 /* Two float images */
#define INT8_IMAGE (int)4096 /* 8 byte per pixel (int64_t) */
typedef struct {
float re; /* real image part */
float im; /* imaginary image part */
} HComplexPixel;
typedef struct {
int16_t* p; /* gray values */
int8_t num_bits; /* number of used bits */
} HInt2Pixel;
typedef struct {
uint16_t* p; /* gray values */
int8_t num_bits; /* number of used bits */
} HUInt2Pixel;
typedef struct {
float* row; /* row direction */
float* col; /* column direction */
} HVFPixel;
The pixel data is stored as a one-dimensional array (image vector) of one of the pixel types.
The indices of the array range from 0 to width*height-1.
A linear coordinate L within an image is derived from the row index R and column index C as follows:
This transformation is performed by the following macro HLinCoor:
There are two additional macros for computing rows (HRow) and columns (HCol):
Please see Global data for routines to allocate image data within Himage.
Region data (Hrlregion)đź”—
In HALCON region data is represented by a special variant of the runlength encoding – a chord encoding: For every line (chord) of a region its row index (“y coordinate”,“line number”) and the column index (“x coordinate”) of its start and end point is stored. Both the start point and the end point belong to the region.
Chord data must fulfill the following conditions:
- a chord is limited to one row
- chords may not overlap
- chords are sorted in ascending order
If a region is read from the HALCON database of iconic objects, its representation fulfills all the conditions above. When writing a region, condition 2 and 3 need not to be sufficed in all cases, as the Extension Package Interface automatically modifies the data (at cost of computation time).
typedef struct {
HIMGCOOR l; /* line number (row) of run */
HIMGCOOR cb; /* column index of beginning of run */
HIMGCOOR ce; /* column index of ending of run */
} Hrun;
typedef struct {
bool is_compl; /* region is complement */
HITEMCNT num; /* number of runs */
HITEMCNT num_max; /* maximum number of runs */
HRegFeature feature; /* already processed features */
Hrun* rl; /* pointer on array of run lengths */
} Hrlregion;
Data type Hrlregion for region encoding shows the type declaration for chords.
In the structure Hrlregion, all chords are stored in an array of the type Hrun, where num is the current and num_max the maximum allowed number of chords (depending on the size of the region specified at its creation, see also Managing memory in extension packages).
The flag is_compl allows an easy transformation of a region in its complement.
Operators that work on regions must consider this flag and react according to its value.
The structure HRegFeature (see Data type HRegFeature for region shape features) contains all region shape features extracted so far to avoid repeating a computation.
HFeatureFlags encodes, which features already have been extracted.
Do not forget to reset these flags if you modify a region.
typedef struct {
union {
HFeatureFlags single;
long all; /* if possible use 64 bits!
} def;
uint8_t shape; /* SHAPE_*
bool is_convex;
bool is_filled;
bool is_connected4;
bool is_connected8;
bool is_thin; /* one pixel thin
double circularity;
double compactness;
double contlength;
double convexity;
double phi;
double ra, rb; /* elliptic_axis
double ra_, rb_; /* elliptic_shape
double anisometry, bulkiness, structure_factor;
double m11, m20, m02, ia, ib;
double row, col;
HIMGCNT area;
HIMGCOOR row1, col1, row2, col2;
double row_rect, col_rect, phi_rect, length1, length2;
double row_circle, col_circle, radius;
HIMGCOOR min_chord, max_chord;
HIMGCOOR min_chord_gap, max_chord_gap;
double rectangularity;
} HRegFeature;
Normally, a variable of type Hrlregion is allocated with the procedure HAllocRLTmp or HAllocRLNumTmp, see Managing memory in extension packages.
These routines initialize the data, especially num_max that is needed for tests of overflow.
When allocating a variable “by hand”, the programmer must provide a suitable initialization by himself/herself.
Whereas all coordinates within runlength codes are stored as (row,column), linear coordinates are used to address HALCON image matrices.
Thus, the macros CB and CE are very helpful, especially when processing gray values (in linear coordinates) along a chord.
The programs in A typical application of HAllFilter: A filter operator and A typical application of HAllFilter2 illustrate how to use them.
Their functionality can be seen in Linear coordinates from Hrlregion.
The first parameter (rl) contains a pointer to the chords as it is used within Hrlregion.
index specifies the index of the chord to work on and width contains the image width.
CB returns the linear coordinate of the start point and CE that of the end point of the chord.
Names
Synopsis
#include "Halcon.h"
HLINCOOR CB(Hrun* rl,
HITEMCNT index,
HIMGDIM width)
HLINCOOR CE(Hrun* rl,
HITEMCNT index,
HIMGDIM width)
XLDs (Hcont, Hpoly)đź”—
XLDs (eXtended Line Descriptions) are specific iconic HALCON objects to represent subpixel accurate contours and polygons.
The corresponding data types Hcont and Hpoly are listed in The XLD data type Hcont for subpixel contours and The XLD data type Hpoly for subpixel polygons.
typedef enum cont_class {
cont_unknown, /* unknown */
cont_no_junc, /* neither start nor end point points */
/* are junctions */
cont_start_junc, /* start point is a junction */
cont_end_junc, /* end point is a junction */
cont_both_junc, /* both start and end point are junctions */
cont_closed /* closed contour */
} Hcont_class;
typedef struct cont_attrib {
char *name; /* name of the attribute */
HSUBATTR *val; /* value of the attribute (per point) */
} Hcont_attrib;
typedef struct cont_global_attrib {
char *name; /* name of the global attribute */
HSUBATTR val; /* value of the attribute (per contour) */
} Hcont_global_attrib;
typedef struct cont_type {
HITEMCNT num; /* number of points along the contour */
HSUBCOOR* row; /* points / row indices (y coordinates) */
HSUBCOOR* col; /* points / column indices (x coord.) */
Hcont_class cont_class; /* contour class */
int32_t num_attrib; /* number of additional attributes */
Hcont_attrib* attribs; /* additional attributes (for each point) */
int32_t num_global; /* number of additional global attributes */
Hcont_global_attrib* global;/* additional attributes (per contour) */
int32_t h; /* auxiliary (temporary) */
} Hcont;
typedef struct lin_seg_type {
HSUBCOOR row,col; /* a control point of the polygon: */
/* row (y) and column (x) coordinate */
HSUBATTR length; /* length of the line from the */
/* current to the next point */
HSUBATTR phi; /* orientation (rad) of this line */
Hkey ref; /* database key of the underlying */
/* contour */
HITEMCNT first; /* index of the first point of the */
/* underlying contour belonging to */
/* current side of the polygon */
HITEMCNT last; /* index of the last contour point */
} Hline_seg;
typedef struct poly_type {
HITEMCNT num_line; /* number of lines */
HITEMCNT len_line; /* maximum number of lines (size */
/* of the array lines) */
Hline_seg* lines; /* control points of the polygon */
} Hpoly;
HALCON contours of type Hcont contain an array of subpixel points along a contour.
A contour might be classified concerning to topological considerations (cont_class).
Additionally, an arbitrary number of additional contour attributes for each point along the contour can be included (attribs), for example, the edge amplitude of subpixel edge points or the orientation of the local gradient.
Finally, an arbitrary number of additional global attributes, i.e., attributes valid for the entire contour, can be included (global), for example, the individual parameters of a regression line to the contour or the parameters of an ellipse segment fitted to the contour.
Names
Synopsis
#include "Halcon.h"
Herror HCopyXLDCont( Hproc_handle proc_handle,
Hcont* cont_in,
bool preserve_attribs,
bool preserve_global_attribs,
Hcont** cont_out)
Herror HCopyXLDContPart( Hproc_handle proc_handle,
Hcont* cont_in,
INT4_8 min_index,
INT4_8 max_index,
bool preserve_attribs,
bool preserve_global_attribs,
Hcont** cont_out)
Names
Synopsis
#include "Halcon.h"
HAddXLDContAttrib( Hproc_handle proc_handle,
Hcont* cont,
char* name,
int32_t* index)
HLookupXLDContAttrib( Hcont* cont,
char* name,
int32_t* index)
HAddXLDContGlobalAttrib( Hproc_handle proc_handle,
Hcont* cont,
char* name,
int32_t* indx);
HLookupXLDContGlobalAttrib( Hcont* cont,
char* name,
int32_t* indx);
Please see Global data for routines to allocate/deallocate contours.
Two important auxiliary routines to copy contours are listed in Auxiliary routines for contours of type Hcont.
HCopyXLDCont copies a complete contour, whereas HCopyXLDContPart copies only a part of the original contours specified by two indices min_index and max_index.
They refer to the first and the last point along the contour to be copied (starting with index 0).
For closed contours a negative value might be specified for min_index.
This will lead to a “wrap-around”, that is the part of the contour to be copied starts at cont_in->num + min_index.
Both HCopyXLDCont and HCopyXLDContPart allocate the output contour themselves.
So just pass a pointer to a pointer to Hcont without allocating any memory for cont_out.
Both routines provide two additional parameters, preserve_attribs and preserve_global_attribs, to control whether the non-global and the global contour attributes should be copied.
The routines provided for handling contour attributes of contour points are summarized in Handling contour attributes of contour pixels (within Hcont).
HAddXLDContAttrib is used to add a new class of contour attributes to a given contour cont.
Note that this routine allocates memory for the attribute values, but it does not set the values themselves.
An arbitrary name for the attribute can be specified by the parameter name.
The index of the new attribute within the attribs array in cont is returned in index and can be used to address the values by cont->attribs[index].val[xxx].
The same holds for global attributes: HAddXLDContGlobalAttrib is used to add new global attributes, which can be accessed by cont->global[index].val.
These values can be accessed within the HALCON system (that is on the application layer) using the operators get_contour_attrib_xld and get_contour_global_attrib_xld.
Within HALCON, a specific attribute of a contour can be accessed using HLookupXLDContAttrib, while a specific global attribute can be accessed using HLookupXLDContGlobalAttrib.
These routines return the index of the desired attribute within attribs or global of cont, or the error code H_ERR_XLD_CAND as result of the procedure call, if no attribute with the specified name is defined.
The XLD data type Hpoly, displayed in The XLD data type Hpoly for subpixel polygons, encodes subpixel accurate polygons.
Basically it contains an array of control points.
In many applications such polygons are derived from contours.
Thus, the data structure can also hold a reference to the underlying part of a contour specified by a HALCON database key.
Control parametersđź”—
typedef union {
INT4_8 l; /* 4/8 byte integer */
double d; /* 8 byte real */
char* s; /* string */
Hphandle H; /* Pointer to handle */
} Hpar;
typedef struct {
Hpar par;
int type;
} Hcpar;
HALCON’s basic and essential view on control data are arrays. These arrays are used to pass control parameter values to supply procedures and can assume five different types, four basic or a mixed type, see Parameter description.
Basic types are supported INT4_8 arrays, coded as LONG_PAR, double arrays coded as DOUBLE_PAR, handle arrays coded as HANDLE_PAR, and string arrays, i.e., char* arrays, coded as STRING_PAR.
Note that all strings passed to and from the HALCON library must be encoded in UTF-8.
The legacy encoding mode (set_system('filename_encoding','locale') is not supported for extension packages that use strings with non-ASCII characters.
The structure Hcpar enables HALCON to pass a mixed type (MIXED_PAR), holding any of the basic types in the union Hpar, encoded by the specifyer type.
Data types Hpar and Hcpar for control parameters shows the corresponding definitions.
Thus, it is possible to pass a native array type or to combine different types within an array of Hcpar values.
For it, the selector type must be set to one of the basic type codes LONG_PAR, DOUBLE_PAR, HANDLE_PAR or STRING_PAR.
The Extension Package Interface procedures described in Reading and writing control parameters are used to access the control parameters of HALCON operators and pass the control data arrays through the interface.