Skip to content

Environments and prerequisitesđź”—

Adhere to the following to prepare your environment for the corresponding programming language.

Relevant directories and files

Overview of relevant folders and files, relative to %HALCONROOT%:

include
Include directory; contains, for example, Halcon.h, which is referenced by HalconCpp.h
include\halconcpp\HalconCpp.h
Include file; contains all user-relevant definitions of the HALCON system and the declarations necessary for the C++ interface
bin\%HALCONARCH%\halcon.dll, lib\%HALCONARCH%\halcon.lib
HALCON library
bin\%HALCONARCH%\halconcpp.dll, lib\%HALCONARCH%\halconcpp.lib
HALCON/C++ library
bin\%HALCONARCH%\halconxl.dll, halconcppxl.dll, lib\%HALCONARCH%\halconxl.lib, halconcppxl.lib
Corresponding libraries of HALCON XL
include\HProto.h
External function declarations
%HALCONEXAMPLES%\cpp\console\CMakeLists.txt
Example CMake file, which can be used to compile the example programs
%HALCONEXAMPLES%\cpp\console\README.md
Information about building the examples using CMake
%HALCONEXAMPLES%\cpp\console\source\
Directory containing the source files of the example programs
%HALCONEXAMPLES%\images\
Images used by the example programs

Overview of relevant directories and files, relative to $HALCONROOT:

include
Include directory; contains, for example, Halcon.h, which is referenced by HalconCpp.h
include/halconcpp/HalconCpp.h
Include file; contains all user-relevant definitions of the HALCON system and the declarations necessary for the C++ interface
lib/$HALCONARCH/libhalcon.so
HALCON library
lib/$HALCONARCH/libhalconcpp.so
HALCON/C++ library
lib/$HALCONARCH/libhalconxl.so, libhalconcppxl.so
Corresponding libraries of HALCON XL
include/HProto.h
External function declarations
$HALCONEXAMPLES/cpp/console/CMakeLists.txt
Example CMake file, which can be used to compile the example programs
$HALCONEXAMPLES/cpp/console/README.md
Information about building the examples using CMake
$HALCONEXAMPLES/cpp/console/source/
Directory containing the source files of the example programs
$HALCONEXAMPLES/images/
Images used by the example programs

Despite the platform-independence of .NET, applications still depend on their target .NET runtime environment and, for GUI applications, the corresponding implementations for Windows Forms or WPF.

Versions and compatibility

Table 1 indicates the minimum requirements and capabilities of the different HALCON/.NET interface variants.

Note

Historically, there were two main environments, .NET Framework and .NET Core. The .NET unification plan started with .NET 5, .NET 6 delivered its final parts.

Generally, the dependencies are backwards compatible within a branch. For example, an application targeting .NET Framework 2.0 should run with all newer .NET Framework versions and .NET 5 and later.

Table 1: Properties of different HALCON/.NET interface variants
Minimum development environment HALCON/.NET interface Minimum runtime environment Windows Forms WPF Linux support2
Visual Studio 2013 %HALCONROOT%\bin\dotnet20 .NET Framework 2.0 Yes No Mono
Visual Studio 2013 %HALCONROOT%\bin\dotnet35 .NET Framework 3.5 Yes Yes Mono (no WPF)
.NET Core 3.1 SDK (Windows)1 MVTec.HalconDotNet (NuGet package)
MVTec.HalconDotNet-Windows (NuGet package)
.NET Standard 2.0

.NET Core 3.1
No

Yes
No

Yes
Yes

No
.NET Core 3.1 SDK (Linux) MVTec.HalconDotNet (NuGet package) .NET Standard 2.0 No No Yes

While NuGet uses semantic versioning (“SemVer”)  to version packages, HALCON versions are not SemVer compatible. To avoid unnecessary conflicts, .NET Core packages receive a SemVer-compatible version by combining the major, minor, and revision into a new version, for example:

Table 2: SemVer-compatible versions of HALCON/.NET for .NET Core
HALCON version HALCON/.NET package version
24.11.1 → 24111.0.0
26.05.0 → 2650.0.0
26.11.1 → 26111.0.0

HALCON/.NET is not a self-contained package but an interface to the native HALCON library. Therefore, the package version used by your project has to match the installed HALCON version exactly.

Even for maintenance releases, which are backwards compatible at application level, mixing of binaries from different releases is not recommended because the internal communication between HALCON/.NET and the native HALCON library is not guaranteed to be always compatible. Therefore, the revision of the HALCON release is also part of the SemVer major version.
The SemVer minor and patch version are reserved for fully backwards-compatible intermediate releases of the package itself. See Using a newer HALCON/.NET release for updating dependencies.

The provided examples generally target the oldest supported environment. For example, Windows Forms applications target .NET Framework 2.0 and are shipped with Visual Studio 2013 versions that open in all newer versions of Visual Studio.

The non-WPF C# examples also come with makefiles to support building via command line both with .NET Framework under Windows or Mono under Linux. Source files are placed in a separate, shared source directory next to the project or makefile directories. Some dedicated .NET Core examples are provided, which are suitable for building via command line using the .NET Core SDK.

Using a newer HALCON/.NET release

.NET Core

.NET Core projects resolve a specific version the moment you add the package. If you want to update to a newer HALCON version, for example from 26.5.1 to 26.11.1, you must change the version specified in your project.

Example

For example, change your project’s .csproj from

<PackageReference Include="MVTec.HalconDotNet" Version="2650.0.0 " />
to
<PackageReference Include="MVTec.HalconDotNet" Version="26111.0.0" />
.NET Framework
Applications that use HALCON/.NET have local copies of the corresponding assemblies. After installing a newer release of HALCON, these applications would therefore still use their old HALCON assemblies. To use the new HALCON/.NET DLL, re-build your project (Visual Studio > Solution > Rebuild Solution).
If you want to replace the HALCON/.NET DLL without recompiling the application, you need to both manually replace the HALCON/.NET DLL with the newly installed one, and update the application’s app.config to inform the executable of the new HALCON/.NET DLL.
Do this by copying either bin\dotnet20\app.config or bin\dotnet35\app.config into the directory containing the HALCON/.NET DLL, and rename the file to <application_name>.exe.config.

  1. Visual Studio 2019 or later is required. â†©

  2. See also HALCON/.NET applications under Linux using Mono. â†©

HALCON/Python packages are pip compatible.
Use the following command to add HALCON/Python to your project:

pip install mvtec-halcon==26111

Versions and compatibility

While the PyPA specifications (previously: PEP 440) and by extension PyPI do not require semantic versioning (“SemVer”)  , HALCON/Python and other language interface packages follow a SemVer approach to avoid unnecessary conflicts and tooling issues. However, HALCON versions are not SemVer compatible, so Python packages receive a SemVer-compatible version by combining the major, minor, and revision into a new version, as shown in Table 3.

Table 3: SemVer-compatible versions of HALCON/Python
HALCON version HALCON/Python package version
24.11.1 → 24111.0.0
26.05.0 → 2650.0.0
26.11.1 → 26111.0.0

Important

HALCON/Python is not a self-contained package but an interface to the native HALCON library. Therefore, the package version used by your project has to match the installed HALCON version exactly.

Even for maintenance releases, which are backwards compatible at application level, mixing of binaries from different releases is not recommended because the internal communication between HALCON/Python and the native HALCON library is not guaranteed to be always compatible. Therefore, the revision of the HALCON release is also part of the SemVer major version. The SemVer minor and patch version are reserved for fully backwards-compatible intermediate releases of the package itself. See Using a newer HALCON/Python release for updating dependencies.

To use the packages offline, download them from the PyPI website .

Relevant directories and files

Overview of relevant folders and files, relative to %HALCONROOT%:

include\HalconC.h
Include file; contains all user-relevant definitions of the HALCON system and the declarations necessary for the C interface
bin\%HALCONARCH%\halcon.dll, lib\%HALCONARCH%\halcon.lib
HALCON library
bin\%HALCONARCH%\halconc.dll, lib\%HALCONARCH%\halconc.lib
HALCON/C++ library
bin\%HALCONARCH%\halconxl.dll, halconcxl.dll, lib\%HALCONARCH%\halconxl.lib, halconcxl.lib
Corresponding libraries of HALCON XL
include\HProto.h
External function declarations
%HALCONEXAMPLES%\c\CMakeLists.txt
Example CMake file, which can be used to compile the example programs
%HALCONEXAMPLES%\c\README.md
Information about building the examples using CMake
%HALCONEXAMPLES%\c\source\
Directory containing the source files of the example programs
%HALCONEXAMPLES%\images\
Images used by the example programs

Overview of relevant directories and files, relative to $HALCONROOT:

include/HalconC.h
Include file; contains all user-relevant definitions of the HALCON system and the declarations necessary for the C++ interface
lib/$HALCONARCH/libhalcon.so
HALCON library
lib/$HALCONARCH/libhalconc.so
HALCON/C library
lib/$HALCONARCH/libhalconxl.so, libhalconcxl.so
Corresponding libraries of HALCON XL
include/HProto.h
External function declarations
$HALCONEXAMPLES/c/CMakeLists.txt
Example CMake file, which can be used to compile the example programs
$HALCONEXAMPLES/c/README.md
Information about building the examples using CMake
$HALCONEXAMPLES/c/source/
Directory containing the source files of the example programs
$HALCONEXAMPLES/images/
Images used by the example programs

Example programsđź”—

You can find several example programs in the HALCON/C++ distribution (%HALCONEXAMPLES%\cpp\source\console). To experiment with these examples, we recommend creating a private copy in your working directory.

error_handling.cpp
Demonstrates the C++ exception handling (see also About error handling)
ia_callback.cpp
Shows the usage of the HALCON image acquisition callback functionality
matching.cpp
Locates a chip on a board and measures the pins
serialized_item.cpp
Shows how to use the serialization of HALCON objects and tuples in the C++ interface

You can find additional examples in the subdirectories mfc and qt of %HALCONEXAMPLES%\cpp.

You can find several example programs in the following directories:

C#
%HALCONEXAMPLES%\c#
Visual Basic.NET
%HALCONEXAMPLES%\vb.net
(Managed) C++
%HALCONEXAMPLES%\cpp.net

To experiment with these examples, we recommend creating a private copy in your working directory.

You can find several example programs in the HALCON/Python distribution (%HALCONEXAMPLES%\python). To experiment with these examples, we recommend creating a private copy in your working directory.

The examples are written in Python 3.8. They work at least on the following platforms when using CPython as interpreter and runtime: x64-win64 and x64-linux.

Newer Python versions should work without problems. It is possible that other platforms and alternative Python implementations are functional, too. In this case, native HALCON binaries also need to be available on that platform.

You can find several example programs in the HALCON/C distribution (%HALCONEXAMPLES%\c\source). To experiment with these examples, we recommend creating a private copy in your working directory.

example1.c
Reads an image and demonstrates several graphics operators
example2.c
Introduces several image processing operators
example3c
Shows the usage of the tuple mode
example4.c
Shows more (basic) image processing operators like the sobel filter for edge detection, region growing, thresholding, histograms, the skeleton operator, and the usage of different color lookup tables
example5.c
Describes the HALCON messages and error handling
example6.c
Demonstrates the generic calling interface for the tuple mode (T_call_halcon_by_id)
example7.c
Demonstrates the creation of an image from user memory
example_extern7.c
Demonstrates the creation of an image from user memory. In contrast to example7.c, the memory is not copied but pointed to.
example_multithreaded1.c
This special case demonstrates the use of HALCON in a multithreaded application. It does not make sense to run the example on a single-processor or single-core computer.

Relevant environment variablesđź”—

Running HALCON programs requires the following environment variables to be set.

Note

Under Windows, all necessary variables are automatically set during the installation.

HALCONROOT
While a HALCON program is running, it accesses several files internally. To tell HALCON where to look for these files, the environment variable HALCONROOT has to be set. HALCONROOT points to the HALCON home directory.
HALCONARCH
Describes the platform on which HALCON is used. For more information, see also Supported platforms and minimum system requirements.
HALCONEXAMPLES
Indicates where the provided examples are installed
HALCONEXTENSIONS
If user-defined packages are used, this environment variable has to be set. HALCON will look for possible extensions and their corresponding help files in the directories given in HALCONEXTENSIONS.

Keep the following in mind when considering the example programs:

  • Default location for images
    The default directory for the HALCON operator read_image to look for images is %HALCONEXAMPLES%\images. If the images reside in different directories, the appropriate path must be set in read_image or the default image directory must be changed, using set_system('image_dir', '...').
    Alternatively, you can set the environment variable HALCONIMAGES before starting the program.
  • Output terminal under Linux
    In the example programs, no host name is passed to open_window. Therefore, the window is opened on the machine that is specified in the environment variable DISPLAY. If output on a different terminal is desired, this can be done either directly in OpenWindow(...,'hostname',...) or by specifying a host name in DISPLAY.