Skip to content

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:

  1. Open the page INSTALLED.

    โคท All installed HALCON versions are listed.

  2. Open the three-dots menu of the HALCON version to which you wish to add the license.

  3. Click Install license file.
  4. Click Choose a license to select the license file.
  5. 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 in
  • HALCONEXAMPLES: 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/$HALCONARCH
  • LD_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

echo $LD_LIBRARY_PATH

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:

  1. Click on the bell icon or open the pop-up menu and select Update.
  2. 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:

  1. Start SOM.
  2. 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 utility hcheck_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:

  1. Start SOM.
  2. 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.

  1. Open a Windows command prompt by pressing Win+R and entering cmd.

  2. Delete the installation directory.

    Warning

    The license file and any local additions to this directory will be lost. A backup of these files is highly recommended.

    rmdir /S "%HALCONROOT%"
    
    You can also use Windows Explorer to do this.
  3. Delete all HALCON registry keys.
    To remove the registry keys for a user installation of HALCON, replace HKLM with HKCU.

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

    Replace <version> with the version you are uninstalling, for example, 26.11-Progress-Steady.
    You can also use the Windows registry editor regedit.exe to delete the keys.

  4. 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 HALCONROOT
    
    reg delete HKCU\Environment /V HALCONARCH
    reg delete HKCU\Environment /V HALCONEXAMPLES
    reg delete HKCU\Environment /V HALCONIMAGES
    reg delete HKCU\Environment /V HALCONROOT
    

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

  1. Remove the content of the HALCON base directory $HALCONROOT and all its subdirectories, for example, by executing

    rm -rf $HALCONROOT
    
  2. Remove the subdirectory .hdevelop of the directory referenced by the environment variable $HOME. HDevelop creates this directory to save options, window positions, and the file history.

  3. 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:

  1. Open Visual Studio.
  2. Select Extensions > Manage Extensions.
  3. 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:

  1. Locate the shared objects.

    • cuBLAS libraries:

      • libcublas.so
      • libcublasLt.so

      They can be found where the CUDA Toolkit has been installed.

    • cuDNN libraries:

      • libcudnn.so
      • libcudnn_adv_train.so
      • libcudnn_ops_infer.so
      • libcudnn_cnn_infer.so
      • libcudnn_ops_train.so
      • libcudnn_adv_infer.so
      • libcudnn_cnn_train.so

      They are generally contained in the lib64 subdirectory.

  2. Make them detectable for HALCON. Of the following options, we recommend the first one:

    • Extend the environment variable LD_LIBRARY_PATH to include the respective libraries. This can be done with the following commands, for example:

      LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/aarch64-linux-gnu
      LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/cuda/targets/aarch64-linux/lib
      
    • Copy the required libraries libcuda.so and the mentioned cuBLAS and cuDNN library to the third party directory:
      $HALCONROOT/lib/$HALCONARCH/thirdparty/cuda11_4.

  3. All libraries needed for CUDA 11 have to reside in the subdirectory cuda11_4. If the subdirectory thirdparty/cuda11_4 does not exist, create it first.\

  4. Extend the environment variable LD_LIBRARY_PATH to include the respective libraries. This can be done with a command like the following:

    LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HALCONROOT/lib/$HALCONARCH/thirdparty/cuda11_4
    

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:

  1. Rename the license file of HALCON 26.11 to, for example, license-26.11.dat
  2. Copy the renamed file to the %HALCONROOT%\license directory of the older HALCON Steady installation.

See also the troubleshooting section.