Creating an applicationđź”—
Your own C++ programs that use HALCON operators must include the file HalconCpp.h, which contains all user-relevant definitions of the HALCON system and the declarations necessary for the C++ interface.
Do this by adding the following command near the top of your C++ file:
To create an application, link the library halconcpp.lib to your program.
The example projects show the necessary Visual C++ project settings. Basically, you need to specify the correct include path in the compiler settings, and the correct library path and libraries in the linker settings:
- Compiler > Include Directories
$(HALCONROOT)\include,$(HALCONROOT)\include\halconcpp- Linker > Library Directories
$(HALCONROOT)\lib\$(HALCONARCH)- Linker > Additional Dependencies
halconcpp.lib
HALCON XL applications
If you want to use HALCON XL, link the library halconcppxl.lib instead.
Only use HALCON XL when you need its features.
Compiling and linking an example program
The following example shows a very basic C++ program called main.cpp, which reads an image and then prints its width and height:
#include "HalconCpp.h"
#include <iostream>
int main(int argc, char **argv)
{
HalconCpp::HObject hobj;
HalconCpp::HTuple width, height;
HalconCpp::ReadImage(&hobj, "printer_chip/printer_chip_01");
HalconCpp::GetImageSize(hobj, &width, &height);
std::cout << "Image - width: " << width.I() << ", height: " << height.I() << '\n';
return 0;
}
To compile and link the program, run
cl main.cpp /I %HALCONROOT%\include /I %HALCONROOT%\include\halconcpp
/link %HALCONROOT%\lib\%HALCONARCH%\halconcpp.lib
Building HALCON examples with CMake
You can find examples that showcase various HALCON use cases and how they are implemented in C++ in the directories below %HALCONEXAMPLES%\cpp.
You can build them with CMake by using the provided CMakeLists.txt file.
To build example programs using CMake, do the following:
- If required, download CMake (version 3.7.1 or later) from the CMake website and install it.
-
Create a build directory and then run
To configure, CMake needs to know the location of the HALCON installation, the location of the example files, and which HALCON architecture to use:cmaketo configure the build and create the application:- Specify the location of the HALCON installation via the
HALCON_DIRCMake option, or via the%HALCONROOT%environment variable if the option is not set. - Specify the location of the HALCON example files via the
%HALCONEXAMPLES%environment variable. - Specify the HALCON architecture with the
HALCON_ARCHITECTURECMake option, or via the%HALCONARCH%environment variable. If neither the option nor the environment variable are set, CMake will try to guess the architecture based on the host build system.
For general information on how to use CMake, see the CMake documentation .
HALCON XL applications: By default, the examples will be built using the normal version of HALCON. If you want to build using HALCON XL, set the option
HALCON_XLtoONor1in CMake during the configuration step. For this, use the following syntax:cmake -DHALCON_XL=1 %HALCONEXAMPLES%\cpp\console - Specify the location of the HALCON installation via the
-
Optionally, you can use the
-Goption to specify the generator for a new build tree. For more information about CMake generators, see the CMake documentation .
You can find corresponding CMakeLists.txt files in the other subfolders as well (mfc\FGMultiThreading, mfc\Matching, mfc\MatchingExtWin, qt\Matching).
Your own C++ programs that use HALCON operators must include the file HalconCpp.h, which contains all user-relevant definitions of the HALCON system and the declarations necessary for the C++ interface.
Do this by adding the following command near the top of your C++ file:
To specify the include path for the compiler on the command line, use the following syntax:
To create an application, you have to link two libraries to your program:
The library libhalconcpp.so contains the various components of the HALCON/C++ interface.
The library libhalcon.so is the HALCON library.
To specify the library path and the libraries for the linker, use the following syntax:
On some systems, you also have to link the libraries libdl.so and librt.so (by using the additional options -ldl and -lrt, respectively).
HALCON XL applications
If you want to use HALCON XL, link the libraries libhalconcppxl.so and libhalconxl.so instead.
Only use HALCON XL when you need its features.
To link and run applications under Linux, ensure that the system variable LD_LIBRARY_PATH contains the HALCON library path $HALCONROOT/lib/$HALCONARCH.
Compiling and linking an example program
The following example shows a very basic C++ program called main.cpp, which reads an image and then prints its width and height:
#include "HalconCpp.h"
#include <iostream>
int main(int argc, char **argv)
{
HalconCpp::HObject hobj;
HalconCpp::HTuple width, height;
HalconCpp::ReadImage(&hobj, "printer_chip/printer_chip_01");
HalconCpp::GetImageSize(hobj, &width, &height);
std::cout << "Image - width: " << width.I() << ", height: " << height.I() << '\n';
return 0;
}
To compile and link the program, run
g++ -o example main.cpp -I$HALCONROOT/include -I$HALCONROOT/include/halconcpp \
-L$HALCONROOT/lib/$HALCONARCH -lhalconcpp -lhalcon -lpthread
Building HALCON examples with CMake
You can find examples that showcase various HALCON use cases and how they are implemented in C++ in the directories below $HALCONEXAMPLES/cpp.
You can build them with CMake by using the provided CMakeLists.txt file.
To build example programs using CMake, do the following:
- If required, download CMake (version 3.7.1 or later) from the CMake website and install it.
-
Create a build directory and then run
To configure, CMake needs to know the location of the HALCON installation, the location of the example files, and which HALCON architecture to use:cmaketo configure the build and create the application:- Specify the location of the HALCON installation via the
HALCON_DIRCMake option, or via the$HALCONROOTenvironment variable if the option is not set. - Specify the location of the HALCON example files via the
$HALCONEXAMPLESenvironment variable. - Specify the HALCON architecture with the
HALCON_ARCHITECTURECMake option, or via the$HALCONARCHenvironment variable. If neither the option nor the environment variable are set, CMake will try to guess the architecture based on the host build system.
For general information on how to use CMake, see the CMake documentation .
HALCON XL applications: By default, the examples will be built using the normal version of HALCON. If you want to build using HALCON XL, set the option
HALCON_XLtoONor1in CMake during the configuration step. - Specify the location of the HALCON installation via the
-
Optionally, you can use the
-Goption to specify the generator for a new build tree. For more information about CMake generators, see the CMake documentation .
You can find corresponding CMakeLists.txt files in the other subdirectories as well (mfc/FGMultiThreading, mfc/Matching, mfc/MatchingExtWin, qt/Matching).
For .NET Framework, the examples are given in C#, using Visual Studio under Windows as development environment. If programming constructs or activities differ in Visual Basic.NET or managed C++, this is noted at the first occurrence.
For .NET Core, the examples are given in C# using the .NET Core SDK, usable on both Windows and Linux. Currently, MVTec does not officially support using the .NET Core interface with other languages. Only C# has been in focus for testing and documentation.
Adding HALCON/.NET to an application
Adding a HALCON/.NET package reference to a .NET Core application
To leverage the cross-platform nature of .NET Core, the interface is offered in two package variants. Both of them contain the complete HALCON/.NET and HDevEngine/.NET language bindings.
MVTec.HalconDotNet- This package targets .NET Standard 2.0 and can be used on all architectures supported by HALCON.
MVTec.HalconDotNet-Windows- This package targets .NET Core 3.1 and additionally includes Windows Forms and WPF controls for integrating HALCON windows into GUI applications. This package can only be used on Windows, as other .NET Core 3.1 implementations do not offer Windows Forms or WPF support.
To add package references to your project, use the following command:
To use the packages offline, download them from the NuGet website .
To source your project reliably from a file system, consider adding a nuget.config file:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<add key="LocalHalconPackages" value="path/to/package" />
</packageSources>
</configuration>
HALCON XL applications
When developing an application with HALCON XL, select the following XL packages:
MVTec.HalconDotNetXLMVTec.HalconDotNetXL-Windows
Only use HALCON XL when you need its features.
Managing NuGet packages in Visual Studio
When working in Visual Studio, you can also add the NuGet package reference to the project by using the NuGet Package Manager from the Solution Explorer. When using the command line, make sure you choose the matching package version for your installed HALCON version.
Creating a WPF application with visualization in Visual Studio
To create a WPF application in Visual Studio that uses a HALCON window for visualization, follow these steps:
- Use the common Visual Studio mechanism for creating a WPF application.
- Add a package reference as described in the previous section.
The required package isMVTec.HalconDotNet-Windows. -
Edit the XAML file.
-
Add the HALCON namespace reference:
-
Add the
⤷ After this change, the XAML file should look something like this:HSmartWindowControlWPFelement:<Window x:Class="WpfApp2.MainWindow" xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:d="http://schemas.microsoft.com/expression/blend/2008" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:ha="http://schemas.mvtec.com/halcondotnet" xmlns:local="clr-namespace:WpfApp2" mc:Ignorable="d" Title="MainWindow" Height="513" Width="862"> <Grid Margin="0,0,-433,-146"> <Button Content="Button" HorizontalAlignment="Left" Height="5" Margin="178,121,0,0" VerticalAlignment="Top" Width="7" /> <Button Name="MyButton" Content="My Button

" HorizontalAlignment="Left" Height="84" Margin="156,121,0,0" VerticalAlignment="Top" Width="151" Click="Button_Click" /> <ha:HSmartWindowControlWPF Name="MyControl" Margin="399,55,313,55" /> </Grid> </Window>
-
Adding HALCON/.NET to a .NET Framework application
To add HALCON/.NET to an application, follow these steps:
- For the first application, customize the Visual Studio toolbox.
- For each application, add a reference to HALCON/.NET and specify the namespace.
Customizing the Visual Studio toolbox
The HALCON/.NET assembly provides not only a class library but also one control HSmartWindowControl (or HSmartWindowControlWPF), which contains a HALCON graphics window for visualizing images and results.
Note
The older control HWindowControl is still available for backwards compatibility.
We strongly advise against using this control for new projects.
See section Window controls for visualization for information about the differences.
You can add these controls to the Visual Studio toolbox by performing the following steps. Note that the exact menu names slightly differ in different versions of Visual Studio:
-
Right-click the toolbox and select Choose Items (Customize Toolbox in previous versions of Visual Studio).
⤷ A dialog opens, displaying all available .NET Framework components in a tab.
-
Click Browse, navigate to the directory
%HALCONROOT%\bin\dotnet20or%HALCONROOT%\bin\dotnet35, and select HALCON/.NET DLL.⤷ The icons of
HSmartWindowControland the olderHWindowControlappear in the toolbox.
HALCON XL applications
When developing an application with HALCON XL, select HALCON/.NET XL DLL instead of HALCON/.NET DLL.
In the toolbox, the control appears with the same name but with a different icon.
You can add both HALCON versions to the toolbox, but only one of them to an application.
Only use HALCON XL when you need its features.
Adding a reference to HALCON/.NET
In many applications, you will use at least one instance of HSmartWindowControl to visualize results.
By adding the control to the form (as described in section “Customizing HSmartWindowControl for the Visualization”), you automatically create a reference to the assembly HALCON/.NET DLL.
If you do not want to use HSmartWindowControl, add a reference as follows:
- Right-click References in the Solution Explorer and select Add Reference.
- Click Browse, navigate to the subdirectory
%HALCONROOT%\bin\dotnet20or%HALCONROOT%\bin\dotnet35, and select the assembly HALCON/.NET DLL.
HALCON XL applications
When developing an application with HALCON XL, select HALCON/.NET XL DLL instead of HALCON/.NET DLL.
If you already added a reference to the HALCON version, delete this reference and add one to HALCON/.NET XL DLL.
Only use HALCON XL when you need its features.
Deploying an application
.NET applications typically include all .NET package and assembly dependencies in their build output, hence deployment is simply a copy operation. Depending on whether the build type is self-contained or not, the appropriate .NET runtime must be installed on the destination machine as well.
Native DLLs are resolved at runtime from the system environment.
Therefore, a matching HALCON version and license must be installed on the destination computer, and the environment variables HALCONROOT and HALCONARCH must be set correctly.
Remote access security
For performance reasons, HALCON/.NET suppresses unmanaged code security when making calls into the native HALCON library. If your machine vision application runs in an environment that allows remote access, explicitly check permissions for code calling within your application or library.
HALCON/.NET applications under Linux using Mono
Note
If you want to target Linux and do not need Windows Forms, consider using .NET Core.
Restrictions
Note the following restrictions when developing or using HALCON/.NET applications via Mono:
- Mono only supports Windows Forms 2.0.
-
HWindowControlis not yet initialized in the eventLoadof a form, due to a different initialization order of X Window widgets. Place initialization and similar code in the event handler of theHSmartWindowControl’s (orHWindowControl’s) eventHInitWindow.
Deploying HALCON/.NET applications created under Windows
Because of HALCON/.NET’s platform independence, you can copy an application created under Windows to a Linux computer and simply start it there, provided that Mono and HALCON are installed on the destination computer (see Deploying an application).
Compiling HALCON/.NET applications created with Mono
Most of the HALCON/.NET examples provide a set of makefiles in the subdirectory makefiles to let you compile them under Linux.
To start the compilation, enter gmake\
⤷ The executable is placed in the subdirectory makefiles/bin.
HALCON XL applications
To create a HALCON XL application, enter gmake XL=1 instead.
Only use HALCON XL when you need its features.
In some cases, Mono may not find the native HALCON library libhalcon.so, which should be resolved via the environment variable LD_LIBRARY_PATH and issue a corresponding error.
You can create configuration files for the HALCON/.NET assembly that explicitly specify the path to the HALCON library by calling gmake config.
Configuration file with HALCON being installed in the directory /opt/halcon
If you want to create a configuration file for only one of the assemblies, use the make commands config_halcon and config_engine.
Tip
You can also use xbuild (Mono’s implementation of msbuild) with the project files.
Using other GUI libraries
In principle, you can also use other GUI libraries instead of Windows Forms or WPF, for example, Gtk#.
However, HSmartWindowControl or HSmartWindowControlWPF are Windows Forms or WPF elements, respectively, and thus cannot be used in that case.
Instead, you can open HALCON graphics windows directly with the operator OpenWindow.
If you want to place a graphics window inside another element, pass the element’s native window handle in the parameter fatherWindow.
Note that HALCON/.NET has not been tested with other GUI libraries.
There is no standard way for assembling Python applications into ready-to-use applications. Approaches range from just copying files to embedding the source code, interpreter, and runtime via tools like cx_Freeze.
Native DLLs are resolved at runtime from the system environment.
Therefore, a matching HALCON version and license must be installed on the destination computer, and the environment variables HALCONROOT and HALCONARCH must be set correctly.
Using a newer HALCON/Python release
You can check which HALCON/Python version is installed in your Python environment by running pip freeze.
If you want to update to a newer HALCON version, install the new version in your Python environment.
For example, to update to 26.11.1, run this command in a shell inside your project directory:
Your own C programs that use HALCON operators must include the file HalconC.h, which contains all user-relevant definitions of the HALCON system and the declarations necessary for the C interface.
Do this by adding the following command near the top of your C file:
To create an application, link the library halconc.lib/.dll to your program.
The example projects show the necessary Visual C++ project settings.
For the examples, the project should be of the “WIN 32 ConsoleApplication” type.
Note that the Visual C++ compiler implicitly calls “Update all dependencies” when a new file is added to a project.
As HALCON runs on both Windows and Linux, the include file HalconC.h also contains several Linux-specific headers.
As these do not exist under Windows, and as the Visual C++ compiler ignores the operating system-specific cases in the include files, you will receive several warning messages about missing header files.
You can safely ignore these warnings.
Make sure that the stacksize is sufficient. Some sophisticated image processing problems require up to 1 MB stacksize, so ensure to configure your compiler accordingly. See your compiler manual for additional information on this topic.
HALCON XL applications
If you want to use HALCON XL, link the libraries halconxl.lib/.dll and halconcxl.lib/.dll instead.
Only use HALCON XL when you need its features.
Building HALCON examples with CMake
You can find examples that showcase various HALCON use cases and how they are implemented in C in the directories below %HALCONEXAMPLES%\c.
You can build them with CMake by using the provided CMakeLists.txt file.
To build example programs using CMake, do the following:
- If required, download CMake (version 3.7.1 or later) from the CMake website and install it.
-
Create a build directory and then run
To configure, CMake needs to know the location of the HALCON installation, the location of the example files, and which HALCON architecture to use:cmaketo configure the build and create the application:- Specify the location of the HALCON installation via the
HALCON_DIRCMake option, or via the%HALCONROOT%environment variable if the option is not set. - Specify the location of the HALCON example files via the
%HALCONEXAMPLES%environment variable. - Specify the HALCON architecture with the
HALCON_ARCHITECTURECMake option, or via the%HALCONARCH%environment variable. If neither the option nor the environment variable are set, CMake will try to guess the architecture based on the host build system.
For general information on how to use CMake, see the CMake documentation .
HALCON XL applications: By default, the examples will be built using the normal version of HALCON. If you want to build using HALCON XL, set the option
HALCON_XLtoONor1in CMake during the configuration step. For this, use the following syntax:cmake -DHALCON_XL=1 %HALCONEXAMPLES%\c - Specify the location of the HALCON installation via the
-
Optionally, you can use the
-Goption to specify the generator for a new build tree. For more information about CMake generators, see the CMake documentation .
Your own C programs that use HALCON operators must include the file HalconC.h, which contains all user-relevant definitions of the HALCON system and the declarations necessary for the C++ interface.
Do this by adding the following command near the top of your C file:
Using this syntax, the compiler looks for HalconC.h in the current directory only.
Alternatively, you can tell the compiler where to find the file by giving it the -I<pathname> command line flag to denote the include file directory.
To create an application, you have to link two libraries to your program:
The library libhalconc.so contains the various components of the HALCON/C interface.
The library libhalcon.so is the HALCON library.
HALCON XL applications
If you want to use HALCON XL, link the libraries libhalconcxl.so and libhalconxl.so instead.
Only use HALCON XL when you need its features.
To link and run applications under Linux, ensure that the system variable LD_LIBRARY_PATH contains the HALCON library path $HALCONROOT/lib/$HALCONARCH.
Building HALCON examples with CMake
You can find examples that showcase various HALCON use cases and how they are implemented in C in the directories below $HALCONEXAMPLES/c.
You can build them with CMake by using the provided CMakeLists.txt file.
To build example programs using CMake, do the following:
- If required, download CMake (version 3.7.1 or later) from the CMake website and install it.
-
Create a build directory and then run
To configure, CMake needs to know the location of the HALCON installation, the location of the example files, and which HALCON architecture to use:cmaketo configure the build and create the application:- Specify the location of the HALCON installation via the
HALCON_DIRCMake option, or via the$HALCONROOTenvironment variable if the option is not set. - Specify the location of the HALCON example files via the
$HALCONEXAMPLESenvironment variable. - Specify the HALCON architecture with the
HALCON_ARCHITECTURECMake option, or via the$HALCONARCHenvironment variable. If neither the option nor the environment variable are set, CMake will try to guess the architecture based on the host build system.
For general information on how to use CMake, see the CMake documentation .
HALCON XL applications: By default, the examples will be built using the normal version of HALCON. If you want to build using HALCON XL, set the option
HALCON_XLtoONor1in CMake during the configuration step. - Specify the location of the HALCON installation via the
-
Optionally, you can use the
-Goption to specify the generator for a new build tree. For more information about CMake generators, see the CMake documentation .