Skip to content

HALCON Architecture and General Conceptsđź”—

HALCON’s basic architecture is depicted in Figure 1. The main part is the image processing library, which consists of more than 2 000 operators. You use the operators in your application via language interfaces like HALCON/C++ or HALCON/Python. These are libraries, which allow a direct use of the operators in the typical programming style of the different programming languages.

Figure 1: Basic architecture of HALCON

To access image acquisition devices, HALCON provides image acquisition interfaces, which allow you to use quite different acquisition devices in a common way. The libraries containing the device-specific implementations are loaded dynamically when needed.
In the same fashion, I/O devices are accessed through device-specific I/O interfaces.

Operatorsđź”—

Whenever any kind of functionality is used from the HALCON library, it is done via an operator. Most of them comprise multiple methods, which are selected via parameters. A full list of all operators can be found in the HALCON Operator Reference, which is available in HDevelop, .NET, Python, C++, and C syntax.

Important features of operators are:

  • Operators have no hierarchy. From the software architecture point of view, all operators are on the same level.
  • Operators are logically grouped. For example, this can be seen in the classes offered for C++ and .NET, in which operators processing the same data type are member functions of the corresponding classes.

  • The design of the operators follows the rules of the open architecture. Therefore, you can create your own operators and thus extend HALCON (see Extension Packages).

  • Many operators can make transparent use of automatic parallelization, which allows an easy way of speeding up the program when using large images on a multi-processor or multi-core computer.

  • Operators have standardized rules for ordering input and output parameters (see below):
    input iconic, output iconic, input control, and output control. Not all of the groups may be needed for a given operator.
    In general, input parameters of operators are not modified, which results in a clear and simple semantics. There are only a few exceptions to this design, for example, set_grayval, overpaint_gray, and overpaint_region.

Parameters and Data Structuresđź”—

HALCON has two basic types of parameters: iconic data and control data.

Iconic Datađź”—

Images, regions, and XLDs (eXtented Line Description) belong to the iconic data.

Images
Images mainly consist of channels, that is, matrices containing pixel values. All channels of an image have the same size. For detailed information about pixels and channels, see Image in the HALCON Operator Reference.

For each image, the so-called region of interest (ROI) specifies which part of the image is processed. The ROI can be defined very flexibly (from a simple rectangle to a set of unconnected pixels).

More Info

For details about ROI handling, see “Region Of Interest” in the Solution Guide I – Basics

Regions
Regions are a set of pixels. The pixels of a region do not need to be connected. Even an arbitrary collection of pixels can be handled as a single region. With the operator connection, a region can be split into its connected regions, that is, components consisting of connected pixels.
XLDs
XLDs comprise all contour- and polygon-based data. Subpixel-accurate operators like edges_sub_pixreturn the contours as XLD data. A contour is a sequence of 2D control points, which are connected by lines. Typically, the distance between control points is about one pixel.
XLD objects contain, besides the control points, so-called local and global attributes. Typical examples for these are the edge amplitude of a control point or the regression parameters of a contour segment.
Besides the extraction of XLD objects, HALCON supports further processing. Examples for this are the selection of contours based on given feature ranges for the segmentation of a contour into lines, arcs, polygons, or parallels.

Control Datađź”—

The control data includes handles and basic data types like integer, real, or string.

Handles
Handles are references to complex data structures, for example, a connection to an image acquisition interface or a model for the shape-based matching. For efficiency and data security reasons, not the entire structure but only the handle is passed between the operators.
Handles are magic values that must not be changed and can differ from execution to execution and version to version. They are automatically cleared once all references are overwritten. Examples where handles are used are graphics windows, files, sockets, image acquisition interfaces, OCR, OCV, measuring, and matching.

Extension Packagesđź”—

HALCON can be extended by new operators. Although HALCON already contains an abundant set of operators for various tasks, you may wish to implement new operators, for example, to access a special hardware or to implement an alternative algorithm. To do so, HALCON provides the Extension Package Interface, which allows the integration of new operators (implemented in C) in the form of so-called extension packages.
The Extension Package Interface contains several predefined routines and macros for the easy handling of image data and memory objects in C. Once a new operator has been successfully integrated, it can be used like any other HALCON operator.

More Info

For detailed information, see the Extension Package Programmer’s Manual .

Language Interfacesđź”—

Preview Restrictions

HDevelopEVO does not support language interfaces yet.

As shown in Figure 1, HALCON provides so-called language interfaces. These are native language bindings, which enable you to call operators and use HALCON data types directly from within your application, be it Python, C, C++, or .NET.

Note

  • For each language interface, the names of types, classes, the naming conventions of operators, etc. may differ to be compliant with the typical rules that apply for the selected language. The operator signatures for the supported programming languages are documented in the HALCON Operator Reference.

  • To start the development, we recommend that you first check one of the ready-to-run example programs below. They show how the project must be set up and how operators and types are used.

The Python interface stands out for its simplicity and its ability for rapid prototyping. HALCON operators are called directly as standalone functions, after importing the HALCON/Python module. Note that operator parameters in HALCON/Python are split into function parameters (inputs) and return values (output).

Example

The following code reads an image and computes the number of connected regions in it.

img = ha.read_image('pcb')
region = ha.threshold(img, 0, 122)
num_regions = ha.count_obj(ha.connection(region))
print(f'Number of Regions: {num_regions}')

The C interface is the simplest interface supported by HALCON. Each operator is represented by either one or two global functions, where the operator name and the parameter sequence are identical to the HDevelop language.

Example

The following code reads an image and computes the number of connected regions in it.

Hobject img;
read_image(&img, "pcb");

Hobject region;
threshold(img, &region, 0, 122);

Hobject connected_regions;
connection(region, &connected_regions);

Hlong num_regions = 0;
count_obj(connected_regions, &num_regions);

printf("Number of Regions: %" PRIdPTR "\n", num_regions);

The C++ interface is much more sophisticated than the C interface. Here, the advantages of C++ and object-oriented programming are used, i.e., automatic type conversion, construction and destruction, or grouping functions together with their data into classes. Like in the C interface, global functions for each HALCON operator are provided for a procedural style of programming.

Example

The following code reads an image and computes the number of connected regions in it.

HImage img{"pcb"};

HRegion region = img.Threshold(0, 122);
Hlong numRegions = region.Connection().CountObj();

std::cout << "Number of Regions: " << numRegions << '\n';

C# and Visual Basic .NET use HALCON via the .NET interface.

Analogously to C++, two styles of programming are offered: procedural and object-oriented. For the procedural style, the class HOperatorSet provides all HALCON operators, where HObject is used to handle iconic data and HTuple is used for control data. For the object-oriented style, classes like HDataCode2d, HMeasure, or HShapeModel are provided for the central functionality. In addition, classes for iconic data, e.g., HImage or HRegion, are available.

Example

The following code reads an image and computes the number of connected regions in it.

HImage img = new HImage("pcb");

HRegion region = img.Threshold(0d, 122d);
int numRegions = region.Connection().CountObj();

Console.WriteLine("Number of Regions: " + numRegions);

Image Acquisition Interfacesđź”—

HALCON’s image acquisition interfaces build the bridge between software provided by the manufacturer of the image acquisition device and HALCON. They form a common, generic interface that requires a small set of operators only.

Currently, HALCON provides interfaces for more than 50 frame grabbers and hundreds of industrial cameras in the form of dynamically loadable libraries (Windows: DLLs; Unix-like systems: shared libraries).
Library names start with the prefix hAcq; libraries ending with the suffix xl are used by HALCON XL.

The most widely used interfaces based on industry standards are already installed together with the HALCON libraries. Additional interfaces, as well as the latest versions of already included interfaces can be downloaded under www.mvtec.com/products/interfaces. The HALCON image acquisition interfaces may change more frequently than the HALCON library itself, as MVTec continuously develops new interfaces. Further, if the software provided by the manufacturers of image acquisition devices changes, the corresponding HALCON interfaces will be adapted.

Once you successfully installed your image acquisition device, all you need to do to access it from HALCON is to call the operator open_framegrabber, specifying the name of the image acquisition interface and some additional information, like the connected camera. Then, images can be grabbed by calling the operator grab_image (or grab_image_async).

More Info

For detailed information, see the Solution Guide II-A – Image Acquisition .

I/O Interfacesđź”—

HALCON provides interfaces for several I/O devices to enable data acquisition. These interfaces are available as dynamically loadable libraries (Windows: DLLs; Unix-like systems: shared libraries).
Library names start with the prefix hio; libraries ending with the suffix xl are used by HALCON XL.

The HALCON I/O device interfaces provide unified access to different I/O devices using a small set of operators. After you have installed your I/O device, a connection is established using the operator open_io_device, specifying the name of the I/O device interface and, optionally, some device-specific parameters.
Once the connection is established, a transmission channel can be opened by calling open_io_channel. To read and write values on this channel, use the operators read_io_channel and write_io_channel, respectively.

The HALCON I/O device interfaces may change more frequently than the HALCON library itself. You can find the latest information together with downloadable interfaces (including documentation) under www.mvtec.com/products/interfaces.