23.11.0.0 MVTec Software

Product Information

Specifications

• Product Name: HALCON 23.11 Progress
• Version: 23.11.0.0
• Installation Type: Software
• Platform: Windows, Linux

About This Manual

The manual provides the necessary information to install HALCON
and setup the licensing mechanism successfully. It is divided into
the following chapters:

• Notation
• Symbols
• Introduction
• Installing HALCON

Product Usage Instructions

Chapter 1: Introduction

1.1 HALCON Editions

This section provides information about different editions of
HALCON.

1.2 HALCON Configurations

This section explains various configurations available for
HALCON.

1.3 Releases and HALCON Versions

This section provides information about different releases and
versions of HALCON.

1.4 Supported Platforms and Minimum System Requirements

This section provides information about the platforms supported
by HALCON and the minimum system requirements.

1.4.1 Platform-Specific HALCON Versions

This subsection provides information about HALCON versions
specific to different platforms.

1.4.2 Platform-Independent Applications

This subsection provides information about platform-independent
applications supported by HALCON.

1.4.3 HALCON Variable Inspect (Visual Studio Extension)

This subsection provides information about the requirements for
using HALCON Variable Inspect, a Visual Studio Extension.

1.4.4 Requirements for Deep Learning and Deep-Learning-Based

Methods

This subsection provides information about the requirements for
using deep learning and deep-learning-based methods in HALCON.

1.4.5 Requirements for Language Interface Examples

This subsection provides information about the requirements for
using language interface examples in HALCON.

1.5 Limitations

This section provides information about the limitations of
HALCON.

1.5.1 General Limitations

This subsection provides information about general limitations
of HALCON.

1.5.2 Limitations for Dongle-based Licenses

This subsection provides information about limitations specific
to dongle-based licenses of HALCON.

1.5.3 Limitations Related to Compute Devices

This subsection provides information about limitations related
to compute devices in HALCON.

1.5.4 Limitations Related to Image Acquisition

This subsection provides information about limitations related
to image acquisition in HALCON.

1.5.5 Limitations Related to OpenGL

This subsection provides information about limitations related
to OpenGL in HALCON.

1.5.6 Limitations Related to Extension Packages

This subsection provides information about limitations related
to extension packages in HALCON.

1.6 Licensing

This section provides information about licensing HALCON.

Chapter 2: Installing HALCON

2.1 Downloading HALCON

This section provides instructions on how to download
HALCON.

2.2 Starting the Installation

This section provides instructions on how to start the
installation of HALCON.

FAQ

Q: What are the different editions of HALCON?

A: The different editions of HALCON are…

Q: What are the minimum system requirements for HALCON?

A: The minimum system requirements for HALCON are…

Installation Guide
HALCON 23.11 Progress

All about installing and licensing HALCON, Version 23.11.0.0 All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission of the publisher.
Copyright © 2003-2023 by MVTec Software GmbH, Munich, Germany MVTec Software GmbH Protected by the following patents: US 7,239,929, US 7,751,625, US 7,953,290, US 7,953,291, US 8,260,059, US 8,379,014, US 8,830,229, US 11,328,478. Further patents pending. Microsoft, Windows, Windows 10 (x64 editions), 11, Windows Server 2016, 2019, 2022 Microsoft .NET, Visual C++ and Visual Basic are either trademarks or registered trademarks of Microsoft Corporation. AMD and AMD Athlon are either trademarks or registered trademarks of Advanced Micro Devices, Inc. Arm is a registered trademark of Arm Limited. CodeMeter is a trademark of WIBU SYSTEMS AG. Intel and Pentium are either trademarks or registered trademarks of Intel Corporation. Linux is a trademark of Linus Torvalds. OpenCL is a trademark of Apple Inc. NVIDIA, CUDA, cuBLAS, and cuDNN are either trademarks or registered trademarks of NVIDIA Corporation. OpenGL is a trademark of Silicon Graphics, Inc. SuSE is a trademark of Novell, Inc. All other nationally and internationally recognized trademarks and tradenames are hereby recognized. More information about HALCON can be found at: http://www.halcon.com

About This Manual
The manual provides the necessary information to install HALCON and setup the licensing mechanism successfully. It is divided into the following chapters:
· Introduction A short overview of the different HALCON versions, available licensing schemes, and the system requirements.
· Installing HALCON How to install HALCON, either for the first time or in form of an update.
· Uninstalling HALCON How to uninstall HALCON.
· Installing Third-Party Components How to install third-party libraries for deep learning on Linux aarch64.
· All About HALCON Licenses Detailed information about the different types of licenses and how to obtain and install them.
· Troubleshooting Possible problems and how to solve them.
· More on the Installation Details like the installed file structure and the relevant environment variables.
Notation
Except for Linux-specific sections, file paths and environment variables are printed in the Windows convention, e.g.,
%HALCONEXAMPLES%extension_packagehalconuser
to denote the subdirectory halconuser containing an example package within the HALCON examples directory referenced by the environment variable HALCONEXAMPLES (see section A.4 on page 43 for more information on environment variables). The same expression in Linux convention would look like
$HALCONEXAMPLES/extension_package/halconuser
Symbols
The following symbols are used within the manual:
This symbol indicates a tip.
! This symbol indicates an information you should pay attention to.

Contents

1 Introduction

7

1.1 HALCON Editions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.2 HALCON Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.3 Releases and HALCON Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.4 Supported Platforms and Minimum System Requirements . . . . . . . . . . . . . . . . . . . . . . 8

1.4.1 Platform-Specific HALCON Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.4.2 Platform-Independent Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.4.3 HALCON Variable Inspect (Visual Studio Extension) . . . . . . . . . . . . . . . . . . . . 9

1.4.4 Requirements for Deep Learning and Deep-Learning-Based Methods . . . . . . . . . . . 10

1.4.5 Requirements for Language Interface Examples . . . . . . . . . . . . . . . . . . . . . . . 12

1.5 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.5.1 General Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.5.2 Limitations for Dongle-based Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.5.3 Limitations Related to Compute Devices . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.5.4 Limitations Related to Image Acquisition . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.5.5 Limitations Related to OpenGL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.5.6 Limitations Related to Extension Packages . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.6 Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2 Installing HALCON

15

2.1 Downloading HALCON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.2 Starting the Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.2.1 Windows/Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.3 Switching HALCON Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2.4 Updating HALCON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2.5 Installing I/O Device and Image Acquisition Interfaces . . . . . . . . . . . . . . . . . . . . . . . 19

2.6 Installing Extension Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

2.6.1 Using an Extension Package Within HDevelop . . . . . . . . . . . . . . . . . . . . . . . 19

2.6.2 Using an Extension Package in a Stand-Alone Application . . . . . . . . . . . . . . . . . 19

3 Uninstalling HALCON

21

3.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.2 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4 Installing Third-Party Components

23

4.1 Third-Party Components for Deep Learning on Linux aarch64 . . . . . . . . . . . . . . . . . . . 23

4.1.1 Getting the Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

4.1.2 Including the Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

4.1.3 Additional Required General Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

5 All About HALCON Licenses

25

5.1 What is a License? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

5.2 Evaluation Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.3 Development Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

5.3.1 License Bound to a Network Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

5.3.2 License Bound to a Dongle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

5.3.3 License Bound to a Remote Dongle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

5.4 Runtime Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

5.4.1 Getting a Runtime License Restricted to Specific Modules . . . . . . . . . . . . . . . . . 28 5.4.2 Dynamic Modules for Deep-Learning-Based Applications . . . . . . . . . . . . . . . . . 29 5.5 How to Upgrade a License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 5.6 How to Check the Genuineness of HALCON (Windows) . . . . . . . . . . . . . . . . . . . . . . 30

6 HALCON in a Docker Container

31

6.1 Include a HALCON Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

6.1.1 Basic HALCON Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

6.1.2 Required System Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

6.1.3 HALCON Language Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6.2 Include External Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6.2.1 NVIDIA GPUs for Deep Learning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6.2.2 NVIDIA GPUs for OpenCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

6.3 Licensing HALCON within a Docker Container . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

6.3.1 Remote Dongle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

6.3.2 Forward USB License Dongle Into Container (Linux Only) . . . . . . . . . . . . . . . . . 34

7 Troubleshooting

35

7.1 Problems During Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

7.1.1 HALCON Variable Inspect (Visual Studio Extension) . . . . . . . . . . . . . . . . . . . . 35

7.2 Problems Concerning Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

7.2.1 Extracting Host IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

7.3 Troubleshooting in HDevelop or HALCON Applications . . . . . . . . . . . . . . . . . . . . . . 37

7.3.1 Startup Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

A More on the Installation

39

A.1 Software Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

A.2 The Installed File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

A.2.1 Main Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

A.2.2 Machine Configuration Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

A.2.3 User Configuration Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

A.3 HALCON tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

A.4 HALCON’s Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

A.4.1 Setting Environment Variables Under Windows . . . . . . . . . . . . . . . . . . . . . . . 43

A.4.2 Setting Environment Variables Under Linux . . . . . . . . . . . . . . . . . . . . . . . . . 43

A.4.3 HALCON-Specific Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . 43

A.4.4 General Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Index

45

Introduction

7

Introduction

Chapter 1
Introduction
To use HALCON on a computer, you must 1. install HALCON on this computer and 2. obtain a license.
Before looking into the details of these two steps in chapter 2 on page 15 and chapter 5 on page 25, this chapter gives an overview of the different HALCON versions and licensing methods. Finally, it describes the system requirements for running HALCON.
1.1 HALCON Editions
HALCON comes in two editions: · HALCON Progress Edition This edition is available by subscription with a six-month release cycle. · HALCON Steady Edition This edition is available as a regular purchase with a biennial release cycle. The development version is provided in two variants (see below).
1.2 HALCON Configurations
You can use HALCON in two configurations: 1. Development version The development version (sometimes also denoted as full version) includes the full spectrum of HALCON, i.e., language interfaces to C, C++, .NET, and Python, interfaces to image acquisition and I/O devices, the Extension Package Interface, which allows you to integrate your own HALCON operators, and, of course, the interactive development environment HDevelop. You need this version whenever you want to develop applications based on HALCON. The development version of HALCON Steady is available in two variants: HALCON Steady and HALCON Steady Deep Learning, which includes the deep learning functionality. 2. Runtime version If you have finished developing an application based on HALCON, you only need a runtime version of HALCON for each computer where the application is to be run. Since the runtime version is not determined for developing applications it does not include the interactive development environment HDevelop. Furthermore, you can obtain runtime version licenses that include only parts of the functionality (so-called modules). For more information, see section 5.4 on page 28 and contact your local distributor.

8

Introduction

1.3 Releases and HALCON Versions
The term version has a second meaning: It denotes the HALCON major releases, e.g., HALCON 23.11.0.0 (HALCON Progress), or HALCON 23.11.1.0 (HALCON Steady). For HALCON Steady there might also be so-called maintenance releases like HALCON 23.11.2.0 or higher. The main differences between these two types of releases are:
· Functionality A new HALCON version always represents a major step in the functionality. This means that it contains a significant number of new operators, but possibly also new functionality in HDevelop, e.g., new assistants. Furthermore, the functionality of individual operators may be extended or operators have been sped up. Of course, all currently known bugs in the preceding release will have been fixed.
In contrast, the main intention of a maintenance release is to fix all currently known bugs. Nevertheless, such a release typically also brings some speed-ups and minor functional extensions.
· Compatibility A new HALCON version is not downward compatible, with the following implications: First, you must upgrade your HALCON license (see section 5.5 on page 30). Second, if you want to run applications created with an older release under the new version, you must regenerate the applications, as the new HALCON library is not binary compatible to the old one. The term ‘applications’ includes also image acquisition interfaces and extension packages you created yourself based on an older release. Note that a new version may also be source-code incompatible in some parts, e.g., the signature of an operator or a class method may have been changed. These changes are indicated in the release notes of the HALCON version. In such a case, you must adapt the source code of your application before regenerating it.
In contrast, a maintenance release is in most cases fully downward compatible to its corresponding version. This compatibility includes the license. Please note, however, that some maintenance releases may not be fully binary or source-code compatible because of technical reasons. In such cases, the release notes will contain corresponding warnings and describe how to proceed.

1.4 Supported Platforms and Minimum System Requirements
HALCON runs on Windows and Linux. The minimum system requirements are listed in table 1.1; more details follow below.
1.4.1 Platform-Specific HALCON Versions
For the operating systems listed in table 1.1 on page 9, platform-specific versions of HALCON’s executables and libraries are provided. The name of the currently used version is stored in the environment variable HALCONARCH. On Windows and Linux, HALCON uses AVX2-optimized code for many operators, when run on a machine that supports AVX2. Note that HALCON should also run on newer versions of the operating systems than the ones listed; however, we cannot guarantee this. HALCONARCH appears in several directory paths: Executable HALCON programs like hdevelop, and DLLs like halcon.dll (Windows only), reside in %HALCONROOT%bin%HALCONARCH%. On Windows systems, this path is therefore automatically included in the environment variable PATH; on a Linux system, you must include it in your login script. The libraries that you need for linking programs, e.g., halcon.lib (Windows) or libhalcon.so (Linux) reside in the directory %HALCONROOT%lib%HALCONARCH%. Please note that when creating a 64-bit application, both the development computer and the computer on which the application will run must be 64-bit platforms. To create .NET applications under Linux, you need to install .NET Core or Mono.

1.4 Supported Platforms and Minimum System Requirements

9

Introduction

Architecture Processor
Disk Space Memory Display Resolution Supported OS Versions
Compiler HALCONARCH Specifics
Libraries
Application-Specific Requirements
Compute Device with OpenCL

Windows

Linux

x64

x64

aarch64

armv7a

64-bit

64-bit

64-bit

32-bit

Intel 64 or AMD 64 SSE2 (AVX2 dispatch)

Intel 64 or AMD 64 SSE2 (AVX2 dispatch)

Armv8-A with AArch64 support

Armv7-A with NEON support

4 GB / 1 GB (full installation / Runtime ­ without deep learning)

256 MB

1024 × 768

1024 × 768

­

­

Windows 10 (x64 editions), 11, Windows Server 2016, 2019, 2022

Linux x86_64

Linux aarch64

Linux armv7a

Visual Studio 2013

gcc 7.5

gcc 7.5

gcc 7.5

x64-win64

x64-linux

aarch64-linux

armv7a-linux

Kernel with hidraw support

Kernel with hidraw support, hard-float ABI

GLIBC_2.27, GLIBCXX_3.4.24

GLIBC_2.27, GLIBCXX_3.4.24

GLIBC_2.27, GLIBCXX_3.4.24

X11R7, freetype 2.4.11, fontconfig 2.10.95, OpenGL 2.0, OpenSSL 1.1.1, libdbus-1-3 (HDevelop)

X11R7, freetype 2.4.11, fontconfig 2.10.95, OpenGL 2.0, OpenSSL 1.1.1

X11R7, freetype 2.4.11, fontconfig 2.10.95, OpenGL 2.0, OpenSSL 1.1.1

OpenCL 1.1

OpenCL 1.1

OpenCL 1.1 [1]

OpenCL 1.1 [1]

Table 1.1: Minimum system requirements. Further requirements occur for the HALCON Variable Inspect and deep learning applications. Please see the corresponding sections below. [1]: The support of OpenCL depends highly on the platform and the OpenCL driver coming with it, use at your own risk.

1.4.2 Platform-Independent Applications
Even when using a platform-specific version of HALCON, you can still create platform-independent applications, in two ways:
· With HDevelop, HALCON’s integrated development environment (IDE). HDevelop programs are stored in a platform-independent format, thus, you can run them on any supported platform.
· With HALCON/.NET, HALCON’s interface to .NET programming languages. Applications written in .NET languages are stored in a platform-independent intermediate language, which is then converted by the so-called common language runtime into platform-specific code.
· With HALCON/Python, HALCON’s interface to Python script language. Python is an interpreted, highlevel and general-purpose programming language that runs your code platform independently on a language interpreter engine.
You can combine both methods by using HDevEngine/.NET to run HDevelop programs from a HALCON/.NET application.

1.4.3 HALCON Variable Inspect (Visual Studio Extension)
HALCON Variable Inspect is shipped in two packages. Which package to use depends on the version of Visual Studio to support. The respective package of HALCON Variable Inspect depends on the following components:
Variable Inspect Extension for Visual Studio 2019 and earlier · Visual Studio 2013 (Update 5 or higher) through Visual Studio 2019

10

Introduction

· .NET 4.6 Older installations of Visual Studio 2013 might be missing the .NET 4.6 framework. If the installation of HALCON Variable Inspect fails with an error, install the .NET 4.6 framework first.
Variable Inspect Extension for Visual Studio 2022 and later · Visual Studio 2022 and later · .NET 4.7.2

1.4.4 Requirements for Deep Learning and Deep-Learning-Based Methods

Disk space requirement for HALCON including deep learning:

Runtime:

3.4 GB (using CUDA 12.1.0).

Full installation:

20 GB.

Applications of deep learning as well as deep-learning-based methods, like Deep OCR, may have further requirements depending on the device (CPU or GPU) on which they are running. These requirements are given below in table 1.3 and table 1.4, respectively.
Whether an implementation is available for a specific device depends on the method and task. An overview for the different deep-learning-based methods is given in table 1.2.

Method (Model ‘type’)
3D Gripping Point Detection (‘3d_gripping_point_detection’)
Anomaly Detection (‘anomaly_detection’)
Classification (‘classification’)
Deep Counting
Component: Backbone (‘counting’)
Deep OCR
Component: Detection (‘ocr_detection’)
Component: Recognition (‘ocr_recognition’)
Global Context Anomaly Detection (‘gc_anomaly_detection’)
Multi-Label Classification (‘multi_label_classification’)
Object Detection and Instance Segmentation (‘detection’)
Semantic Segmentation and Edge Extraction (‘segmentation’)

Training

GPU

CPU [1] [1] [1] [1] [1,2] [1] [1] [1]

Inference

GPU

CPU

[1]

Table 1.2: Deep learning: Model dependencies. [1]: With exception of aarch64 and armv7a. [2]: Supported but not optimized and as a consequence time- intensive.

GPU Applications: When running deep learning as well as deep-learning-based applications on GPU, additional prerequisites apply. Table 1.3 lists additional prerequisites for which HALCON has been tested successfully. In case of multiple entries the ones corresponding have to be used.
HALCON checks which CUDA-version is installed and looks automatically for the corresponding subdirectories with its libraries. Under Windows or Linux x64, these libraries are provided in a separate package (see

Introduction

1.4 Supported Platforms and Minimum System Requirements

11

OS Versions GPU NVIDIA driver supporting Libraries

CUDA cuBLAS cuDNN

Windows

Linux

x64

x64

aarch64

Windows 10, 11

Linux x86_64

Linux aarch64

NVIDIA GPU with minimal compute capability 5.0

12.1.0

12.1.0

11.4 [1]

12.1.3.1

12.1.3.1

11.6.6.84

8.9.2

8.9.2

8.6.0

Table 1.3: Requirements for deep-learning-based applications on GPU. [1]: Install NVIDIA JetPack 5.1.1.

section A.1 on page 39.) Under Linux aarch64 these libraries have to be installed manually as described in chapter 4 on page 23.
CPU Applications: The following table 1.4 lists all platforms that support the execution of deep-learning-based applications.

Platform

Windows
x64 min. SSE4.1

x64 min. SSE4.1

Table 1.4: Requirements for Deep Learning applications on CPU. [1]: With exception of anomaly detection.

Linux aarch64 [1]

armv7a [1]

12

Introduction

1.4.5 Requirements for Language Interface Examples
For HALCON language interface examples additional requirements may apply.

Building HALCON examples with CMake

Minimum requirements depend on the language:

C and C++

Minimum supported CMake version: 3.7.1

.NET

Minimum supported CMake version: 3.8.2

Building Easy Extension Interface for .NET

CMake

Minimum supported CMake version: 3.7.1

C/C++-tooling

For example from Visual Studio

.NET Runtime

At least .NET runtime 6.0. Newer versions may be incompatible.

1.5 Limitations
1.5.1 General Limitations
Below, we list limitations that are relevant for typical application development with HALCON.
· String processing: ­ The HALCON library does not handle multibyte characters internally. File names containing multibyte characters are supported after calling set_system(‘filename_encoding’,’utf8′).
· Processing of NaNs: ­ Due to performance reasons, the HALCON library does not check for NaNs in input data. Using such input can lead to undefined behavior.
· Maximum image size: ­ HALCON: 32 768×32 768 ­ HALCON XL: 1 073 741 824×1 073 741 824 (230 × 230)
· Maximum number of channels per image: ­ The number of channels per image is limited to 65535.
Range for coordinates: ­ HALCON: from -32 767 to +32 767 ­ HALCON XL: from -1 073 741 823 to 1 073 741 823 (-230 to 230 – 1)
· Maximum number of windows: 600

1.5.2 Limitations for Dongle-based Licenses
After starting applications based on HALCON 20.05 (or later), the dongle must be removed and inserted again before starting applications based on HALCON 19.11 (or earlier). This problem can be avoided by installing the CodeMeter Runtime from WIBU SYSTEMS AG. The CodeMeter Runtime is not shipped with HALCON and must be downloaded from https://www.wibu.com in the download area.
On Arm platforms (aarch64 architecture) with GLIBC 2.21, it is no longer possible to run both 64-bit and 32-bit HALCON processes in parallel because they might block each other.

1.5 Limitations

13

Introduction

1.5.3 Limitations Related to Compute Devices
Operators that are based on texture are limited to the maximum size of the graphics card. Currently this limit is 8192×8192. This is relevant for the following operators:
· projective_trans_image and projective_trans_image_size, · affine_trans_image and affine_trans_image_size, · polar_trans_image, polar_trans_image_inv, and polar_trans_image_ext, · rotate_image, · mirror_image, · map_image, · image_to_world_plane, and · change_radial_distortion_image.
Further limitations are listed below.
· All other operators are restricted to the maximum allocated block size, e.g., 200 MB on the Tesla C2050. · edges_sub_pix and lines_gauss are not Open CL accelerated for HALCON XL. · edges_sub_pix and lines_gauss need a lot of memory on the compute device.

1.5.4 Limitations Related to Image Acquisition
· Maximum number of acquisition interfaces: 128 · Maximum number of open handles per acquisition interface: 256 · Maximum number of interface-specific parameters: 2048

1.5.5 Limitations Related to OpenGL
Operators using OpenGL for visualization (e.g., disp_object_model_3d) require OpenGL 2.1, GLSL 1.2, and the OpenGL extensions “GL_EXT_framebuffer_object” and “GL_EXT_framebuffer_blit”. Therefore, those operators cannot be used via Windows Remote Desktop or SSH forwarding. Other operators, like find_shape_model_3d), have an optimized implementation when OpenGL is available. Which operators benefit from OpenGL can be found in the reference documentation of the corresponding operators. To figure out which OpenGL features are available and offered by the driver, HALCON opens a hidden OpenGL window during initialization when the first HALCON operator is called. Thus, if the system has defective OpenGL drivers installed, HALCON may crash during initialization. To work around this issue, HALCON can be told to ignore OpenGL entirely by defining and setting the system environment variable “HALCON_NO_OPENGL” to 1.

1.5.6 Limitations Related to Extension Packages

Maximum number of parameters:

Iconic input parameters:

9

Iconic output parameters: 9

Control input parameters: 20

Control output parameters: 20

14

Introduction

1.6 Licensing
To run HALCON on a computer, you need a license. For HALCON Steady, licenses are always issued for a certain HALCON version (i.e., major release, see section 1.3 on page 8). However, a license is not exclusively bound to this version: It is upward compatible within the version number, i.e., licenses for major releases are also valid for follow-up maintenance releases. For HALCON Progress, licenses are issued for the subscription period.
The license file is typically called “license.dat”. Between “license” and “.dat”, arbitrary information can be included. Thus, different licenses for different versions (e.g., license-23.11.dat for version 23.11) can be stored in the same directory.
The three possible licensing types mainly correspond to the different HALCON versions described in section 1.2 on page 7. Detailed information about HALCON licenses can be found in chapter 5 on page 25.
· Evaluation license To evaluate the full power of HALCON, you can obtain an evaluation license from your local distributor free of charge. This type of license is not bound to any computer hardware, i.e., you can use HALCON on any computer you installed it on; however, it is only valid for a limited time, typically for a month. Note that you may not use this license to develop commercial applications.
· Development license To develop HALCON applications, whether in HDevelop or via a programming language, you need a development license. In contrast to the evaluation license, this license is permanent. Furthermore, this license is bound to a certain hardware component (network card or dongle, see section 5.1 on page 25). If you want to use HALCON on multiple computers simultaneously, you need a license for each of them.
· Runtime license If you finished developing your application based on HALCON and now want to install and run it on a customer’s computer, you only need a runtime license. Like development licenses, runtime licenses are permanent and bound to a certain hardware component (network card or dongle). As already noted, you can obtain runtime licenses that cover only parts of the functionality (so-called modules). Please contact your local distributor for more information.

Installing HALCON

15

Installation

Chapter 2
Installing HALCON
2.1 Downloading HALCON
Note that you first need to register before downloading software. 1. Log in to MVTec’s Download Area at http://www.mvtec.com/downloads. 2. Click HALCON DOWNLOADS. 3. Choose PRODUCT VERSION, OPERATING SYSTEM, and, if applicable, the ARCHITECTURE. 4. Download one of the following: · “MVTec Software Manager” (SOM) A lightweight package manager that downloads only the necessary packages during installation. · “Full Version” The download for Windows and Linux includes SOM and all packages required for the full HALCON installation. · “Runtime Version” This download includes SOM and all packages required for the HALCON runtime installation.
2.2 Starting the Installation
2.2.1 Installing HALCON Under Windows/Linux
There are two installation options: · GUI-based installation, i.e., controlling SOM via your web browser (section 2.2.1.1 on page 16). · Command line installation, with the possibility for a silent installation (section 2.2.1.2 on page 16).
In both cases, you can run SOM with user permissions (“user mode”) or with administrator permissions (“system mode”). Software packages can be installed only for yourself or for all users of the system. In the latter case, SOM will request the credentials for system-wide installation when the corresponding option has been selected. For more information, see the section “Running SOM” in SOM’s internal documentation. Both installation methods require a valid login to the download area. You can only log in from the GUI (start
SOM, and click the LOGIN button). The login is remembered across SOM sessions and will be used by the !
command line installation. For aarch64-linux only: To use the deep learning functionality on GPUs, two third-party libraries need to be
installed manually (see chapter 4 on page 23). For inference on CPUs, the third-party libraries are not required, !
but it may be necessary to link the correct OpenMP. For more information, see Programmer’s Guide, section 2.4 on page 19.

16

Installing HALCON

2.2.1.1 GUI-based Installation
To install HALCON using the SOM GUI in the browser, do the following:
1. If you downloaded the “Full Version” or the “Runtime Version”, unzip the downloaded archive. 2. Execute som. If som is not executable under Linux, adapt its file permissions.
SOM opens a page in your default web browser. If SOM is not yet installed or up-to-date, a welcome dialog offers to install SOM or to update your current installation of SOM. You can skip or postpone this step by closing the dialog. To install HALCON, an installation of SOM is not required. Nonetheless, installing SOM is recommended, because it can manage and update your installation(s) and provides easy access to HDevelop and the documentation. 3. Open the page AVAILABLE. All available HALCON versions are listed. 4. To start the default installation, click the INSTALL button of the HALCON version you wish to install. The “Packages” dialog opens, with all necessary packages already pre-selected. Alternatively, click SELECT PACKAGES to set up the installation without pre-selections. See section A.1 on page 39 for information about the packages. You can install additional packages at a later time by starting SOM again and selecting the packages you need. 5. Click APPLY. The installation starts. The installed HALCON version appears under INSTALLED.
To complete the HALCON installation, add a license (section 2.2.1.3 on page 17) and, if applicable, configure your installation (section 2.2.1.4 on page 17).
2.2.1.2 Command Line Installation
SOM can also be operated from the command line. This enables script-driven installation and removal of software packages. For more information, see the chapter “Command line usage” of SOM’s internal documentation. If you want to install HALCON remotely, see also the chapter “Headless operation” .
1. If you downloaded the “Full Version” or the “Runtime Version”, unzip the downloaded archive. 2. Run “MVTec Software Manager CLI” if you have installed SOM. Otherwise, open a command prompt,
and change to the directory where you saved the som executable. 3. List the catalog and available feed URLs:
som cat
4. To install, for example the runtime version of HALCON, type:
som -f FEED install rt
where FEED has to be replaced with the actual feed URL or a unique substring of the feed URL, e.g., halcon-23.11-progress. The EULA is shown, followed by a line repeating your last command line with an additional parameter –accept HASH. 5. To open the help, enter
som help
6. Copy and paste the line to start the installation, for example:
som –accept HASH -f FEED install rt

2.2 Starting the Installation

17

To complete the HALCON installation, add a license (section 2.2.1.3 on page 17) and, if applicable, configure your installation (section 2.2.1.4 on page 17).
Silent Installation You can also use the last command for non-interactive (i.e., silent) installations. To install silently, suppress the command output as usual, i.e., under Windows with > nul, and under Linux with > /dev/null. For example:
som –accept HASH -f halcon-23.11-progress install rt > nul

Installation

2.2.1.3 License Installation
Installing a License File
You can either place the license file license.dat manually into the directory $HALCONROOT/license. Alternatively, you can use SOM to install the license file. Note that SOM overwrites licenses of the same file name.
If you want to avoid this, you have to rename the license file in advance. The correct notation for license files is !
license*.dat. To install the license file via SOM:
1. Open the page INSTALLED. All installed HALCON versions are listed.
2. Open the three-dots pop-up menu of the HALCON version you wish to add the license to. 3. Select Manage packages. 4. Click Browse… to select the license file. 5. Click install license file.
HALCON can now be started out of SOM.
Installing 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 (see also section 7.2.1 on page 36).
2.2.1.4 Configuration
Setting Environment Variables
On Windows, the environment variables are set during the installation. On Linux, the following environment variables must be set in order for HALCON to work independent from a SOM session (see section A.4 on page 43 for more information about these and other environment variables):
· 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: select value corresponding to the used platform (see table 1.1 on page 9). · PATH: this system variable should include $HALCONROOT/bin/$HALCONARCH. · LD_LIBRARY_PATH: this system variable should include $HALCONROOT/lib/$HALCONARCH.

18

Installing HALCON

HALCONROOT=”/home/foo/MVTec/HALCON-23.11-progress”; 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
Figure 2.1: Example for a shell script with environment variables in sh syntax, generated when installing HALCON into the directory /home/foo/MVTec/HALCON-23.11-progress on a Linux system.
It is recommended that you set the environment variables in a login script or a shell resource script, e.g., .cshrc or .profile. The installation script automatically creates an example shell script .profile_halcon in $HALCONROOT which contains the necessary settings in sh syntax, see figure 2.1 on page 18. The shell script can be included in your login script. Make sure LD_LIBRARY_PATH is set correctly after a reboot, e.g., with:
echo $LD_LIBRARY_PATH
Some systems disallow setting LD_LIBRARY_PATH in .profile. If the variable is not set after reboot, you should 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 the Programmer’s Guide, section 2.1.1 on page 15.

2.3 Switching HALCON Versions

If multiple versions of HALCON are installed on your system, the active version may be switched using SOM on Windows. To switch the HALCON version:

1. Open SOM. Note the different HALCON versions under INSTALLED.

2. Click the radio button in front of HDevelop or HDevelop XL to register the corresponding HALCON

version.

!

Please note that you should use HALCON XL only when you need its features.

Only one HALCON version can be active at any given time. See also “Handling of HALCON versions” in SOM’s internal documentation.
You can also switch the HALCON versions manually:

· On Linux systems, by setting the environment variable HALCONROOT accordingly. Note that 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. See figure 2.1 on page 18 for an example.

· Under Windows, you must adapt those environment variables that are set during the installation, i.e., HALCONROOT, HALCONARCH, PATH, HALCONEXAMPLES, and HALCONIMAGES, and those you set yourself (e.g., HALCONEXTENSIONS). Please refer to section A.4 on page 43 for more information about setting environment variables.

2.4 Updating 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 section 1.3 on page 8, 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:

2.5 Installing I/O Device and Image Acquisition Interfaces

19

1. Click on the bell icon or open the pop-up menu and select Update. 2. Click APPLY.

Installation

2.5 Installing I/O Device and Image Acquisition Interfaces
With every HALCON installation, you obtain several already installed I/O device and image acquisition interfaces (see also section A.2 on page 40). Additional interfaces are obtainable from the MVTec/HALCON Download area.
In between HALCON releases, image acquisition interfaces might be updated by MVTec or the manufacturer of an image acquisition device. Such updates are indicated on MVTec’s WWW server, to which you can connect by selecting HDevelop’s menu entry Help HALCON News (WWW) or in the Start Dialog which appears when starting HDevelop. You can then download the interface together with its documentation and HDevelop example programs.

2.6 Installing Extension Packages
The HALCON Extension Package Interface enables you to integrate newly developed image processing algorithms into HALCON in the form of so-called extension packages. The same mechanism is used by MVTec to extend the current HALCON release with additional functionality. Which extension packages are currently available can be checked by selecting HDevelop’s menu entry Help HALCON News (WWW). This section describes how to integrate a (downloaded) package named newextpkg in order to use it within your HALCON system.
1. Extract the package to a directory of your choice, e.g., %HALCONROOT%.
2. Add the complete path of the package, e.g., %HALCONROOT%packagesnewextpkg to the environment variable HALCONEXTENSIONS. Note, that the delimiter between paths in an environment variable is a semicolon on Windows systems and a colon on Linux systems.
Never change the name of an extension package or the corresponding names of the libraries or DLLs con-
tained in it. These names are encoded within the libraries/DLLs. If you change the names this information will no !
longer match. Thus, the loader of the operating system will fail to open the dynamic libraries. If the package contains images used, e.g., within example programs we recommend including the complete path to the corresponding directory images within the package in the environment variable HALCONIMAGES (see section A.4 on page 43) to access those images without specifying a complete path.
2.6.1 Using an Extension Package Within HDevelop
To use a new package within HDevelop under Windows, you just need to restart the program. HDevelop automatically integrates all extension packages specified in HALCONEXTENSIONS, i.e., the operators contained in a package can be accessed and used like any other HALCON operator. Under Linux, you must include the package library subdirectory (i.e., lib/$HALCONARCH) in the environment variable LD_LIBRARY_PATH before starting HDevelop the first time (see table 1.1 on page 9 for the possible values of HALCONARCH).
2.6.2 Using an Extension Package in a Stand-Alone Application
If you want to generate a stand-alone application that uses an extension package, you have to link the package libraries (DLLs under Windows, shared libraries under Linux) to the application code, in addition to the HALCON library.

20

Installing HALCON

2.6.2.1 Using an Extension Package Under Windows
In order to create new application programs you have to link the corresponding language interface library, e.g., packagecpp.lib for a C++ application, to your objects. Furthermore, you will need the HALCON interface library, in the example of a C++ application halconcpp.lib, as for any HALCON application. To be able to link the package DLL to your application program, the complete DLL file path of the new package, e.g.,
%HALCONROOT%packagesnewextpkgbin%HALCONARCH% must be added to the environment variable PATH (see table 1.1 on page 9 for the possible values of HALCONARCH).
! Do not copy a package DLL into the Windows system directories, as it would be loaded twice in this case.
2.6.2.2 Using an Extension Package Under Linux
In order to create new application programs, you must link libnewextpkg.so and the corresponding language interface library, e.g., libnewextpkgcpp.so for a C++ application, to your objects (besides libhalcon.so and the HALCON interface library, in the example of a C++ application libhalconcpp.so, as for any HALCON application). Furthermore, you have to add the path to the package library subdirectory lib/$HALCONARCH to the environment variable LD_LIBRARY_PATH, otherwise the loader will fail to access the libraries.

Uninstalling HALCON

21

Installation

Chapter 3
Uninstalling HALCON

3.1 Uninstalling HALCON Under Windows

The preferred method to uninstall HALCON is to use the automatic uninstallation program as described in the following section. If you want to keep track of what is happening to your system, you can follow the instructions given in section 3.1 on page 21.
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.

Uninstalling Automatically
To uninstall HALCON:
1. Open SOM.
2. Open the pop-up menu of the HALCON version to be uninstalled and select Uninstall.
Alternatively, you can remove HALCON via the Control Panel of Windows.
Note that the uninstallation removes exactly those files that were installed. This has two implications: If you
added files after the installation manually, e.g., new image acquisition interfaces, extension packages, images, or !
manuals, these files and the corresponding directories will “survive” the uninstallation. On the other hand, if you only modified a file, e.g., an example, without changing its name, the uninstallation will remove it nevertheless. Therefore, you might want to copy such files to another directory before starting the uninstallation.
The uninstallation process will not remove any user-specific settings. This means that entries concerning, e.g., the layout of HDevelop or its file history, will be left in the file %APPDATA%MVTecHDevelop.ini. If you have run the utility hcheck_parallel, AOP information has been stored in %ProgramData%MVTecHALCON 23.11 .aop_info. You can remove these files manually without risk. Moreover, the uninstaller does not remove the MVTec GigE Vision streaming filter driver if it is installed. This driver needs to be removed separately.

Uninstalling Manually

The commands given in the following description should be entered in a Windows command prompt, which can be obtained by entering cmd.exe in the dialog Start Run. You need administrator privileges to perform the uninstallation.

1. Delete the installation directory.

You can also use Windows Explorer to do this. Note that the license file and any local additions to this

directory will be lost. A backup of these files is highly recommended.

!

rmdir /S “%HALCONROOT%”

22

Uninstalling HALCON

2. Delete all HALCON registry keys. You can also use the Windows registry editor regedit.exe to delete the keys. To remove the registry keys for a user installation of HALCON, replace HKLM with HKCU.
reg delete “HKLMSOFTWAREMicrosoftWindowsCurrentVersionUninstallMVTec HALCON version” reg delete HKLMSOFTWAREClasses.hdev reg delete HKLMSOFTWAREClasses.dev reg delete HKLMSOFTWAREClasses.hdpv reg delete HKLMSOFTWAREClasses.dpv reg delete HKLMSOFTWAREClasses.hdpl reg delete HKLMSOFTWAREClasses.hobj reg delete HKLMSOFTWAREClassesHDevelop.Source.File reg delete HKLMSOFTWAREClassesHDevelop.External.Procedure reg delete HKLMSOFTWAREClassesHDevelop.Procedure.Library reg delete HKLMSOFTWAREClassesHALCON.Object
Replace version with the version you are uninstalling, e.g., 23.11-Progress.
3. Delete all environment variables.
reg delete “HKLMSYSTEMCurrentControlSetControlSession ManagerEnvironment” /V HALCONARCH reg delete “HKLMSYSTEMCurrentControlSetControlSession ManagerEnvironment” /V HALCONEXAMPLES reg delete “HKLMSYSTEMCurrentControlSetControlSession ManagerEnvironment” /V HALCONIMAGES reg delete “HKLMSYSTEMCurrentControlSetControlSession ManagerEnvironment” /V HALCONROOT
reg delete HKCUEnvironment /V HALCONARCH reg delete HKCUEnvironment /V HALCONEXAMPLES reg delete HKCUEnvironment /V HALCONIMAGES reg delete HKCUEnvironment /V HALCONROOT
Please also use the GUI to manually remove the HALCON binary directory from the environment variable PATH. See section A.4 on page 43 on how to edit environment variables using the Windows GUI.

3.2 Uninstalling HALCON Under Linux
Uninstalling Automatically To uninstall HALCON:
1. Open SOM. 2. Open the pop-up menu of the HALCON version to be uninstalled and select Uninstall.
Unistalling Manually
! Please note: The following procedure will delete your local additions to the HALCON base directory.
The actual uninstallation consists of simply removing the content of the HALCON base directory $HALCONROOT and all its subdirectories, e.g., by executing
rm -rf $HALCONROOT
Furthermore, remove the subdirectory .hdevelop of the directory referenced by the environment variable HOME (see section A.4 on page 43); HDevelop creates this directory to save options, window positions, and the file history. Finally, delete references to HALCON from the environment variables (see section 2.2.1.4 on page 17).

Installing Third-Party Components

23

Third-Party

Chapter 4
Installing Third-Party Components
This chapter describes how to install third-party components that might be required in order to use a specific functionality of HALCON. Currently, this is limited to users of Deep Learning and deep-learning-based methods on NVIDIA GPUs. Please note that 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 e.g., Deep OCR. In addition to a valid license, 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 section 1.4 on page 8 for the system requirements), · the NVIDIA CUDA Basic Linear Algebra Subroutine library from the CUDA Toolkit (cuBLAS), · the NVIDIA CUDA Deep Neural Network library (cuDNN). Under Windows or Linux x64, these libraries are provided in a separate package via SOM. Therefore, the follow-
ing sections do not apply for these systems. Under Linux aarch64 the libraries have to be installed separately, see !
the section section 4.1 on page 23.
4.1 Third-Party Components for Deep Learning on Linux aarch64
4.1.1 Getting the Components
In order to run Deep Learning, additional requirements apply. Please see section 1.4.4 on page 10. Running Deep Learning on GPUs on Linux aarch64, the following components must be installed additionally:
· CUDA with the cuBLAS library · the cuDNN library The required versions are listed in table 1.2 on page 10. A convenient way to install them is the NVIDIA “JetPack” installer version 5.1.1, which you can download from https://developer.nvidia.com/embedded/jetpack. Make sure to select the CUDA Toolkit and cuDNN Package as to install on the target. It might 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.
4.1.2 Including the Libraries
HALCON needs to find the libraries. For this, firstly you need to locate the shared objects. · The cuBLAS libraries:

24

Installing Third-Party Components

· libcublas.so
· libcublasLt.so They can be found where the CUDA Toolkit has been installed. · The 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.
Secondly, you need to make them findable for HALCON. To do so, you have the following options, whereof we recommend the first one:
a Extend the environment variable LD_LIBRARY_PATH to include the respective libraries. This may be done e.g., with the following commands:
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/aarch64-linux-gnu LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/cuda/targets/aarch64-linux/lib
b Copy the required libraries libcuda.so and 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 be in the subdirectory cuda11_4. If the subdirectory thirdparty/cuda11_4 does not exist, create it first. Additionally extend the environment variable LD_LIBRARY_PATH to include the respective libraries. This may be done e.g., with a command like the following:
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HALCONROOT/lib/$HALCONARCH/thirdparty/cuda11_4

4.1.3 Additional Required General Settings
The HALCON process must be granted read-write access on: /dev/nvhost-ctrl This can be achieved e.g., via membership in the “video” group.

All About HALCON Licenses

25

Licensing

Chapter 5
All About HALCON Licenses

Section 1.6 on page 14 already contained an overview of the possible licensing schemes. In this chapter, you will find detailed information about how to obtain and install
· evaluation licenses (section 5.2 on page 26), · development licenses (section 5.3 on page 27), and · runtime licenses (section 5.4 on page 28),
Finally, section 5.5 on page 30 shows how to upgrade a license.

5.1 What is a License?

HALCON licenses are stored in so-called license files. The content of these files specifies

· what is licensed (e.g., development version, runtime version, etc.)

· which modules are licensed (e.g., Calibration, Matching, etc.)

· whether the license is temporary (e.g., evaluation license) or permanent

· the hardware to which the license is bound (see below)

License files are named license.dat (or license-23.11.dat or similar, see section 1.6 on page 14) and reside

in the subdirectory license of the directory where you installed HALCON. Note that HALCON will not run if

you modify the license keys within the license file manually!

!

A single license allows you to run a specific version of HALCON by one user on one system.

The system is identified by a unique host ID. Depending on the type of host ID, you may install HALCON on any number of computers, but in any case you must use it only on the one computer to which the host ID is attached. Further information about licenses can be found in the EULA.

The license is not bound to a specific user. Consequently, different users may use the licensed HALCON version, but not simultaneously. To have multiple users run HALCON at the same time, the corresponding number of licenses are needed. Note that each system service or daemon which executes HALCON is also counted as user. Thus, if only one license is available and a system service executes HALCON, the regular user is not able to run another instance of HALCON in parallel.

Network Card Versus Dongle Binding
As noted in section 1.6 on page 14, development and runtime licenses are bound to a certain hardware component. This is either the network card (see section 5.3.1 on page 27) or a dongle (see section 5.3.2 on page 27).
Dongle-bound licenses allow using HALCON on different computers by moving the dongle. Of course, network cards can also be switched between computers, but in practice they can be regarded as fixed. Thus, if you want to develop applications with HALCON on more than one stand-alone computer at different times, the easiest solution is to obtain a dongle-bound license.

26

All About HALCON Licenses

Identifying the Hardware
The license manager software identifies a network card or a HALCON dongle by a so-called host ID. A valid host ID is the unique, immutable, machine-readable identification of an actual piece of hardware as devised by the hardware vendor.
HALCON includes a tool to query the host IDs from the command line. Open a Command Prompt window or a Linux shell, and then enter the following command:
hhostid

This command produces a list of host IDs, which are available for licensing. For example: 0d00cafebabe 3-3123456

Use hhostid -i to get additional information, such as the type of a certain host ID:
hhostid -i #0: 0d00cafebabe [MAC] #1: 3-3123456 [CM]