Interactive HALCON datatype explorer

A product of heindl-solutions.com.

HALCON is a product of MVTec Software GmbH.

Did you ever ask yourself: "What's the meaning of all these different data types in HALCON?". Here's an interactive overview. First, select the configuration of HALCON you are using. Then click on the data type nodes in the tree to see details.

Please contact us for commercial service offerings.

Product version

Currently we support data types of HALCON 11 and HALCON 12. Select the major version you are using.

Architecture

The used architecture of HALCON. The x64-* architectures can only be used on an x64 operating system. Available architectures depend on the selected product version.

XL

HALCON comes in two variants: standard and XL. HALCON XL is optimized for large images (larger than 32k x 32k).

Expert

Show additional fields and additional details.


Details

Interactive HALCON datatype explorer. Reveal the details of the HALCON machine vision library.

Click on a node on the left to see details here.

Please contact us for commercial service offerings.

An object or iconic variable is one of the two most basic types used in HALCON. The other basic type is a tuple or control variable. HALCON operators can have input objects, output objects, input tuples, and output tuples (if used they always appear in this sequence in an operator's function signature).

An object can consist of a practically arbitrary number of images, regions, XLD contours,XLD polygons, and XLD parallel contours, these can be mixed within one object, too.

An empty object containing zero elements may be created with the operator gen_empty_obj.

An image organizes the pixel data received e.g. from a camera. An image can contain an arbitrary number of channels. Most common are one channel respresenting a grayscale image or three channels representing the red, green, and blue components of the pixels. The dimensions of an image are defined as HIMGDIM, i.e. the maximum size of an image is . However, the coordinates within an image are defined to be HIMGCOOR, which differes from HIMGDIM in the standard (non-XL) HALCON version.
A region or ROI in HALCON is an area, often defined on an image. The area is runlength encoded, i.e. sequential columns within one row are encoded with row, column begin, and column end.

The internal representation of the region chords can be accessed by calling the operator get_region_runs.

By default, HALCON clips regions (get_system ('clip_region', ClipRegion) returns ClipRegion := 'true') to a maximum size of 512 x 512 (get_system ('height', Height) returns Height := 512). You can change this behavior with set_system ('clip_region', "false") .

An empty region (area = 0) may be created with the operator gen_empty_region.

XLD contours describe subpixel-accurate contours. In addition, an XLD contour can contain global and local attributes. Coordinates of points and additional optional attributes in an XLD contour have the data types HSUBCOOR and HSUBATTR.
XLD polygons describe subpixel-accurate approximations of contours as polygons. Coordinates of points and additional optional attributes in an XLD polygon have the data types HSUBCOOR and HSUBATTR. XLD polygons are typically rarely used compared to XLD contours.
XLD parallels describe subpixel-accurate parallel XLD polygons. Coordinates of points and additional optional attributes in an XLD parallel have the data types HSUBCOOR and HSUBATTR. XLD parallels are typically rarely used compared to XLD contours.

A channel contains the gray value data for one component of the pixels. Unlike many formats encountered in other applications, HALCON separates multiple channels in memory, so the internal layout for an RGB image is something like ['RRRRR...', 'GGGGG...', 'BBBBB...'] in HALCON and not ['RGBRGBRGB...'] as one might eventually expect.. All channels have the size (width and height) of the parent image but each channel can have a different channel type.

The number of channels can be determined by calling the operator count_channels.

A single channel can be accessed by calling the operator access_channel or decompose2 (2-channel image), decompose3 (3-channel image), decompose4, decompose5, decompose6, or decompose7.

A domain is the region or ROI bound to an image that defines which region HALCON operators consider when applied to that image.

For more details see the description of region.

Each channel of an image contains a linearized array of gray values, e.g. the red components of all pixels in the image.

In HALCON, one row of pixels equals exactly the stride, i.e. there is no special alignment of pixels that start a new row. The maximum number of pixels is defined through HIMGCNT, i.e. the maximum number of pixels is .

The number of pixels can be determined by calling the operator get_image_pointer1 or get_image_size. Then NumPixels := Height * Width .

The height of an image is defined as HIMGDIM, i.e. the maximum height of an image is . Be aware that the maximum image coordinate is defined to be HIMGCOOR though, see also the description of image.

The height of an image can be determined by calling the operator get_image_size.

The width of an image is defined as HIMGDIM, i.e. the maximum width of an image is . Be aware that the maximum image coordinate is defined to be HIMGCOOR though, see also the description of image.

The height of an image can be determined by calling the operator get_image_size.

Possible channel types are:
byte1 byte per pixel, unsigned0..255
int11 byte per pixel, signed-128..127
uint22 bytes per pixel, unsigned0..65535
int22 bytes per pixel, signed-32768..32767)
int44 bytes per pixel, signed-2147483648..2147483647)
int88 bytes per pixel, signed (only available on 64 bit systems)-9223372036854775808..9223372036854775807)
real4 bytes per pixel, floating point-3.4e38..3.4e38
6 significant decimal digits
complexTwo matrices of type real
vector_field_relativeTwo matrices of type realInterpretation: Vectors
vector_field_absoluteTwo matrices of type realInterpretation: Absolute coordinates
direction1 byte per pixel, unsigned0..179
Interpretation: Angle divided by two
cyclic1 byte per pixel, unsigned, cyclic arithmetics0..255
See the operator documentation for gen_image_const for further details.

The type of a channel can be determined by calling the operator get_image_pointer1 or get_image_type.

A single run or chord of a region.

The maximum number of runs or chords is defined through HITEMCNT, i.e. the maximum number of runs or chords is .

The row of a single run or chord of a region.

The row is defined through HIMGCOOR, i.e. the maximum row is .

The column in which a single run or chord of a region begins, including the column itself.

The column is defined through HIMGCOOR, i.e. the maximum column is .

The length of a run is given by Length := ColumnEnd - ColumnStart + 1 .

The column in which a single run or chord of a region ends, including the column itself.

The column is defined through HIMGCOOR, i.e. the maximum column is .

The length of a run is given by Length := ColumnEnd - ColumnStart + 1 .

Each image channel contains a reference to its creator operator. Get the creator with the operator get_channel_info with Request = 'creator'.
Each image channel contains a timestamp at which the image was created. Get the time stamp with the operator get_image_time.
XLDs can contain global attributes generated in previous operator calls (e.g. regress_contours_xld creates XLDs with the global attributes 'regr_norm_row', 'regr_norm_col', ... Global attributes are defined per contour in contrast to local attributes which are defined for each point of a contour. Global attributes can be queried with the operators query_contour_global_attribs_xld and get_contour_global_attrib_xld.
XLDs can contain local attributes generated in previous operator calls (e.g. regress_contours_xld creates XLDs with the local attributes 'angle', 'response', ... Local attributes are defined for each point of a contour in contrast to global attributes which are defined for the whole contour. Local attributes can be queried with the operators query_contour_attribs_xld and get_contour_attrib_xld.
Name of a global attribute. Names can be queried with the operator query_contour_global_attribs_xld.
Value of a global attribute. Values can be queried with the operator get_contour_global_attrib_xld. Global attributes in an XLD contour have the data type HSUBATTR.
Name of a local attribute. Names can be queried with the operator query_contour_attribs_xld.
Value of a local attribute. Values can be queried with the operator get_contour_attrib_xld. Local attributes in an XLD contour have the data type HSUBATTR.

A tuple or control variable is one of the two most basic types used in HALCON. The other basic type is an object or iconic variable. HALCON operators can have input objects, output objects, input tuples, and output tuples (if used they always appear in this sequence in an operator's function signature).

Many operators on (large) tuples will work faster if all data types in a tuple are the same.

The tuple length is defined by Hlong, i.e. the maximum number of elements in a tuple is .

An empty object containing zero elements may be created with Tuple := [] .

A tuple can contain integers, defined as Hlong.

An integer is defined by Hlong, i.e. the minimum value is and the maximum value is .

A tuple can contain real numbers, defined as double.

Double has a minimum value of and a maximum value of .

A tuple can contain strings (0-terminated). Strings are defined using single quotes in HALCON (e.g. 'str').