Installing and configuring HALCON๐
How to install HALCON๐
Download and install HALCON using the MVTec Software Manager (SOM).
aarch64-linux only
To use the deep learning functionality on GPUs on aarch64 systems, two third-party libraries need to be installed manually. For inference on CPUs, the third-party libraries are not required, but it can be necessary to link the correct OpenMP. For more information, see Using HALCON with OpenMP.
To complete the HALCON installation, add a license and, if applicable, configure your installation.
How to install a license๐
You can place the license file license.dat manually into the directory $HALCONROOT/license.
The correct notation for license files is license*.dat.
Alternatively, you can use SOM to install the license file.
Important
SOM overwrites licenses of the same file name. If you want to avoid this, rename the license file in advance.
To install the license file via SOM:
-
Open the page INSTALLED.
โคท All installed HALCON versions are listed.
-
Open the three-dots menu of the HALCON version to which you wish to add the license.
- Click Install license file.
- Click Choose a license to select the license file.
-
Click Upload.
โคท HALCON can now be started out of SOM.
How to install a dongle-bound license๐
If you are using a CodeMeter dongle and CodeMeter Runtime is running, CodeMeter Runtime needs to be at least version 6.00. Otherwise, the dongle is not recognized correctly, and HALCON throws an error regarding the license file.
Under Linux, you need to allow access to the hidraw device for CodeMeter dongles.
This can be done by copying the file $HALCONROOT/misc/linux/udev/rules.d/59-halcon-codemeter.rules to the /etc/udev/rules.d system directory.
More Info
For more information, see About HALCON licenses.
How to configure HALCON๐
Basic usage of HALCON only requires little configuration.
Setting environment variables๐
On Windows, the environment variables are set during the installation.
On Linux, the following environment variables must be set for HALCON to work independent from a SOM session.
HALCONROOT: directory you installed HALCON inHALCONEXAMPLES: directory the example programs are installed in ($HALCONROOT/examples)HALCONIMAGES: directory the example images are installed in ($HALCONEXAMPLES/images)HALCONARCH: value corresponding to the used platform (see system requirements)PATH: should include$HALCONROOT/bin/$HALCONARCHLD_LIBRARY_PATH: should include$HALCONROOT/lib/$HALCONARCH
It is recommended that you set the environment variables in a login script or a shell resource script, for example, .cshrc or .profile.
The installation script automatically creates an example shell script .profile_halcon in $HALCONROOT, which contains the necessary settings in sh syntax and which can be included in your login script.
See the code example for a shell script below:
HALCONROOT="/home/foo/MVTec/HALCON-26.11-progress-steady"; export HALCONROOT
HALCONARCH="x64-linux"; export HALCONARCH
PATH="$HALCONROOT/bin/$HALCONARCH:$PATH"; export PATH
LD_LIBRARY_PATH="$HALCONROOT/lib/$HALCONARCH:$LD_LIBRARY_PATH"; export LD_LIBRARY_PATH
Verify that LD_LIBRARY_PATH is set correctly after a reboot, for example, using
Some systems disallow setting LD_LIBRARY_PATH in .profile.
If the variable is not set after reboot, try to set LD_LIBRARY_PATH in other initialization files like .bashrc.
Optimizing parallelization๐
Optionally, you can optimize HALCONโs automatic operator parallelization for your computer as described in Automatic parallelization.
How to switch HALCON versions๐
If multiple versions of HALCON are installed on your system, the active version can be switched. Only one HALCON version can be active at any given time.
Note
You should only use HALCON XL when you need its features.
The active version can be switched using SOM. For more information, see the Software Manager documentation.
You can also switch the HALCON versions manually:
Adapt the environment variables set during the installation, that is, HALCONROOT, HALCONARCH, PATH, HALCONEXAMPLES, and HALCONIMAGES, and those you set yourself (for example, HALCONEXTENSIONS).
Set the environment variable HALCONROOT accordingly.
Important
In order for this method to work, paths based on HALCONROOT in other environment variables like PATH and LD_LIBRARY_PATH must use the variable and not its content.
For more information, see Setting environment variables.
How to update HALCON๐
With HALCON, the term โupdateโ means to install a newer maintenance release over a release based on the same HALCON version. As described in About releases and HALCON versions, you can update HALCON without needing a new license.
To check for available updates, open SOM and watch for the bell icon. This icon signifies available HALCON updates.
To update HALCON:
- Click on the bell icon or open the pop-up menu and select Update.
- Click APPLY.
For more information, see the SOM documentation.
Installing I/O device and image acquisition interfaces๐
With every HALCON installation, you obtain several already installed I/O device and image acquisition interfaces. You can get additional interfaces from mvtec.com/downloads.
Between HALCON releases, image acquisition interfaces may be updated by MVTec or the manufacturer of an image acquisition device. Such updates are available on MVTecโs webserver and in SOM. You can then download the interface together with its documentation and HDevelop example programs.
Uninstalling HALCON๐
The preferred method to uninstall HALCON is to use the automatic uninstallation program as described in the following. If you want to keep track of what is happening on your system, follow the instructions given in How to uninstall manually.
Multiple versions and HALCON Variable Inspect
If you have installed different HALCON versions simultaneously with a compatible HALCON Variable Inspect Extension for Visual Studio, uninstalling either of these versions will also uninstall the Variable Inspect extension. As a result, the Variable Inspect extension will be missing in the remaining HALCON version.
How to uninstall automatically๐
To uninstall HALCON:
- Start SOM.
- Open the three-dots menu of the HALCON version to be uninstalled and select Uninstall.
Alternatively, you can remove HALCON via the Control Panel of Windows.
Note
-
The uninstallation removes exactly those files that were installed. This has the following implications:
- If you added files after the installation manually, for example, new image acquisition interfaces, extension packages, images, or manuals, these files and the corresponding directories will โsurviveโ the uninstallation.
- If you only modified a file, for example, an example, without changing its name, the uninstallation will remove it. Therefore, copy files you want to keep to another folder before starting the uninstallation.
-
The uninstallation process does not remove any user-specific settings. This means that entries concerning, for example, the layout of HDevelop or its file history, will be left in the file
%APPDATA%\MVTec\HDevelop.ini. If you have run the utilityhcheck_parallel, AOP information has been stored in%ProgramData%\MVTec\HALCON 26.11\.aop_info. You can remove these files manually without risk. - The uninstaller does not remove the MVTec GigE Vision streaming filter driver if it is installed. This driver needs to be removed separately.
To uninstall HALCON:
- Start SOM.
- Open the three-dots menu of the HALCON version to be uninstalled and select Uninstall.
How to uninstall manually๐
You need administrator privileges to perform the uninstallation.
-
Open a Windows command prompt by pressing Win+R and entering
cmd. -
Delete the installation directory.
You can also use Windows Explorer to do this.Warning
The license file and any local additions to this directory will be lost. A backup of these files is highly recommended.
-
Delete all HALCON registry keys.
To remove the registry keys for a user installation of HALCON, replaceHKLMwithHKCU.reg delete "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\MVTec HALCON <version>" reg delete HKLM\SOFTWARE\Classes\.hdev reg delete HKLM\SOFTWARE\Classes\.dev reg delete HKLM\SOFTWARE\Classes\.hdpv reg delete HKLM\SOFTWARE\Classes\.dpv reg delete HKLM\SOFTWARE\Classes\.hdpl reg delete HKLM\SOFTWARE\Classes\.hobj reg delete HKLM\SOFTWARE\Classes\HDevelop.Source.File reg delete HKLM\SOFTWARE\Classes\HDevelop.External.Procedure reg delete HKLM\SOFTWARE\Classes\HDevelop.Procedure.Library reg delete HKLM\SOFTWARE\Classes\HALCON.ObjectReplace
<version>with the version you are uninstalling, for example,26.11-Progress-Steady.
You can also use the Windows registry editorregedit.exeto delete the keys. -
Delete all HALCON environment variables.
reg delete "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /V HALCONARCH reg delete "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /V HALCONEXAMPLES reg delete "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /V HALCONIMAGES reg delete "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /V HALCONROOTreg delete HKCU\Environment /V HALCONARCH reg delete HKCU\Environment /V HALCONEXAMPLES reg delete HKCU\Environment /V HALCONIMAGES reg delete HKCU\Environment /V HALCONROOTUse the Windows GUI to manually remove the HALCON binary directory from the environment variable
PATH.
Warning
The following procedure will delete your local additions to the HALCON base directory.
-
Remove the content of the HALCON base directory
$HALCONROOTand all its subdirectories, for example, by executing -
Remove the subdirectory
.hdevelopof the directory referenced by the environment variable$HOME. HDevelop creates this directory to save options, window positions, and the file history. -
Delete references to HALCON from the environment variables (see Setting environment variables).
How to remove HALCON Variable Inspect from Visual Studio๐
To remove HALCON Variable Inspect Extension for Visual Studio, do the following:
- Open Visual Studio.
- Select Extensions > Manage Extensions.
- Search for โHALCON 26.11 Variable Inspectโ in the list of installed extensions, and then select Uninstall.
Installing third-party components๐
You may have to install third-party components required to use a specific functionality of HALCON. Currently, this is limited to users of Deep Learning and deep-learning-based methods on NVIDIA GPUs.
Note
For Deep Learning, either of the Deep Learning modules Inference or Training must be licensed. This condition does not necessarily apply to deep-learning-based methods as, for example, Deep OCR.
The following third-party components are required for the training of a network or the inference on GPUs:
- NVIDIA GPU and up-to-date graphics driver (see System requirements > GPU applications)
- NVIDIA CUDA Basic Linear Algebra Subroutine library from the CUDA Toolkit (cuBLAS)
- NVIDIA CUDA Deep Neural Network library (cuDNN)
Installing third-party components for deep learning on Linux aarch64๐
In order to run Deep Learning, additional requirements apply.
To run Deep Learning on GPUs on Linux aarch64, install the following additional components:
- CUDA with the cuBLAS library
- cuDNN library
The required versions are listed in this table. A convenient way to install them is the NVIDIA โJetPackโ installer version 5.1.1, which you can download from the NVIDIA homepage. Make sure to select the CUDA Toolkit and cuDNN Package as to install on the target.
It can still be necessary to install CUDA.
In this case, libcuda.so is contained in an executable installer.
Run install.sh on /home/nvidia/NVIDIA_INSTALLER.
How to include the libraries๐
To enable HALCON to find the libraries, do the following:
-
Locate the shared objects.
-
cuBLAS libraries:
libcublas.solibcublasLt.so
They can be found where the CUDA Toolkit has been installed.
-
cuDNN libraries:
libcudnn.solibcudnn_adv_train.solibcudnn_ops_infer.solibcudnn_cnn_infer.solibcudnn_ops_train.solibcudnn_adv_infer.solibcudnn_cnn_train.so
They are generally contained in the
lib64subdirectory.
-
-
Make them detectable for HALCON. Of the following options, we recommend the first one:
-
Extend the environment variable
LD_LIBRARY_PATHto include the respective libraries. This can be done with the following commands, for example: -
Copy the required libraries
libcuda.soand the mentioned cuBLAS and cuDNN library to the third party directory:
$HALCONROOT/lib/$HALCONARCH/thirdparty/cuda11_4.
-
-
All libraries needed for CUDA 11 have to reside in the subdirectory
cuda11_4. If the subdirectorythirdparty/cuda11_4does not exist, create it first.\ -
Extend the environment variable
LD_LIBRARY_PATHto include the respective libraries. This can be done with a command like the following:
Additionally required settings๐
The HALCON process must be granted read-write access on /dev/nvhost-ctrl.
This can be achieved via membership in the โvideoโ group, for example.
How to use HALCON Variable Inspect with previous versions๐
You can use HALCON Variable Inspect Extension for Visual Studio 26.11 with previously installed versions of HALCON as well. To be able to use the new version with a previous version of HALCON Steady:
- Rename the license file of HALCON 26.11 to, for example,
license-26.11.dat - Copy the renamed file to the
%HALCONROOT%\licensedirectory of the older HALCON Steady installation.
See also the troubleshooting section.