Skip to content

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:

#include "HalconCpp.h"

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:

  1. If required, download CMake (version 3.7.1 or later) from the CMake website and install it.
  2. Create a build directory and then run cmake to configure the build and create the application:

    mkdir build
    cd build
    cmake %HALCONEXAMPLES%\cpp\console
    cmake --build .
    
    To configure, CMake needs to know the location of the HALCON installation, the location of the example files, and which HALCON architecture to use:
    • Specify the location of the HALCON installation via the HALCON_DIR CMake 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_ARCHITECTURE CMake 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_XL to ON or 1 in CMake during the configuration step. For this, use the following syntax: cmake -DHALCON_XL=1 %HALCONEXAMPLES%\cpp\console

  3. Optionally, you can use the -G option 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:

#include "HalconCpp.h"

To specify the include path for the compiler on the command line, use the following syntax:

-I$HALCONROOT/include -I$HALCONROOT/include/halconcpp

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:

-L$HALCONROOT/lib/$HALCONARCH -lhalconcpp -lhalcon -lpthread

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:

  1. If required, download CMake (version 3.7.1 or later) from the CMake website and install it.
  2. Create a build directory and then run cmake to configure the build and create the application:

    mkdir build
    cd build
    cmake $HALCONEXAMPLES/cpp/console
    cmake --build .
    
    To configure, CMake needs to know the location of the HALCON installation, the location of the example files, and which HALCON architecture to use:
    • Specify the location of the HALCON installation via the HALCON_DIR CMake 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_ARCHITECTURE CMake 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_XL to ON or 1 in CMake during the configuration step.

  3. Optionally, you can use the -G option 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:

dotnet add package <PACKAGE_NAME> -v 26111

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.HalconDotNetXL
  • MVTec.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:

  1. Use the common Visual Studio mechanism for creating a WPF application.
  2. Add a package reference as described in the previous section.
    The required package is MVTec.HalconDotNet-Windows.
  3. Edit the XAML file.

    1. Add the HALCON namespace reference:

      xmlns:ha="http://schemas.mvtec.com/halcondotnet
      
    2. Add the HSmartWindowControlWPF element:

      ha:HSmartWindowControlWPF Name="MyName"  Margin="xyz"
      
      ⤷ After this change, the XAML file should look something like this:
      <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&#xD;&#xA;&#xD;&#xA;"
        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:

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:

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

  2. Click Browse, navigate to the directory %HALCONROOT%\bin\dotnet20 or %HALCONROOT%\bin\dotnet35, and select HALCON/.NET DLL.

    ⤷ The icons of HSmartWindowControl and the older HWindowControl appear 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:

  1. Right-click References in the Solution Explorer and select Add Reference.
  2. Click Browse, navigate to the subdirectory %HALCONROOT%\bin\dotnet20 or %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.
  • HWindowControl is not yet initialized in the event Load of a form, due to a different initialization order of X Window widgets. Place initialization and similar code in the event handler of the HSmartWindowControl’s (or HWindowControl’s) event HInitWindow.

    Example

    private void hWindowControl1_HInitWindow(object sender, System.EventArgs e)
    {
      window = hWindowControl1.HalconWindow;
      window.SetDraw("margin");
      window.SetColor("cyan");
    }
    

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

<configuration> 
  <dllmap dll="halcon"
          target="/opt/halcon/lib/x64-linux/libhalcon.so"/> 
</configuration>

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:

pip install -Iv mvtec-halcon==26111

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:

#include "HalconC.h"

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:

  1. If required, download CMake (version 3.7.1 or later) from the CMake website and install it.
  2. Create a build directory and then run cmake to configure the build and create the application:

    mkdir build
    cd build
    cmake %HALCONEXAMPLES%\c
    cmake --build .
    
    To configure, CMake needs to know the location of the HALCON installation, the location of the example files, and which HALCON architecture to use:
    • Specify the location of the HALCON installation via the HALCON_DIR CMake 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_ARCHITECTURE CMake 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_XL to ON or 1 in CMake during the configuration step. For this, use the following syntax: cmake -DHALCON_XL=1 %HALCONEXAMPLES%\c

  3. Optionally, you can use the -G option 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:

#include "HalconC.h"

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:

  1. If required, download CMake (version 3.7.1 or later) from the CMake website and install it.
  2. Create a build directory and then run cmake to configure the build and create the application:

    mkdir build
    cd build
    cmake $HALCONEXAMPLES/c
    cmake --build .
    
    To configure, CMake needs to know the location of the HALCON installation, the location of the example files, and which HALCON architecture to use:
    • Specify the location of the HALCON installation via the HALCON_DIR CMake 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_ARCHITECTURE CMake 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_XL to ON or 1 in CMake during the configuration step.

  3. Optionally, you can use the -G option to specify the generator for a new build tree. For more information about CMake generators, see the CMake documentation .