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 byHalconCpp.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 byHalconCpp.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.
| 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:
| 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.
- .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.configto inform the executable of the new HALCON/.NET DLL.
Do this by copying eitherbin\dotnet20\app.configorbin\dotnet35\app.configinto the directory containing the HALCON/.NET DLL, and rename the file to<application_name>.exe.config.
-
Visual Studio 2019 or later is required. ↩
-
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:
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.
| 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
HALCONROOThas to be set.HALCONROOTpoints 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 operatorread_imageto look for images is%HALCONEXAMPLES%\images. If the images reside in different directories, the appropriate path must be set inread_imageor the default image directory must be changed, usingset_system('image_dir', '...').
Alternatively, you can set the environment variableHALCONIMAGESbefore starting the program. - Output terminal under Linux
In the example programs, no host name is passed toopen_window. Therefore, the window is opened on the machine that is specified in the environment variableDISPLAY. If output on a different terminal is desired, this can be done either directly inOpenWindow(...,'hostname',...)or by specifying a host name inDISPLAY.