Quick Guide to HALCON - MVTec

1 A product of MVTecQuick GuideHALCON Quick access to the functionality of HALCON , Version 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 2003-2021by MVTec Software GmbH, M nchen, GermanyMVTec Software GmbHProtected 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. Further patents , Windows, Windows Server 2008/2012/2012 R2/2016, Windows 7/8 , Microsoft .NET, Visual C++, and VisualBasic are either trademarks or registered trademarks of Microsoft is a trademark of Linus and OpenCL are trademarks of Apple , CUDA, cuBLAS, and cuDNN are either trademarks or registered trademarks of NVIDIA is a trademark of Silicon Graphics, other nationally and internationally recognized trademarks and tradenames are hereby information about HALCON can be found at: This ManualThis manual introduces you to HALCON .

2 It is intended for beginners without prior knowledge of manual can also be used as a reference Guide to several other HALCON manuals, as it interconnects themalong the following topics:1. Installing HALCON (page 7)This chapter introduces the MVTec Software Manager (SOM).2. HALCON Architecture (page 9)Some theoretical background, needed to understand what HALCON is and how it How to Develop Applications (page 15)This chapter explains three basic approaches for developing with HALCON and guides you through a firstprogramming How to Continue (page 19)This chapter refers to additional sources of Installing HALCON72 HALCON .. and Data Structures .. Packages .. Interfaces .. ++ .. Acquisition Interfaces .. Interfaces ..133 How to Develop.

3 Program .. Prototype in HDevelop .. Visual Studio Project .. Library Project .. Library Project into Visual Studio ..184 How to Continue19 Installing HALCON7 Chapter 1 Installing HALCONFor Linux und Windows users, we recommend downloading and installing HALCON via the MVTec SoftwareManager (SOM). SOM is an installation manager for software packages. It provides access to a remote cata-log of products, and supports, among other features, downloading and installation of packages. A step by stepintroduction on how to install HALCON via SOM can be found in the Installation HALCONHALCON Architecture9 Chapter 2 HALCON ArchitectureHALCON s basic architecture is depicted in figure The main part is the image processing library, whichconsists of more than 2000 operators.

4 You can also develop your own operators in the form of so-called ex-tension packages (page 11). You use the operators in your application via language interfaces (page 11) likeHALCON/C++ or HALCON /Python. These are libraries which allow a direct use of the operators in the typicalprogramming style of the different programming Image Processing LibraryHALCON/PythonHALCON/CHALCON/C++HA LCON/.NETHD evelopPythonCC++C# ApplicationsGigE Vision2 USB3 VisionGenICamTLMany Devices3D Cameras, Boards, CamerasExtension PackagesImage Acquisition InterfacesI/O InterfacesFigure : Basic architecture of the access of image acquisition devices, HALCON provides image acquisition interfaces (page 13) whichallow you to use quite different acquisition devices in a common way.

5 The libraries containing the device-specificimplementations are loaded dynamically when needed. In the same fashion, I/O devices are accessed throughdevice-specific I/O interfaces (page 13).Architecture10 HALCON OperatorsWhenever any kind of functionality is used from the HALCON library, it is done via anoperator. Most of themcomprise multiple methods, which are selected via parameters. A full list of all operators can be found in theHALCON Operator Reference available in HDevelop, .NET, Python, C++, and C syntax. Important features ofoperators are: There is no hierarchy among operators. From the software architecture point of view, all operators are on thesame level. Of course, there are logical groups of operators. For example, this can be seen by the classes offered forC++ and.

6 NET, where operators processing the same data type are member functions of the correspondingclasses. The design of the operators follows the rules of the open architecture. Therefore, you can create your own op-erators and thus extend HALCON (see section ). The Extension Package Programmer s Manual containsdetailed information about extending the operator library. Many operators can make transparent use of automatic parallelization, which allows an easy way of speedingup the program when using large images on a multi-processor or multi-core computer. Detailed informationon parallel programming can be found in the technical note Parallel programming , as well as in the Program-mer s Guide . Operators have standardized rules for ordering input and output parameters:input iconic, output iconic, inputcontrol, and output control(see section ).

7 Not all of the groups might be needed for a given operator. Ingeneral, input parameters of operators are not modified, which results in a clear and simple semantics. Thereare only a few exceptions to this design, ,set_grayval,overpaint_gray, Parameters and Data StructuresHALCON has two basic types of parameters:iconic dataandcontrol data. Images, regions, and XLDs (eXtentedLine Description) belong to the iconic mainly of channels, , matrices containing pixel values. All channels of an image have the samesize. For detailed information about pixels and channels, please read the chapter Image of the HALCONO perator each image, the so-calledregion of interest (ROI)specifies which part of the image is processed. TheROI can be defined very flexibly (from a simple rectangle to a set of unconnected pixels).

8 For details aboutROI handling see the Solution Guide I, Region Of Interest on page a set of pixels. The pixels of a region do not need to be connected. Even an arbitrary collectionof pixels can be handled as a single region. With the operatorconnectiona region can be split into itsconnected regions, , components consisting of connected all contour and polygon based data. Subpixel-accurate operators likeedges_sub_pixreturnthe contours as XLD data. A contour is a sequence of 2D control points, which are connected by , the distance between control points is about one pixel. XLD objects contain, besides the controlpoints, so-called local and global attributes. Typical examples for these are, , the edge amplitude ofa control point or the regression parameters of a contour segment.

9 Besides the extraction of XLD objects, HALCON supports further processing. Examples for this are the selection of contours based on given featureranges for the segmentation of a contour into lines, arcs, polygons or Extension Packages11 The control data includes handles and basic data types like integer, real, references to complex data structures, , a connection to an image acquisition interface or a modelfor the shape-based matching. For efficiency and data security reasons, not the entire structure but onlythe handle is passed between the operators. Handles are magic values that must not be changed and candiffer from execution to execution and version to version. They are automatically cleared once all referencesare overwritten. Examples where handles are used are graphics windows, files, sockets, image acquisitioninterfaces, OCR, OCV, measuring, and Extension PackagesHALCON may be extended by new operators.

10 Although HALCON already contains an abundant set of operatorsfor various tasks, you may wish to implement new operators, , to access a special hardware or to implement analternative algorithm. To do so, HALCON provides the Extension Package Interface, which allows the integrationof new operators (implemented in C) in the form of so-calledextension packages. The Extension Package Interfacecontains several predefined routines and macros for the easy handling of image data and memory objects in C. Oncea new operator has been successfully integrated, it can be used like any other HALCON operator. The ExtensionPackage Programmer s Manual contains detailed information about extending the operator Language InterfacesAs shown in figure on page 9, HALCON provides so-calledlanguage interfaces.