Skip to content

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.

Data type Himage for images
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.

Definitions of pixel types
#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)       */
Data types for Himage
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:

L = R * image.width + C

This transformation is performed by the following macro HLinCoor:

L = HLinCoor(R,C,image.width);

There are two additional macros for computing rows (HRow) and columns (HCol):

R = HRow(L,image.width);
C = HCol(L,image.width);

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

Data type Hrlregion for region encoding
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.

Data type HRegFeature for region shape features
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

CB, CE

Synopsis

Linear coordinates from Hrlregion
#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.

The XLD data type Hcont for subpixel contours
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;
The XLD data type Hpoly for subpixel polygons
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

HCopyXLDCont, HCopyXLDContPart

Synopsis

Auxiliary routines for contours of type Hcont
#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

HAddXLDContAttrib, HLookupXLDContAttrib,
HAddXLDContGlobalAttrib, HLookupXLDContGlobalAttrib

Synopsis

Handling contour attributes of contour pixels (within Hcont)
#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đź”—

Data types Hpar and Hcpar for 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.