HALCON Extension Package Programmer's Manual

HALCON Version 6.0MVTec Software GmbHHALCON Extension Package InterfaceProgrammer’s Manual

About This ManualThis manual describes how to extend HALCON by additional operators encapsulated in HAL-CON packages using the Extension Package Interface. Before starting to use the ExtensionPackage Interface, MVTec strongly recommends that the user should be familiar with the standardHALCON system.This manual is written for the expert HALCON user who wants to extend the system for specificrequirements. Thus, the reader should be familiar with the standard HALCON system.Furthermore, C programming skills are required. Finally, the reader should know about his/herprogramming environment (that is how to invoke the compiler/linker etc.).This manual is divided into the following parts:¯ IntroductionThis chapter provides a short overview of HALCON packages and their creation. Furthermore,an example showing the integration of a simple operator is presented.¯ Operator Description (-files)This chapter summarizes the minimum required operator description used by the HAL-CON compiler ÓÑÔ as well as the complete operator description which is needed toprovide a full integration of new operators in HDevelop and to generate documentationfiles.¯ Style Guide for ProgrammingThis chapter introduces basic style guides for how to program HALCON operators. Especially,the HALCON memory management is explained.¯ HALCON Data TypesIn this chapter the most important HALCON data structures to handle iconic data andcontrol parameters are presented.¯ Handling Iconic Objects and Control ParametersThis chapters contains a set of routines to facilitate the programming of the operator interfaceand accessing the basic HALCON data structures.¯ Special Routines for Typical Supply ProceduresThis chapter describes a set of convenience routines for standard situations.¯ Creating a New HALCON PackageThe last chapter explains how to use the HALCON compiler ÓÑÔ to generate HALCONpackages for different architectures.

Dl Iosub menţionează că diferenţe între sumele prevăzute pentru obiectivul extinderereţea de gaze naturale.Dl Primar precizează că acesea se datorează faptului că trebuie luată în calculposibilitatea realizării întregii acţiuni de către Primărie în funcţie de cum se va încheiacontractul de E. ON.Dl Iordache întreabă care este lista cu străzile ce urmează a fi reparate.Dl Primar precizează că pentru acest obiectiv de investiţii este alocată suma de 160 mldlei şi vizează următoarele activităţi: covoare asfaltice – străzile : Ştefan Dracinschi, Prunului,Dimitrie Dan, Oituz, Petru Rareş, Dragoş Vodă, Armenească, Ion Creangă, Univeristăţii, SamoilIsopescu, Ştefăniţă Vodă, 6 Noiembrie (continuare), Mirăuţi (continuare), Luca Arbore, ŞtefanTomşa, Ştefan Dracinschi 2, Bradului, Grigore Ureche, Ion Neculce, Bogdan Vodă, în CartierulObcini – străzile: Măgurei, Victoriei, Viitorului, Slătioarei, Bistriţei, Castanilor, Duzilor,Mesteacănului, în Cartierul George Enescu – străzile: Scurtă, Zorilor, Teilor, Saturn, Venus; înCartierul Burdujeni – străzile: Eroilor, Păcii, Muncii, Prieteniei, Avântului, Brânduşei,Rândunicii, Aurora, Amugului, Bazelor, Iacob Zadik, Grigore Antipa, Cuza Vodă; în CartierulIţcani – străzile: Aurel Vlaicu (continuare), Ion Luca Caragiale, Slt. Turturică, 28 Noiembrie,Micşunelelor, Stadionului, Pasaj Iţcani, Zefirului. Plombări vor fi realizate la străzile: Ilie Ilaşcu,Zamcei, Brădetului, Mitropoliei, Trandafirilor, Atanasie Crimca, Vasile Bumbac, Ştefan celMare, Tudor Vladimirescu, Calea Burdujeni, Biruinţei, Aron Pumnul şi Mitocului. Trotuare cupevele – străzile: Corneliu Coposu, Gavril Tudoraş, Mihai Viteazu, Mihai Eminescu, NicolaeBălcescu şi George Enescu. Balastări – străzile: Cartierul Iţcani: Câmpului, Constantin Moraru,Alexandru Vlahuţă, Grigore Cobălescu, Emil Racoviţă, Lipoveni, Cartierul Burdujeni: LevTolstoi, Tiberiu Popeea, Plevnei, Pictor Panaiteanu, Dobrilă Eugen, Crângului, Ştefan Luchian,Căpitan Grigore Andrei. În Cartierul Burdujeni Sat urmează să fie realizate lucrări de betonare astrăzilor însă după extinderea reţelelor de apă şi canalizare. Propune modificarea proiectului debuget în sensul includerii propunerilor făcute în şedinţa privind dezbaterea publică a bugetuluilocal al municipiului Suceava, respectiv: adresa nr. 3777/2008 aparţinând locuitorilor dinCartierul Burdujeni Sat prin care solicită reabilitarea reţelelor stradale - străzile: Dobrilă Eugen,Făgetului, Molidului; adresa nr. 3771/2008 aparţinând cetăţenilor din Cartierul Iţcani privindreabilitarea reţelelor stradale şi introducerea canalizării pe străzile: Voievidca, Merilor, Perilor –obiectiv ce va fi realizat în etapa a II a prin Proiectul ISPA; adresa Asociaţiei de proprietari nr.26 înregistrată la Consiliul Local al municipiului Suceava sub nr. 17/2008 prin care se solicităreabilitarea aleii care face legătura între strada Samoil Isopescu şi Punctul Termic „TudorVladimirescu”; adresa SC Rulexim prin care solicită extinderea canalizării în zona show – room– urilor de pe E 85, adresă care nu se încadrează în prevederile legale dat fiind faptul că aceiagenţi conomici plătesc taxele şi impozitele la Comuna Moara şi adresa Asociaţiei „Gospodarul”Iţcani înregistrată sub nr. 1104/2008 prin care solicită monitorizarea lucrărilor cuprinse înProgramul ISPA prin Proiectul „Reabilitare şi optimizarea reţelelor de alimentare cu apă – canalşi modernizarea staţiei de epurare (străzile: Eracle Porumbescu, 28 Noiembrie, Micşunelelor,Stadionului, Depoului), obiectiv ce va fi realizat în etapa a II a prin Programul ISPA.Dl Iordache propune trei amendamente, astfel:7

ivContents7.2.3 Creating theC++ Interface . . . . . . . . . . . . . . . . . . . . . . . . 1037.2.4 Creating New Applications . . . . . . . . . . . . . . . . . . . . . . . . 1037.2.5 AdditionalInformationforSpecific Architectures . . . . . . . . . . . . 1037.3 HALCON Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111A HALCON Error Codes 113HALCON Extension Package Interface / 2000-11-16

Chapter 1IntroductionHALCON can be extended by up to 99 additional operator packages. During the initializationof the system all packages indicated by the environment variable ÀÄÇÆÌÆËÁÇÆË areautomatically loaded. A package typically contains libraries with the new operators, their prototypes,the operator information needed by HDevelop, and the HTML online documentation.For the programming of such a package the HALCON Extension Package Interface is used,e.g., to manipulate parameters of HALCON operators and to read or write iconic data (images,regions, XLDs 1 ) from the HALCON data base.Furthermore, the operators provided by HALCON itself are also based on the functionality ofthe Extension Package Interface. Thus, the Extension Package Interface is both the interface betweenapplication programs and the operator layer of the the HALCON system and the interfacebetween the operator layer and the object data base.A reason why to extend the capabilities of HALCON by using the Extension Package Interfacemight be one of the following:¯ Extension of the pool of image processing operators,¯ Integration of special image processing hardware,¯ Integration of a special graphics software package.Once the user has extended HALCON by a package containing his/her own operators, they canbe used within all supported host-languages, and the interactive tool ÀÚÐÓÔ.This chapter gives a short introduction to HALCON packages and operators, includingan example describing the integration of a simple operator. The followingchapters present detailed information that will allow you to write your own packages.As a common example, a package called ÐÓÒÙ×Ö will be used (see±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×ÒÜØÒ×ÓÒ ÔÒÐÓÒÙ×Ö on the HALCON CD).Except of UNIX specific sections in this manual file paths and environment variables are printedin the Windows NT/ 2000 convention, e.g.,±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×ÒÜØÒ×ÓÒ ÔÒÐÓÒÙ×Ö1 eXtended Line Description; i.e. subpixel contours and polygons.1

2 CHAPTER 1. INTRODUCTIONto denote the subdirectory ÐÓÒÙ×Ö containing an example package within the HALCONbase directory referenced by the environment variable ÀÄÇÆÊÇÇÌ. The same expression inUNIX convention would look like°ÀÄÇÆÊÇÇÌ»ÜÑÔÐ×»ÜØÒ×ÓÒ Ô»ÐÓÒÙ×Ö1.1 HALCON OperatorsThis section describes the external interface of HALCON operators, i.e., how to use them in aprogramming language, and their internal structure.1.1.1 Using HALCON Operators in C and C++There are two different modes of calling operators from HALCON/C 2 : One way is to call operatorsfor simple applications with only one value per control parameter (simple mode). This isthe easiest way and sufficient for many applications. When using complex procedures that needmore than one value per parameter, data is transfered within tuples (ÀØÙÔÐ). Iconic objects arealways represented as tuples (ÀÓØ) so that one image object can contain several images,regions, or XLDs.There exists a special interface for C++ supporting a flexible management of several types.Especially, the handling of multi-value control parameters is transparent to the user. Moreover,this interface enfolds an appropiate class hierarchy for handling different image analysis data.However, the defined class hierarchy has a fixed mapping between the HALCON operators andthe provided classes. This mapping follows predefined rules and is therefore partly generic.A user-defined HALCON operator cannot be linked to an arbitrary position inside the classhierarchy. Thus, these operators are integrated in C++ as C functions using the generic datatype ÀÓØ in order to pass arguments to and from the operator. This kind of integration isalso used if you export your ÀÚÐÓÔ program as C++ code.For further information please take a look at the corresponding manuals.1.1.2 Internal Structure of HALCON OperatorsHALCON operators (like the new operators in ÐÓÒÙ×Ö) typically consist of two procedures:One procedure – the supply procedure – receives the input data, tests its consistency,passes it to the processing action procedure and returns the output data after the processing.If the input data contains any composed objects, e.g., image tuples, the supply procedure hasto extract the single parts. An object key can represent an unlimited number of iconic objectsand every image object may consist of several components (one region and an unlimited numberof gray value channels; see also Fig. 5.2 on page 61). Generally, a user may assume thata HALCON operator is able to handle single iconic objects as well as composed objects (i.e.ÑÙÐØÚÐÙ ÓÔØÓÒÐ is set; see page 29) and that it can work on multi-channel images(i.e. ÑÙÐØÒÒÐ ÓÔØÓÒÐ is set; see page 34). So, the author of a new HALCON operatorshould implement appropriate mechanisms for extracting the needed data from composed2 The HALCON version that allows the usage of HALCON operators within C programs.HALCON Extension Package Interface / 2000-11-16

1.1. HALCON OPERATORS 3objects (or multi-channel images) within the supply procedure. The name of this proceduredesignates the internal C-procedure name specified in the -file (cf. sections 2 and 2.2).After preprocessing the input data, the action procedure is called within the supply procedure.This procedure performs the specific image processing. In most cases the action procedure receivesonly the already extracted single components (e.g., regions of type ÀÖÐÖÓÒ, channelsof type ÀÑ, or pointers to the raw image data) and parameter values. The results are returnedto the supply procedure where they are passed to the generated interface that returns themto the calling system. Any supply procedure returns an error code of type ÀÖÖÓÖ. Thus, it isnecessary to return an error code, which is À ÅË ÌÊÍ if no error occurred. In Windows NT andWindows 2000, the supply procedures (like ÁÈÍ×ÖÌÖ×Óдµ in ÔÙ×ÖØÖ×Óк)must be explicitly exported by the operator DLL ÔºÐÐ. This is done by the macroÀÍ×ÖÜÔÓÖØ as a prefix to ÀÖÖÓÖ, see Fig. 1.6. In UNIX environments ÀÍ×ÖÜÔÓÖØ maybe omitted, but in this case the package will not run on Windows NT and Windows 2000 systems.Only one parameter (a so called procedure handle) is passed to a supply procedure. All otherinput data (iconic objects and control values) is read and written with the help of this identifier.Moreover, it allows the unique identification of a HALCON operator call while running HAL-CON on parallel hardware. Instead of further parameters, all in- and output to and from thesupply procedure is done with the help of several (internal) buffers, as illustrated in Fig. 1.1.InputApplication ProgramsOutputC or C++ InterfaceHALCONDatabaseBufferBufferControl IconicControlIconicParameter Objects Parameter ObjectsSupply ProcedureAction ProcedureFigure 1.1: Data flow within HALCON.The buffer contains input data as well as output data. Control parameters (containing all kindof control values like integers, floating-point values or strings) are stored directly in the buffers,whereas all iconic data (including images, regions and XLDs) are represented by an object key.Accesses to iconic data can be done with the help of data base procedures by using these objectkeys. The Extension Package Interface provides special procedures and macros for reading andwriting elements of the parameter buffer within the supply procedure. Every parameter belongsto one of the four classesHALCON 6.0

6 CHAPTER 1. INTRODUCTION¯ ÐÔ: This subdirectory contains files with data for the online access to the knowledgebase. They must be generated and placed in this directory in order to use a package insideof ÀÚÐÓÔ. Without these files ÀÚÐÓÔ cannot retreive the information needed toaccess the operators of a package.We also recommend to provide additional subdirectories:¯ ÒÐÙ: In this directory the generated include files containing the prototypes for theoperators of a package should be placed.¯ Ó: In this directory the documentation of the package should be placed (see also%HALCONROOT%Òdoc for comparison). Especially, it is necessary to put the generatedHTML files in docÒhtmlÒreferenceÒhdevelop in order to enjoy the online help fromthe operator window of ÀÚÐÓÔ.¯ ÜÑÔÐ×: This directory might contain some typical example programs (e.g., ÀÚÐÓÔdev-files) demonstrating the use of the new operators.¯ Ñ×: If the provided examples need specific images, they should be placed in thisdirectory. In that case we recommend to include the path to this subdirectory in theenvironment variable HALCONIMAGES in order to allow access to these images withoutusing an absolute file path in the programs.1.2.3 How to Create and Use a HALCON PackageIn summary, the following steps are necessary to create a HALCON package with the nameÔ integrating new operators into the HALCON system. As noted in section 1.2.1, tocreate a Parallel HALCON package, you must create a second version of the libraries. A detaileddescription of the steps can be found in the referenced sections of this manual:1. Description of the new operator(s) in one or more -file(s) (cf. chapter 2).2. Creation of a library (called Ô) containing the supply procedures in C and thecorresponding action procedures (cf. chapter 3–6). This library has to be placed in thepackage subdirectory 7 Ð or ÐÒ±ÊÀÁÌÌÍʱ.3. Creation of a library containing the language dependent operator interface (Ôand ÔÔÔ) based on the -file(s) with the help of ÓÑÔ (cf. section 7.1).These libraries have to be placed in the subdirectory Ð or ÐÒ±ÊÀÁÌÌÍʱ ofthe package.4. Generation of files for online access to the knowledge base with the help of ÓÑÔ.These files are used, e.g., by ÀÚÐÓÔ. They have to be placed in the subdirectoryÐÔ of the package.5. Generating the HTML reference files with the help of ÓÑÔ (optional). The generatedfiles have to be placed in the subdirectory ÓÒØÑÐÒÖÖÒÒÚÐÓÔ, , orÔÔof the package.7 In the Windows NT/ 2000 version, the DLLs corresponding to the link libraries have to to be placed in Ò orÒÒ±ÊÀÁÌÌÍʱ.HALCON Extension Package Interface / 2000-11-16

1.3. INSTALLING A HALCON PACKAGE 76. Generating PostScript- manuals with the help of ÓÑÔ (optional).7. Extension of the package list in the environment variable ÀÄÇÆÌÆËÁÇÆË by thecomplete file path of the new package, e.g.,±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×ÒÜØÒ×ÓÒ ÔÒÐÓÒÙ×ÖFor specific architectures additional environment variables have to be modified, see sections1.3 and 7.2.5.8. Linking of the generated libraries together with the HALCON library to the image analysisapplication (cf. chapter 7). For this, you have to modify additional environmentvariables, depending on the operating system (see below). Please note, that HDevelopis able to access the new operators dynamically without linkage.1.3 Installing a HALCON PackageIn order to install a HALCON package you have to copy the package to your hard disk and addthe complete path of the package to the environment variable ÀÄÇÆÌÆËÁÇÆË, e.g.,±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×ÒÜØÒ×ÓÒ ÔÒÐÓÒÙ×ÖNote, that the delimiter between paths in an environment variable is a semicolon on WindowsNT or Windows 2000 systems and a colon on UNIX systems.Never change the name of a package or the corresponding names of the librariesor DLLs contained in a package.These names are encoded within the libraries/DLLs. If you change the names this informationwill not match any longer. Thus, the loader of the operationg system will fail to open thedynamic libraries. In order to use the new package within HDevelop you have to restart theprogram. For generating a standalone application using the package you have to link the C orC++ interface library of the package to the application code, see sections 7.2 and 7.2.5.If the package contains images used e.g., within example programs you might want to includethe corresponding directory (e.g., Ñ× within the package) in the environment variableÀÄÇÆÁÅË to access those images without specifying a complete path.For UNIX architectures you have to modify additional environment variables in order to use aHALCON package (see below).1.3.1 Additional Information for Windows NT and Windows 2000To be able to link the package DLL to your application program, the complete DLL file path ofthe new package, e.g.,±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×ÒÜØÒ×ÓÒ ÔÒÐÓÒÙ×ÖÒbinÒ¹ÒØhas to be added to the environment variable ÈÌÀ.Do not copy a package DLL into the Windows system directories, as it would be loadedtwice in this case!HALCON 6.0

8 CHAPTER 1. INTRODUCTION1.3.2 Additional Information for LinuxOn UNIX PCs running Linux you have to include the package library subdirectoryл¹ÐÒÙܾº¾ in the environment variable Ä ÄÁÊÊ ÈÌÀ in order to use a package.This has to be done in any case – regardless whether you plan to use a package withinHDevelop only or you want to create stand-alone applications. Otherwise the operating systemwill fail to open the interface library ÐÔº×Ó or ÐÔÔÔº×Ó needed to accessthe package.1.3.3 Additional Information for SolarisOn UNIX workstations running Solaris you have to add the package library subdirectoryл×ÔÖ¹×ÙÒ¹×ÓÐÖ× to the environment variable Ä ÄÁÊÊ ÈÌÀ in order to runstand-alone applications based on the package. Otherwise the loader will fail to access theinterface library ÐÔº×Ó or ÐÔÔÔº×Ó linked to the application, see section7.2.5.Note, that it is not necessary to modify Ä ÄÁÊÊ ÈÌÀ in order to use the package withinHDevelop.1.3.4 Additional Information for IRIXOn UNIX workstations running IRIX you have to include the package library subdirectoryлÑÔ×¹×¹Öܺ in the environment variable Ä ÄÁÊÊ ÈÌÀ in order to run standaloneapplications based on the package. Otherwise the loader will fail to access the interfacelibrary ÐÔº×Ó or ÐÔÔÔº×Ó linked to the application, see section 7.2.5.Note, that it is not necessary to modify Ä ÄÁÊÊ ÈÌÀ in order to use the package withinHDevelop.1.3.5 Additional Information for HP-UXOn UNIX workstations running HP-UX you have to include the package library subdirectoryлÔÔ½º½¹Ô¹ÔÙܽ¼ in the environment variable ËÀÄÁ ÈÌÀ in order to use a package.This has to be done in any case – regardless whether you plan to use a package within HDeveloponly or you want to create stand-alone applications. Otherwise the operating system will failto open the interface library ÐÔº×Ð or ÐÔÔÔº×Ð needed to access thepackage.1.3.6 Additional Information for DIGITAL UNIX (Tru64 UNIX)On UNIX workstations running DIGITAL UNIX (now called Tru64 UNIX) you have to includethe package library subdirectory лÐÔ¹¹Ó׺¼ in the environment variableÄ ÄÁÊÊ ÈÌÀ in order to run stand-alone applications based on the package. Otherwise theloader will fail to access the interface library ÐÔº×Ó or ÐÔÔÔº×Ó linkedto the application, see section 7.2.5.HALCON Extension Package Interface / 2000-11-16

1.4. AN EXAMPLE 9Note, that it is not necessary to modify Ä ÄÁÊÊ ÈÌÀ in order to use the package withinHDevelop.1.4 An ExampleThe following example illustrates the steps described in section 1.2. Assume, one wants toimplement a new operator named Ù×Ö ØÖ× to extract all pixels with a gray value largerthan a threshold value specified in an input parameter. The use of Ù×Ö ØÖ× within a Cprogram is illustrated in Fig. 1.2.ÑÒ´µßÀÓØÒØÁѸÊÓÒÌÖ×ÐÖÑ´²ÁѸÑÓÒݵÌÖ× ½¼¼Ù×ÖØÖ×´ÁѸ²ÊÓÒ¸ÌÖ×µFigure 1.2: Calling the operator Ù×Ö ØÖ× in C. A more detailed example is provided in±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×Ò ÒØÖÒÐÓÒÙ×ÖÒ×ÓÙÖÒØ×ØØÖ×Óк.To use Ù×Ö ØÖ× in this way within C-programs 8 ,¯ The new operator must be implemented.¯ The corresponding HALCON interface-code must be generated.¯ The corresponding package must be created especially containg the operator and interfacelibraries.¯ The application must be linked.Ù×ÖØÖ× ¹ ÁÈÍ×ÖÌÖ×ÓÐÁÑÊÓÒÌÖ×Óа℄Figure 1.3: Defining a new operator Ù×Ö ØÖ×.First of all one has to create a definition file (file extension º), as illustrated in Fig. 1.3 andFig. 1.4. Fig. 1.3 shows only the absolute minimum of information that a definition file mustcontain in order to call a new operator within C-programs. When using C++ or ÀÚÐÓÔ,an extended version is necessary as described in section 2.2. The minimal form of such anextended definition is illustrated in Fig. 1.4. The -file specifies:¯ the name of the operator (Ù×Ö ØÖ×),8 To use it within C++ basically the same steps are necessary, see section 7.HALCON 6.0

10 CHAPTER 1. INTRODUCTIONÙ×ÖØÖ× ¹ ÁÈÍ×ÖÌÖ×ÓÐÁÑÊÓÒÌÖ×ÓÐ℄×ÓÖغÖÑÒËÛÐÐÛÖØÓÔÖØÓÖº×ÓÖغÒÐ×ËÐØÓÒ Ó ÖÝ ÚÐÙ× Ý ØÖ×ÓÐÒºÑÓÙÐ×ÔØÖºÖÑÒÒÙØÞÖÖÛØÖÙÒÒÔØÖºÒÐ×Í×ÖÜØÒ×ÓÒ×ÙÒØÓÒÐØÝÑÔÖÑØÖÁÑ×ÑØÝÔÔÖÑØÖÊÓÒ×ÑØÝÔÔÖÑØÖÌÖ×ÓÐÙÐØØÝÔÑÙÐØÚÐÙ×ÑØÝÔÒÔÙØÓØÑÓÙØÔÙØÓØÖÓÒÒÔÙØÓÒØÖÓÐÒØÖÐ×ÒÙÑÖFigure 1.4: An example for an extended -file of the operator Ù×Ö ØÖ× (minimal form), cf.±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×Ò ÒØÖÒÐÓÒÙ×ÖÒÒØÖ×Óк.¯ the name of the supply procedure that has to be implemented in C (ÁÈÍ×ÖÌÖ×ÓÐ),¯ names and types of the operator’s parameter(s). The names of the parameters are onlyimportant for the manuals and within ÀÚÐÓÔ.The minimal form of the extended operator -file includes: A short description (×ÓÖØ), theHALCON module (ÑÓÙÐ) the operator belongs to, the mapping to a chapter (ÔØÖ) ofthe manual, the mapping to an object (ÙÒØÓÒÐØÝ), and for every parameter its semantictype (×Ñ ØÝÔ). In addition, the type (ÙÐØ ØÝÔ) and number (ÑÙÐØÚÐÙ) must bespecified for control parameters.Our operator Ù×Ö ØÖ× has got the following parameters:¯ one input object parameter (ÁÑ),¯ one output object parameter (ÊÓÒ),HALCON Extension Package Interface / 2000-11-16

1.4. AN EXAMPLE 11¯ one input control parameter (ÌÖ×ÓÐ) of type ÒØ with exactly one value and¯ no output control parameter.ÓÑÔ ¹Ù ¹ ¹ÔÐÓÒÙ×Ö ØÖ×ÓкFigure 1.5: Call of ÓÑÔ for HALCON/C.The operator definition within the -file now is used by ÓÑÔ to generate the appropriateinterface code. Fig. 1.5 shows the call of ÓÑÔ. Note, that within this manual ÐÓÒÙ×Ö isused as name of the HALCON package to be created. By calling ÓÑÔ with this options 9 thefiles ÀÐÓÒÙ×Öº (interface-code) and ÀÐÓÒÙ×Öº (prototype of the new HALCONoperator) are created.In the next step one has to program the new HALCON operator. This is done by implementingthe supply and action procedure. This results in the typical structure of HALCON operators asillustrated in Fig. 1.6.» ØÓÒ ÔÖÓÙÖ »ÀÖÖÓÖ ÁÈÌÖ×ÓдÔÖÓÒиÖÓҸѸÛظØÖ×ÓиÖÓÒÓÙصߺººÐ» ×ÙÔÔÐÝ ÔÖÓÙÖ ¹ ÐÛÝ× ÛØ Ø× ÔÖÑØÖ »ÀÍ×ÖÜÔÓÖØ ÀÖÖÓÖ ÁÈÍ×ÖÌÖ×ÓдÀÔÖÓÒÐ ÔÖÓÒеßÀØÈÖ´ºº¸²ÌÖ×Óиººµ » Ø ÓÒØÖÓÐ »» ÔÖÑØÖ »ÀÐÐËÑ´ÔÖÓÒи²ÖÓÒ¸²Ñ¸½¸µ » ÛÓÖ ÓÒ ÐÐ »» ÒÔÙØ Ñ× »ßÀÈ´ÔÖÓÒиÁÈÌÖ×Óдºººµµ » ÐÐ ØÓÒ »» ÔÖÓÙÖ »ÀÆÛÊÓÒ´ÔÖÓÒиÖÓÒÓÙص » ×ØÓÖ ´Ö×ÙÐص »» ÖÓÒ »ÐÖØÙÖÒ´ÀÅËÌÊ͵ÐFigure 1.6: Sample source code of supply ÁÈÍ×ÖÌÖ×Óдµ and action ÁÈÌÖ×Óдµprocedure.Compiling the source code generates an object file (in the example ÔÙ×ÖØÖ×ÓкÓ)that should be integrated into the user extension library (ÐÓÒÙ×Ö). Moreover, the generatedinterface code must be converted to the corresponding language dependent interfacelibrary: In case of a C application 10 this is ÐÓÒÙ×Ö containing ÀÐÓÒÙ×ÖºÓ. The9 see section 7.1 for a complete description.10 ÀÚÐÓÔ uses the C version as well.HALCON 6.0

12 CHAPTER 1. INTRODUCTIONfile ÑÐ in the directory ±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×ÒÜØÒ×ÓÒ ÔÒÐÓÒÙ×Öcontains a makefile for generating the example package itself under UNIX. ÑкÒØ is thecorresponding file to be used via ÒÑ under Windows NT and Windows 2000. The makefilesÑÐ Ø×ØÔÖÓ and ÑÐ Ø×ØÔÖÓºÒØ generate example applications usingthe new operators.Now we can use our new operators within C-programs. But they are not yet available withinÀÚÐÓÔ, because the online help files have not been generated so far. There is also stillmissing any kind of documentation, such as the HTML manual pages.ÓÑÔ ¹Ù ¹Å ØÖ×ÓкFigure 1.7: Calling the HALCON compiler ÓÑÔ to create the help files.The generation of the online help files (as they are used e.g., by ÀÚÐÓÔ) can also be done withthe help of the HALCON compiler ÓÑÔ, see Fig. 1.7. However, to do so an extended versionof the -file must be available. The generated help files must be placed in the subdirectoryÐÔ of the package.ËÇÍÊËÀÇÅÈ ØÖ×Óк °´ÀÄÇÆÊÇÇ̵»Ò»°´ÊÀÁÌÌÍʵ»ÓÑÔÐÐ ÚÐÓÔ ÔÔÚÐÓÔ °´ËÇÍÊ˵°´ÀÇÅȵ ¹ÄØÐÐ °´ËÇÍÊ˵ÑÚ ºØÑÐ Ó»ØÑлÖÖÒ»ÚÐÓÔ °´ËÇÍÊ˵°´ÀÇÅȵ ¹ÄÐÐ °´ËÇÍÊ˵ÑÚ ºØÑÐ Ó»ØÑлÖÖÒ»ÔÔ °´ËÇÍÊ˵°´ÀÇÅȵ ¹Ä··ÐÐ °´ËÇÍÊ˵ÑÚ ºØÑÐ Ó»ØÑлÖÖÒ»ÔÔFigure 1.8: Makefile for generating HTML references.The help files generated by now are used to access information about the new operators bycalling specific HALCON operators like Ø ÓÔÖØÓÖ ÒÓ. This is of importance especiallyfor constructing graphical user interfaces like ÀÚÐÓÔ. For the user a more convenient way toaccess information online is to browse through HTML documents. The HTML documentationof HALCON operators can be generated by ÓÑÔ as well, see Fig. 1.8. In this example, HTMLdocuments are generated in Trias (ÀÚÐÓÔ) syntax (¹ÄØÐÐ), in C-syntax (¹ÄÐÐ),and in C++- syntax (¹Ä··ÐÐ). The HTML files have to be placed in the correspondingsubdirectories ÓÒØÑÐÒÖÖÒÒÚÐÓÔ, , orÔÔ of the package.If you now add the package path to ÀÄÇÆÌÆËÁÇÆË and start ÀÚÐÓÔ theuser extensions, e.g. Ù×Ö ØÖ×, are automatically available in the specified menuHALCON Extension Package Interface / 2000-11-16

1.5. ADDITIONAL SOURCES OF INFORMATION 13(i.e., chapter). In our example this menu is called Í×ÖÜØÒ×ÓÒ× as specified in±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×Ò ÒØÖÒÐÓÒÙ×ÖÒÒØÖ×Óк. 11 You can selectand execute the user-defined operators like all the built-in operators of the HALCON system.The HTML documentation is available via the ÀÐÔ button within the operator window.Examples of how to use the user defined extensions in ÀÚÐÓÔ can be found in the subdirectoryÜÑÔÐ× of ±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×ÒÜØÒ×ÓÒ ÔÒÐÓÒÙ×Ö (ºÚ).Furthermore, the ºÚ programs have been exported as C++ programs. The ºÔÔ filescan be found in the subdirectory ×ÓÙÖ. You can compile the C++ files using the alreadymentioned makefiles. These ºÔÔ files also serve as an example for the integrationof user defined operators into the host language C++. Note, that before compiling theexported C++ code containing operators from the package ÐÓÒÙ×Ö, the correspondinguser extension libraries must have been created. This can be done via the ÑÐ in±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×ÒÜØÒ×ÓÒ ÔÒÐÓÒÙ×Ö which will also generate theneeded user extension C++ library ÐÓÒÙ×ÖÔÔ.Please note, that on some systems not all users have writing permissions in the directoriesmentioned above. To experiment with the example package we recommend to create a privatecopy in your working directory. In such a case you must of course use the actual path to yourcopy when modifying environment variables.1.5 Additional Sources of InformationFor further information you may consult the following manuals:¯ Getting Started with HALCONAn introduction to HALCON in general, including how to install and configure HALCON.¯ HDevelop User’s ManualAn introduction to the graphical development environment of the HALCON system.¯ HALCON/C++ User’s ManualHow to use the HALCON library in your C++ programs.¯ HALCON/C User’s ManualHow to use the HALCON library in your C programs.¯ HALCON/COM User’s ManualHow to use the HALCON library in your COM programs, e.g., in Visual Basic.¯ Frame Grabber Integration Programmer’s ManualA guide on how to integrate a new frame grabber in the HALCON system. Note thatin some cases you might define new operators (using the Extension Package Interface)instead of using the standard HALCON Frame Grabber Integration Interface in order toexploit specific hardware features of a framegrabber board.¯ HALCON/HDevelop, HALCON/C++, HALCON/C, HALCON/COMThe reference manuals for all HALCON operators (versions for HDevelop, C++, C, andCOM).11 Í×ÖÜØÒ×ÓÒ× is integrated into the menu ÇÔÖØÓÖ of ÀÚÐÓÔ.HALCON 6.0

14 CHAPTER 1. INTRODUCTIONAll these manuals are available as ÈÓ×ØËÖÔØ ´Ô×µ and ÖÓØ ÊÖ ´Ôµ documents.The reference manuals are available as HTML documents as well. For the latest versionof the manuals please checkØØÔ»»ÛÛÛºÑÚغÓÑ»ÐÓÒ»Please see also the example package±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×ÒÜØÒ×ÓÒ ÔÒÐÓÒÙ×Öwhich will be referenced many times within this manual.HALCON Extension Package Interface / 2000-11-16

Chapter 2Operator Description (-files)The following chapters give a detailed description of the steps mentioned insection 1. This is done with respect to the examples within the directory±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×ÒÜØÒ×ÓÒ ÔÒÐÓÒÙ×Ö as well as system-definedHALCON operators. We start with the generation of an operator description.2.1 Short Operator DescriptionBefore implementing an operator the author should think about the task of the operator and whatkind of user interface is best for calling the operator. This specification is used to automaticallygenerate the interface code for the desired host language with the HALCON compiler ÓÑÔ.To do this, it is necessary to describe at least the following features beside the operator name ina -file:¯ the name of the operator as used within the application programming language,¯ the name of the C-procedure (supply procedure) called by HALCON in order to start theprocessing (this procedure must be implemented later on),¯ all iconic objects and control parameters that are needed by the operator as input (inputparameters),¯ all iconic objects and control parameters that are returned by the operator as result (outputparameters),¯ the types of these parameters,¯ the number of values per parameter (there is only a distinction between parameters thatneed or can process exactly one value and those expecting more than one value).There exist two kinds of parameters within HALCON: Iconic object parameters and parameterscontaining any other data –socalledcontrol parameters. By distinguishing input- and outputparameterswe get four classes of parameters: Input iconic object parameters, output iconicobject parameters, input control parameters, andoutput control parameters. Basically, specifyingthe number of parameters per class would suffice to describe the operator. The internalaccess (in particular within the supply procedure) on individual parameters works this way byusing the parameter’s position within its class. But to refer to single parameters and add furtherinformation regarding a parameter, it is useful to give it a name.15

16 CHAPTER 2. OPERATOR DESCRIPTION (’DEF’-FILES)The information specified up to now is already sufficient to integrate an operator within theHALCON/Extension Package Interface by using ÓÑÔ. It describes the operator properly andmay be specified as a “one line short version” of the -file according to the following syntax:ÜØÖÒÓÔÖØÓÖÒÑ ¹ ÁÒØÖÒÈÖÓÙÖÁÒÔÙØÇØ×ÇÙØÔÙØÇØ×ÁÒÔÙØØÖÐÈÖÑ×ÇÙÔÙØØÖÐÈÖÑ×℄Chapter 2.2 explains the meaning of the single identifiers and the name convention. Pleasenote, that in contrast to the header mentioned there, the short version header must be finishedby a semicolon (;) and that the default type and the number of values is specified together withthe name of a control parameter (ÁÒÔÙØØÖÐÈÖÑ× and ÇÙÔÙØØÖÐÈÖÑ×). This is doneby concatenating a dollar sign and an additional character to the name encoding the type andnumber of values (cf. the example in Fig. 2.1).Ù×ÖÒ× ¹ ÁÈÍ×ÖËÐØÊÓÒ×ÊÓÒËÐØÊÓÛ°¸ÓÐÙÑÒ°℄Figure 2.1: Short version of the definition of the operator Ù×Ö Ò× (cf.±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×Ò ÒØÖÒÐÓÒÙ×ÖÒÒÖÓÒØÙÖ׺).The following table shows how to code types and number of values into a character. Lower-casecharacters stand for exactly one value in the specified parameter. This corresponds to assigningÑÙÐØÚÐÙ Ð× in the extended version. Capital letters specify parameters that containmore than one value passed as a tuple (ÑÙÐØÚÐÙ ØÖÙ).TypeC-typeCodeOne Value Unlimited NumberInteger ÐÓÒ i IFloating-point Value ÓÙÐ f FString Ö s SThe specification described so far is sufficient to integrate the operator into C applications.However, in general the new operators should also be usable by HDevelop or within C++ applications.To achieve this, an extended version of the operator description must be generated.This is described in the following section.2.2 Extended Operator DescriptionAn operator description within a -file must start with a Ö. The following entries arevariable in their order. All of these slots begin with a determined keyword and are finished by asemicolon (). Semicolons within the text not defining the end of a slot must be quoted with abackslash ().Some slots are language dependent: For example ×ÓÖغÒÐ× contains a short descriptionof the operator in English, ×ÓÖغÖÑÒ the same description in German. The currently supportedlanguages are English and German. In order to allow an international usage of operatorswe strongly recommend always to provide all ºÒÐ× slots.HALCON Extension Package Interface / 2000-11-16

2.2. EXTENDED OPERATOR DESCRIPTION 17Note, that all slots specified within the operator description are accessible online within theHALCON system using the operator Ø ÓÔÖØÓÖ ÒÓ, see the Reference Manuals for details.Describing the single parameters completes the operator description. Section 2.3 explainshow to do this.2.2.1 HeaderThe operator description starts with the headerÜØÖÒÓÔÖØÓÖÒÑ ¹ ÁÒØÖÒÈÖÓÙÖÁÒÔÙØÇØ×ÇÙØÔÙØÇØ×ÁÒÔÙØØÖÐÈÖÑ×ÇÙÔÙØØÖÐÈÖÑ×℄Note, that in contrast to the short version described in section 2 the header doesn’t containany information about the types of the control parameters (e.g. °) and does not end with asemicolon (;).The following example is a short version of the operator description for the dynamic thresholdoperator ÝÒ ØÖ×ÓÐ. For better legibility there should be a comment at the beginning ofevery operator description, like» ÝÒØÖ×ÓÐ »ÝÒØÖ×ÓÐ ¹ ÁÈÝÒÌÖ×ÓÐÇÖÁѸÌÖ×ÓÐÁÑÊÓÒÝÒÌÖ×Ç×ظÄØÖ℄Comments within -files are indicated according to the C-syntax (» ººº »).There are a couple of conventions/restrictions concerning the names of parameters: All wordparts should begin with a capital letter (e.g., ÊÓÒÝÒÌÖ×). They are directly concatenatedwithout any separating character. Especially, they must not contain any underscore (‘ ’)!The external operator name exclusively consists of lower-case characters with word parts separatedby underscores. This operator name is used within C programs, low-level calls 1 of theoperator in C++, or within HDevelop.The four parameter classes (input-/output object/control) are separated by colons (:). One classis described by a list of all parameter names within the class separated by commas. If there is nomember of a class for an operator, the list remains empty. The example described above definesthe following mapping between parameters and parameter classes:parameter class keyword (cf. page 27) parameter in the exampleinput iconic objects ÒÔÙØ ÓØ OrigImage, ThresholdImageoutput iconic objects ÓÙØÔÙØ ÓØ RegionDynThreshinput control parameters ÒÔÙØ ØÖÐ Offset, LightDarkoutput control parameters ÓÙØÔÙØ ØÖÐ 1 Within the HALCON/C++ class hierarchy corresponding methods use slightly different conventions:ÜØÖÒ ÓÔÖØÓÖ ÒÑ is transformed into ÜØÖÒÇÔÖØÓÖÆÑ.HALCON 6.0

18 CHAPTER 2. OPERATOR DESCRIPTION (’DEF’-FILES)It is helpful to follow certain conventions, when choosing names for parameters. They shouldbe meaningful (i.e. one should avoid names like ‘Aac’) and consequently should be given inEnglish. It is convention to denote parameters that specify a position within an image matrix byRow(s) (not Line!) and Column(s) or Col(s). Parameters defining a dimension are called Widthand Height.2.2.2 shortThe keyword ×ÓÖØ starts the short description of the operator, in our example×ÓÖغÒÐ×ËÑÒØ Ò Ñ Ù×Ò ÐÓÐ ØÖ×ÓкAs all slots specified by the keyword ºÒÐ×, this slot contains purely textual information.Text can be written in different languages and can contain L A TEX-commands according to specialsyntactic rules that are defined in section 2.4.2.2.3 abstractA more detailed description of the operator is given within the slot ×ØÖØ. The descriptionof the example is here shown as a shortened version:HALCON Extension Package Interface / 2000-11-16

2.2. EXTENDED OPERATOR DESCRIPTION 19×ØÖغÒÐ×ÇÔÊßÝÒØÖ×ÓÐÐ ×ÐØ× ÖÓÑ Ø ÒÔÙØ Ñ ØÓ×ÖÓÒ× Ò Û Ø ÔÜÐ ÙÐÐÐ ØÖ×ÓÐ ÓÒØÓÒº ÄØ°ßÓÐ ßÈÖÊßÇÖÁÑÐа¸ Ò °ßÑÐ ßÈÖÊßÌÖ×ÓÐÁÑÐаº ÌÒ Ø ÓÒØÓÒ ÓÖÈÖÊßÄØÖÐ ÎÐÊß³ÐسР×Ó Ñ · Ç×ØÐßÓÐ ßÑÐ · ÈÖÊßÇ×ØÐ℄ÓÖ ÈÖÊßÄØÖÐ ÎÐÊß³Ö³Ð Ø ÓÒØÓÒ ×Ó Ñ ¹ Ç×ØÐßÓÐ Ð ßÑÐ ¹ ÈÖÊßÇ×ØÐ℄ÒÐÐݸ ÓÖ ÈÖÊßÄØÖÐ ÎÐÊß³ÕÙÐ³Ð Ø ×Ñ ¹ Ç×Ø Ó Ñ · Ç×ØÐßÑÐ ¹ ÈÖÊßÇ×ØÐ Ð ßÓÐ Ð ßÑÐ · ÈÖÊßÇ×ØÐ℄Ì× ÑÒ× ØØ ÐÐ ÔÓÒØ× Ò ÈÖÊßÇÖÁÑÐ ÓÖ Û ØÖÝ ÚÐÙ × ÐÖÖ ÓÖ ÕÙÐ ØÓ Ø ÖÝ ÚÐÙ ÒÈÖÊßÌÖ×ÓÐÁÑÐ ÔÐÙ× Ò Ó×Ø Ö ÖØ ÒØÓ ØÖ×ÙÐØÒ ÖÓÒºAgain, refer to section 2.4 for the special syntax of text.2.2.4 moduleÑÓÙÐ×This slot denotes the module inside HALCON the operator should belong to. For user extensionsthe module ‘×’ is recommended.2.2.5 chapterTo achieve a useful structuring of HALCON operators, they are all arranged in a hierarchy ofchapters and sections. The assignment defined in the slot ÔØÖ is reflected in the referencemanuals and in the menu ÇÔÖØÓÖ of ÀÚÐÓÔ.HALCON 6.0

20 CHAPTER 2. OPERATOR DESCRIPTION (’DEF’-FILES)ÔØÖºÒÐ×ËÑÒØØÓÒThe structuring can be refined by specifying a section: ÔØÖ¸×ØÓÒ℄, e.g.,ÔØÖºÒÐ×ÐØÖ¸×Note, that it is not allowed to insert operators and sections into the same chapter at the samelevel of hierarchy. So if you decide to use sections within a chapter, all operators within thischapter must be assigned to one of these sections. Furthermore, the chapter names may notcontain spaces. If you need multi-word chapter names, please use a dash (¹) between eachword, e.g., Ò¹ÌÖÒ×ÓÖÑØÓÒ×.2.2.6 functionalityÙÒØÓÒÐØÝÑThis slot denotes the class of which the operator should become a method within an objectoriented programming language like C++ 2 . Generally this corresponds to the semantic type ofthe first parameter, e.g., an image object (Ñ). The specified name is only a symbolic one.The actual class name depends on the programming language and is provided by the HALCONcompiler ÓÑÔ. Possible values for ÙÒØÓÒÐØÝ in the current version areÒÝ, ÛÒÓÛ, Ñ, ÖÓÒ, ÓØ, ÜÐ ÓÒØ, ÜÐ ÔÓÐÝ, ÜÐ ÔÖ,ÜÐ ÑÓ ÔÖ, andÜÐ ÜØ ÔÖ.2.2.7 keywordsFurthermore, one can assign a list of keywords to an operator. They are used e.g., by HDevelopto support the search for the proper operators for a given problem.ÝÛÓÖ׺ÒÐ×ÌÖ×Óи ÖݹÎÐÙ¹ÌÖ×Óи ÝÒѹÌÖ×Óи ÄÓйÌÖ×ÓÐ2.2.8 predecessor, successor, alternativesThe following slots also support interactive development of image processing applicationwith HALCON. They are used to define potential, convenient or necessary predecessor(ÔÖ××ÓÖ) and successor operators (×Ù××ÓÖ) or to define alternatives(ÐØÖÒØÚ×). All operators within these lists are referenced by their name.2 User defined extensions are not inserted in the class hierarchy but considered as global methods.HALCON Extension Package Interface / 2000-11-16

2.2. EXTENDED OPERATOR DESCRIPTION 21ÔÖ××ÓÖÑÒѸ×ÑÓÓØѸÙ××Ñ×Ù××ÓÖÓÒÒØÓÒ¸×ÐØ×Ô¸ÖÙÓÑÒ¸×ÐØÖݸÖÒÖÓÒ¸ÐØÓÒ½¸ÓÔÒÒÐØÖÒØÚ×Ô×׸ØÖ×ÓиÖÓÙÒ×2.2.9 see alsoThe slot × Ð×Ó contains a list of operators that are used for similar tasks or help to understandhow an operator works.×Ð×ÓÑÒѸ×ÑÓÓØѸÙ××ѸÓÒÒØÓÒ¸ÖÒÖÓÒ¸ÐØÓÒ½2.2.10 attentionThe slot ØØÒØÓÒ contains hints for using the operator or specific limitations.ØØÒØÓÒºÒÐ×Á ÈÖÊßÇ×ØÐ × Ó×Ò ÖÓÑ ¹½ ºº ½ а¹½ÓØ×½°Ù×ÙÐÐÝ ÚÖÝ ÒÓ×Ý ÖÓÒ × ÒÖظ ÖÕÙÖÒ ÐÖ ×ØÓÖºÁ ÈÖÊßÇ×ØÐ × Ó×Ò ØÓÓ ÐÖ ´°° ¼¸ ×ݵ Ø ÑÝ ÔÔÒØØ ÒÓ ÔÓÒØ× ÙÐÐÐ Ø ØÖ×ÓÐ ÓÒØÓÒ ´ºº Ò ÑÔØÝÖÓÒ × ÖØÙÖÒµº Á ÈÖÊßÇ×ØÐ × Ó×Ò ØÓÓ ×ÑÐÐ ´°°¹¼¸ ×ݵ Ø ÑÝ ÔÔÒ ØØ ÐÐ ÔÓÒØ× ÙÐÐÐ Ø ØÖ×ÓÐÓÒØÓÒ ´ºº ÙÐÐ ÖÓÒ × ÖØÙÖÒµº2.2.11 result stateThe slot Ö×ÙÐØ ×ØØ defines the result value of an operator and the corresponding exceptionhandling. The syntactical rules for the text are again the same as described in section 2.4.Ö×ÙÐØ×ØغÒÐ×ÇÔÊßÝÒØÖ×ÓÐÐ ÖØÙÖÒ× ÌÊÍ ÐÐ ÔÖÑØÖ× ÖÓÖÖغ Ì ÚÓÖ ÛØ Ö×ÔØ ØÓ Ø ÒÔÙØ Ñ× Ò ÓÙØÔÙØÖÓÒ× Ò ØÖÑÒ Ý ×ØØÒ Ø ÚÐÙ× Ó Ø Ð×ÎÐÊß³ÒÓÓØÖ×ÙÐسи ÎÐÊß³ÑÔØÝÖÓÒÖ×ÙÐسи ÒÎÐÊß³×ØÓÖÑÔØÝÖÓҳРÛØ ÇÔÊß×Ø×Ý×ØÑкÁ Ò××Öݸ Ò ÜÔØÓÒ × Ö׺HALCON 6.0

22 CHAPTER 2. OPERATOR DESCRIPTION (’DEF’-FILES)2.2.12 parallelizationThe slot ÔÖÐÐÐÞØÓÒ contains information about the parallelization characteristics of anoperator when used in Parallel HALCON (see the manual Getting Started with HALCONfor more information about Parallel HALCON). On the one hand, this regards the possibilityof using the operator in a parallel, for example, multithreaded application and on the otherhand this regards the automatic parallelization which Parallel HALCON uses to speed up theoperator’s processing when working with multi-processor hardware.The slot ÔÖÐÐÐÞØÓÒ consists of several sub-slots, each starting with a characteristickeyword followed by a colon and finishing with a semicolon. The example below shows theslot for the operator ÝÒ ØÖ×ÓÐ, which is not “local”, needs neither complete nor mutualexclusion, and is parallelized on tuple level. The single subslots and their meaning will bedescribed in the following sections.ÔÖÐÐÐÞØÓÒÔÖÓ××ÜÐÙ×ÚÐÝ Ð×ÔÖÓ××ÐÓÐÐÝ Ð×ÔÖÓ××ÑÙØÙÐ Ð×ÑØÓ×ÔÐØØÙÔÐÔÖÓ×× ÜÐÙ×ÚÐÝ ØÖÙ¸Ð×This subslot of ÔÖÐÐÐÞØÓÒ assigns, whether an operator is processed completelyexclusively (‘true’) by the main HALCON process/thread or not. An exclusive processingmeans that no other operator will be processed by Parallel HALCON while the exclusiveoperator is running. If an exclusive operator is started and other operators are still running,the processing of the exclusive operator is delayed until all other (currently running)operators have completed.An exclusively processed operator is always processed without any parallelization by themain HALCON thread/process. Note that even if Parallel HALCON is reentrant for mostof the operators, there are still some operators that have to be processed exclusively dueto reasons of their implementation.If no subslot ÔÖÓ×× ÜÐÙ×ÚÐÝ is filled in with an operator, it is assumed that theoperator needs no completely exclusive processing (“optimistic” assumption).ÔÖÓ×× ÑÙØÙÐ ØÖÙ¸Ð×This subslot of ÔÖÐÐÐÞØÓÒ assigns, whether Parallel HALCON processes an operatorunder mutual exclusion (‘true’) against itself or not. Here, a mutual exclusionmeans that the same operator may not run twice or more at the same time; for example,there will only run one instance of ÔØ ØÑÔÐØ at a time, whereas other operatorsmay run concurrently to ÔØ ØÑÔÐØ.An exclusively processed operator is always processed without any parallelization by themain HALCON thread/process.If no subslot ÔÖÓ×× ÑÙØÙÐ is filled in with an operator, it is assumed that the operatorneeds no mutual exclusion (“optimistic” assumption).ÔÖÓ×× ÐÓÐÐÝ ØÖÙ¸Ð×This subslot of ÔÖÐÐÐÞØÓÒ assigns, whether an operator must be processed locallyHALCON Extension Package Interface / 2000-11-16

2.2. EXTENDED OPERATOR DESCRIPTION 23(‘true’) by a program thread, or whether it may called by any (“external”) thread withoutproblems. The slot is mainly important when programming multithreaded applicationsunder Windows NT and Windows 2000. Here, there exists a direct mapping betweenprogram threads and graphical elements, such as windows, dialog boxes or button controls.In short, a graphical element only exists in the context of its associated thread. Thiscan cause severe problems, for example, hang the application, if another thread tries toperform user interactions via graphical elements which belong to other threads. For example,troubles might occur under Windows NT/ 2000, if one thread opens a window viaÓÔÒ ÛÒÓÛ and another thread tries to get input from this window via ÖÛ ÖÐ.As it is not always obvious for all operators, whether they work with critical (graphical)elements or not, the slot ÔÖÓ×× ÐÓÐÐÝ was introduced. If ÔÖÓ×× ÐÓÐÐÝ isset to ‘true’, this signals the programmer that the corresponding operator must be usedcarefully within multithreaded Windows NT/ 2000 applications. The most simple wayto avoid any problems with such operators is to process them all under mutual exclusionwithin the main thread of the program.As a side effect, Parallel HALCON processes an operator without parallelization regardlessthe settings of the subslots ÑØÓ and ÓÑÒ ×ÔÐØ,ifÔÖÓ×× ÐÓÐÐÝ is set to‘true’. This avoids problems with ‘local’ operators and multithreading and makes sensebecause ‘local’ operators normally are responsible for graphical interaction and thus arenot suitable for parallelization.If no subslot ÔÖÓ×× ÐÓÐÐÝ is filled in with an operator, it is assumed that the operatormust be processed “locally” (“pessimistic” assumption). However, this subslot should befilled in in any case, because it contains a very useful information for programmers ofmultithreaded applications.ÑØÓ ÒÓÒ¸×ÔÐØ ØÙÔи×ÔÐØ ÒÒи×ÔÐØ ÓÑÒThis subslot of ÔÖÐÐÐÞØÓÒ can contain one or more of the strings above andspecifies, which type of (automatic) parallelization the operator is suitable for:¯ ×ÔÐØ ØÙÔÐ: Parallel HALCON does not automatically parallelize the operator.¯ ×ÔÐØ ØÙÔÐ: Parallel HALCON parallelizes the operator by splitting every inputimage tuple into several subsets of the tuple; the tuple subsets are then processed inparallel.¯ ×ÔÐØ ÒÒÐ: Parallel HALCON parallelizes by splitting every multichannel(input) image into several subsets of the channels; the subsets are then processedin parallel.¯ ×ÔÐØ ÓÑÒ: Parallel HALCON parallelizes by splitting the domain of everyinput image into several parts; the parts are then processed in parallel.If ÑØÓ is set to anything other but ‘none’, the parameter slot Ó×Ø× ÛØ must befilled in for every input control parameter and the parameter slot ÔÓ×ØÔÖÓ××Ò mustbe filled in for every output control parameter of the operator (see page 29)!If ÑØÓ is set to ‘split domain’, the slot ÓÑÒ ×ÔÐØ (see below) must also be setcorrectly and may not be omitted !If the slot ÔÖÓ×× ÐÓÐÐÝ is set to ‘true’, ÑØÓ should be set to ‘none’, because theoperator won’t be parallelized then (see description of ÔÖÓ×× ÐÓÐÐÝ above).HALCON 6.0

24 CHAPTER 2. OPERATOR DESCRIPTION (’DEF’-FILES)Note that the slot ÑØÓ may contain any combination of the strings ‘split tuple’,‘split channel’, and ‘split domain’, because an operator may be parallelized by using anycombination of those three methods. However, if ‘none’ is specified with the slot ÑØÓ,no other string should be specified with it in order to keep the description consistent.If no slot ÑØÓ is filled in with an operator, it is assumed that the operator is not suitablefor being automatically parallelized (“pessimistic” assumption).ÓÑÒ ×ÔÐØ an unsigned integer valueThis subslot of ÔÖÐÐÐÞØÓÒ must (only) be set for operators that are suitable forbeing parallelized by splitting the domain of iconic input objects (i.e. slot ÑØÓ contains‘split domain’). For such operators the value of ÓÑÒ ×ÔÐØ assigns, whether the inputdomain may be split disjunctively (value ‘0’) or not. In the latter case the domain is splitinto several ÓÚÖÐÔÔÒ stripes (note, that the splitting of domain regions is alwaysdone row-wise).If the domain is split disjunctively, the value ( ¼) ofÓÑÒ ×ÔÐØ assigns the index([1..n]) of that input control parameter which determines the extent of the overlappingregions (in number of pixels) by its content. For example, for the operatorÐÑÒØ ÑÒ ÑÜ the extent of the overlapping regions depends on the height of thefilter mask. Therefore, the content of the second input control parameter (compare theoperator’s description in the Reference Manuals) directly determines the extent of theoverlapping regions. Thus, the slot ÓÑÒ ×ÔÐØ is set to ‘2’ for ÐÑÒØ ÑÒ ÑÜ.The example below shows the whole ÔÖÐÐÐÞØÓÒ slot for ÐÑÒØ ÑÒ ÑÜ.ÔÖÐÐÐÞØÓÒÔÖÓ××ÜÐÙ×ÚÐÝ Ð×ÔÖÓ××ÐÓÐÐÝ Ð×ÔÖÓ××ÑÙØÙÐ Ð×ÑØÓ×ÔÐØØÙÔи ×ÔÐØÒÒи ×ÔÐØÓÑÒÓÑÒ×ÔÐØ ¾If ÑØÓ contains ‘split domain’, the slot ÓÑÒ ×ÔÐØ must be filled in. In all othercases, the slot should be omitted!Though, we recommend to specify the whole slot ÔÖÐÐÐÞØÓÒ, it is also possible tocompletely leave it out in an operator’s description. In this case, it is assumed that the operatoris reentrant, i.e.itisnot processed under (complete or mutual) exclusion, and that it must beprocessed “locally”. The latter also means that no parallelization is used when processing theoperator. This assumption corresponds exactly to those which are used in the case of missingsingle subslots (see descriptions above).2.2.13 complexityThe slot ÓÑÔÐÜØÝ describes the complexity of the operation in terms of number of pointsalong a contour, the area of an image region etc.ÓÑÔÐÜØݺÒÐ×ÄØ °° Ø Ö Ó Ø ÒÔÙØ ÖÓÒºÓÑÔÐÜØÝ × °Ç´µ°ºÌÒ Ø ÖÙÒØÑHALCON Extension Package Interface / 2000-11-16

2.3. DESCRIBING THE PARAMETERS 252.2.14 exampleIt is possible to describe an example under the keyword ÜÑÔÐ in order to illustrate theusage of an operator. An extension of the keyword specifies the programming language ofthe example.ÜÑÔкØÖ×» ÄÓÓÒ ÓÖ ÖÓÒ× ÛØ Ø ÑØÖ »ÑÒÑ´ÁÑÅÒ¾¸¾µ ÝÒØÖ×ÓдÁѸÅÒ˸³Ðسµ ÓÒÒØÓÒ´ËÇØ×µºThe extension ºØÖ× denotes the image processing language Trias that uses a syntax basicallyequal to the notation within ÀÚÐÓÔ. Moreover, the extensions º and º·· can be used. Thetext of the example is processed unmodified, so it must not contain any L A TEX-special characters.The only exception is the semicolon that needs a prefixed backslash, because it would signalthe end of the example text otherwise. This must be considered especially for C- and C++examples.2.2.15 referencesThe slot ÖÖÒ× (not specified in the dyn threshold example) is used to insert referencesto literature into the documentation, e.g.,ÖÖÒ×ʺź ÀÖи úº ËÔÖÓ ÓÑÔÙØÖ Ò ÊÓÓØ Î×ÓÒ³³ÎÓк ½¸ ×ÓÒ¹Ï×ÐÝ ÈÙÐ×Ò ÓÑÔÒݸ ½¾º2.3 Describing the ParametersAgain, the definition of ÝÒ ØÖ×ÓÐ is used as an example. Every description of a singleparameter starts with the keyword ÔÖÑØÖ and contains several slots. A slot begins with acharacteristic keyword followed by a colon and is finished by a semicolon. All slots specifiedfor the parameters of an operator are accessible online within the HALCON system using theoperator Ø ÔÖÑ ÒÓ, see the Reference Manuals for details.HALCON 6.0

26 CHAPTER 2. OPERATOR DESCRIPTION (’DEF’-FILES)ÔÖÑØÖÇÖÁÑÒÔÙØÓØ×ÖÔØÓÒºÒÐ× ÁÑ ØÓ ×ÑÒغ×ÑØÝÔÑØÝÔÐ×ØÝظÒؾ¸ÒظÖÐÑÙÐØÚÐÙÓÔØÓÒÐÔÖÑØÖÌÖ×ÓÐÁÑ ÒÔÙØÓØ×ÖÔØÓÒºÒÐ× ÁÑ ÓÒØÒÒ Ø ÐÓÐ ØÖ×ÓÐ׺×ÑØÝÔÑØÝÔÐ×ØÝظÒؾ¸ÒظÖÐÑÙÐØÚÐÙÓÔØÓÒÐÔÖÑØÖÊÓÒÝÒÌÖ× ÓÙØÔÙØÓØ×ÖÔØÓÒºÒÐ× ËÑÒØ ÖÓÒ׺×ÑØÝÔÖÓÒÑÙÐØÚÐÙÓÔØÓÒÐÔÖÑØÖÇ×ØÒÔÙØÓÒØÖÓÐ×ÖÔØÓÒºÒÐ× Ç×Ø ØÓ ÌÖ×ÓÐÁѺ×ÑØÝÔÒÙÑÖØÝÔÐ×ØÒØÖ¸ÖÐÙÐØØÝÔ ÖÐÙÐØÚÐÙ º¼ÚÐÙ×½º¼¸ ¿º¼¸ º¼¸ º¼¸ ½¼º¼¸ ¾¼º¼¸ ¿¼º¼ÑÙÐØÚÐÙÐ×××ÖØÓÒ¹¾ Ç×Ø ²² Ç×Ø ¾Ó×Ø×ÛØ ¼ÔÖÑØÖÄØÖÒÔÙØÓÒØÖÓÐ×ÖÔØÓÒºÒÐ× ÜØÖØ Ðظ Ö ÓÖ ×ÑÐÖ Ö××ÑØÝÔ×ØÖÒØÝÔÐ×Ø×ØÖÒÙÐØØÝÔ ×ØÖÒÙÐØÚÐÙ ÐØÚÐÙÐ×ØÖ¸ÐظÕÙиÒÓØÕÙÐÑÙÐØÚÐÙÐ×Ó×Ø×ÛØ ¼The minimum of information needed for every parameter is its name and type, its default type,its semantic type, the number of values allowed (ÑÙÐØÚÐÙ), and, if the operator should beautomatically parallelized, the “costs weight” of input control parameters and the “postprocessing”of output control parameters, see below.HALCON Extension Package Interface / 2000-11-16

2.3. DESCRIBING THE PARAMETERS 272.3.1 NameÔÖÑØÖNameÒÔÙØÓظÓÙØÔÙØÓظÒÔÙØÓÒØÖÓиÓÙØÔÙØÓÒØÖÓÐThis defines the name and the class of a parameter. The parameters must be described in thesame order as in their definition within the header of the operator description.2.3.2 default typeÙÐØØÝÔÒØÖ¸Öи×ØÖÒOnly for control parameters! This slot specifies, what C-type to use in general. It must haveexactly one of the three above values.2.3.3 sem type×ÑØÝÔclass[.spec]This slot determines the semantics and specifies the class of data passed as parameters, whenusing an object-oriented language. Names of classes within the -file are only symbolic. Themapping to the actual class names is is provided by the HALCON compiler ÓÑÔ. HDevelopalso uses the semantic types, e.g., in order to provide specific inspection routines (like for framegrabber handles). For complex classes it must be defined by .spec, which aspect of the classis represented by the parameter. By this, one can pass complex objects that are described byseveral parameters of the C-procedure as one logical parameter.The following semantic types (classes) are availabe at the moment:¯ Iconic data (object parameters):– ÓØ (any iconic object: images, regions, XLDs)– Ñ (images)– ÖÓÒ (regions)– ÜÐ (any XLDs: lines in eXtended Line Description)– ÜÐ ÓÒØ, ÜÐ ÔÓÐÝ, ÜÐ ÔÖ, ÜÐ ÑÓ ÔÖ, ÜÐ ÜØ ÔÖ.¯ Elementary data (control parameters):– ÒÙÑÖ (unspecific)– ÒØÖ, ÖÐ, ×ØÖÒ– ÖÝÚÐ (gray value)– ÒÒÐ (channel number).¯ Handles (control parameters):– ÖÑ ÖÖHALCON 6.0

28 CHAPTER 2. OPERATOR DESCRIPTION (’DEF’-FILES)– Ж ÓÖ (OCR classifier)– ×ØÑØÓÒ (see the HALCON operator ÖØ ×Ø)– Ð×× ÓÜ (general classifier)– ÛÒÓÛº (HALCON window).¯ Arrays (control parameters):– ×ØÓÖѺÚÐÙ× (gray value histogram)– ×ØÖÙØÓÒºÚÐÙ× (distribution).¯ Geometric data (control parameters):– ÔÓÒغܸ ÔÓÒØºÝ (position)– ÜØÒغܸ ÜØÒØºÝ (dimensioning)– ÖкÒØֺݸ ÖкÒØֺܸ ÖкÖÙ× (circle)– ÐҺҺݸ ÐҺҺܸ ÐҺҺݸ ÐÒºÒºÜ (line)– ÖØÒкÓÖҺݸ ÖØÒкÓÖÒºÜ (rectangle: upper left corner),ÖØÒкÓÖÒֺݸ ÖØÒкÓÖÒÖºÜ (lower right corner) orÖØÒкÜØÒØºÜ ÖØÒкÜØÒØºÝ (expansion – as alternative to specifyingthe ¾ Ò corner)– ÖØÒоºÒØֺݸ ÖØÒоºÒØÖºÜ (rectangle with arbitrary orientation:center),ÖØÒоºÒÐºÖ (orientation – in radians),ÖØÒоºÛظ ÖØÒоºØ (half the size)– ÐÐÔ׺ÒØֺݸ ÐÐÔ׺ÒØÖºÜ (ellipse: centre),ÐÐÔ׺ÒÐºÖ (orientation – in radians),ÐÐÔ׺ÖÙ×½¸ ÐÐÔ׺ÖÙ×¾ (radii)– ÖºÒØֺݸ ÖºÒØÖºÜ (circle: center),ÖºÒÐºÖ (angle stretched by the circular arc – in radians),ֺҺݸ ÖºÒºÜ (starting point of circular arc¯ Numerical region descriptions (control parameters):– ÓÓÖÒØ׺ݸ ÓÓÖÒØ×ºÜ (coordinates)– ÓÒØÓÙֺݸ ÓÒØÓÙÖºÜ (points of a contour)– Óֺݸ Óֺܽ¸ Óֺܾ (runlength code)– ÔÓÐÝÓҺݸ ÔÓÐÝÓÒºÜ (polygoneal representation)– ҺҺݸ ҺҺܸ ÒºÓ (chain code).¯ Miscellaneous (control parameters):– ÒÐºÖ or Òк (angle in radians or degrees)– ÐÒѺÒÑ (file name).HALCON Extension Package Interface / 2000-11-16

2.3. DESCRIBING THE PARAMETERS 29Please note:¯ y-coordinates correspond to rows, x-coordinates to columns in the image.¯ Please use the above semantic types for characterizing parameters whenever they areapplicable.¯ For control parameters characterizing a composed object like a ÖÐ etc.: Please usethe specific order of parameters like indicated above.2.3.4 multivalueÑÙÐØÚÐÙØÖÙ¸Ð׸ÓÔØÓÒÐThis slot describes the number of values passed in a parameter: ‘true’ means that an array (tuple)of values must be passed. If ‘false’ is specified, exactly one value must be passed. ‘optional’allows both.All slots mentioned so far must appear in any extended operator description. Moreover, thefollowing optional slots are recommended to provide further information about parameters:2.3.5 costs weightÓ×Ø×ÛØan unsigned integer valueThis slot must only be used for input control parameters of operators which are suitable for beingautomatically parallelized (i.e. for operators for that the ÔÖÐÐÐÞØÓÒ subslot ÑØÓdoes not contain ‘none’; see page 23). Here, it assigns, whether the time for processing theoperator directly depends on the content (value) of the corresponding input control parameter. IfÓ×Ø× ÛØ is set to ‘0’, the duration of the operator processing does not directly depend onthe content of the corresponding input control parameter. In this case, the parameter will not betaken into account when Parallel HALCON decides, whether an operator should be parallelizedfor a given allocation of input parameters or not. This also means, that this parameter will not bechecked during the hardware training (compare the description of ÔÖ Û ÔÓØÒØÐin the Reference Manuals). This helps to speed up the training. If Ó×Ø× ÛØ containsa value greater than ‘0’, this assigns that there is a direct dependency between the contentof the corresponding input control parameter and the computation time of the operator. Inthis case, Parallel HALCON will take into account this parameter during its hardware check( ÔÖ Û ÔÓØÒØÐ) in order to determine its influence on the operator’s processingtime. Note that the slot Ó×Ø× ÛØ must be filled in for every input control parameter, if theoperator should be automatically parallelized, i.e. if the operator’s slot ÑØÓ does not contain‘none’ (see page 23).2.3.6 postprocessingÔÓ×ØÔÖÓ××ÒÒÓÒ¸ØÙÔиØÙÔÐÑÒ¸ØÙÔÐÑܸØÙÔÐÓÒظÒÒиÒÒÐÑÒ¸ÒÒÐÑܸÒÒÐÓÒظÓÑÒ¸ÓÑÒÑÒ¸ÓÑÒÑܸÓÑÒÓÒØHALCON 6.0

30 CHAPTER 2. OPERATOR DESCRIPTION (’DEF’-FILES)This slot must only be used for output control parameters of operators which are suitable for beingautomatically parallelized (i.e. for operators for that the ÔÖÐÐÐÞØÓÒ subslot ÑØÓdoes not contain ‘none’; see page 23). Here, ÔÓ×ØÔÖÓ××Ò specifies, which kind of postprocessingis used with the single result values of a parallel processed operator. If, for example,an operator is parallelized by splitting a tuple of iconic input objects and the single result valuesof the parallel processed operator must be put into one output control object again, the slotÔÓ×ØÔÖÓ××Ò should contain the keyword ‘tuple concat’ which means “concatenate resultvalues”. Or if an operator is parallelized by splitting the single channels of iconic input objectsand the overall result value is the minimum of the single result values of the parallel processedoperator, ÔÓ×ØÔÖÓ××Ò should contain the keyword ‘channel minimum’. Obviously, theslot ÔÓ×ØÔÖÓ××Ò can contain several strings in order to define different postprocessingsteps for different levels of parallelization (tuple, channel,anddomain); of course, there shouldonly be one string per level. If ‘none’ is specified (in this case, no other string should be specified),no postprocessing is done on every parallelization level. This means, that the overallresult value of the corresponding output control parameter is directly determined by the resultvalue of the first parallelized operator instance (e.g. the instance which worked on the first tupleelement).Alltogether, Parallel HALCON currently supports the following postprocessing steps:¯ ÒÓÒ: no postprocessing; adopt first value;¯ ØÙÔÐ : overall result value is the sum of the single result values of the tuple parallelization;¯ ØÙÔÐ ÑÒ: overall result value is the minimum of the single result values of the tupleparallelization;¯ ØÙÔÐ ÑÜ: overall result value is the maximum of the single result values of the tupleparallelization;¯ ØÙÔÐ ÓÒØ: overall result value is a tuple which contains all the result values of thetuple parallelization (“concatenation”);¯ ÒÒÐ : overall result value is the sum of the single result values of the channelparallelization;¯ ÒÒÐ ÑÒ: overall result value is the minimum of the single result values of the channelparallelization;¯ ÒÒÐ ÑÜ: overall result value is the maximum of the single result values of the channelparallelization;¯ ÒÒÐ ÓÒØ: overall result value is a tuple which contains all the result values ofthe channel parallelization (“concatenation”);¯ ÓÑÒ : overall result value is the sum of the single result values of the parallelizationondomainlevel;¯ ÓÑÒ ÑÒ: overall result value is the minimum of the single result values of the parallelizationon domain level;¯ ÓÑÒ ÑÜ: overall result value is the maximum of the single result values of the parallelizationon domain level;HALCON Extension Package Interface / 2000-11-16

2.3. DESCRIBING THE PARAMETERS 31¯ ÓÑÒ ÓÒØ: overall result value is a tuple which contains all the result values of theparallelization on domain level (“concatenation”);The example below shows the definition of ÔÓ×ØÔÖÓ××Ò for the operator ÖÙÐÖØÝ,which calculates the shape factor for the circularity (similarity to a circle) of input regions. IfÖÙÐÖØÝ is tuple parallelized the overall result is a tuple of values, of which the singleelements contain the “circularity” of the single input regions. Thus the postprocessing of thecorresponding output control parameter is assigned by ‘tuple concat’.ÔÖÑØÖÖÙÐÖØÝ×ÖÔØÓÒºÒÐ××ÑØÝÔØÝÔÐ×ØÙÐØØÝÔÑÙÐØÚÐÙ××ÖØÓÒÔÓ×ØÔÖÓ××ÒÓÙØÔÙØÓÒØÖÓÐÊÓÙÒÒ×× Ó Ø ÒÔÙØ ÖÓÒ´×µºÖÐÖÐÖÐÓÔØÓÒм ÖÙÐÖØÝ ²² ÖÙÐÖØÝ ½º¼ØÙÔÐÓÒØNote that the slot ÔÓ×ØÔÖÓ××Ò must be filled in for every output control parameter, if theoperator should be automatically parallelized, i.e. if the operator’s slot ÑØÓ does not contain‘none’ (see page 23).2.3.7 description×ÖÔØÓÒºÒÐ×L A TEX/Ascii-TextThis slot contains a short description of the parameter. The extension ºÒÐ× refersto a English description. In addition to that a German description might be given in×ÖÔØÓÒºÖÑÒ. For the syntax of L A TEX/Ascii-Text see section 2.4.2.3.8 type listThe slot ØÝÔ Ð×Ø is only used in connection with object parameters with ×Ñ ØÝÔ Ñand for control parameters.For images (×Ñ ØÝÔ Ñ):ØÝÔÐ×ØÒݸÝظÒؽ¸Òؾ¸ÒظÖиÝиÖØÓÒ¸ÓÑÔÐÜFor images this slot contains an enumeration of all supported pixel types. Note, that in manycases there will be more than one supported pixel type. Thus, ØÝÔ Ð×Ø is a list separated bycommas.For control parameters:ØÝÔÐ×ØÒØÖ¸Öи×ØÖÒFor control parameters this slot contains a list of all C-types allowed for the parameter.HALCON 6.0

32 CHAPTER 2. OPERATOR DESCRIPTION (’DEF’-FILES)2.3.9 default valueÙÐØÚÐÙDefault ValueThis slot defines the default value e.g., used by HDevelop to initialize the paramater in the operatorwindow. Suggesting default values can help the programmer to find suitable values of parameters.Generally, strings are unquoted in the description (not ³ØËØÖÒ³, butØËØÖÒ);exceptions: empty string (³³) and strings with special characters (³Ø ×ØÖÒ³).2.3.10 valuesÚÐÙ×List of some typical valuesThis slot contains a collection of possible values. This list does not have to be complete. It justsuggests some typical values the user might want to try.2.3.11 value listÚÐÙÐ×ØList of all valuesThis slot contains a complete list of all allowed values. So, if a parameter can hold only adiscrete number of specific values, ÚÐÙ Ð×Ø should be specified, otherwise ÚÐÙ× mightbe used to provide some typical values.2.3.12 value min, value maxÚÐÙÑÒÚÐÙÑÜNumberNumberInstead of a list an interval may be used to specify the range of allowed values for a parameter.The interval may be unlimited in one direction. The slot ÚÐÙ ÑÒ specifies the minimum ofthe allowed values, ÚÐÙ ÑÜ the maximum.2.3.13 step rec, step min, value function×ØÔÖ×ØÔÑÒÚÐÙÙÒØÓÒNumberNumberÐÒ¸ÐÓ¸ÕÙ¸ ...If a range of values is possible for a parameter it might be a useful information to specify asuitable step width (×ØÔ Ö) between distinct values to be tested. Based on this informationa user interface might generate a list of suggestions for parameter values. The correspondingminimum reasonable step width can be provided by ×ØÔ ÑÒ. The step width can also bemodified by specifying a function in the slot ÚÐÙ ÙÒØÓÒ.HALCON Extension Package Interface / 2000-11-16

2.3. DESCRIBING THE PARAMETERS 332.3.14 value numberÚÐÙÒÙÑÖboolean expressionThis slot contains a boolean expression that determines how the number of passed or returnedvalues of a parameter is absolutely or relatively connected to the number of values in otherparameters or some absolute values. The operators and functions listed in table 2.1 may appearwithin the expression.Group Symbol meaningUnary Operators logical NOT¹ negationBinary Operators ²² logical AND logical OR equal not equal greater greater or equal less less or equal· sum¹ difference multiplication» division (DIV)± rest of division (MOD)Functions Ó true, if oddÚÒ true, if evenÐ binary logarithmÐÒØ lengthÒÙÑÖ number of values (only for ××ÖØÓÒ)ÛØ (image-)widthØ (image-)heightExamples:Table 2.1: Operators and functions used for the slots ÚÐÙ ÒÙÑÖ and ××ÖØÓÒ.ÈÖѽ ÈÖѾ ²² ÈÖѾ ¼This means that the same number of values and at least one value must be passed withparameter 1 and parameter 2.ÈÖѾ ¿This means that exactly three values must be passed with parameter 2.For output parameters this can be seen as an assertion. This may also refer to input parameters,e.g.: ÊÓÒÇÙØ ÊÓÒÁÒ in connection with the HALCON operator select shapeexpresses the fact that the number of output regions does not exceed the number of input regions.HALCON 6.0

34 CHAPTER 2. OPERATOR DESCRIPTION (’DEF’-FILES)2.3.15 assertion××ÖØÓÒboolean expressionThis slot contains a boolean expression that determines how the passed or returned values ofparameters are absolutely or relatively connected to the values of other parameters or someabsolute values. The same expressions may appear as described above for ÚÐÙ ÒÙÑÖ, seetable 2.1.Examples:ÈÖѽ ÈÖѾ ²² ÈÖѾ ¼This means that parameter 1 and 2 must have the same value and this value is greater than0.¼ ÈÖѾ ²² ÈÖѾ ¾This means that parameter 2 must have a value between 0 and 255.ÈÖѽ ÒÙÑÖ´ÁÑÁÒµThis means that the value of parameter 1 must be less or equal the number of input images.ÈÖѾ ÛØ´ÁÑÁÒµ ²² ÈÖѾ ¼ ²² Ó´ÈÖѾµThis means that the value of parameter 2 must be between 0 and the width of the inputimage and must be an even number.2.3.16 multichannelÑÙÐØÒÒÐØÖÙ¸Ð׸ÓÔØÓÒÐThis slot is only used in connections with image objects. It contains an assertion about thenecessary or supported number of channels of an image. If set to Ð×, the processing is doneonly on the first channel (all others are ignored), if set to ØÖÙ, a multichannel image must bepassed. ÓÔØÓÒÐ specifies operators that can work on more than one channel but can alsowork on only one channel as well.2.4 Text in -filesWithin a -file the semicolon (;) is used to separate the single slots. So, when using a semicolonwithin a text, it must be quoted with a backslash ().-files are not only used to create interface code, but also allow the generation of the manuals,the HTML documentation, and the ÐÔ files used to access operator knowledge via HALCONoperators like Ø ÓÔÖØÓÖ ÒÓ. For the online help and the HTML files an ASCII versionof each text is needed, whereas the manuals are produced compiling a L A TEX-file generated fromthe -files. To avoid the necessity of writing two text blocks for one operator (ASCII andL A TEX), both versions are generated by using one text. Therefore, the following conventionsmust be observed:HALCON Extension Package Interface / 2000-11-16

2.4. TEXT IN ’DEF’-FILES 35Umlauts: All German umlauts are written in the L A TEX-typical notation: , ..., Í, ×.Quotation marks: There are two kinds of quotation marks’string’: This notation signals that the quoted text is a string as used within programminglanguages. So ÓÑÔ treats ³×ØÖÒ³ as a string-parameter.“Text”: This notation must be used in all other cases, particularly when quoting a wordor text segment because of its content. So ÓÑÔ treats ÌÜس³ as a quoted sectionof a text. Please do not forget or permute the quotation marks (starting with andending with ³³).Underscores: An underscore can be used without the necessity of prefixing a backslash asnecessary in L A TEX() so that the text is easier to read. The backslashes are insertedautomatically in the generated L A TEX-version of the text. Note, that this mechanism isonly active within the ASCII part of the text.Backslash: All backslashes () within the text are ignored while generating the ASCII version.So the L A TEX-linefeed-symbol () can be used without any problems.Tilde: To use the tilde (e.g. as symbol for negation: ×Ø´³ÐÖ³µ), the followingspecial notation must be used for the L A TEX-text: ×Ø´³ßÐÐÖ³µ.Formulas: Short formulas can be bracketed by dollar symbols ($) just as in L A TEX. Thesesymbols are ignored for the ASCII version of the text.To set an index of one character (e.g. )L A TEX allows to simply write °°. This is notpossible here, because of the special underscore handling. Therefore, any index must bewritten exactly as any longer index within L A TEX: ßÐ.HALCON : The string HALCON is generated by ÀÐÓÒ. Note, that in the PostScript filesderived from the generated L A TEX version of the -files, no space is generated after thestring HALCON. Thus, if you do not want to start the next character/string without ablank, that is concatenated to the string HALCON, you should use ÀÐÓÒ instead. So“ÀÐÓÒ ” results in “HALCON XYZ” and “ÀÐÓÒ ” results in “HALCONXYZ”. With the ASCII version all backslashes are ignored (see above).Names of parameters and operators: Any reference to HALCON parameters oroperators has to be written as ÈÖÊparameter name, respectively asÇÔÊoperator name. These keywords and the brackets are ignored, whengenerating the ASCII version so that only parameter name or operator name remainsin the ASCII file. For the HTML documentation hyper links are generated from thesereferences.Parameter values: A specific value for a parameter should be written asÎÐÊparameter value . For example, the parameter ÈÖÊLightDark ofthe operator ÇÔÊdyn threshold can hold one of the values ÎÐÊ’light’,ÎÐÊ’dark’, or ÎÐÊ’equal’. The keyword ÎÐÊ and the brackets areignored, when generating the ASCII version so that only parameter value remains in theASCII file.Other L A TEX commands: If you would like to use additional L A TEX command within a text segment,two versions of this segment must be provided – one for ASCII (with signallingHALCON 6.0

36 CHAPTER 2. OPERATOR DESCRIPTION (’DEF’-FILES)the start of the ASCII section) and another as pure L A TEX text (with Ð starting the L A TEXversion and ending the special section). This technique is in particular necessary fortables and larger formulas.Example:Ó Ñ · ÈÖÊßÇ×ØÐÐ ßÓÐ ßÑÐ · ÈÖÊßÇ×ØÐ ℄This parenthesis can also be used for only one of the two text types:ººº ØÜØ ØÜØ Ð ËÔÐÄØÜÓÑÑÒ ØÜØ ØÜØ ºººHALCON Extension Package Interface / 2000-11-16

Chapter 3Style Guide for ProgrammingThe following chapter contains some recommendations for implementing new HALCON operators.They aim on portable code that should be easy to understand for other HALCONprogrammers. One of the major topics is the memory management discussed in section 3.2.3.1 Basic Numeric Data TypesThis section describes the usage of basic numeric data types. Since C makes no assumptionabout the size of integers, the following types have been defined:Type NameÁÆ̽ÀÌÍÁÆ̽ÁÆ̾ÍÁÆ̾ÁÆÌÍÆÌÁÆÌ ÍÁÆÌ ÁÆÌÍÁÆÌSize/Range of Valuesone byte with signone byte, unsignedthesameasÀÌtwo bytes with sign (generally ×ÓÖØ)two bytes, unsignedfour bytes with signfour bytes, unsignedfour or eight bytes with signfour or eight bytes, unsignedAt least two, maximal eight bytes with signAt least two, maximal eight bytes, unsignedUsing these types ensures the portability of HALCON operators.3.1.1 Local Variables / Temporary ResultsTypes and sizes for local variables (no arrays) should be handled as follows:37

38 CHAPTER 3. STYLE GUIDE FOR PROGRAMMINGType Size C-Data Type1 byteÁÆÌ or ÍÁÆÌ2 byteInteger3 byteÁÆÌ or ÍÁÆÌ 4 byteFloating-point Number ÓÙÐ3.1.2 Procedure ParametersParameters of procedures should be of the following types within HALCON:Type Size C-Data TypeInteger1 byte2 byteÁÆÌ3 byte4 byteÁÆÌ Floating-point Number ÓÙÐStructure pointer3.1.3 ArraysFor arrays or structures (i.e. larger sets) always the smallest possible data type should be used.Type Size C-Data Type1 byte ÁÆ̽2 byte ÁÆ̾ oder ÍÁÆ̾Integer3 byteÁÆÌ oder ÍÁÆÌ4 byte4 byte ÐÓØFloating-point Number8 byte ÓÙÐStructurepointer3.2 Memory ManagementHALCON provides a sophisticated memory management not only to handle iconic objects,but also to allocate/deallocate arbitrary data. Please use the corresponding HALCON ExtensionPackage Interface routines exclusively. Do not create/destroy memory blocks on the heapwith the standard routines of the operating system (like ÑÐÐÓ and Ö) since the HALCONroutines provide a caching mechanism, garbage collection for temporary data, and debuggingfacilities.We strongly recommend not do use global variables within HALCON operators. If they arenot avoidable at least make them ×ØØ within the file of usage. If even this is undesirablegroup them into structures to keep the number of global names small.HALCON Extension Package Interface / 2000-11-16

3.2. MEMORY MANAGEMENT 39If you use ×ØØ variables, be aware that they are shared between multiple threads. Pleasenote, that Parallel HALCON uses multithreading to exploit multi-processor hardware (see themanual Getting Started with HALCON for more information). This means, that if you useParallel HALCON, either by linking the corresponding libraries to your program or by usingParallel HDevelop, multiple instances of your code will actually share all the static variables!Furthermore, be aware that large static arrays consume a lot of memory – keep in mind thatHALCON is a very large system enfolding hundreds of operators.3.2.1 Temporary DataNamesÀÐÐÓÌÑÔ¸ ÀÖÌÑÔ¸ ÀÖÆÌÑÔ¸ ÀÖÍÔÌÓÌÑÔ¸ ÀÖÐÐÌÑÔ¸ÀÐÐÓÊÄÌÑÔ¸ ÀÐÐÓÊÄÆÙÑÌÑÔ¸ ÀÖÊÄÌÑÔSynopsisÒÐÙ ÀÐÓÒºÀÖÖÓÖ ÀÐÐÓÌÑÔ´ÀÖÖÓÖ ÀÖÌÑÔ´ÀÖÖÓÖ ÀÖÆÌÑÔ´ÀÖÖÓÖ ÀÖÍÔÌÓÌÑÔ´ÀÖÖÓÖ ÀÖÐÐÌÑÔ´ÀÖÖÓÖ ÀÐÐÓÊÄÌÑÔ´ÀÖÖÓÖ ÀÐÐÓÊÄÆÙÑÌÑÔ´ÀÖÖÓÖ ÀÖÊÄÌÑÔ´ÀÔÖÓÒÐ ÔÖÓÒиÚÓÔÓÒØÖ¸×ÞØ ×ÞµÀÔÖÓÒÐ ÔÖÓÒиÚÓÔÓÒØÖµÀÔÖÓÒÐ ÔÖÓÒиÁÆÌÒÙѵÀÔÖÓÒÐ ÔÖÓÒиÚÓÔÓÒØÖµÀÔÖÓÒÐ ÔÖÓÒеÀÔÖÓÒÐ ÔÖÓÒиÀÖÐÖÓÒ ÖÓÒµÀÔÖÓÒÐ ÔÖÓÒиÀÖÐÖÓÒ ÖÓÒ¸×ÞØ ÐÒµÀÔÖÓÒÐ ÔÖÓÒиÀÖÐÖÓÒ ÖÓÒµFigure 3.1: HALCON stack management for temporary data.HALCON 6.0

40 CHAPTER 3. STYLE GUIDE FOR PROGRAMMINGFig. 3.1 shows HALCON routines to allocate/deallocate temporary memory blocks. Internally,those blocks are stored within a stack. Therefore, the memory must be deallocated in reverseorder of it’s allocation. There are two major advantages of using these routines:¯ The underlying stacks are initialy allocated as large blocks of memory. Thus, the memoryis not fragmented and memory allocation is fast for subsequent calls.¯ An automatic garbage collection deallocates all temporary data after a HALCON operatorwas executed. This is especially of importance in case of an error during the execution ofthe operator (otherwise, the data should have been deallocated anyway).ÀÐÐÓÌÑÔ is used for arbitrary data with the corresponding deallocation routine ÀÖÌÑÔ.ÀÖÆÌÑÔ deallocates the last ÒÙÑ blocks allocated by ÀÐÐÓÌÑÔ, ÀÖÍÔÌÓÌÑÔ deallocatesall recently allocated blocks up to (and including) the specified block. ÀÖÐÐÌÑÔ deallocatesall temporary blocks.ÀÐÐÓÊÄÌÑÔ and ÀÐÐÓÊÄÆÙÑÌÑÔ are convenience routines that are based on ÀÐÐÓÌÑÔ.ÀÐÐÓÊÄÌÑÔ allocates as much memory as is necessary for the largest region actuallystored in the HALCON data base (the minimal size is ÊÄ ÄÆÌÀ = 50000 chords).ÀÐÐÓÊÄÆÙÑÌÑÔ allows to determine the size of memory to be allocated by specifying thenumber of chords. Furthermore, ÀÐÐÓÊÄÌÑÔ and ÀÐÐÓÊÄÆÙÑÌÑÔ initialize the data structureÀÖÐÖÓÒ for the new region (see section 4.2 for a description of ÀÖÐÖÓÒ). Note, thatsince these routines are based on ÀÐÐÓÌÑÔ the corresponding memory blocks are interleavedwith the blocks allocated directly via ÀÐÐÓÌÑÔ. This has to be considered while deallocatingthe corresponding memory.Temporary data on arbitrary heap positionsThe temporary data management routines described so far use a stack. This is of advantageconcerning runtime, but it lecks flexibility if you do not want to deallocate memory in a fixedorder again. Therefore, HALCON also provides routines for allocating temporary memory onan arbitrary position of the heap, see Fig. 3.2. Memory blocks allocated by ÀÐÐÓÄÓÐ can bedeallocated by ÀÖÄÓÐ in an arbitrary order. However, similar to the stack-based temporarydata management, all these blocks are automatically deallocated at the end of a HALCONoperator. Again this mainly aims on preventing memory leaks in case of errors. As usual,the routine ÀÊÐÐÓÄÓÐ is used to allocate a new memory block with modified size whilepreserving the data of the original memory block. The latter is deallocated. So never try toaccess ÔÓÒØÖ subsequent to ÀÊÐÐÓÄÓÐ – use ÒÛ ÔÓÒØÖ exclusively.The convenience routines ÀÐÐÓÊÄÄÓÐ, ÀÐÐÓÊÄÆÙÑÄÓÐ, ÀÊÐÐÓÊÄÆÙÑÄÓÐ, andÀÖÊÄÄÓÐ are used for handling temporary region data based on ÀÐÐÓÄÓÐ. Otherwisetheir behaviour is similar to ÀÐÐÓÊÄÌÑÔ etc., see above. However, note that it ispossible to change the size of regions (i.e., the number of chords) using this set of routines(ÀÊÐÐÓÊÄÆÙÑÄÓÐ) since the underlying memory blocks are not allocated within the internalstacks.HALCON Extension Package Interface / 2000-11-16

3.2. MEMORY MANAGEMENT 41NamesÀÐÐÓÄÓи ÀÊÐÐÓÄÓи ÀÖÄÓи ÀÖÐÐÄÓиÀÐÐÓÊÄÄÓи ÀÐÐÓÊÄÆÙÑÄÓи ÀÊÐÐÓÊÄÆÙÑÄÓи ÀÖÊÄÄÓÐSynopsisÒÐÙ ÀÐÓÒºÀÖÖÓÖ ÀÐÐÓÄÓдÀÖÖÓÖ ÀÊÐÐÓÄÓдÀÖÖÓÖ ÀÖÄÓдÀÖÖÓÖ ÀÖÐÐÄÓдÀÖÖÓÖ ÀÐÐÓÊÄÄÓдÀÖÖÓÖ ÀÐÐÓÊÄÆÙÑÄÓдÀÔÖÓÒÐ ÔÖÓÒи×ÞØ ×Þ¸ÚÓÔÓÒØÖµÀÔÖÓÒÐ ÔÖÓÒиÚÓÔÓÒØÖ×ÞØ ×Þ¸ÚÓÒÛÔÓÒØÖµÀÔÖÓÒÐ ÔÖÓÒиÚÓÔÓÒØÖµÀÔÖÓÒÐ ÔÖÓÒеÀÔÖÓÒÐ ÔÖÓÒиÀÖÐÖÓÒ ÖÓÒµÀÔÖÓÒÐ ÔÖÓÒиÀÖÐÖÓÒ ÖÓÒ¸×ÞØ ÐÒµÀÖÖÓÖ ÀÊÐÐÓÊÄÆÙÑÄÓд ÀÔÖÓÒÐ ÔÖÓÒиÀÖÐÖÓÒ ÖÓÒ×ÞØ ÐÒ¸ÀÖÐÖÓÒ ÒÛÖÓÒµÀÖÖÓÖ ÀÖÊÄÄÓдÀÔÖÓÒÐ ÔÖÓÒиÀÖÐÖÓÒ ÖÓÒµFigure 3.2: Temporary data on arbitrary heap positions.HALCON 6.0

42 CHAPTER 3. STYLE GUIDE FOR PROGRAMMING3.2.2 Permanent DataThe HALCON Extension Package Interface also provides routines for permanently allocating/deallocatingmemory (see Fig. 3.3 and 3.4). They work similar to the standard -proceduresÑÐÐÓ and Ö, but use a caching mechanism for small data blocks and provide additionaldebugging information.Note, that in contrast to ÀÐÐÓÄÓÐ memory allocated by ÀÐÐÓ is not deallocated automaticallyafter the execution of a HALCON operator. Thus, this routine should be used toallocate permanent data. For example, all the iconic objects stored in the HALCON data baseare allocated with this routine (see chapter 5 and 6).ÀÆÛÁÑ allocates raw image data inside 1 the data structure ÀÑ (see section 4.1) basedon ÀÐÐÓ. Furthermore, Ñ is initialized and the timestamp is set to the current time. Theimage matrix itself is initialized with ¼ if ³ÒØ ÒÛ Ñ³ has been set to ³ØÖÙ³ using theHALCON operator ×Ø ×Ý×ØÑ. This flag can be read inside HALCON using the ExtensionPackage Interface callÀÊδÔÖÓÒи ÀÁÒØÆÛÁѸ ²ÒØÒÛѵwith ÒØ ÒÛ Ñ of type ÀÇÇÄ and setÀÏÖØδÔÖÓÒи ÀÁÒØÆÛÁѸ ßÌÊ͸ÄËеThus, it is possible to buffer the global setting of this flag, set the flag to ÄË prior toÀÆÛÁÑ, and restore the old value afterwards, if you would like to prevent an initializationin any case.ÀÆÛÁÑÈØÖ does not allocate memory for the image data, but inserts the pointer Ø inthe ÀÑ structure Ñ instead. For this routine the initialization of the image data iscontrolled via the parameter ÒØÁÑ. Note, that you will encounter program crashes duringdeallocation of image objects, if you insert a memory block that has not been allocated viaÀÐÐÓ in the underlying ÀÑ structure (see e.g., ÀÈÙØÁÑ in section 5.4). However, inspecific situations (for example while doing a frame grabber integration) it might be desirableto use existing buffers allocated by some other procedures. In that case you have to provideyour own deallocation routine Í×ÖÐÖÈÖÓÙÖ using ËØÐÖÁÑ for the imagedata when creating a HALCON image object in a supply procedure:ÀÈÙØÁÑ´ÔÖÓÒиѸÄ˸²ÑݵÀÈ´ËØÐÖÁÑ´ ÔÖÓÒиÑݸ´ÖÁÑÈÖÓµÍ×ÖÐÖÈÖÓÙÖµµwhere ÖÁÑÈÖÓ is defined asØÝÔ ÚÓ ´ÖÁÑÈÖÓµ´ÚÓ Ñѵthat means, the deallocation routine has got one parameter of type ÚÓ and no return value. Ifyou pass a ÆÍÄÄ pointer instead of Í×ÖÐÖÈÖÓÙÖ the image data will not be deallocated1 So ÀÆÛÁÑ does not allocate memory for the ÀÑ structure itself.HALCON Extension Package Interface / 2000-11-16

3.2. MEMORY MANAGEMENT 43NamesÀÐÐÓ¸ ÀÊÐÐÓ¸ ÀÖ¸ ÀÆÛÁѸ ÀÆÛÁÑÈØÖ¸ÀÐÐÓÄÓÒظ ÀÖÄÓÒØSynopsisÒÐÙ ÀÐÓÒºÀÖÖÓÖ ÀÐÐÓ´ÀÖÖÓÖ ÀÊÐÐÓ´ÀÔÖÓÒÐ ÔÖÓÒи×ÞØ ×Þ¸ÚÓÔÓÒØÖµÀÔÖÓÒÐ ÔÖÓÒиÚÓÔÓÒØÖ×ÞØ ×Þ¸ÚÓÒÛÔÓÒØÖµÀÖÖÓÖ ÀÖ´ ÀÔÖÓÒÐ ÔÖÓÒиÚÓÔÓÒØÖµÀÖÖÓÖ ÀÆÛÁÑ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÑ Ñ¸ÁÆÌÒ¸ÁÆÌÛظÁÆÌصÀÖÖÓÖ ÀÆÛÁÑÈØÖ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÑ Ñ¸ÁÆÌÒ¸ÁÆÌÛظÁÆÌظÚÓظÀÇÇÄÒØÁѵÀÖÖÓÖ ÀÐÐÓÄÓÒØ´ ÀÔÖÓÒÐÀÓÒØ×ÞØÔÖÓÒиÓÒظÒÙÑÔÓÒØ×µÀÖÖÓÖ ÀÖÄÓÒØ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÓÒØÓÒصFigure 3.3: General memory management within HALCON.during the deallocation of the HALCON image object containing Ñ. Note, that this mightlead to a memory leak. Note further, that inserting image data in HALCON image objects usingÀÆÛÁÑÈØÖ can cause undesirable side effects: By overwriting the underlying data youHALCON 6.0

44 CHAPTER 3. STYLE GUIDE FOR PROGRAMMINGmight implicitly change one or more HALCON objects. Be aware that you have to take careabout such problems, if you decide not to use the standard HALCON memory management(that is ÀÆÛÁÑ).For both ÀÆÛÁÑ and ÀÆÛÁÑÈØÖ the pixel type of the raw data within Ñ is specifiedby the parameter Ò. Please see Fig. 4.2 on page 50 for the supported values.ÀÐÐÓÄÓÒØ allocates an XLD contour 2 of type ÀÓÒØ (see section 4.3) including memoryfor ÒÙÑ ÔÓÒØ× contour points. Internally this routine is based on ÀÐÐÓ. ÀÖÄÓÒØ isused to deallocate a contour again (inluding all the points and all attributes defined for ÓÒØ,see page 53).NamesÀÐÐÓÊĸ ÀÐÐÓÊÄÆÙѸ ÀÊÐÐÓÊÄÆÙѸ ÀÖÊÄSynopsisÒÐÙ ÀÐÓÒºÀÖÖÓÖ ÀÐÐÓÊÄ´ÀÖÖÓÖ ÀÐÐÓÊÄÆÙÑ´ÀÔÖÓÒÐ ÔÖÓÒиÀÖÐÖÓÒ ÖÓÒµÀÔÖÓÒÐ ÔÖÓÒиÀÖÐÖÓÒ ÖÓÒ¸×ÞØ ÐÒµÀÖÖÓÖ ÀÊÐÐÓÊÄÆÙÑ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÖÐÖÓÒ ÖÓÒ×ÞØ ÐÒ¸ÀÖÐÖÓÒ ÒÛÖÓÒµÀÖÖÓÖ ÀÖÊÄ´ÀÔÖÓÒÐ ÔÖÓÒиÀÖÐÖÓÒ ÖÓÒµFigure 3.4: General memory management for region data.The convenience routines ÀÐÐÓÊÄ, ÀÐÐÓÊÄÆÙÑ, ÀÊÐÐÓÊÄÆÙÑ, and ÀÖÊÄ (seeFig. 3.4) are used for handling permanent region data based on ÀÐÐÓ. Otherwise their behaviouris similar to ÀÐÐÓÊÄÌÑÔ etc., see page 40. Note that it is possible to change the sizeof regions (i.e., the number of chords) using ÀÊÐÐÓÊÄÆÙÑ.2 In contrast to ÀÆÛÁÑ and ÀÆÛÁÑÈØÖ ÀÐÐÓÄÓÒØ also allocates memory for the structure ÀÓÒØitself, not only for the data inside that structure.HALCON Extension Package Interface / 2000-11-16

3.3. STRUCTURING PROGRAMS 453.2.3 DebuggingThe HALCON memory management provides debugging mechanisms. Every time a memoryblock is deallocated a couple of consistency checks is performed automatically. Moreover, theconsistency of memory blocks can be checked for debugging reasons at any time using specificExtension Package Interface routines, see Fig. 3.5.NamesÀÌ×ØÅѸ ÀÌ×ØÈØÖ¸ ÀÌ×ØÐÐÌÑÔ¸ ÀÌ×ØÌÑÔSynopsisÒÐÙ ÀÐÓÒºÀÖÖÓÖ ÀÌ×ØÅÑ´ÚÓµÀÖÖÓÖ ÀÌ×ØÈØÖ´ ÚÓ ÔÓÒØÖµÀÖÖÓÖ ÀÌ×ØÐÐÌÑÔ´ ÀÔÖÓÒÐÔÖÓÒеÀÖÖÓÖ ÀÌ×ØÌÑÔ´ ÀÔÖÓÒÐ ÔÖÓÒиÚÓÔÓÒØÖµFigure 3.5: HALCON memory management: Check of consistency.ÀÌ×ØÅÑ checks all the memory allocated with ÀÐÐÓ or ÀÐÐÓÄÓÐ, whereas ÀÌ×ØÈØÖchecks only the specified memory block. Similar to that ÀÌ×ØÐÐÌÑÔ checks all the memoryallocated via ÀÐÐÓÌÑÔ and ÀÌ×ØÌÑÔ checks the specified block. With any failure of theconsistency check, the routines return an error number (À ÊÊ ÁÅ – inconsistent memory).Furthermore, if the global variable ÀÓÄÓÛÖÖÓÖ is set to ÌÊÍ, they display a description of theerror either on ×ØÖÖ (UNIX) or within an alert box (Windows NT/ 2000). This variable canbe set in an application with the operator ×Ø ×Ý×ØÑ´Ó ÐÓÛ ÖÖÓÖ¸ØÖÙ»Ð×µor used directly inside the newly written operator.3.3 Structuring ProgramsHALCON operators are typically implemented by at least two routines: one procedure (supplyprocedure) receives/unpacks all input data and checks it’s consistency. Afterwards it calls theaction procedure that performs the image processing. In some cases it might be convenient toimplement several action procedures dependent on special parameter values or pixel types ofimage data. Generally, these steps are performed within a loop over all input objects that mayinclude further loops over different parameter values and over all image channels. The resultsare collected and finally returned to the HALCON interface to the application.HALCON 6.0

46 CHAPTER 3. STYLE GUIDE FOR PROGRAMMINGSupply procedures are of type ÀÖÖÓÖ and have only one parameter (a handle of typeÀÔÖÓ ÒÐ for instances of HALCON operators or HALCON threads). Do not forget toreturn an appropriate value at the end of every supply procedure (standard value: À ÅË ÌÊÍ)and every action procedure (standard value À ÅË ÇÃ).Typically, action procedures perform the image processing itself. They should return an errorcode of type ÀÖÖÓÖ as well. It is convenient to implement an action procedure for each pixeltype of image data.3.4 Name Conventions for ProceduresTo ease the interpretation of program code, HALCON introduces some conventions for procedurenames. The most important ones are summarized in the following section.The names of action procedures typically begin with “ÁÈ” (image processing procedure), “ÁÇ”(input/output procedure), or “” (data base procedure). The rest of the name describes thetask performed by the procedure (in english language, beginning with a capital letter). In caseof filters an additional token might be inserted between these two parts of the name encodingthe pixel type(s) of images to be processed, e.g., “”(ÀÌ), “Á”(INT4)or“” (float).Examples:ÁÈÄÓÛÔ×ÁÈÁÌÖ×ÓÐÁÇ×ÔÊÓÒØÌÙÔÐBasic routines performing a small task that might be used by many other routines should startwith “À” (for Help). The leading “H” should be followed by a string encoding the data theroutine works on, e.g., “ÊÄ” for an auxiliary routine processing region data, or “Ä” for routinesworking on XLDs.Examples:ÀÊÄÍÒÓÒÀÄÓÒØÄÒÀÄÓÒØÊÖ××Names of supply procedures start with “” (this stands for Core). The rest is determined bythe name of the underlying action procedure (if there is only one). If there are several actionprocedures whith names differing only by the symbols for different pixel types, the pixel typeis left out in the name of the supply procedure.Examples:ÁÈÄÓÛÔ×ÁÈÌÖ×ÓÐÁÇÇÔÒÏÒÓÛ3.5 Input / OutputExcept explicit IO routines HALCON procedures should not contain any input/output commands,especially no ÔÖÒØ commands. Any interaction should be done either via parametersHALCON Extension Package Interface / 2000-11-16

3.6. ERROR HANDLING 47or via Extension Package Interface in-/output procedures. Error messages should be encodedby proper error numbers returned by the procedure (see next section).3.6 Error HandlingError messages are represented by integer constants, the error numbers of type ÀÖÖÓÖ. Ifanerror occurs, the corresponding error number should be returned by the procedure.The file ±ÀÄÇÆÊÇÇ̱ÒÒÐÙÒÀÓÒ×غ contains predefined error messages for all typicalerrors, see also appendix A. But it may happen that none of them fits an error occurring in a new,user-defined operator. So the user is allowed to define new numbers that should be greater than10 000 to avoid re-using an already allocated number or a number reserved for future extensionsof the HALCON system. If the user-defined operator returns a user-defined error, the error willbe reported asÆÓ ÖÖÓÖ Ñ×× ÚÐÐ ÓÖ Ø× ÖÖÓÖ Ó ´ÖÖÓÖ ÒÙÑÖµ ºIn order to provide user-defined errors with error messages, the functionÀÖÖÓÖ ÀËØÖÖÌÜØ´Ö ÖÖÓÖØÜصcan be called immediately before the operator returns the error code with ÖØÙÖÒ ÀÊÊ. Inthis case the error message ÖÖÓÖØÜØ will be displayed by the next 3 call of the HALCONoperator Ø ÖÖÓÖ ØÜØ.Error numbers are specified via Ò and are called À ÊÊ .Examples:ÀÊÊÏÁÈƽ » ÛÖÓÒ ÒÙÑÖ Ó ÚÐÙ× Ò ÒÔÙØ ÓÒØÖÓÐ »» ÔÖÑØÖ ½ »ÀÊÊÏÁÈο » ÛÖÓÒ ÔÖÑØÖ ÚÐÙ ´ÓÒØÖÓÐ ÔÖѺ ¿µ »ÀÊÊÏÁÈ̾ » ÛÖÓÒ ØÝÔ Ó ÚÐÙ× ´ÓÒØÖÓÐ ÔÖѺ ¾µ »ÀÊÊÏÁÇƽ » ÛÖÓÒ ÒÙÑÖ Ó ÓØ× Ò ÒÔÙØ ÓØ »» ÔÖÑØÖ ½ »ÀÊÊÏÁÌ » ÛÖÓÒ Ñ ØÝÔ »ÀÅËÁÄ » ÔÖÓÙÖ Ð »ÀÅËÌÊÍ » ÒÓ ÖÖÓÖ ´×ÙÔÔÐÝ ÔÖÓÙÖµ »ÀÅËÇà » ÒÓ ÖÖÓÖ ´ÒÝ ÓØÖ ÔÖÓÙÖµ »All HALCON procedures return an error code. So this code has to be checked after calling anyHALCON procedure. This is done by using the following macro to call a procedure:ÀÈ´µIt checks the return value and exits the actual procedure if an error occurred (a detailed descriptionof the macro is given in the section 5.6.1). Please note, that some of the ExtensionPackage Interface macros described in chapter 5 and 6 (e.g. ÀØÈÖ) perform similar testsautomatically and return a proper error code implicitly.3 Within this call the error text is reset to “No error message available ... ” again to ensure that the user-definederror text is up to date.HALCON 6.0

48 CHAPTER 3. STYLE GUIDE FOR PROGRAMMING3.7 Notes on Image Processing Operators¯ HALCON images are variable in their size (format). Therefore, no constants should beused for image formats (except Å ÇÊÅÌ for the maximum format). The actual formatof an image can be extracted from the structure ÀÑ (cf. Fig. 4.1).¯ Notice that more than one pixel type may occur, when performing gray value operations.An operator should be able to work on all of them, see also the discussion in section 6.1.3.If an operator can only process a reduced set of types, this can be specified in the -filewith ØÝÔ Ð×Ø (cf. page 31). An operator should reject all images that it can not processby returning À ÊÊ ÏÁÌ – wrong image type.¯ In many cases an operator might receive more than one iconic object as input, i.e. thesupply procedure must contain a loop over all iconic objects (e.g., using ÀÐÐÊ andÀÐÐËÑ described in section 6.1 or ÀÐÐÇ in section 5.3.1). This is true for regionsas well as images or XLDs. Furthermore, images may contain more than one channel. Soa second loop over all channels (components) within an image is needed (see ÀÐÐÓÑÔ,section 5.3.2).¯ All procedures should only work within the image’s area of definition, especially whenperforming feature extraction, filter or segmentation tasks.HALCON Extension Package Interface / 2000-11-16

Chapter 4HALCON Data TypesThe HALCON Extension Package Interface provides special data types to handle iconic objects.All iconic objects in the application layer are represented by a key refering to the HAL-CON data base. The internal structure is hidden from the HALCON user. However, using theExtension Package Interface it is possible to work directly on the data structures for images,regions, and XLDs. Special macros can be used to access the internal representation of suchan object. Furthermore, data structures for contol parameters are provided. All data types describedin the following sections are defined in the files ±´ÀÄÇÆÊÇÇ̵»ÒÐÙÒÁÈØÝÔº±and ±´ÀÄÇÆÊÇÇ̵»ÒÐÙÒÀ׺±.4.1 Pixel Data (ÀÑ)Gray value images are represented by a rectangular image matrix. Several matrices (calledcomponents) can be combined to a multi-channel image . Each channel can be accessed separately,i.e. the components are not interleaved. The structure ÀÑ contains size, pixel type,and pixel data of one component. Furthermore, a time-stamp is included. Fig. 4.1 shows thecorresponding type declaration.The maximum for ÛØ and Ø (Å ÇÊÅÌ) is currently set to 32768. The origin ofan image matrix is at position ´¼ ¼µ. Row coordinates range from ¼ to Ø ¹ ½, columncoordinates from ¼ to ÛØ ¹ ½. The image pointer (ÀÈÜÐÁÑ) refers to the first pixelof the matrix (index: 0,0). Different pixel types are supported. They are distinguished by aselector (Ò), see Fig. 4.2. The pixel types include basic types like ÀÌ, ÁÆ̽, ÁÆÌ, andÐÓØ as well as composed types. Their definitions can be seen in Fig. 4.3.The pixel data is stored as a one-dimensional array (vector) of one of the pixel types. Theindices of the array range from ¼ to ÛØع½. Alinear coordinate L within an imageis derived from the row index R and column index C as follows:Ä Ê ÑºÛØ · This transformation is performed by the following macro :Ä ÀÄÒÓÓִʸ¸ÑºÛص49

50 CHAPTER 4. HALCON DATA TYPESØÝÔ ÙÒÓÒ ßÀÌ » ¼ºº¾ ´ÌÁŵ »ÀÌ Þ » ¼ºº¾ ÑÓ ¾ ´ÄÁÁŵ »ÀÌ » ÓÖÒØØÓÒ ¼ºº½¼ ´ÁÊÁŵ »ÁÆ̽ » ¹½¾ºº½¾ ´ÁÆ̽Áŵ »ÁÆÌ Ð » ÝØ ÒØÖ ´ÄÇÆÁŵ »ÐÓØ » ÝØ ÖÐ ´ÄÇÌÁŵ »ÀÈÜÐ ÜÝ » ×ÔÐÑÒØ ÚØÓÖ Ð »» ´Áŵ »ÀÓÑÔÐÜÈÜÐ » ÓÑÔÐÜ Ñ ´ÇÅÈÄÁŵ »ÀÄÙØÈÜÐ ÐÙØ » ÝØ ÛØ ÄÍÌ ´ÄÍÌÁŵ »ÀÁÒؾÈÜÐ × » ¾ ÝØ× ÛØ ×Ò ´ÁÆ̾Áŵ »Ð ÀÈÜÐÁÑØÝÔ ×ØÖÙØ ßÁÆÌ Ò » ÔÜÐ ØÝÔ »ÀÈÜÐÁÑ ÔÜÐ » ÔÜÐ Ø »ÁÆÌ ÛØ » Ñ ÛØ »ÁÆÌ Ø » Ñ Ø »» ØÑ Ó ÖØÓÒ Ó Ñ »ÍÁÆ̾ Ñ× » ÑÐÐ×ÓÒ× ¼ºº »ÍÁÆ̽ × » ×ÓÒ× ¼ºº »ÍÁÆ̽ ÑÒ » ÑÒÙØ× ¼º »ÍÁÆ̽ ÓÙÖ » ¼ºº¾¿ »ÍÁÆ̽ Ý » ½ºº¿½ »ÍÁÆ̾ ÝÝ » ½ºº¿ »ÍÁÆ̽ ÑÓÒ » ½ºº½¾ »ÍÁÆ̾ ÝÖ » ×ØÖØÒ Ø ½¼¼ »Ð ÀÑFigure 4.1: Data type ÀÑ for images.Ò ÌÁÅ ´ÁÆ̵½ » ½ ÝØ ÔÖ ÔÜÐ ´¼ºº¾µ »Ò ÄÇÆÁÅ ´ÁÆ̵¾ » ÝØ ÔÖ ÔÜÐ ´ÁÆ̵ »Ò ÄÇÌÁÅ ´ÁÆ̵ » ÝØ ÔÖ ÔÜÐ ´ÐÓص »Ò ÁÊÁÅ ´ÁÆ̵ » ÓÖÒØØÓÒ ¼ºº½¼ »Ò ÄÁÁÅ ´ÁÆ̵½ » ¼ºº¾ ÝÐ »Ò ÁÆ̽ÁÅ ´ÁÆ̵¿¾ » ¹½¾ºº½¾ »Ò ÁÅ ´ÁÆ̵ » ¾ ÝØ Ñ× ÛØ ×Ò »Ò ÇÅÈÄÁÅ ´ÁÆ̵½¾ » ¾ ÐÓعÑ× »Ò ÄÍÌÁÅ ´ÁÆ̵¾ » ´¼ºº¾µ ÛØ ÓÐÓÖ ØÐ »Ò ÁÆ̾ÁÅ ´ÁÆ̵½¾ » ¾ ÝØ× ÛØ ×Ò »Figure 4.2: Definitions of pixel types.There are two additional macros for computing rows and columns:Ê ÀÊÓ۴ĸѺÛص ÀÓдĸѺÛصHALCON Extension Package Interface / 2000-11-16

4.2. REGION DATA (’HRLREGION’) 51ØÝÔ ×ØÖÙØ ßÐÓØ Ö » ÖÐ Ñ ÔÖØ »ÐÓØ Ñ » ÑÒÖÝ Ñ ÔÖØ »Ð ÀÓÑÔÐÜÈÜÐØÝÔ ×ØÖÙØ ßÁÆ̾ Ô » ÔÜÐ »ÁÆ̽ ÒÙÑØ× » ÒÙÑÖ Ó Ù× Ø× »Ð ÀÁÒؾÈÜÐØÝÔ ×ØÖÙØ ßÁÆ̽ ÖÓÛ » ݹÖØÓÒ »ÁÆ̽ ÓÐ » ܹÖØÓÒ »Ð ÀÈÜÐØÝÔ ×ØÖÙØ ßÀÌ » ¼ºº¾ »ÁÆÌ ÒÙÑÐÙØ » ÐÒØ Ó ÓÐÓÖ ØÐ »ÀÌ Ö¾℄ÀÌ ÖÒ¾℄ÀÌ ÐÙ¾℄Ð ÀÄÙØÈÜÐFigure 4.3: Data types for ÀÑ.Please see section 3.2.2 for routines to allocate image data within ÀÑ.4.2 Region Data (ÀÖÐÖÓÒ)In HALCON region data is represented by a special variant of the runlength encoding – a chordencoding: For every line (chord) of a region its row index (“y coordinate”,“line number”) andthe column index (“x coordinate”) of its start and end point is stored. Both the start point andthe end point belong to the region.Chord data must fulfill the following conditions:¯ a chord is limited to one row¯ chords may not overlap¯ chords are sorted in ascending orderIf a region is read from the HALCON data base, its representation fulfills all the conditionsabove. When writing a region, condition 2 and 3 need not to be sufficed in all cases, as theExtension Package Interface automatically modifies the data (at cost of computation time).Fig. 4.4 shows the type declaration for chords. All chords are stored in an array of the type ÀÖÙÒ,where ÒÙÑ is the current and ÒÙÑ ÑÜ the maximum allowed number of chords (depending onthe size of the region specified at its creation, see also sections 3.2). The flag × ÓÑÔÐ allows anHALCON 6.0

52 CHAPTER 4. HALCON DATA TYPESØÝÔ ×ØÖÙØ ßÁÆ̾ Ð » ÐÒ ÒÙÑÖ ´ÖÓÛµ Ó ÓÖ »ÁÆ̾ » ÓÐÙÑÒ ÒÜ Ó ÒÒÒ Ó ÓÖ »ÁÆ̾ » ÓÐÙÑÒ ÒÜ Ó ÒÒ Ó ÓÖ »Ð ÀÖÙÒØÝÔ ×ØÖÙØ ßÀÇÇÄ ×ÓÑÔÐ » ÖÓÒ × ÓÑÔÐÑÒØ »ÁÆÌ ÒÙÑ » ÒÙÑÖ Ó ÓÖ× »ÁÆÌ ÒÙÑÑÜ » ÑÜÑÐ ÒÙÑÖ Ó ÓÖ× »ÀÊØÙÖ ØÙÖ » ÐÖÝ ÔÖÓ×× ØÙÖ× »ÀÖÙÒ ÖÐÊÄÄÆÌÀ℄ » ÖÖÝ Ó ÓÖ× »Ð ÀÖÐÖÓÒFigure 4.4: Data type ÀÖÐÖÓÒ for region encoding.easy transformation of a region in its complement. Operators that work on regions must considerthis flag and react according to its value. The structure ÀÊØÙÖ (see Fig. 4.5) containsall features extracted so far to avoid repeating a computation. ÀØÙÖÐ× encodes, whichfeatures already have been extracted. Do not forget to reset these flags if you modify a region.Normally, a variable of type ÀÖÐÖÓÒ is allocated with the procedure ÀÐÐÓÊÄÌÑÔ orÀÐÐÓÊÄÆÙÑÌÑÔ, see section 3.2. These routines initialize the data, especially ÒÙÑ ÑÜ thatis needed for tests of overflow. When allocating a variable “by hand”, the programmer mustprovide a suitable initialization by himself/herself.Whereas all coordinates within runlength codes are stored as (row,column), linear coordinatesare used to address HALCON image matrices. Thus, the macros and are very helpful,especially when processing gray values (in linear coordinates) along a chord. The programs onpage 93 and 95 illustrate how to use them. Their functionality can be seen in Fig. 4.6. The firstparameter (ÖÐ) contains a pointer to the chords as it is used within ÀÖÐÖÓÒ . ÒÜ specifiesthe index of the chord to work on and ÛØ contains the image width. returns the linearcoordinate of the start point and that of the end point of the chord.4.3 XLDs (ÀÓÒØ, ÀÔÓÐÝ)XLDs (eXtended Line Descriptions) are specific iconic HALCON objects to represent subpixelaccurate contours and polygons. The corresponding data types are listed in Fig. 4.7 andFig. 4.10.HALCON contours of type ÀÓÒØ contain an array of subpixel points along a contour. A contourmight be classified concerning to topological considerations (ÓÒØ Ð××). Additionally,an arbitrary number of additional attributes for each point along the contour can be included(ØØÖ×), e.g., the edge amplitude of subpixel edge points or the orientation of the local gradient.Finally, an arbitrary number of additional global attributes, i.e., attributes valid for theentire contour, can be included (ÐÓÐ), e.g., the individual parameters of a regrssion line tothe contour or the parameters of an ellipse segment fitted to the contour.HALCON Extension Package Interface / 2000-11-16

4.3. XLDS (’HCONT’, ’HPOLY’) 53ØÝÔ ×ØÖÙØ ßÙÒÓÒ ßÀØÙÖÐ× ×ÒÐ » ØÐ »ÐÓÒÐÐÐÍÁÆ̽ ×Ô » ËÀÈ »ÀÇÇÄ×ÓÒÚÜÀÇÇÄ×ÐÐÀÇÇÄ×ÓÒÒظ ×ÓÒÒØÀÇÇÄ×ØÒÐÓØÖÙÐÖØÝÐÓØÓÑÔØÒ××ÐÓØÓÒØÐÒØÐÓØÓÒÚÜØÝÐÓØÔÐÓØÖ¸ ÖÐÓØÖ¸ ÖÐÓØÒ×ÓÑØÖݸ ÙÐÒ×׸ ×ØÖÙØÙÖØÓÖÐÓØѽ½¸ Ѿ¼¸ Ѽ¾¸ ¸ ÐÓØÖÓÛ¸ ÓÐÁÆÌÖÁÆ̾ÖÓÛ½¸Óн¸ÖÓÛ¾¸ÓоÐÓØÖÓÛÖظ ÓÐÖظ ÔÖظ ÐÒؽ¸ ÐÒؾÐÓØÖÓÛÖи ÓÐÖи ÖÙ×ÁÆ̾ÑÒÓÖ¸ ÑÜÓÖÁÆ̾ÑÒÓÖÔ¸ ÑÜÓÖÔÐ ÀÊØÙÖFigure 4.5: Data type ÀÊØÙÖ for region features.Please see section 3.2.2 for routines to allocate/deallocate contours. Two important auxiliaryroutines to copy contours are listed in Fig. 4.8. ÀÓÔÝÄÓÒØ copies a contour including allattributes, whereas ÀÓÔÝÄÓÒØÈÖØ copies only a part of the original contours specifiedby two indices ÑÒ ÒÜ and ÑÜ ÒÜ. They refer to the first and the last point along thecontour to be copied (starting with index 0). For closed contours a negative value might bespecified for ÑÒ ÒÜ. This will lead to a “wrap-around”, that is the part of the contour to becopied starts at ÓÒØ Ò¹ÒÙÑ · ÑÒ ÒÜ. Both ÀÓÔÝÄÓÒØ and ÀÓÔÝÄÓÒØÈÖØallocate the output contour themselves. So just pass a pointer to ÀÓÒØ without allocating anymemory for ÓÒØ ÓÙØ.The routines provided for handling attributes of contour points are summarized in Fig. 4.9.ÀÄÓÒØØØÖ is used to add a new class of attributes to a given contour ÓÒØ. Note, thatthis routine allocates memory for the attribute values, but it does not set the values themselves.An arbitrary name for the attribute can be specified by the parameter ÒÑ. The index of thenew attribute within the ØØÖ× array in ÓÒØ is returned in ÒÜ and can be used to addressthe values by ÓÒعØØÖ×ÒÜ℄ºÚÐÜÜÜ℄. The same holds for global attributes:ÀÄÓÒØÐÓÐØØÖ is used to add new global attributes, which can be accessed byÓÒعÐÓÐÒÜ℄ºÚÐ. Note that these values can be accessed within the HALCONsystem (that is on the application layer) using the operators Ø ÓÒØÓÙÖ ØØÖ ÜÐ andHALCON 6.0

54 CHAPTER 4. HALCON DATA TYPESNames¸ SynopsisÒÐÙ ÀÄÇƺÁÆÌ ´ÀÖÙÒÁÆÌÁÆÌÁÆÌ ´ÀÖÙÒÁÆÌÁÆÌÖиÒܸÛصÖиÒܸÛصFigure 4.6: Linear coordinates from ÀÖÐÖÓÒ.Ø ÓÒØÓÙÖ ÐÓÐ ØØÖ ÜÐ. See the Reference Manuals for details. Within HALCON,a specific attribute of a contour can be accessed using ÀÄÓÓÙÔÄÓÒØØØÖ, while a specificglobal attribute can be accessed using ÀÄÓÓÙÔÄÓÒØÐÓÐØØÖ. These routinesreturn the index of the desired attribute within ØØÖ× or ÐÓÐ of ÓÒØ, or the error codeÀ ÊÊ Ä Æ as result of the procedure call, if no attribute with the specified name is defined.The XLD data type ÀÔÓÐÝ , displayed in Figure 4.10, encodes subpixel accurate polygons.Basically it contains an array of control points. In many applications such polygons are derivedfrom contours. Thus, the data structure can also hold a reference to the underlying part of acontour specified by a HALCON data base key.4.4 Control Parameters (ÀÔÖ, ÀÔÖ)The HALCON data types ÀÔÖ and ÀÔÖ are used within the Extension Package Interface topass control parameters to supply procedures. Fig. 4.11 shows the corresponding definitions.ÀÔÖ encodes a single parameter value of one of the basic types ÒØÖ, ÖÐ or ×ØÖÒ, seesection 2.3. In addition to that, ÀÔÖ also encodes the corresponding type. Thus, it is possibleto combine different types within an array of ÀÔÖ values. The selector ØÝÔ can be set toÄÇÆ ÈÊ, ÄÇÌ ÈÊ or ËÌÊÁÆ ÈÊ.The Extension Package Interface procedures ÀØÈÖ, ÀØËÈÖ, ÀØÈÈÖ, ÀÈÙØÈÖ, andÀÈÙØÈÈÖ (section 5.5) are based on ÀÔÖ. They are used to access control parameters ofHALCON operators.HALCON Extension Package Interface / 2000-11-16

4.4. CONTROL PARAMETERS (’HPAR’, ’HCPAR’) 55ØÝÔ ÒÙÑ ÓÒØÐ×× ßÓÒØÙÒÒÓÛÒ¸ » ÙÒÒÓÛÒ »ÓÒØÒÓÙÒ¸ » ÒØÖ ×ØÖØ ÒÓÖ Ò ÔÓÒØ ÔÓÒØ× »» Ö ÙÒØÓÒ× »ÓÒØ×ØÖØÙÒ¸ » ×ØÖØ ÔÓÒØ × ÙÒØÓÒ »ÓÒØÒÙÒ¸ » ×ØÖØ ÔÓÒØ × ÙÒØÓÒ »ÓÒØÓØÙÒ¸ » ÓØ ×ØÖØ Ò Ò ÔÓÒØ Ö ÙÒØÓÒ× »ÓÒØÐÓ× » ÐÓ× ÓÒØÓÙÖ »Ð ÀÓÒØÐ××ØÝÔ ×ØÖÙØ ÓÒØØØÖ ßÖ ÒÑ » ÒÑ Ó Ø ØØÖÙØ »ÐÓØ ÚÐ » ÚÐÙ Ó Ø ØØÖÙØ ´ÔÖ ÔÓÒص »Ð ÀÓÒØØØÖØÝÔ ×ØÖÙØ ÓÒØÐÓÐØØÖ ßÖ ÒÑ » ÒÑ Ó Ø ÐÓÐ ØØÖÙØ »ÐÓØ ÚÐ » ÚÐÙ Ó Ø ØØÖÙØ ´ÔÖ ÓÒØÓÙÖµ »Ð ÀÓÒØÐÓÐØØÖØÝÔ ×ØÖÙØ ÓÒØØÝÔ ßÁÆÌ ÒÙÑ » ÒÙÑÖ Ó ÔÓÒØ× ÐÓÒ Ø ÓÒØÓÙÖ »ÐÓØ ÖÓÛ » ÔÓÒØ× » ÖÓÛ Ò× ´Ý ÓÓÖÒØ×µ »ÐÓØ ÓÐ » ÔÓÒØ× » ÓÐÙÑÒ Ò× ´Ü ÓÓÖºµ »ÀÓÒØÐ×× ÓÒØÐ×× » ÓÒØÓÙÖ Ð×× »ÁÆÌ ÒÙÑØØÖ » ÒÙÑÖ Ó ØÓÒÐ ØØÖÙØ× »ÀÓÒØØØÖ ØØÖ× » ØÓÒÐ ØØÖÙØ× ´ÓÖ ÔÓÒص »ÁÆÌ ÒÙÑÐÓÐ » ÒÙÑÖ Ó ØÓÒÐ ÐÓÐ ØØÖÙØ× »ÀÓÒØÐÓÐØØÖ ÐÓл ØÓÒÐ ØØÖÙØ× ´ÔÖ ÓÒØÓÙÖµ »ÁÆÌ » ÙÜÐÖÝ ´ØÑÔÓÖÖݵ »Ð ÀÓÒØFigure 4.7: The XLD data type ÀÓÒØ for subpixel contours.HALCON 6.0

56 CHAPTER 4. HALCON DATA TYPESNamesÀÓÔÝÄÓÒظ ÀÓÔÝÄÓÒØÈÖØSynopsisÒÐÙ ÀÐÓÒºÀÖÖÓÖ ÀÓÔÝÄÓÒØ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÓÒØÓÒØÒ¸ÀÓÒØÓÒØÓÙصÀÖÖÓÖ ÀÓÔÝÄÓÒØÈÖØ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÓÒØ ÓÒØÒ¸ÁÆÌ ÑÒÒܸÁÆÌ ÑÜÒܸÀÓÒØ ÓÒØÓÙصNamesFigure 4.8: Auxiliary routines for contours of type ÀÓÒØ.ÀÄÓÒØØØÖ¸ ÀÄÓÓÙÔÄÓÒØØØÖ¸ÀÄÓÒØÐÓÐØØÖ¸ ÀÄÓÓÙÔÄÓÒØÐÓÐØØÖSynopsisÒÐÙ ÀÐÓÒºÀÄÓÒØØØÖ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÓÒØÓÒظÖÒѸÁÆÌÒܵÀÄÓÓÙÔÄÓÒØØØÖ´ ÀÓÒØ ÓÒظÖÒѸÁÆÌÒܵÀÄÓÒØÐÓÐØØÖ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÓÒØÓÒظÖÒѸÁÆÌÒܵÀÄÓÓÙÔÄÓÒØÐÓÐØØÖ´ ÀÓÒØÖÁÆÌ ÒܵÓÒظÒѸFigure 4.9: Handling attributes of contour pixels (within ÀÓÒØ).HALCON Extension Package Interface / 2000-11-16

4.4. CONTROL PARAMETERS (’HPAR’, ’HCPAR’) 57ØÝÔ ×ØÖÙØ ÐÒ×ØÝÔ ßÐÓØ ÖÓÛ¸ÓÐ » ÓÒØÖÓÐ ÔÓÒØ Ó Ø ÔÓÐÝÓÒ »» ÖÓÛ ´Ýµ Ò ÓÐÙÑÒ ´Üµ ÓÓÖÒØ »ÐÓØ ÐÒØ » ÐÒØ Ó Ø ÐÒ ÖÓÑ Ø »» ÙÖÖÒØ ØÓ Ø ÒÜØ ÔÓÒØ »ÐÓØ Ô » ÓÖÒØØÓÒ ´Öµ Ó Ø× ÐÒ »ÀÝ Ö » Ø × Ý Ó Ø ÙÒÖÐÝÒ »» ÓÒØÓÙÖ »ÁÆÌ Ö×Ø » ÒÜ Ó Ø Ö×Ø ÔÓÒØ Ó Ø »» ÙÒÖÐÝÒ ÓÒØÓÙÖ ÐÓÒÒ ØÓ »» ÙÖÖÒØ × Ó Ø ÔÓÐÝÓÒ »ÁÆÌ Ð×Ø » ÒÜ Ó Ø Ð×Ø ÓÒØÓÙÖ ÔÓÒØ »Ð ÀÐÒ×ØÝÔ ×ØÖÙØ ÔÓÐÝØÝÔ ßÁÆÌ ÒÙÑÐÒ » ÒÙÑÖ Ó ÐÒ× »ÁÆÌ ÐÒÐÒ » ÑÜÑÙÑ ÒÙÑÖ Ó ÐÒ× ´×Þ »» Ó Ø ÖÖÝ ÐÒ×µ »ÀÐÒ× ÐÒ× » ÓÒØÖÓÐ ÔÓÒØ× Ó Ø ÔÓÐÝÓÒ »Ð ÀÔÓÐÝFigure 4.10: The XLD data type ÀÔÓÐÝ for subpixel polygons.ØÝÔ ÙÒÓÒ ßÁÆÌ Ð » ÝØ ÒØÖ »ÐÓØ » ÝØ ÖÐ »Ö × » ×ØÖÒ »Ð ÀÔÖØÝÔ ×ØÖÙØ ßÀÔÖ ÔÖÁÆ̽ ØÝÔÐ ÀÔÖFigure 4.11: Data types ÀÔÖ and ÀÔÖ for control parameters.HALCON 6.0

58 CHAPTER 4. HALCON DATA TYPESHALCON Extension Package Interface / 2000-11-16

Chapter 5Handling Iconic Objects and ControlParametersThe HALCON Extension Package Interface provides a large set of procedures and macros forhandling control parameters and iconic objects. It supports tasks like:¯ Accessing iconic input objects in the HALCON data base.¯ Accessing single iconic objects within a tuple of objects.¯ Accessing specific components (regions, gray value channels) of image objects.¯ Accessing XLDs.¯ Creating iconic output objects in the HALCON data base based on the computed results.¯ Reading input control parameters.¯ Writing output control parameters.The routines of the Extension Package Interface described in this and the following chapterespecially facilitate the programming of support procedures (that is the access of the HALCONdata base and all the parameter handling).In this chapter the “low level” interface routines are introduced. They allow a straightforwardaccess to all parameters of an operator – to iconic objects (and their components) and to controlparameters. Moreover, some routines for creating objects and writing output object parametersand control parameters are introduced.Based on these low level routines a set of convenience routines are presented in chapter 6. Theyare designed to further facilitate the programming of very typical support procedures.5.1 Basic Access to Iconic Input ObjectsThis section introduces some basic routines for accessing iconic objects (regions, gray valuechannels, XLDs), see Fig. 5.1. They form a basic interface to the HALCON data base. Fig. 5.2illustrates how they are used to read image and region data from input object parameters.59

60 CHAPTER 5. HANDLING ICONIC OBJECTS AND CONTROL PARAMETERSNamesÀØǸ ÀØÓÑÔ¸ ÀØÊĸ ÀØÁѸ ÀØÄSynopsisÒÐÙ ÀÐÓÒºÀØÇ´ ÀÔÖÓÒÐ ÔÖÓÒиÁÆÌÔÖÒÙѸÁÆÌÓÒÙÑÀÝÓݵÀØÓÑÔ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÝÓݸÁÆÌÓÑÔÀÝÓÑÔݵÀØÊÄ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÝÖÓÒݸÀÖÐÖÓÒ ÖÓÒµÀØÁÑ´ ÀÔÖÓÒÐÀÝÀÑÔÖÓÒиÑݸѵÀØÄ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÝÓݸÁÆÌÜÐØÝÔ¸ÄÜеFigure 5.1: Basic routines for accessing iconic input objects.5.1.1 ÀØÇÀØÇ (see Fig. 5.1) returns the data base key (type: ÀÝ) of an iconic object correspondingto the input object parameter number ÔÖ ÒÙÑ of the HALCON operator.The iconic object can either be a region (object that contains only a region component), animage object (object that contains a region component and one or more image channels) , or anXLD (object that contains a contour or a polygon). For the sake of simplicity we will refer toall of them using the term object.The parameters of a HALCON operator are numbered consecutively from ½ to Ò (not from ¼to Ò ½) for each parameter class (input/output object/control). The parameter ÔÖ ÒÙÑ ofÀØÇ refers to this number, thus specifying the desired input object parameter. All objectspassed within a single input object parameter are numbered from ½ to Ñ, with the first object inthe list having the number ½. The parameter Ó ÒÙÑ of ÀØÇ denotes the index of a desiredobject within this list (½ Ó ÒÙÑ Ñ).HALCON Extension Package Interface / 2000-11-16

5.1. BASIC ACCESS TO ICONIC INPUT OBJECTS 61operator call1st input object parameter2nd input object parameter1st input object parameter1st objectof 1st input object parameterregionchannel1channel2parameter numberHGetObjHkeyobj_keyHGetCompHkey comp_keyHGetImageHimageimageHGetRLHrlregionregionFigure 5.2: Direct access to input image objects.ÁÆ̾ ÒÔÔÖ×ÁÆÌ ÒÙÑÓ×ÀÝ Ýººº» Ø ÒÙÑÖ Ó ÒÔÙØ ÓØ ÔÖÑØÖ× »» ÒÓØ Ì× ÒÙÑÖ × ÒÓÛÒ Ò ÒÖÐ ¹ Ø × ×Ô Ý »» Ø ÓÔÖØÓÖ Ö Ò Ø ÓÖÖ×ÔÓÒÒ ¹Ð Ó Ø »» ÓÔÖØÓÖ »ÀÊδÔÖÓÒиÀÒÔÓ¸²ÒÔÔÖ×µÓÖ ´Ô½ ÔÒÔÔÖ× Ô··µ ß» Ø ÒÙÑÖ Ó ÒÔÙØ ÓØ× ÔÖ ÒÔÙØ Óº ÔÖÑØÖ »ÀÊδÔÖÓÒиÀÒÙÑÓ¸²ÒÙÑÓ׸ԵÓÖ ´Ó½ ÓÒÙÑÓ× Ó··µ ßÀØÇ´ÔÖÓÒиԸӸ²Ýµ » Ø Ý Ó ÓØ »» ÙÖØÖ ÔÖÓ××Ò ººº »ÐÐFigure 5.3: Example for ÀØÇ: Data base keys of all iconic objects of all input object parameters.The number of input object parameters for an operator is specified in the corresponding file1 , but the number of objects within an input object parameter is dynamic. This value isaccessible via the Extension Package Interface routine ÀÊÎ:ÀÊδÔÖÓÒиÀÒÙÑÓ¸²ÒÙÑÓ׸Եwhere Ô denotes the parameter number and ÒÙÑ Ó× is the desired number of objects. There1 So this number is actually known by the programmer. However, using ÀÊÎ it can be read from theoperator context as well, see Fig. 5.3.HALCON 6.0

62 CHAPTER 5. HANDLING ICONIC OBJECTS AND CONTROL PARAMETERSis an alternative for reading the number of objects of an input object parameter, which does notneed the ÀÊÎ routine, namely ÀØÇÆÙÑ (see page 67).Note, that a loop over all objects passed to an operator within an input object parameter is avery common task. Therefore, HALCON provides a macro for this problem: See ÀÐÐÇ onpage 69.5.1.2 ÀØÓÑÔÀØÓÑÔ (see Fig. 5.1) returns the data base key of a component (image matrix: Ñ Ý orregion: ÖÓÒ Ý) of an image object that is stored under the key Ó Ý in the HALCONdata base.ÁÆ̾ ÓÒÒÐ×ÀÝ ÓÝÀÝ ÖÓÒÝÀÝ Ñݺºº» Ø Ý Ó ÓØ »ÀØÇ´ÔÖÓÒиԸӸ²Óݵ» Ø Ý Ó ÖÓÒ »ÀØÓÑÔ´ÔÖÓÒиÓݸÊÁÇƸ²ÖÓÒݵ» Ø ÒÙÑÖ Ó ÒÒÐ× »ÀÈ´ÀÈÆÙÑÇÒÒÐ×´ÔÖÓÒиԸӸ²ÓÒÒÐ×µµÓÖ ´½ ÓÒÒÐ× ··µ ß» Ø Ñ ÑØÖÜ Ý »ÀØÓÑÔ´ÔÖÓÒиÓݸ¸²Ñݵ» ºººÙÖØÖ ÔÖÓ××Ò »ÐFigure 5.4: Example for ÀØÓÑÔ: Data base keys of all regions and channels within an inputimage object.All components of an object are consecutively numbered from ¼ to Ò, with ¼ denoting the regionand ½ Òdenoting the channels (image matrices). To get a better legibility of program code,the constants ÊÁÇÆ (= 0), ÁÅ ÁÆ (= 1), ÁŽ (= 1), Áž (= 2) etc. have beendefined globally and may be used as parameter values.The number of channels per image object Ó ÒÙÑ of parameter ÔÖ ÒÙÑ is accessible viaÀÈÆÙÑÇÒÒÐ×, see Fig. 5.4 and 5.5:ÀÈÆÙÑÇÒÒÐ×´ÔÖÓÒиÔÖÒÙѸÓÒÙѸ²ÓÒÒÐ×µSee also ÀÆÙÑÇÒÒÐ× in section 5.6.4 for a convenience version of this routine when dealingwith the first input object parameter. More examples of how to use ÀØÓÑÔ can be foundin Fig. 5.6 and 5.7.HALCON Extension Package Interface / 2000-11-16

5.1. BASIC ACCESS TO ICONIC INPUT OBJECTS 63NamesÀÈÆÙÑÇÒÒÐ×SynopsisÒÐÙ ÀÐÓÒºÀÖÖÓÖ ÀÈÆÙÑÇÒÒÐ×´ ÀÔÖÓÒÐ ÔÖÓÒиÁÆÌÔÖÒÙѸÁÆÌ ÓÒÙѸÁÆÌÒÒÙѵFigure 5.5: Auxiliary routine ÀÈÆÙÑÇÒÒÐ×.5.1.3 ÀØÊÄÀØÊÄ (see Fig. 5.1) reads the chord encoding of a region (type: ÀÖÐÖÓÒ, see section 4.2)denoted by the data base key ÖÓÒ Ý from the HALCON data base.ÀÖÐÖÓÒ ÖÓÒÀÝ ÓÝÀÝ ÖÓÒݺººÀÈ´ÀÐÐÓÊÄÌÑÔ´ÔÖÓÒи²ÖÓÒµµÀØÇ´ÔÖÓÒиԸӸ²ÓݵÀØÓÑÔ´ÔÖÓÒиÓݸÊÁÇƸ²ÖÓÒݵÀØÊÄ´ÔÖÓÒиÖÓÒݸÖÓÒµ» ÔÖÓ××Ò ´Ò ÒÖÐ Ø× ×ÓÙÐ ÓÒ ÐÐÒ Ò ØÓÒ ÔÖÓºµ »Ö ¼ÓÖ ´¼ ÖÓÒ¹ÒÙÑ ··µÖ · ÖÓÒ¹ÖÐ℄º ¹ ÖÓÒ¹ÖÐ℄º · ½ÀÈ´ÀÖÊÄÌÑÔ´ÔÖÓÒиÖÓÒµµFigure 5.6: Example for ÀØÊÄ: Calculate the area of a region.Since the region data is copied to ÖÓÒ, it might be overwritten with new values (in contrastto ÀØÁÑ and ÀØÊÄ, cf. section 5.1.4 and 5.2.2). However, this means that enoughmemory for ÖÓÒ must be allocated before calling ÀØÊÄ, see section 3.2.1. Fig. 5.6 and5.7 show exemplary applications of ÀØÊÄ.5.1.4 ÀØÁÑÀØÁÑ (see Fig. 5.1) reads the image data (type: ÀÑ, see section 4.1) of a specific grayvalue component (channel) of an image object referenced by its key in the HALCON data base.The data structure ÀÑ contains the gray values, the gray value type, and the size of theimage matrix. Instead of copying the image matrix, ÀØÁÑ only returns a pointer to theHALCON 6.0

64 CHAPTER 5. HANDLING ICONIC OBJECTS AND CONTROL PARAMETERSÀÝ ÓÝÀÝ ÑÝÀÝ ÖÓÒÝÀÑ ÑÀÖÐÖÓÒ ÖÓÒºººÀØÓÑÔ´ÔÖÓÒиÓݸÁÅÁƸ²ÑݵÀØÓÑÔ´ÔÖÓÒиÓݸÊÁÇƸ²ÖÓÒݵÀØÁÑ´ÔÖÓÒиÑݸ²ÑµÀØÊÄ´ÔÖÓÒиÖÓÒݸÖÓÒµ×ÛØ ´ÑºÒµ ß× ÌÁÅ» ÔÖÓ××Ò ´Ò ÒÖÐ Ø× ×ÓÙÐ »» ÓÒ ÐÐÒ Ò ØÓÒ ÔÖÓÙÖµ »Ö ×ÙÑ ¼ÓÖ ´¼ ÖÓÒ¹ÒÙÑ ··µ ßÓÖ ´´ÖÓÒ¹Öи¸ÑºÛص´ÖÓÒ¹Öи¸ÑºÛص ··¸ Ö··µ×ÙÑ · ѺÔÜк℄ÐÚÖ ×ÙÑ » ÖÖÙÐØ ÖØÙÖÒ´ÀÊÊÏÁ̵ » ÛÖÓÒ Ñ ØÝÔ »ÐFigure 5.7: Example for ÀØÁÑ: Average gray value of first channel.raw data in ѺÔÜÐ. This is much more efficient, but means that only read access tothe image matrix is recommended (otherwise you will encounter unpredictable side effects).Fig. 5.7 shows an application of ÀØÁÑ.5.1.5 ÀØÄÀØÄ (see Fig. 5.1) is used to access XLD objects in the HALCON data base. The object ofinterest is specified by the data base key Ó Ý. The parameter ÜÐ ØÝÔ allows to specifythe kind of XLD data to be accessed: It has to be set to Ä ÇÆÌÇÍÊ Á in case of a contourand to Ä ÈÇÄÇÆ Á in case of a polygon. Corresponding to the selected type ÀØÄexpects a pointer to ÀÓÒØ or a pointer to ÀÔÓÐÝ in the parameter ÜÐ. In both cases notthe underlying data within the structures ÀÓÒØ or ÀÔÓÐÝ but only the pointers to the data arecopied from the data base. Thus, please avoid any write access to this data. Otherwise youwill encounter unpredictable side effects (changing other HALCON objects). Fig. 5.8 shows asimple example for how to use ÀØÄ.HALCON Extension Package Interface / 2000-11-16

5.2. ADDITIONAL ROUTINES FOR ACCESSING INPUT IMAGE OBJECTS 65ÀÝÀÔÖÀÓÒØÓÝÒÙÑÔÓÒØ×ÓÒØÀØÇ´ÔÖÓÒиÔÖÒÙѸÓÒÙѸ²ÓݵÀØÄ´ÔÖÓÒиÓݸÄÇÆÌÇÍÊÁ¸´ÎÇÁȵ²ÓÒص» ÔÖÓ××Ò ´Ò ÒÖÐ Ø× ×ÓÙÐ ÓÒ ÐÐÒ Ò ØÓÒ ÔÖÓºµ »ÒÙÑÔÓÒØ׺ØÝÔ ÄÇÆÈÊÒÙÑÔÓÒØ׺ÔֺРÓÒعÒÙÑÀÈÙØÈÖ´ÔÖÓÒи½¸²ÒÙÑÔÓÒØ׸½µFigure 5.8: Example for ÀØÄ: Return the number of points of the contour with numberÓ ÒÙÑ within input object parameter ÔÖ ÒÙÑ.NamesÀØÊĸ ÀØÊĸ ÀØÍÊĸ ÀØÁѸ ÀØÇÆÙÑSynopsisÒÐÙ ÀÐÓÒºÀØÊÄ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÝÓݸÀÖÐÖÓÒ ÖÓÒµÀØÊÄ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÝÓݸÀÖÐÖÓÒ ÖÓÒµÀØÍÊÄ´ ÀÔÖÓÒÐ ÔÖÓÒиÁÆÌÔÖÒÙѸÀÖÐÖÓÒ ÖÓÒµÀØÁÑ´ÀÔÖÓÒÐÀÝÁÆÌÀÑÀØÇÆÙÑ´ÀÔÖÓÒÐÁÆÌÁÆÌÔÖÓÒиÓݸÒÒиѵÔÖÓÒиÔÖÒÙѸÒÙѵFigure 5.9: Additional routines for accessing input image objects.HALCON 6.0

66 CHAPTER 5. HANDLING ICONIC OBJECTS AND CONTROL PARAMETERS5.2 Additional Routines for Accessing Input Image ObjectsThis section introduces some routines that ease the programming of supply procedures in manyapplications, see Fig. 5.9. Basically they are combinations of the routines described in theprevious section. These additional routines only require the data base keys of the input objectsthat can be extracted by using the routines ÀØÇ (se section 5.1.1) or ÀÐÐÇ (see section5.3.1). For ÀØÍÊÄ even this step can be omitted.5.2.1 ÀØÊÄÀÖÐÖÓÒ ÖÓÒÀÝ ÓݺººÀÈ´ÀÐÐÓÊÄÌÑÔ´ÔÖÓÒи²ÖÓÒµµÀØÇ´ÔÖÓÒиÔÖÒÙѸÓÒÙѸ²ÓݵÀØÊÄ´ÔÖÓÒиÓݸÖÓÒµ» ÔÖÓ××Ò ´Ò ÒÖÐ Ø× ×ÓÙÐ ÓÒ ÐÐÒ Ò ØÓÒ ÔÖÓºµ »Ö ¼ÓÖ ´¼ ÖÓÒ¹ÒÙÑ ··µÖ · ÖÓÒ¹ÖÐ℄º ¹ ÖÓÒ¹ÖÐ℄º · ½ÀÈ´ÀÖÊÄÌÑÔ´ÔÖÓÒиÖÓÒµµFigure 5.10: Application of ÀØÊÄ.ÀØÊÄ (see Fig. 5.9) combines ÀØÓÑÔ (section 5.1.2) and ÀØÊÄ (section 5.1.3). It readsthe chord encoding of a region (type: ÀÖÐÖÓÒ, see section 4.2) specified by the data base keyÓ Ý of an image object. The region data is copied to ÖÓÒ that must have been allocatedbefore with a suitable size (e.g., by using ÀÐÐÓÊÄÌÑÔ, see section 3.2.1). Therefore, thisregion data can be overwritten without side effects. On the other hand, the memory must bedeallocated at the end of the supply procedure (e.g., by using ÀÖÊÄÌÑÔ). Fig. 5.10 shows anexample application of ÀØÊÄ.5.2.2 ÀØÊÄIn contrast to ÀØÊÄ only a pointer to the region data is returned by ÀØÊÄ (see Fig. 5.9).So there is no need to allocate memory for the data. On the other hand, only read access to thedata is allowed. An example application of ÀØÊÄ can be seen in Fig. 5.11.5.2.3 ÀØÍÊÄÀØÍÊÄ (see Fig. 5.9) reads all regions passed in the input object parameter with numberÔÖ ÒÙÑ, computes the union of all these regions, and returns the resulting region in ÖÓÒ.The ÀÖÐÖÓÒ data referenced by ÖÓÒ must have been allocated before with a suitable sizeHALCON Extension Package Interface / 2000-11-16

5.2. ADDITIONAL ROUTINES FOR ACCESSING INPUT IMAGE OBJECTS 67ÀÝ ÓÝÀÖÐÖÓÒ ÖÓÒºººÀØÊÄ´ÔÖÓÒиÓݸ²ÖÓÒµ» ÔÖÓ××Ò ´Ò ÒÖÐ Ø× ×ÓÙÐ ÓÒ ÐÐÒ Ò ØÓÒ ÔÖÓºµ »Ö ¼ÓÖ ´¼ ÖÓÒ¹ÒÙÑ ··µÖ · ÖÓÒ¹ÖÐ℄º ¹ ÖÓÒ¹ÖÐ℄º · ½Figure 5.11: Application of ÀØÊÄ.(e.g., by using ÀÐÐÓÊÄÌÑÔ, see section 3.2.1). Therefore, this region data can be overwrittenwithout side effects. On the other hand, the memory must be deallocated at the end of the supplyprocedure (e.g., by using ÀÖÊÄÌÑÔ). Fig. 5.12 shows an application of ÀØÍÊÄ. Note, thatthe area calculated in the example may differ from the sum of the areas of all single regions,because the single regions may overlap.ÀÖÐÖÓÒ ÖÓÒºººÀÈ´ÀÐÐÓÊÄÌÑÔ´ÔÖÓÒи²ÖÓÒµµÀØÍÊÄ´ÔÖÓÒиÔÖÒÙѸÖÓÒµ» ÔÖÓ××Ò ´Ò ÒÖÐ Ø× ×ÓÙÐ ÓÒ ÐÐÒ Ò ØÓÒ ÔÖÓºµ »Ö ¼ÓÖ ´¼ ÖÓÒ¹ÒÙÑ ··µÖ · ÖÓÒ¹ÖÐ℄º ¹ ÖÓÒ¹ÖÐ℄º · ½ÀÈ´ÀÖÊÄÌÑÔ´ÔÖÓÒиÖÓÒµµFigure 5.12: Application of ÀØÍÊÄ.5.2.4 ÀØÁÑÀØÁÑ (see Fig. 5.9) combines ÀØÓÑÔ (section 5.1.2) and ÀØÁÑ (section 5.1.4).It reads the data of the gray value component ÒÒÐ of the image object specified by the database key Ó Ý and returns it in the ÀÑ structure (Ñ).For the sake of efficiency, only a pointer to the image matrix is copied to Ñ, instead ofcopying the data itself. So, only read access to the image data is recommended in order to avoidunpredictable side effects. Fig. 5.13 shows an application of ÀØÁÑ.5.2.5 ÀØÇÆÙÑÀØÇÆÙÑ (see Fig. 5.9) returns the number of iconic objects which are stored in the inputobject parameter denoted by its index ÔÖ ÒÙÑ (from ½ to Ò). It is an alternative to the usageof ÀÊÎ (compare page 61). By using ÀØÇÆÙÑ, the example of figure 5.3 (page 61)looks as follows (see figure 5.14).HALCON 6.0

68 CHAPTER 5. HANDLING ICONIC OBJECTS AND CONTROL PARAMETERSÀÑ ÑÀÔÖ ÖÓÛ¸ÓиÖݺººÀØËÈÖ´ÔÖÓÒи½¸ÄÇÆÈʸ²ÖÓÛ¸½µ » ÖÓÛ »ÀØËÈÖ´ÔÖÓÒи¾¸ÄÇÆÈʸ²Óи½µ » ÓÐÙÑÒ »ÓÓÖ ÀÄÒÓÓÖ´ÖÓÛºÔֺиÓкÔֺиѺÛصÀØÁÑ´ÔÖÓÒиÓݸÁÅÁƸ²Ñµ» ÔÖÓ××Ò ´Ò ÒÖÐ Ø× ×ÓÙÐ ÓÒ ÐÐÒ Ò ØÓÒ ÔÖÓºµ »×ÛØ ´ÑºÒµ ß× ÌÁÅÖݺÔֺРѺÔÜкÓÓÖ℄ÖݺØÝÔ ÄÇÆÈÊÖ× ÄÇÌÁÅÖݺÔÖº ѺÔÜкÓÓÖ℄ÖݺØÝÔ ÄÇÌÈÊÖÙÐØÖØÙÖÒ´ÀÊÊÏÁ̵ » ÛÖÓÒ Ñ ØÝÔ »ÐÀÈÙØÈÖ´ÔÖÓÒи½¸²Öݸ½µFigure 5.13: Application of ÀØÁÑ: Return the gray value at position (row,col) in the firstchannel of the input object Ó Ý.ÁÆ̾ ÒÔÔÖ×ÁÆÌ ÒÙÑÓ×ÀÝ ÝÁÆÌ Ô¸Óººº» Ø ÒÙÑÖ Ó ÒÔÙØ ÓØ ÔÖÑØÖ× »» ÒÓØ Ì× ÒÙÑÖ × ÒÓÛÒ Ò ÒÖÐ ¹ Ø × ×Ô Ý »» Ø ÓÔÖØÓÖ Ö Ò Ø ÓÖÖ×ÔÓÒÒ ¹Ð Ó Ø »» ÓÔÖØÓÖ »ÀÊδÔÖÓÒиÀÒÔÓ¸²ÒÔÔÖ×µÓÖ ´Ô½ ÔÒÔÔÖ× Ô··µ ß» Ø ÒÙÑÖ Ó ÒÔÙØ ÓØ× ÔÖ ÒÔÙØ Óº ÔÖÑØÖ »ÀØÇÆÙÑ´ÔÖÓÒиԸ²ÒÙÑÓ×µÓÖ ´Ó½ ÓÒÙÑÓ× Ó··µ ßÀØÇ´ÔÖÓÒиԸӸ²Ýµ » Ø Ý Ó ÓØ »» ÙÖØÖ ÔÖÓ××Ò ººº »ÐÐFigure 5.14: Application of ÀØÇÆÙÑ: Get the number of iconic objects of an input objectparameter.HALCON Extension Package Interface / 2000-11-16

5.3. LOOP MACROS FOR ACCESSING SINGLE INPUT OBJECTS 695.3 Loop Macros for Accessing Single Input ObjectsThis section describes two macros that ease accessing all iconic objects and image componentswithin an input object parameter, see Fig. 5.15. Please see also the additional loop macros insection 6.1 that further facilitate programming typical supply procedure.NamesÀÐÐǸ ÀÐÐÓÑÔSynopsisÒÐÙ ÀÐÓÒºÀÐÐÇ´ ÀÔÖÓÒÐÁÆÌÀÝÁÆÌÀÐÐÓÑÔ´ÀÔÖÓÒÐÀÝÀÝÀÑÁÆÌÔÖÓÒиÔÖÒÙѸ²Óݸ²ÒܵÔÖÓÒиÓݸ²ÑÒݸ²ÑÒ¸²ÒܵFigure 5.15: Basic loop macros to access iconic objects. “&” denotes output parameters of themacros. This is only a special notation to make clear that these parameters are changed bythe macros. So do not pass pointers to variables but the variables itself to the macro.5.3.1 ÀÐÐÇÀÐÐÇ (see Fig. 5.15) performs a loop over all iconic objects of a specified input objectparameter and returns their data base keys.ÀÝ ÓÝÀÖÐÖÓÒ ÖÓÒÀÑ ÑÁÆÌ ÒܺººÀÐÐÇ´ÔÖÓÒи½¸ÓݸÒܵ ßÀØÊÄ´ÔÖÓÒиÓݸ²ÖÓÒµÀØÁÑ´ÔÖÓÒиÓݸÁÅÁƸ²ÑµÐFigure 5.16: Application of ÀÐÐÇ: Get the area of definition and the first gray value channelof all input objects of the first input object parameter.HALCON 6.0

70 CHAPTER 5. HANDLING ICONIC OBJECTS AND CONTROL PARAMETERSWithin the loop all iconic objects contained in the input object parameter number 2 ÔÖ ÒÙÑ areaccessed one by one. ÒÜ is set to the number of the current iconic object to be processedand Ó Ý is set to the corresponding data base key. Thus, using ÀÐÐÇ is equivalent toprogramming an explicit loop over all objects contained in a parameter and determining the database keys via ÀØÇ, see also Fig. 5.3. Fig. 5.16 shows an application of ÀÐÐÇ.5.3.2 ÀÐÐÓÑÔÀÐÐÓÑÔ performs a loop over all gray value channels (components) of the image object denotedby the data base key Ó Ý. Within the loop, Ñ Ò Ý is set to the data base keyof the current image object and the corresponding image data is delivered in Ñ Ò. UsingÀÐÐÓÑÔ is equivalent to programming an explicit loop over all channels of an image objectusing ÀØÁÑ. This also implies that the raw image data, that is the image matrix itself,is not copied. Instead, only a pointer to this data is inserted in Ñ Ò. So please restrictyourself to reading this data. Any write access to the image matrix will cause unpredictableside effects.Note, that ÀÐÐÓÑÔ does not check, whether the image object contains at least one channel.Note further, that any region processing should be done outside the loop (otherwise you willprocess the same region again and again for each channel).ÀÝ ÓÒÀÝ ÓÓÙØÀÝ ÑÒÝÁÆÌ ÓÑÔÒÜÀÑ ÑÒ¸ÑÓÙغººÀÐÐÇ´ÔÖÓÒи½¸ÓÒ¸µ ßÀÖÇ´ÔÖÓÒи½¸²ÓÓÙصÀÐÐÓÑÔ´ÔÖÓÒиÓÒ¸ÑÒݸÑÒ¸ÓÑÔÒܵ ßÀÈ´ÀÖÁÑ´ÔÖÓÒиÑÒݸ½¸ÌÁŸÑҺظÑÒºÛظ²ÑÓÙØݸ²ÑÓÙصµÀÈ´ÁÈÊÓؼ´ÑÒºÔÜк¸ÑÒºÛظÖÓÒÒ¸ÑÓÙغÔÜк¸ÛظصµÀÇ´ÔÖÓÒиÓÓÙظÑÓÙØݸÓÑÔÒܵÐÐFigure 5.17: Application of ÀÐÐÓÑÔ: rotate all channels of all image objects of the first inputobject parameter.Fig. 5.17 shows an example of how to use ÀÐÐÓÑÔ. Within the ÀÐÐÇ loop for each inputimage object an output image object is created and added to the object list of the first outputobject parameter (ÀÖÇ, see section 5.4.1). After that, a loop over all gray value channelsof the current image object is performed (ÀÐÐÓÑÔ). Within this loop, for every gray value2 So in contrast to the routines described in section 6.1, ÀÐÐÇ allows to specify the desired parameter by itsnumber.HALCON Extension Package Interface / 2000-11-16

5.4. CREATING OBJECTS AND WRITING OUTPUT OBJECT PARAMETERS 71channel a new image matrix is created (ÀÖÁÑ, see section 5.4.1) and filled with the rotatedinput matrix (ÁÈÊÓؼ). Finally, this matrix is installed as a new gray value channel of theoutput image object (ÀÇ, see section 5.4.1). The corresponding region transformation(rotating the region and defining the rotated region as new area of definition of the output imageobject via ÀÇ) is omitted in this example.5.4 Creating Objects and Writing Output Object ParametersThis section describes routines for creating new iconic objects in the HALCON data base andfor writing output object parameters of a HALCON operator, see Fig. 5.18. Note, that regions,gray value channels, and XLDs are all stored as individual objects within the data base. Thus,for example different image objects can share the same gray value channels (image matrices)or regions (areas of definition). Therefore, in order to return iconic objects as the result of aHALCON operator you have to¯ store the computed regions, channels, and XLDs in HALCON data base objects,¯ combine regions and channels to image objects,¯ and add the appropriate iconic objects to the corresponding output object parameters.5.4.1 ÀÖÇÀÖÇ (see Fig. 5.18) creates a new image object in the HALCON data base and adds it to thelist of objects in the output object parameter with the number ÔÖ ÒÙÑ. Note, that more thanone image object can be returned in the same output parameter by iterating calls of ÀÖÇusing the same ÔÖ ÒÙÑ: Each call appends the data base key of the new object at the end ofthe object list for the parameter.The new image object contains the following default components:¯ The region component specifying the area of definition is set to the empty region. Thiscomponent can be changed using ÀÈÙØÊÄ (see section 5.4.3) or ÀÈÙØÊØ (see section6.2.2).¯ All channels are marked as undefined, that is the new image object contains no gray valuecomponents. Channels can be added to the object using ÀÈÙØÁÑ (see section 5.4.4)and ÀÇ (see section 5.4.5) or ÀÈÙØÁÑ (see section 5.4.6).Fig. 5.17 and 5.21 show examples for how to use ÀÖÇ.HALCON 6.0

72 CHAPTER 5. HANDLING ICONIC OBJECTS AND CONTROL PARAMETERSNamesÀÖǸ ÀÓÔÝǸ ÀÈÙØÊĸ ÀÖÄSynopsisÒÐÙ ÀÐÓÒºÀÖÇ´ ÀÔÖÓÒÐ ÔÖÓÒиÁÆÌÔÖÒÙѸÀÝÓݵÀÓÔÝÇ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÝÓݸÁÆÌÔÖÒÙѸÀÝÓݵÀÈÙØÊÄ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÝÓݸÀÖÐÖÓÒ ÖÓÒ¸ÀÝÖÐݵÀÖÖÓÖ ÀÖÄ´ ÀÔÖÓÒÐ ÔÖÓÒиÁÆÌÔÖÒÙѸÄÜиÁÆÌÜÐØÝÔ¸ÀÝÙ×ÜÐ׸ÁÆÌÒÙÑÙ×ÜÐ׸ÖÈÖÓ ÖÔÖÓ¸ÀÝÓݵFigure 5.18: Basic routines for creating new iconic objects and writing output object parameters(to be continued).5.4.2 ÀÓÔÝÇÀÓÔÝÇ (see Fig. 5.18) creates a new iconic object (image, region, or XLD) in the HALCONdata base containing the same components as an already existing object specified by its data basekey Ó Ý. The new object is appended to the list of objects in the output object parameterwith the number ÔÖ ÒÙÑ. The data base key of the new image object is returned in Ó Ý.Similar to ÀÖÇ, the components of a new image object can be reassigned using ÀÇ etc.ÀÓÔÝÇ is especially useful, when output objects hardly differ from the corresponding inputobjects.HALCON Extension Package Interface / 2000-11-16

5.4. CREATING OBJECTS AND WRITING OUTPUT OBJECT PARAMETERS 73NamesÀÈÙØÁѸ ÀǸ ÀÈÙØÁѸ ÀÖÁÑSynopsisÒÐÙ ÀÐÓÒºÀÈÙØÁÑ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÑ Ñ¸ÀÇÇÄÓÔݸÀÝÓݵÀÇ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÝÓݸÀÝÓÑÔݸÁÆÌÓÑÔµÀÈÙØÁÑ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÝÓݸÁÆÌÓÑÔ¸ÀÑ Ñ¸ÀÇÇÄÓÔݸÀÝÑݵÀÖÖÓÖ ÀÖÁÑ´ ÀÔÖÓÒÐÀÝÁÆÌÁÆÌÁÆÌÀÝÀÑÔÖÓÒиÑÝÒ¸ÒܸØÝÔ¸ÛظظÑÝÓÙظÑÓÙصFigure 5.19: Basic routines for creating new iconic objects and writing output object parameters(continued).5.4.3 ÀÈÙØÊÄÀÈÙØÊÄ (see Fig. 5.18) stores 3 region data encoded in the ÀÖÐÖÓÒ structure ÖÓÒ in theHALCON data base and returns the data base key of the new object. In addition to that, theregion object is assigned to the image object specified by the data base key Ó Ý as theregion component. The latter might have been created before by using ÀÖÇ or ÀÓÔÝÇ,see Figs. 5.20 and 5.21.5.4.4 ÀÈÙØÁÑÀÈÙØÁÑ (see Fig. 5.19) stores the gray value channel (image matrix) Ñ in the data base3 ÀÈÙØÊÄ actually copies the data itself, not only a pointer to the data.HALCON 6.0

74 CHAPTER 5. HANDLING ICONIC OBJECTS AND CONTROL PARAMETERSÀÝ ÓÝÒ¸ÓÝÓÙظÖÝÓÙØÀÖÐÖÓÒ ÖÓÒÒÀÖÐÖÓÒ ÖÓÒÓÙØÁÆÌ ÒÙÑÓ׺ººÔÖÒ ½ » ÒÙÑÖ Ó ÒÔÙØ ÔÖÑØÖ »ÔÖÓÙØ ½ » ÒÙÑÖ Ó ÓÙØÔÙØ ÔÖÑØÖ »ÀÊδÔÖÓÒиÀÒÙÑÓ¸²ÒÙÑÓ׸ÔÖÒµÓÖ ´Ó½ ÓÒÙÑÓ× Ó··µ ßÀØÇ´ÔÖÓÒиÔÖÒ¸Ó¸²ÓÝÒµÀØÊÄ´ÔÖÓÒиÓÝÒ¸²ÖÓÒÒµ» ÓÑÔÙØ ×ÓÑ ÖÓÒ ØÖÒ×ÓÖÑØÓÒ ººº »ØÖÒ×ÓÖÑ´ÖÓÒÒ¸ÖÓÒÓÙصÀÓÔÝÇ´ÔÖÓÒиÓÝÒ¸ÔÖÓÙظ²ÓÝÓÙصÀÈÙØÊÄ´ÔÖÓÒиÓÝÓÙظÖÓÒÓÙظ²ÖÝÓÙصÐFigure 5.20: Create an image object with ÀÓÔÝÇ and insert a region component.and returns the corresponding data base key in the parameter Ó Ý. This key can be usedto insert the gray value channel (now encapsulated in a data base object) as a component of anarbitrary number of image objects (see ÀÇ in section 5.4.5). The parameter ÓÔÝ (ÄËor ÌÊÍ) specifies, whether the pixel data is copied to the HALCON data base 4 or only theaddress of the data is passed to the data base object. Fig. 5.21 shows a typical example for howto use ÀÈÙØÁÑ.ÀÑ ÑÀÖÐÖÓÒ ÖÓÒÀÝ ÑݸÓݺºº» ÔÖÓ×× Ñ Ø Ñ »» ÔÖÓ×× ÖÓÒ Ø ÖÓÒ »ÔÖÒÙÑ ½ÀÈÙØÁÑ´ÔÖÓÒи²Ñ¸ÌÊ͸²ÑݵÀÖÇ´ÔÖÓÒиÔÖÒÙѸ²ÓݵÀÇ´ÔÖÓÒиÓݸÑݸÁÅÁƵÀÈÙØÊÄ´ÔÖÓÒиÓݸÖÓÒ¸²ÖÓÒݵFigure 5.21: Creating a new image object using basic Extension Package Interface routines.5.4.5 ÀÇÀÇ (see Fig. 5.19) reassigns the component ÓÑÔ (¼ Ò) of an image object given byits data base key ÓÑÔ Ý. A typical application of this routine is shown in Fig. 5.21: Imagedata is stored in a data base object using ÀÈÙØÁÑ. Furthermore, a new image object iscreated by ÀÖÇ. This new object does not contain any gray value channels, see section 5.4.1.4 This is necessary if the original data is stored in temporary memory or if the data will be modified later on.HALCON Extension Package Interface / 2000-11-16

5.4. CREATING OBJECTS AND WRITING OUTPUT OBJECT PARAMETERS 75Using ÀÇ the previously stored image data is assigned as default gray value component 1(ÁÅ ÁÆ) of the new image object.5.4.6 ÀÈÙØÁÑÀÈÙØÁÑ (see Fig. 5.19) combines ÀÈÙØÁÑ and ÀÇ. It stores the gray value channel(image matrix) Ñ in the HALCON data base and returns the corresponding data basekey in Ñ Ý. The parameter ÓÔÝ (ÄË or ÌÊÍ) is used as in ÀÈÙØÁÑ and specifies,whether the pixel data is copied 5 or only a pointer to the data is passed to the data base.Moreover, the gray value channel is inserted into the image object Ó Ý as component ÓÑÔ(½ Ò). Fig. 5.22 shows a typical application of this routine.ÀÝ ÓݸÀÑ ÑÀÖÐÖÓÒ ÖÓÒººº» Ñ ÔÖÓ×× ÖÝ ÚÐÙ Ø »» ÖÓÒ ÖÓÒ Ø »ÀÖÇ´ÔÖÓÒиÔÖÒÙѸ²ÓݵÀÈÙØÁÑ´ÔÖÓÒиÓݸÁÅÁƸ²Ñ¸Ä˸²µÀÈÙØÊÄ´ÔÖÓÒиÓݸÖÓÒ¸²µFigure 5.22: Creating a new image object using ÀÈÙØÁÑ and ÀÈÙØÊÄ.5.4.7 ÀÖÁÑÀÖÁÑ (see Fig. 5.19) is used for creating output images especially in the context of filter 6operations. As you know, HALCON image objects can share the underlying image matrices(gray value channels). Thus, input image objects of a filter operation might only differ in theirarea of definition (that is in their region component), but not in their gray values. Such objectshave different data base keys and different regions, but contain references to the same gray valuechannels. Obviously, it is very desirable to propagate this relation to the resulting output imageobjects as well.ÀÖÁÑ allocates memory for the image matrix within the ÀÑ structure Ñ ÓÙØ(similar to ÀÆÛÁÑ in section 3.2.2). The parameters ØÝÔ (Ì ÁÅ, ÄÇÆ ÁÅ,ÄÇÌ ÁÅ etc.; see Fig. 4.2 on page 50), ÛØ and Ø allow to specify the pixeltype and the size of the new matrix. Note, that new matrices are by default initialized with 0.However, this can be suppressed from outside or inside of the operator, see the discussion ofÀÆÛÁÑ in section 3.2.2 for details.Furthermore, ÀÖÁÑ creates a new data base object encapsulating this image data and returnsthe corresponding data base key in Ñ Ý ÓÙØ (similar to ÀÈÙØÁÑ in section 5.4.4).Finally, ÀÖÁÑ establishes a link between the original input image data (referenced by thedata base key Ñ Ý Ò) and this new object to avoid the allocation of multiple output5 This is necessary, if the pixel data was stored in temporary memory or if it will be modified later on.6 This is due to the fact, that filter only modify the gray values but not the regions of image objects.HALCON 6.0

76 CHAPTER 5. HANDLING ICONIC OBJECTS AND CONTROL PARAMETERSÀÝÀÖÐÖÓÒÀÑÓݸÑÝÒ¸ÑÝÓÙظÝÓÙØÖÓÒÑÒ¸ÑÓÙغººÀØËÈÖ´ÔÖÓÒи½¸ÄÇÆÈʸ²ÊÓÛ׸½µ » Ø ÐØÖ Ñ× »ÀØËÈÖ´ÔÖÓÒи¾¸ÄÇÆÈʸ²ÓÐ׸½µ » ÛØ ÐØÖ Ñ× »ÀÐÐÇ´ÔÖÓÒи½¸Óݸµ ß » ÐÐ ÑÔÙØ Ñ× »ÀØÊÄ´ÔÖÓÒиÓݸ²ÖÓÒµ » Ø ÖÓÒ Ø »ÀØÓÑÔ´ÔÖÓÒиÓݸÁŽ¸²ÑÝÒµ ´ÑÝÒ ÍÆÁƵÖØÙÖÒ´ÀÊÊÍÆÁµ » ³ÙÒÒ Ñ³ »ÀØÁÑ´ÔÖÓÒиÑÝÒ¸²ÑÒµ »Ø Ñ Ø»ÀÈ´ÀÖÁÑ´ÔÖÓÒиÑÝÒ¸½¸ÑÒºÒ¸ÑÒºÛظÑҺظ²ÑÝÓÙظ²ÑÓÙصµÐÀÈ´ÁÈÐØÖÇÔÖØÓÒ´²ÑÒ¸ÖÓÒ¸ÊÓÛ׸ÓÐ׸²ÑÓÙصµÀÓÔÝÇ´ÔÖÓÒиÓݸ½¸²ÝÓÙص » ÖØ Ö×ÙÐØ Óº»ÀÇ´ÔÖÓÒиÝÓÙظÑÝÓÙظÁŽµ» Ò×ÖØ Ø Ö×ÙÐØ Ñ Ò ÓÙØÔÙØ ÓØ »Figure 5.23: A typical example for using ÀÖÁÑ: Providing an empty image matrix for a filteroperation.matrices per input matrix. ÀÖÁÑ checks, whether there already exists an output matrix withthe specified index ÒÜ (see below) for a given input image Ñ Ý Ò. If there is any,only a reference to it is returned in Ñ ÓÙØ and Ñ Ý ÓÙØ instead of creating a newmatrix. Without this mechanism, a new matrix would be created again and again within theloop over all input objects (ÀÐÐÇ).The parameter ÒÜ is only of importance, if more than one output matrix per input matrixis needed: This is necessary for example, if an edge filter is performed in x- and y-directionindependently. In this case ÀÖÁÑ must be called several times for every input component– one time for each output matrix to be created. Assign increasing numbers (1, 2, 3, ...) totheparameter ÒÜ to indicate a new output matrix. If there is only one matrix to create for theoutput image set ÒÜ to 1.Fig. 5.23 shows an exemplary application of ÀÖÁÑ.5.4.8 ÀÖÄÀÖÄ (see Fig. 5.18) is used for creating XLD objects in the HALCON data base. Theparameter ÜÐ ØÝÔ allows to specify the kind of XLD to be created: It has to be set toÄ ÇÆÌÇÍÊ Á in case of a contour and to Ä ÈÇÄÇÆ Á in case of a polygon. Correspondingto the selected type ÀÖÄ expects a pointer to ÀÓÒØ or a pointer to ÀÔÓÐÝ in theHALCON Extension Package Interface / 2000-11-16

5.4. CREATING OBJECTS AND WRITING OUTPUT OBJECT PARAMETERS 77parameter ÜÐ. In both cases not the underlying XLD data but only the pointers to the data arecopied to the data base. Thus, you must not deallocate or overwrite the XLD structures aftercalling ÀÖÄ.ÀÔÖÁÆÌÀÝÀÓÒØÖÓÛ×℄¸ ÓÐ×℄¸ÒÙÑÔÓÒØ×ÝÓÙØÓÒغººÀØÈÖ´ÔÖÓÒи½¸ÄÇÌÈʸÖÓÛ׸½¸¸²ÒÙÑÔÓÒØ×µÀØÈÖ´ÔÖÓÒи¾¸ÄÇÌÈʸÓÐ׸½¸¸²ÒÙÑÔÓÒØ×µ» ÖØ ÓÒØÓÙÖ ´Ò ÒÖи Ø× ×ÓÙÐ ÓÒ »» ÐÐÒ Ò ÔÔÖÓÔÖØ ØÓÒ ÔÖÓÙÖµ »ÀÈ´ÀÐÐÓÄÓÒØ´ÔÖÓÒи²ÓÒظÒÙÑÔÓÒØ×µµÓÖ ´¼ ÒÙÑÔÓÒØ× ·· ßÓÒعÖÓÛ℄ ÖÓÛ×℄ºÔÖºÓÒعÓÐ℄ ÓÐ×℄ºÔÖºÐÓÒعÒÙÑ ÒÙÑÔÓÒØ×ÀÖÄ´ÔÖÓ¸½¸ÓÒظÄÇÆÌÇÍÊÁ¸ÆÍÄĸ¼¸´ÖÈÖÓµÀÄÖÓÒØÓÙÖ¸²ÝÓÙصFigure 5.24: A typical example for using ÀÖÄ: Create an XLD contour from a list of points.ÀÝÀÓÒØÀÔÓÐÝÓݸÝÓÙØÓÒØÔÓÐݺººÀÐÐÇ´ÔÖÓÒи½¸Óݸµ ßÀØÄ´ÔÖӸݸÄÇÆÌÇÍÊÁ¸´ÚÓµ²ÓÒصÀÈ´ÀÐÐÓ´ÔÖÓÒи´×Þص×ÞÓ´ÀÔÓÐݵ¸²ÔÓÐݵµµ» ÔÔÖÓÜÑØ ÓÒØ Ý ÔÓÐÝ »ÀÈ´ÀÄÈÓÐÝÓÒ´ÔÖÓÒиÓÒظººº¸²ÔÓÐݵµÀÖÄ´ÔÖÓÒи½¸ÔÓÐݸÄÈÇÄÇÆÁ¸²Óݸ½¸´ÖÈÖÓµÀÄÖÈÓÐÝÓÒ¸²ÝÓÙصÐFigure 5.25: Another typical example for using ÀÖÄ: Create XLD polygons based on XLDcontours.XLD polygons contain a reference to the underlying contours (if any), see the definition ofÀÔÓÐÝ in Fig. 4.10, section 4.3. Such a dependency between XLDs can be specified in ÀÖÄby passing an array of data base keys in Ù× ÜÐ× and the corresponding number of keys inÒÙÑ Ù× ÜÐ×. For contours these parameters typically are set to ÆÍÄÄ and ¼.ÀÖÄ expects an appropriate deallocation routine for the XLD data in the parameterÖ ÔÖÓ. Please useHALCON 6.0

78 CHAPTER 5. HANDLING ICONIC OBJECTS AND CONTROL PARAMETERS´ÖÈÖÓµ ÀÄÖÓÒØÓÙÖfor XLD contours and´ÖÈÖÓµ ÀÄÖÈÓÐÝÓÒfor XLD polygons allocated based on ÀÐÐÓ.Finally, ÀÖÄ not only creates a new data base object, but also appends this object to theoutput object parameter with number ÔÖ ÒÙÑ. Fig. 5.24 and 5.25 show two typical applicationsof ÀÖÄ.5.5 Reading and Writing Control ParametersThis section describes routines for reading and writing in-/output control parameters, seeFig. 5.26. Interchanging control data with the host language is done via the data type ÀÔÖ(see section 4.4).5.5.1 ÀØÈÖÀØÈÖ (see Fig. 5.26) reads the parameter values of the input control parameter numberÔÖ ÒÙÑ (½ Ò) and writes them to the array ÚÐ of ÀÔÖ structures, that must has beenallocated before with a suitable size (note, that ).Note, that for every input value, its type (ÄÇÆ ÈÊ, ÄÇÌ ÈÊ, ËÌÊÁÆ ÈÊ ) is also storedwithin the ÀÔÖ structure. Thus, it is possible to pass different control data types within onecontrol parameter of a HALCON operator. The current number of values is returned in ÒÙÑ.ÀØÈÖ allows to restrict the parameter access in two respects:¯ The expected type can be specified by ØÝÔ. This also includes type combinations suchas ÄÇÆÈÊ ÄÇÌÈÊ.¯ The expected number of values can be specified by the interval (ÑÒ,ÑÜ), whereas ÑÜshould not exceed the number of allocated ÀÔÖ elements within the array ÚÐ.If the specified number or types of values are violated, ÀØÈÖ exits the supply procedurewith an appropriate error message. Fig. 5.27 shows an application of ÀØÈÖ.Note, that in case of string parameters, memory has to be allocated for ÚÐ℄ºÔÖº×. TheeasiestwaytodothisistouseÀÐÐÓËØÖÒÅÑ specifying the expected number of charactersfor all input strings, see section 5.5.7.5.5.2 ÀØËÈÖÀØËÈÖ (see Fig. 5.26) is a simplified version of ÀØÈÖ. In contrast to the latter a fixednumber of parameter values is read, see Fig. 5.28. Therefore, the routine does not return theactual number 7 of values.7 This number is fixed. If more or less values are passed to the HALCON operator, ÀØËÈÖ exits the supplyHALCON Extension Package Interface / 2000-11-16

5.5. READING AND WRITING CONTROL PARAMETERS 79NamesÀØÈÖ¸ ÀØËÈÖ¸ ÀØÈÈÖ¸ ÀØÈÖÆÙѸÀÈÙØÈÖ¸ ÀÈÙØÈÈÖ¸ ÀÐÐÓËØÖÒÅÑSynopsisÒÐÙ ÀÐÓÒºÀØÈÖ´ ÀÔÖÓÒÐ ÔÖÓÒиÁÆÌÔÖÒÙѸÁÆÌØÝÔ¸ÀÔÖÚиÁÆÌ ÑÒ¸ÑܸÁÆÌ ÒÙѵÀØËÈÖ´ ÀÔÖÓÒÐ ÔÖÓÒиÁÆÌÔÖÒÙѸÁÆÌØÝÔ¸ÀÔÖÚиÁÆÌ ÒÙѵÀØÈÈÖ´ ÀÔÖÓÒÐ ÔÖÓÒиÁÆÌ ÔÖÒÙѸ ÀÔÖ ÚиÁÆÌ ÒÙѵÀØÈÖÆÙÑ´ÀÔÖÓÒÐ ÔÖÓÒиÁÆÌ ÔÖÒÙѸÁÆÌ ÒÙѵÀÈÙØÈÖ´ ÀÔÖÓÒÐ ÔÖÓÒиÁÆÌÔÖÒÙѸÀÔÖÚиÁÆÌ ÒÙѵÀÈÙØÈÈÖ´ ÀÔÖÓÒÐ ÔÖÓÒиÁÆÌÔÖÒÙѸÀÔÖÚиÁÆÌ ÒÙѵÀÐÐÓËØÖÒÅÑ´ÀÔÖÓÒÐ×ÞØÔÖÓÒи×ÞµFigure 5.26: Routines for handling control parameters.5.5.3 ÀØÈÖÆÙÑÀØÈÖÆÙÑ (see Fig. 5.26) returns the number of single control values of the input controlprocedure with an error.HALCON 6.0

80 CHAPTER 5. HANDLING ICONIC OBJECTS AND CONTROL PARAMETERSÀÔÖÀÔÖÔÖ½¸ÔÖ¾ÔÖ¿½¼℄» ÐÐÓØ ÑÑÓÖÝ ÓÖ ×ØÖÒ× »ÀÐÐÓËØÖÒÅÑ´ÔÖÓÒи½¼¼¼µ» Ö ×ÓÖØ»ÒØ»ÐÓÒ ÚÐÙ Ò ÔÖÑØÖ ÒÙÑÖ ½ »ÀØÈÖ´ÔÖÓÒи½¸ÄÇÆÈʸ²ÔÖ½¸½¸½¸²ÒÙѵ» ÒÓÛ ÔÖ½ºÔֺР»» Ö ×ØÖÒ Ò ÔÖÑØÖ ÒÙÑÖ ¾ »ÀØÈÖ´ÔÖÓÒи¾¸ËÌÊÁÆÈʸ²ÔÖ¾¸½¸½¸²ÒÙѵ» ÒÓÛ ÔÖ¾ºÔÖº× ÌÜØ »» Ö ØÙÔÐ Ó ÐÓØ ÚÐÙ× Ò ÔÖÑØÖ ÒÙÑÖ ¿ »» ´Ñܺ ½¼ ÚÐÙ×µ »ÀØÈÖ´ÔÖÓÒи¿¸ÄÇÌÈʸÔÖ¿¸½¸½¼¸²ÒÙѵÓÖ ´¼ ÒÙÑ ··µ ß» ÔÖ¿℄ºÔÖº ¼º¸½º¸º »ºººFigure 5.27: Read the control parameter values of the operator callÑÓ´¸³ÌÜس¸¼º¸½º¸º℄µ using ÀØÈÖ.ÀÔÖÀÔÖÔÖ½¸ÔÖ¾ÔÖ¿¿℄» ÐÐÓØ ÑÑÓÖÝ ÓÖ ×ØÖÒ× »ÀÐÐÓËØÖÒÅÑ´ÔÖÓÒи½¼¼¼µ» Ö ×ÓÖØ»ÒØ»ÐÓÒ ÚÐÙ Ò ÔÖÑØÖ ÒÙÑÖ ½ »ÀØËÈÖ´ÔÖÓÒи½¸ÄÇÆÈʸ²ÔÖ½¸½µ» ÒÓÛ ÔÖ½ºÔֺР»» Ö ×ØÖÒ Ò ÔÖÑØÖ ÒÙÑÖ ¾ »ÀØËÈÖ´ÔÖÓÒи¾¸ËÌÊÁÆÈʸ²ÔÖ¾¸½µ» ÒÓÛ ÔÖ¾ºÔÖº× ÌÜØ »» Ö ØÙÔÐ Ó ¿ ÐÓØ ÚÐÙ× Ò ÔÖÑØÖ ÒÙÑÖ ¿ »ÀØËÈÖ´ÔÖÓÒи¿¸ÄÇÌÈʸÔÖ¿¸¿µÓÖ ´¼ ÒÙÑ ··µ ß» ÔÖ¿℄ºÔÖº ¼º¸½º¸º »ºººFigure 5.28: Read the control parameter values of the operator callÑÓ´¸³ÌÜس¸¼º¸½º¸º℄µ using ÀØËÈÖ.parameter number ÔÖ ÒÙÑ (½ Ò). This makes it possible to allocate exactly as much memoryfor parameter values as needed for reading them, for example, via ÀØËÈÖ (note that there isan alternative routine ÀØÈÈÖ, which needs no memory to be allocated).5.5.4 ÀØÈÈÖÀØÈÈÖ (see Fig. 5.26) returns the pointer to an array of ÀÔÖ structures, which contain theHALCON Extension Package Interface / 2000-11-16

5.5. READING AND WRITING CONTROL PARAMETERS 81ÀÔÖÀÔÖÁÆÌÔÖ½¸ÔÖ¾ÔÖ¿ÒÙÑ» ÐÐÓØ ÑÑÓÖÝ ÓÖ ×ØÖÒ× »ÀÐÐÓËØÖÒÅÑ´ÔÖÓÒи½¼¼¼µ» Ö ×ÓÖØ»ÒØ»ÐÓÒ ÚÐÙ Ò ÔÖÑØÖ ÒÙÑÖ ½ »ÀØËÈÖ´ÔÖÓÒи½¸ÄÇÆÈʸ²ÔÖ½¸½µ» ÒÓÛ ÔÖ½ºÔֺР»» Ö ×ØÖÒ Ò ÔÖÑØÖ ÒÙÑÖ ¾ »ÀØËÈÖ´ÔÖÓÒи¾¸ËÌÊÁÆÈʸ²ÔÖ¾¸½µ» ÒÓÛ ÔÖ¾ºÔÖº× ÌÜØ »» Ö ØÙÔÐ Ó ÐÓØ ÚÐÙ× Ò ÔÖÑØÖ ÒÙÑÖ ¿ »» Ö×ظ Ø Ø ÒÙÑÖ Ó ÚÐÙ× »ÀØÈÖÆÙÑ´ÔÖÓÒи¿¸²ÒÙѵ» ÒÓÛ ÒÙÑ ¿ »» ×ÓÒ¸ ÐÐÓØ ÑÑÓÖÝ ÓÖ Ø ÚÐÙ× Ò Ö ØÑ »ÀÈ´ÀÐÐÓÌÑÔ´ÔÖÓÒи´ÚÓµ²ÔÖ¿¸´×Þص´ÒÙÑ×ÞÓ´ÀÔÖµµµµÀØËÈÖ´ÔÖÓÒи¿¸ÄÇÌÈʸÔÖ¿¸ÒÙѵÓÖ ´¼ ÒÙÑ ··µ ß» ÔÖ¿℄ºÔÖº ¼º¸½º¸º »ºººFigure 5.29: Use ÀØÈÖÆÙÑ to get the number of control values before reading the controlparameter values of the operator call ÑÓ´¸³ÌÜس¸¼º¸½º¸º℄µ.parameter values of the input control parameter number ÔÖ ÒÙÑ (½ Ò). It is an alternativeto ÀØÈÖ (see page 78). However, ÀØÈÈÖ is much more efficient in terms of memoryoverhead, because it just returns pointers to the values instead of copying them. Thus, the callerneeds not to allocate any memory before calling ÀØÈÈÖ. On the other hand, the parametervalues may only be read and must not be modified. Note, that for every parameter value, itstype (ÄÇÆ ÈÊ, ÄÇÌ ÈÊ, ËÌÊÁÆ ÈÊ ) is also stored within the ÀÔÖ structure. This isnecessary, because the same control parameter may contain values of different control datatypes. The current number of parameter values is returned in ÒÙÑ.Figure 5.30 shows the usage of ÀØÈÈÖ based on the example which was also used forÀØÈÖ (compare figure 5.27 on page 80).5.5.5 ÀÈÙØÈÖÀÈÙØÈÖ (see Fig. 5.26) writes control data to the output control parameter number ÔÖ ÒÙÑof a HALCON operator. The ÒÙÑ values in the ÀÔÖ structure ÚÐ are copied by this routine.Note, that the types of the parameter values (ÄÇÆ ÈÊ, ÄÇÌ ÈÊ, ËÌÊÁÆ ÈÊ ) are storedwith each ÀÔÖ structure. This allows to use a different type for every data element, seeFig. 5.31.HALCON 6.0

82 CHAPTER 5. HANDLING ICONIC OBJECTS AND CONTROL PARAMETERSÀÔÖ ØÖÐÚн » ÖÖÝ Ó ÀÔÖ ×ØÖÙØÙÖ× »ÁÆÌ ÒÙÑ » ÒÙÑÖ Ó ÚÐÙ× Ó ÔÖÑØÖ ½ »ÀÔÖ ØÖÐÚоÀÔÖ ØÖÐÚп» Ö ÐÐ ÚÐÙ× Ó ÔÖÑØÖ ÒÙÑÖ ½ »ÀØÈÈÖ´ÔÖÓÒи½¸²ØÖÐÚн¸²ÒÙѵ» ÒÓÛ ØÖÐÚн¼℄ºÔֺР»» Ö ×ØÖÒ Ò ÔÖÑØÖ ÒÙÑÖ ¾ »ÀØÈÈÖ´ÔÖÓÒи¾¸²ØÖÐÚо¸²ÒÙѵ» ÒÓÛ ØÖÐÚо¼℄ºÔÖº× ÌÜØ »» Ö ØÙÔÐ Ó ÐÓØ ÚÐÙ× Ò ÔÖÑØÖ ÒÙÑÖ ¿ »» ´ÑÝ ÒÝ ÒÙÑÖ Ó ÚÐÙ×µ »ÀØÈÈÖ´ÔÖÓÒи¿¸²ØÖÐÚп¸²ÒÙѵÓÖ ´¼ ÒÙÑ ··µ ß» ØÖÐÚп℄ºÔÖº ¼º¸½º¸º »ºººFigure 5.30: Read the control parameter values of the operator callÑÓ´¸³ÌÜس¸¼º¸½º¸º℄µ using ÀØÈÈÖ.ÀÔÖÔÖ¾℄ÔÖ¼℄ºÔֺРÔÖ¼℄ºØÝÔ ÄÇÆÈÊÔÖ½℄ºÔÖº ºÔÖ½℄ºØÝÔ ÄÇÌÈÊÀÈÙØÈÖ´ÔÖÓÒи½¸ÔÖ¸¾µFigure 5.31: Write the control parameter values ¸º℄ using ÀÈÙØÈÖ.5.5.6 ÀÈÙØÈÈÖÀÈÙØÈÈÖ (see Fig. 5.26) is an alternative to ÀÈÙØÈÖ and writes control data to the outputcontrol parameter number ÔÖ ÒÙÑ. However, instead of copying the ÒÙÑ values like ÀÈÙØÈÖdoes, ÀÈÙØÈÈÖ directly stores the pointer to the array of ÀÔÖ structures (ÚÐ). Thus, itcauses less overhead. As ÀÈÙØÈÈÖ directly uses the passed ÀÔÖ array without copying, thisarray has to be allocated “permanently”, i.e. it must be allocated by using ÀÐÐÓ (see section3.2.2 on page 42). Furthermore, the array must not be given free after passing it to ÀÈÙØÈÈÖ.Figure 5.32 shows how to write output control data with ÀÈÙØÈÈÖ.Note again, that the types of the parameter values (ÄÇÆ ÈÊ, ÄÇÌ ÈÊ, ËÌÊÁÆ ÈÊ ) arestored with each ÀÔÖ structure, so that every data element may use a different type.5.5.7 ÀÐÐÓËØÖÒÅÑIn case of string parameters, additional memory for the parameter values has to be allocated,because the ÀÔÖ structure only contains a pointer to Ö. The easiest way to do this is to useHALCON Extension Package Interface / 2000-11-16

5.6. AUXILIARY MACROS AND PROCEDURES 83ÀÔÖÔÖÀÈ´ÀÐÐÓ´ÔÖÓÒи´×Þص´×ÞÓ´ÀÔÖµ¾µ¸´ÎÇÁȵ²ÔÖµµÔÖ¼℄ºÔֺРÔÖ¼℄ºØÝÔ ÄÇÆÈÊÔÖ½℄ºÔÖº ºÔÖ½℄ºØÝÔ ÄÇÌÈÊÀÈÙØÈÈÖ´ÔÖÓÒи½¸ÔÖ¸¾µFigure 5.32: Write the control parameter values ¸º℄ using ÀÈÙØÈÈÖ.ÀÐÐÓËØÖÒÅÑ (see Fig. 5.26) specifying the expected number of characters for all inputstrings (parameter ×Þ) at the begin of a supply procedure, see Fig. 5.27 and 5.28. It is notnecessary to deallocate this memory explicetly — this is done automatically at the end of thesupply procedure.5.6 Auxiliary Extension Package Interface Macros andProceduresIn this section a couple of auxiliary routines are described that facilitate the programming ofsupply or action procedures, see Fig. 5.33.5.6.1 ÀÈThe macro ÀÈ (see Fig. 5.33) checks the result state of a procedure call. Most of the HAL-CON procedures are of the type ÀÖÖÓÖ 8 . For internal HALCON procedures the result codeÀ ÅË Çà is returned if no error occurred, see also section 3.6. ÀÈ exits the current procedureif the encapsulated procedure returns any other error code. Moreover, this error code is returnedto the caller of the current procedure.The macro is used to make source code more compact, but still safe with respect to error handling,see Fig. 5.34: Here, the call of the procedure ÀÊÄÓÑÔ is encapsulated within themacro. If any error occurs, the procedure exits with an appropriate error number. Otherwise theprocessing is continued.Be aware, that all memory permanently allocated within a procedure will not be deallocatedin case of an error if you exit the procedure using ÀÈ. This will lead to memoryleaks.8 All interface routines called in the examples in this chapter without being encapsulated by ÀÈ have a functionalitycomparable to ÀÈ, i.e. they exit the current procedure returning an appropriate error number in case ofan error.HALCON 6.0

84 CHAPTER 5. HANDLING ICONIC OBJECTS AND CONTROL PARAMETERSNamesÀȸ ÀÆÓǸ ÀÊÄÓÑÔ¸ ÀÆÙÑÇÒÒÐ×SynopsisÒÐÙ ÀÐÓÒºÀÈ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÖÖÓÖ ´ÔÖÓµµÀÆÓÇ´ ÀÔÖÓÒÐ ÔÖÓÒеÀÖÖÓÖ ÀÊÄÓÑÔ´ ÀÔÖÓÒÐÀÖÐÖÓÒÁÆÌÀÖÐÖÓÒÀÖÐÖÓÒÔÖÓÒиÖÒ¸Ö½¸½¸Ö¾¸¾¸ÖÒÒÖ¸ÖÓÙØÖµÀÆÙÑÇÒÒÐ×´ ÀÔÖÓÒÐ ÔÖÓÒиÁÆÌ ÓÒܸÁÆÌÒÙÑÒÒÐ×µFigure 5.33: Auxiliary Extension Package Interface Macros and Procedures.ÀÖÖÓÖÖÖ» ÛØÓÙØ ÀÈ »ÖÖ ÀÊÄÓÑÔ´ÔÖÓÒиÖÒ¸Ö½¸½¸Ö¾¸¾¸ÖÒÒÖ¸ÖÓÙØÖµ ´ÖÖ ÀÅËÇõ ÖØÙÖÒ ÖÖ» ÛØ ÀÈ »ÀÈ´ÀÊÄÓÑÔ´ÔÖÓÒиÖÒ¸Ö½¸½¸Ö¾¸¾¸ÖÒÒÖ¸ÖÓÙØÖµµFigure 5.34: Error handling with ÀÈ.5.6.2 ÀÆÓÇThe macro ÀÆÓÇ (see Fig. 5.33) is used to check whether all iconic input parameters of anoperator contain at least one object. Otherwise the supply procedure is exited with a return codedepending on the current setting of³ÒÓÓØÖ×ÙÐسaccessible by the HALCON operators ×Ø ×Ý×ØÑ and Ø ×Ý×ØÑ (see the Reference Manualsfor details). The default setting for ÒÓ ÓØ Ö×ÙÐØ is À ÅË ÌÊÍ, that means ÀÆÓÇHALCON Extension Package Interface / 2000-11-16

5.6. AUXILIARY MACROS AND PROCEDURES 85reports “no error” in case of empty iconic input parameters. Note, that in this case all outputparameters are also empty.We recommend to callÀÆÓÇ´ÔÖÓÒеat the beginning of the supply procedure for every operator with iconic input objects to guaranteethe existence of iconic data to be processed within the operator.5.6.3 ÀÊÄÓÑÔÀÊÄÓÑÔ (see Fig. 5.33) is an auxiliary procedure to ease border treatment within theaction procedures of filter operators based on filter masks. It’s prototype is included inлÀÊÄÐÔº.ÀÖÖÓÖ ÁÈÐØÖ´ÀÔÖÓÒÐ ÔÖÓÒи » ÔÖÓº ÒÐ »ÀÌ Ò¸ » ÒÔÙØ Ñ »ÀÖÐÖÓÒ ÖÓÒ¸ » Ö Ó º »ÁÆÌ Ûظظ » Ñ ×Þ »ÀÌ ÓÙص » ÓÙØÔÙØ Ñ »ßºººÀÖÐÖÓÒ ÒÒÖ¸ÓÙØÖÐÀÈ´ÀÐÐÓÊÄÆÙÑÌÑÔ´ÔÖÓÒи²ÒÒÖ¸ÖÓÒ¹ÒÙѵµÀÈ´ÀÐÐÓÊÄÆÙÑÌÑÔ´ÔÖÓÒи²ÓÙØÖ¸ÖÓÒ¹ÒÙѾµµÀÈ´ÀÊÄÓÑÔ´ÔÖÓÒиÖÓÒ¸½¸½¸Ø¹¾¸Ûع¾¸²ÒÒÖ¸²ÓÙØÖµµ» ÐØÖÒ ÛØÓÙØ ÓÖÖ ØÖØÑÒØ »ÓÖ ´¼ ÒÒÖ¹ÒÙÑ ··µÓÖ ´´ÒÒÖ¹Öи¸Ûص ´ÒÒÖ¹Öи¸Ûص ··µÓÙØ℄ ººº» ÐØÖÒ ÛØ ÓÖÖ ØÖØÑÒØ »ÓÖ ´¼ ÓÙØÖ¹ÒÙÑ ··µÓÖ ´´ÓÙØÖ¹Öи¸Ûص ´ÓÙØÖ¹Öи¸Ûص ··µÓÙØ℄ ºººÀÈ´ÀÖÊÄÌÑÔ´ÔÖÓÒиÓÙØÖµµÀÈ´ÀÖÊÄÌÑÔ´ÔÖÓÒиÒÒÖµµFigure 5.35: Border treatment for a ¿ ¢ ¿ filter.The region (respectively area of definition) Ö Ò of the image to be processed is split intotwo parts: Ö ÒÒÖ and Ö ÓÙØÖ. Note, that both new regions must have been allocatedbefore, see section 3.2.1.Ö ÒÒÖ is the original region Ö Ò minus the pixels around the image border. It containsall pixels within the rectangle specified by the upper left corner 9 (Ö½,½) and the lower right9 Ö½ andr2denoterow coordinates, ½ and ¾ column coordinates.HALCON 6.0

86 CHAPTER 5. HANDLING ICONIC OBJECTS AND CONTROL PARAMETERScorner (Ö¾,¾). These coordinates should be selected that way, that the filter mask is completelywithin the image when placed on any pixel inside of the rectangle. Thus, no border treatment isnecessary within Ö Ò.Ö ÓÙØ is set to all remaining pixels within Ö Ò. For those pixels an appropriate (and timeconsuming) border treatment has to be done. Fig. 5.35 shows an application of ÀÊÄÓÑÔ.Note, that the distinction of “inner” and “outer” area only refers to the image border, but not tothe border of the regions specifying the area of definition. So, it is only ensured that no memoryaccess to positions outside the image matrix can happen, but there is no guarantee that all pixelvalues covered by the filter mask when placed on pixels within Ö ÒÒÖ are defined, iftheydo not belong to Ö Ò. This means, a filter might use undefined gray values along the borderof the area of definition of the input images. The HALCON user should keep that in mind, whenapplying a sequence of filters to restricted regions of interest.5.6.4 ÀÆÙÑÇÒÒÐ×ÀÆÙÑÇÒÒÐ× (see Fig. 5.33) returns for the first input object parameter of a HALCONoperator the number of channels of the image object with number Ó ÒÜ. Thus, this routineis just a shortcut for using ÀÈÆÙÑÇÒÒÐ× as defined in Fig. 5.5 with ÔÖ ÒÙÑ ½.HALCON Extension Package Interface / 2000-11-16

Chapter 6Special Routines for Typical SupplyProceduresIn the previous chapter the basic routines for handling iconic objects, object parameters, andcontol parameters of a HALCON operator have been introduced. Based on these this chapterdescribes a set of convenience routines that facilitate the programming of supply procedures intypical situations.6.1 Loop MacrosA frequently needed task is to process all image objects (images or regions) passed to an operatorby one or two input object parameters. This is true for example for most filter and manysegmentation operators. Loop macros provide a framework for this problem, see also section5.3.All macros described in this section have in common that they implement a loop over all imageobjects within the first input object parameter. ÀÐÐÐØÖ¾ also includes a parallel loop overall objects within the second input object parameter. It is assumed that the operator does nothave any more input object parameters. The macros provide users with the region and pixeldata of each image object so that they can work on the data within the loop. Some also createoutput image objects .The macros return the index of the current object Ó ÒÜ (½ Ò) within the input objectparameter. Thus, Ó ÒÜ can be seen as a reference parameter of the macro and therefore isnotated 1 with ’²Ó ÒÜ’. The following table contains an overview of all loop macros, theirareas of application, and the provided image data. Their syntax is defined in Fig. 6.1.1 Note, that this is a specific notation only - do not pass pointers to the macros!87

88 CHAPTER 6. SPECIAL ROUTINES FOR TYPICAL SUPPLY PROCEDURESMacro Application Image Data ProvidedÀÐÐÊÀÐÐËÑÀÐÐÐØÖÀÐÐÐØÖ¾region features,region transformation,binary morphologygray value features,segmentationfilter,image transformationsfilter,segmentation,arithmetics with two input imagesregion data (ÀÖÐÖÓÒ) of inputimage objectregion and image data (ÀÖÐÖÓÒand ÀÑ) of input image objectregion and image data (ÀÖÐÖÓÒand ÀÑ) of input image object,image data structure (ÀÑ) forimage output objectintersection of the regions of bothinput image objects (ÀÖÐÖÓÒ),the image data of both objects, anda image data structure (ÀÑ) forthe image output objectThe macros return all regions as pointers to the original region data within the HALCONdata base. So the programmer is only allowed to read them. The only exception is againÀÐÐÐØÖ¾ that computes the intersection of the region data of both input images and storesit in a new region.6.1.1 ÀÐÐÊÀÐÐÊ (see Fig. 6.1) implements a loop over all objects of the first input image object parameter.For every object within this parameter it returns the region of the object in ÖÓÒ 2 .All gray value channels are ignored.ÀÐÐÊ is a combination of ÀÐÐÇ (see section 5.3.1) and ÀØÊÄ (see section 5.2.2). Itis typically used within feature extraction operators: A list of input regions have to be examinedconcerning special features. Some HALCON operators of this kind are e.g., ÖÙÐÖØÝ,Ö ÒØÖ or ÓÒØÐÒØ. Moreover, it is possible to return new region(s) by using the interfacemacro ÀÆÛÊÓÒ (see page 95) as it is done e.g., by ×ÐØ ×Ô or ×Ô ØÖÒ×.Fig. 6.2 illustrates the application of ÀÐÐÊ showing a complete supply procedure for a hypotheticaloperator ÒØÖ that computes the center of gravity of all input regions. The operatorhas one input object parameter that exclusively contains regions and two output control parametersfor returning the results as tuples of floating-point numbers (the coordinates of the centersof gravity of all regions). The corresponding -file (short version) might look likeÒØÖ ¹ ÁÈÒØÖÊÓÒ×ÊÓÛ×°¸ÓÐÙÑÒ×°℄ÒØÖ may be called with one or more regions as input. ÀÐÐÊ implements a loop over allof them, sets the loop index to the current index of the region (½ Ò), and passes a pointerto the region to the action procedure that performs the center of gravity. In our case the actionprocedure is the internal HALCON procedure ÀÊÄÖ. The result values are written into twoarrays of the type ÀÔÖ and returned by ÀÈÙØÈÖ (see section 5.5.5).2 Remember: HALCON image objects consist of one region specifying the area of definition and an arbitrarynumber of gray value channels containing the pixel dataHALCON Extension Package Interface / 2000-11-16

6.1. LOOP MACROS 89NamesÀÐÐʸ ÀÐÐËѸ ÀÐÐÐØÖ¸ ÀÐÐÐØÖ¾SynopsisÒÐÙ ÀÐÓÒºÀÐÐÊ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÖÐÖÓÒ ÖÓÒ¸ÁÆ̲ÓÒܵÀÐÐËÑ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÖÐÖÓÒ ÖÓÒ¸ÀÑѸÁÆÌÑÜÒÒÐ׸ÁÆ̲ÓÒܵÀÐÐÐØÖ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÖÐÖÓÒ ÖÓÒ¸ÀÑÑÒ¸ÀÑÑÓÙظÁÆÌÑÜÒÒÐ׸ÁÆ̲ÓÒܵÀÐÐÐØÖ¾´ ÀÔÖÓÒÐÀÖÐÖÓÒÀÑÀÑÀÑÁÆÌÁÆÌÔÖÓÒиÖÓÒ¸ÑÒ½¸ÑÒ¾¸ÑÓÙظÑÜÒÒÐ׸²ÓÒܵFigure 6.1: Convenience loop macros to access iconic objects. “&” denotes output parametersof the macros. This is only a special notation to make clear that these parameters are changedby the macros. So do not pass pointers to variables but the variables itself to the macro.Note, that the ÀÔÖ arrays ÊÓÛ and ÓÐ are allocated with a fixed size on the stack usingÅ Ç ÈÊ ÈÊ. This define equals the maximum allowed number of objects per input objectparameter of a HALCON operator. Keep in mind that this number is quite large (100 000 in thecurrent version). Thus, it might be better to allocate the arrays dynamically using ÀÐÐÓÌÑÔ(see section 3.2.1) with only as much elements as needed (see ÀÊ맧ºµ on page 61).6.1.2 ÀÐÐËÑÀÐÐËÑ (see Fig. 6.1) extends ÀÐÐÊ: Not only the region but also all gray value chan-HALCON 6.0

90 CHAPTER 6. SPECIAL ROUTINES FOR TYPICAL SUPPLY PROCEDURESÀÍ×ÖÜÔÓÖØ ÀÖÖÓÖ ÁÈÒØÖ´ÀÔÖÓÒÐ ÔÖÓÒеßÀÔÖ ÊÓÛÅÇÂÈÊÈÊ℄¸ÓÐÅÇÂÈÊÈÊ℄ÓÙÐ ÖÓÛ¸ÓÐÁÆÌ ÖÁÆÌ ÀÖÐÖÓÒ ÖÓÒл Ø Ø ÖÓÒ× Ó ÐÐ ÒÔÙØ ÓØ× Ò Ø Ö×Ø ÔÖѺ »ÀÐÐÊ´ÔÖÓÒи²ÖÓÒ¸µ ßÀÈ´ÀÊÄÖ´ÔÖÓÒиÖÓÒ¸²Ö¸²ÖÓÛ¸²ÓеµÊÓÛ¹½℄ºØÝÔ ÄÇÌÈÊ » ÔÖº ØÝÔ × ÐÓØ »ÊÓÛ¹½℄ºÔÖº ÖÓÛ » Ö×ÙÐØÒ ÖÓÛ »Óй½℄ºØÝÔ ÄÇÌÈÊ » ÔÖº ØÝÔ × ÐÓØ »Óй½℄ºÔÖº ÓÐ » Ö×ÙÐØÒ ÓÐÙÑÒ »ÐÀÈÙØÈÖ´ÔÖÓÒи½¸ÊÓÛ¸µ » ÖØÙÖÒ Ö×ÙÐØ »ÀÈÙØÈÖ´ÔÖÓÒи¾¸Óиµ » ÖØÙÖÒ Ö×ÙÐØ »ÖØÙÖÒ´ÀÅËÌÊ͵Figure 6.2: An application of ÀÐÐÊ: Compute the center of gravity for all input regions in thefirst input object parameter.nels of an object within the first input image object parameter are accessed within a loop.Thus, ÀÐÐËÑ is a combination/modification of ÀÐÐÇ (see section 5.3.1), ÀØÊÄ (seesection 5.2.2), and ÀÐÐÓÑÔ (see section 5.3.2). It is especially useful for segmentation operators(transition of gray value channels to regions). Some typical HALCON operators thatmake use of ÀÐÐËÑ are ØÖ×ÓÐ, ÖÓÒÖÓÛÒ, ÙØÓ ØÖ×Óн, Ð×× Òѽ orÐÐ ØÓ ÖÓÒ.A HALCON image object (in short a HALCON image) consists of one region that specifiesits area of definition and of one or more channels (gray value components) containing the pixeldata. All channels of an image are of the same size, but may have different pixel types. The datacontained in a channel (pixel type, the image matrix etc.) is stored in a structure of type ÀÑ(see section 4.1). If the image has only one channel, the address of a variable of the type ÀÑis passed to ÀÐÐËÑ. For multichannel images an array of the type ÀÑÑÜ ÒÒÐ×℄must be passed to it. The maximal number of channels to be accessed by ÀÐÐËÑ is specifiedby the parameter ÑÜ ÒÒÐ×, see Fig. 6.3.ÀÑ Ñ׿℄ÀÐÐËÑ´ÔÖÓÒиÖÓÒ¸Ñ׸¿¸µ ߺººÀÑ ÑÀÐÐËÑ´ÔÖÓÒиÖÓÒ¸²Ñ¸½¸µ ߺººFigure 6.3: The parameters Ñ and ÑÜ ÒÒÐ× of ÀÐÐËÑ.The parameter ÑÜ ÒÒÐ× only specifies the maximum number of channels. If an imageHALCON Extension Package Interface / 2000-11-16

6.1. LOOP MACROS 91contains less channels, the corresponding ÀÑ elements in the Ñ array are undefined.The actual number of channels can be accessed e.g., using ÀÆÙÑÇÒÒÐ× (see section 5.6.4).An image must contain at least one channel. Otherwise, ÀÐÐËÑ returns an error. If thenumber of channels exceeds ÑÜ ÒÒÐ×, the remaining channels are ignored. Furthermore,the size of all channels is checked for equality 3 .ÀÖÖÓÖ ÁÈËÑ´ÀÔÖÓÒÐ ÔÖÓÒи » ÀÄÇÆ ÔÖÓº ÒÐ »ÀÖÐÖÓÒ ÖÓÒ¸ » Ö Ó ÒØÓÒ »ÀÑ Ñ¸ » ÒÔÙØ Ñ »ÀÖÐÖÓÒ ÓÙص » ×ÑÒØØÓÒ Ö×ÙÐØ »ß» ÓÑÔÙØ ÖÓÒ ÓÙØ ÖÓÑ ÖÓÒ Ò Ñ »ÖØÙÖÒ´ÀÅËÇõÐÀÍ×ÖÜÔÓÖØ ÀÖÖÓÖ ÁÈËÑ´ÀÔÖÓÒÐ ÔÖÓÒеßÁÆÌ ÀÖÐÖÓÒ ÖÓÒ¸ ÒÛÖÓÒÀÑ ÑÀÈ´ÀÐÐÓÊÄÌÑÔ´ÔÖÓÒи²ÒÛÖÓÒµµ » ÐÐÓØ ÑÑÓÖÝ»ÀÐÐËÑ´ÔÖÓÒи²ÖÓÒ¸²Ñ¸½¸µ ß » ÐÐ ÒÔº Ñ×»ÀÈ´ÁÈËÑ´ÖÓÒ¸²Ñ¸ÒÛÖÓÒµµÀÆÛÊÓÒ´ÔÖÓÒиÒÛÖÓÒµ » ÐÐÓØ ÒÛ »Ð » ÖÓÒ »ÀÈ´ÀÖÊÄÌÑÔ´ÔÖÓÒиÒÛÖÓÒµµ » Ö ÑÑÓÖÝ »ÖØÙÖÒ´ÀÅËÌÊ͵ÐFigure 6.4: A typical application of ÀÐÐËÑ: A segmentation operator.Fig. 6.4 shows a framework for a supply procedure for a segmentation operator using ÀÐÐËÑ.The corresponding hypothetical operator ×Ñ has one input object parameter for input imagescontaining at least one channel. The -file (short version) might look like×Ñ ¹ ÁÈËÑÁÑÊÓÒ℄The macro ÀÐÐËÑ used in ÁÈËÑ performs a loop over all image objects within the firstinput object parameter ÁÑ of ×Ñ. With every pass of the loop it returns the image data ofthe current input object in the variables ÖÓÒ (area of definition) and Ñ (first gray valuechannel). The results of the segmentation (ÒÛ ÖÓÒ) are stored via the macro ÀÆÛÊÓÒ(see section 6.2.1, page 95) as new objects of the HALCON data base and returned in the (first)output object parameter (ÊÓÒ). Note, that this simple operator has no control parameters.A new region is allocated for the action procedure via ÀÐÐÓÊÄÌÑÔ (see section 3.2.1) beforeentering the loop. This region is used as temporary memory for the computation result and mustbe deallocated (via ÀÖÊÄÌÑÔ) before exiting the supply procedure.3 Remember: The sizes must be equal, whereas the pixel types of different channels may varyHALCON 6.0

92 CHAPTER 6. SPECIAL ROUTINES FOR TYPICAL SUPPLY PROCEDURES6.1.3 ÀÐÐÐØÖÀÐÐÐØÖ (see Fig. 6.1) further extends the loop macros introduced so far: For every inputimage object a new output image object is created (and added to the first output object parameter)with¯ the same number of channels (components),¯ the same pixel types (of the corresponding channels),¯ the same image size and¯ the same area of definition (region).Thus, ÀÐÐÐØÖ is a combination/modification of ÀÐÐÇ (see section 5.3.1), ÀØÊÄ(see section 5.2.2), ÀÐÐÓÑÔ (see section 5.3.2), ÀÓÔÝÇ (see section 5.4.2), andÀÈÙØÁÑ (see section 5.4.6). It has been designed for filter operators that typically create amodified result image for every input image. The region remains unmodified. Typical examplesfor this functionality are the HALCON operators ×ÓÐ ÑÔ, ÑÒ Ñ, Ø, ×Ð ÑÜ orÐÛ× ÝØ.Fig. 6.5 shows a typical application of ÀÐÐÐØÖ – a hypothetical operator ×Ð ÒÛ thatmultiplies all gray values of the input objects within the first input object parameter with aconstant. The corresponding -file(short version) might look like×ÐÒÛ ¹ ÁÈËÐÆÛÁÑÁÑËÐÅÙÐØ°℄The operator has one input object parameter (ÁÑ) that contains one or more input imageobjects (each consisting of one or more gray value channels and one region as area of definition).With every pass of the loop an image object is accessed and its components are transfered toÖÓÒ and Ñ Ò, see also ÀÐÐËÑ in section 6.1.2. These components are passed tothe action procedure ÁÈËÐÆÛ. In this example only the first channel of each input object isused.ÀÐÐÐØÖ also creates output objects (in the HALCON data base) to return the modified data.Furthermore, these objects are added to the list of objects for the first output object parameter(here ÁÑËÐ). Their underlying image matrices are accessable via Ñ ÓÙØ. Thoseare also passed to the action procedure ÁÈËÐÆÛ within the loop. ÁÈËÐÆÛ calculates thenew gray values for all pixels within the area of definition of the input image and writes theminto the provided image components Ñ ÓÙØ 4 . The regions of the image objects remainunmodified so that all pixels of output objects lying outside the region are undefined.Note, that ÀÐÐÐØÖ creates all necessary image matrices, combines them with the inputregions to new image objects, and returns those in the first output object parameter. So theprogrammer of the supply procedure needs not to bother about the handling of image objectsetc. To access the input control parameter, ÀØËÈÖ (see section 78) is used in the example.The structure Ñ Ò may contain different pixel types. There are several ways to handle thiswithin an operator:4 Note, that Ñ ÓÙØ contains a pointer to a pixel matrix with the same size and pixel type as Ñ Ò.HALCON Extension Package Interface / 2000-11-16

6.1. LOOP MACROS 93ÀÖÖÓÖ ÁÈËÐÆÛ´ÀÖÐÖÓÒÀÑÀÑßÁÆÌ ¸Ð¸ÒÓÙÐ ÖÓÒ¸ÑÒ¸ÑÓÙظÐÓÖ ´¼ ÖÓÒ¹ÒÙÑ ··µ ßÒ ´ÖÓÒ¹Öи¸ÑÒ¹ÛصÓÖ ´Ð´ÖÓÒ¹Öи¸ÑÒ¹Ûص ÐÒ Ð··µ ßÀÁÑ´¸ÑҸеÀÁÑ´ÑÓÙظÑÙÐظеРÐÖØÙÖÒ´ÀÅËÇõÀÍ×ÖÜÔÓÖØ ÀÖÖÓÖ ÁÈËÐÆÛ´ÀÔÖÓÒÐ ÔÖÓÒеßÀÔÖ ÑÙÐØÀÖÐÖÓÒ ÖÓÒÀÑ ÑÒ¸ÑÓÙØÁÆÌ ÐÀØËÈÖ´ÔÖÓÒи½¸ÄÇÌÈʸ²ÑÙÐظ½µÀÐÐÐØÖ´ÔÖÓÒи²ÖÓÒ¸²ÑÒ¸²ÑÓÙظ½¸µ ßÀÈ´ÁÈËÐÆÛ´ÖÓÒ¸²ÑÒ¸ÑÙÐغÔÖº¸²ÑÓÙصµÐÖØÙÖÒ´ÀÅËÌÊ͵Figure 6.5: A typical application of ÀÐÐÐØÖ: A filter operator.1. The simplest method is to implement the operator just for the most common pixel typeÌ ÁÅ and return an error message (À ÊÊ ÏÁÌ) for any other pixel type.2. Another way is to provide several action procedures – one for every pixel type – and callthe appropriate procedure via ×ÛØ´Ñ ÒºÒµ.3. The third (generic) method makes use of the macros ÀÁÑ and ÀÁÑ, seeFig. 6.6. They encapsulate the access to gray values by buffering them in a ÓÙÐvariable.By writing pixel values via ÀÁÑ, theÓÙÐ value ÚÐ is converted into the currentpixel type of Ñ Ò (and therefore may be clipped) and stored in the pixel specifiedby the linear coordinate ÐÒ ÓÓÖ, see section 4.1.The other way around, the specified pixel value is converted to ÓÙÐ and returned inÚÐ when using ÀÁÑ to read image data.The third method has been used in our example, as it allows a very compact source code. Butthis variant naturally shows drawbacks in terms of computation time: Two type conversionshave to be computed with every pixel access and all pixel arithmetic has to be done in ÓÙÐ.HALCON 6.0

94 CHAPTER 6. SPECIAL ROUTINES FOR TYPICAL SUPPLY PROCEDURESNamesÀÁѸ ÀÁÑSynopsisÒÐÙ ÀÐÓÒºÀÁÑ´ ÓÙÐÀÑÁÆÌÀÁÑ´ ÀÑÓÙÐÁÆ̲ÚиѸÐÒÓÓֵѸÚиÐÒÓÓÖµFigure 6.6: Auxiliary macros for generic access to pixel data. “&” denotes an output parameterof ÀÁÑ. This is only a special notation to make clear that this parameter is changed bythe macro. So do not pass a pointer to ÓÙÐ but the ÓÙÐ variable itself to the macro.6.1.4 ÀÐÐÐØÖ¾The macro ÀÐÐÐØÖ¾ (see Fig. 6.1) is a variation of ÀÐÐÐØÖ introduced in the previoussection. It facilitates the implementation of filters with two input object parameters. Examplesfor this technique are the HALCON operators Ñ, ÑÙÐØ Ñ, Ø Ò, andÑÜ ¾ Ñ×.ÀÐÐÐØÖ¾ extends ÀÐÐØÖ so that with every image object of the first input object parameteralso the corresponding image object (with the same object index Ó ÒÜ) ofthesecond input object parameter is provided. Moreover, it checks the image sizes of both imageobjects for equality. If the sizes are equal, the images are provided in the loop variablesÑ Ò½ and Ñ Ò¾, otherwise an error is returned.Moreover, ÀÐÐÐØÖ¾ computes a new input region (ÖÓÒ) by intersecting the areas ofdefinition of both input images. Note, that memory for this region must have been allocatedbefore (e.g. with ÀÐÐÓÊÄÌÑÔ). Furthermore, ÖÓÒ must be deallocated at the end of thesupply procedure (ÀÖÊÄÌÑÔ).Output image objects are created and returned in the first output object parameter in the sameway as decribed for ÀÐÐÐØÖ in section 6.1.3.Fig. 6.7 shows a typical application of ÀÐÐÐØÖ¾ – the implementation of an operator thatadds the gray values of two input images. As in procedure ÁÈËÐÆÛ in Fig. 6.5, the macrosÀÁÑ and ÀÁÑ are used to read and write pixel values. In this example, that exhibitsthe additional advantage that the operator can even add the gray values of two images withdifferent pixel types.HALCON Extension Package Interface / 2000-11-16

6.2. OBJECT GENERATION 95ÀÖÖÓÖ ÁÈÆÛ´ÀÔÖÓÒÐÀÖÐÖÓÒÀÑßÁÆÌ ¸Ð¸ÒÓÙÐ ½¸¾ÔÖÓÒиÖÓÒ¸ÑÒ½¸ÑÒ¾¸ÑÓÙصÐÓÖ ´¼ ÖÓÒ¹ÒÙÑ ··µ ßÒ ´ÖÓÒ¹Öи¸ÑÒ¹ÛصÓÖ ´Ð´ÖÓÒ¹Öи¸ÑÒ¹Ûص ÐÒ Ð··µ ßÀÁÑ´½¸ÑÒ½¸ÐµÀÁÑ´¾¸ÑÒ¾¸ÐµÀÁÑ´ÑÓÙظ½·¾¸ÐµÐ ÐÖØÙÖÒ´ÀÅËÇõÀÍ×ÖÜÔÓÖØ ÀÖÖÓÖ ÁÈÆÛ´ÀÔÖÓÒÐ ÔÖÓÒеßÀÖÐÖÓÒ ÖÓÒÀÑ ÑÒ½¸ÑÒ¾¸ÑÓÙØÁÆÌ ÐÀÈ´ÀÐÐÓÊÄÌÑÔ´ÔÖÓÒи²ÖÓÒµµÀÐÐÐØÖ¾´ÔÖÓÒиÖÓÒ¸²ÑÒ½¸²ÑÒ¾¸²ÑÓÙظ½¸µ ßÀÈ´ÁÈÆÛ´ÔÖÓÒиÖÓÒ¸²ÑÒ½¸²ÑÒ¾¸²ÑÓÙصµÐÀÈ´ÀÖÊÄÌÑÔ´ÔÖÓÒиÖÓÒµµÖØÙÖÒ´ÀÅËÌÊ͵6.2 Object GenerationFigure 6.7: A typical application of ÀÐÐÐØÖ¾.This section describes the convenience routines ÀÆÛÊÓÒ, ÀÈÙØÊØ, andÀÙÔÇ for creatingnew image objects, see Fig. 6.8.ÀÆÛÊÓÒ creates a new image object in the HALCON data base encapsulating the specifiedregion and adds this object to the first output object parameter. ÀÈÙØÊØ inserts a rectangularregion (as area of definition) into an already existing output image object. Finally, ÀÙÔÇadds an iconic input object to the object list of the first output object parameter.6.2.1 ÀÆÛÊÓÒÀÆÛÊÓÒ (see Fig. 6.8) is used to create a new image object in the HALCON data basewhich is also added to the first output object parameter. Only the region component (area ofHALCON 6.0

96 CHAPTER 6. SPECIAL ROUTINES FOR TYPICAL SUPPLY PROCEDURESNamesÀÆÛÊÓÒ¸ ÀÈÙØÊظ ÀÙÔÇSynopsisÒÐÙ ÀÐÓÒºÀÆÛÊÓÒ´ÀÔÖÓÒÐÀÖÐÖÓÒÔÖÓÒиÖÓÒµÀÈÙØÊØ´ ÀÔÖÓÒÐ ÔÖÓÒиÀÝÓݸÁÆÌÛظصÀÙÔÇ´ ÀÔÖÓÒÐ ÔÖÓÒиÁÆÌ ÓÒܵFigure 6.8: Convenience routines for creating output objects.definition) of the new object is defined: It contains a copy of ÖÓÒ. Itiscommontocallanimage object region, when only its region component is used.ÀÍ×ÖÜÔÓÖØ ÀÖÖÓÖ ÁÈÓÒÚÜ´ÀÔÖÓÒÐßÀÖÐÖÓÒ ÖÓÒÀÖÐÖÓÒ ÖÓÒÒÛÔÖÓÒеÐÀÈ´ÀÐÐÓÊÄÌÑÔ´ÔÖÓÒи²ÖÓÒÒÛµ » ÐÐÓØ ÑÑÓÖÝ »ÀÐÐÊ´ÔÖÓÒи²ÖÓÒ¸µ ß » ÐÐ ÖÓÒ× »ÀÈ´ÀÊÄÓÒÚܾ´ÔÖÓÒиÖÓÒ¸ÖÓÒÒÛµµ» ÖØ Ò ÓÙØÔÙØ ÖÓÒ ÓØ ´Ö×Ø ÓÙØÔÙØ ÔÖѺµ »ÀÆÛÊÓÒ´ÔÖÓÒиÖÓÒÒÛµÐÀÈ´ÀÖÊÄÌÑÔ´ÔÖÓÒиÖÓÒÒÛµµ » Ö ÑÑÓÖÝ »ÖØÙÖÒ´ÀÅËÌÊ͵Figure 6.9: A typical application of ÀÆÛÊÓÒ: The region transformation “convex hull”.Typically, ÀÆÛÊÓÒ is used within segmentation procedures (see Fig. 6.4) and region transformingprocedures such as the procedure ÁÈÓÒÚÜ shown in Fig. 6.9. ÁÈÓÒÚÜ correspondsto a hypothetical operator ØÖÒ× ÓÒÚÜ which might be defined likeØÖÒ×ÓÒÚÜ ¹ ÁÈÓÒÚÜÊÓÒÊÓÒÓÒÚÜ℄In the example all regions within ÊÓÒ are provided in ÖÓÒ by ÀÐÐÊ (see section6.1.1) one after the other. The HALCON procedure ÀÊÄÓÒÚܾ computes the convex hull forHALCON Extension Package Interface / 2000-11-16

6.2. OBJECT GENERATION 97each region and writes it to ÖÓÒ ÒÛ. Furthermore, a new region object in the HALCONdata base is created and added to the output object parameter ÊÓÒÓÒÚÜ.Note, that ÀÆÛÊÓÒ was also used in the example in Fig. 6.4 on page 91.6.2.2 ÀÈÙØÊØÀÈÙØÊØ (see Fig. 6.8) inserts a rectangular region in an already existing output object withdata base key Ó Ý. Mostly it is used in connection with operators that create new imageobjects like in the example in Fig. 6.10.ÀÍ×ÖÜÔÓÖØ ÀÖÖÓÖ ÁÇÖÁÑ´ÀÔÖÓÒÐßÀÝ ÓݸÑÝÀÑ ÑÔÖÓÒеÐÀÖÇ´ÔÖÓÒи½¸²ÓݵÀÈ´ÀÆÛÁÑ´ÔÖÓÒи²Ñ¸ÌÁŸ¼¸¼µµ» Ö Ò ÆÌË Ñ ¼ Ü ¼ ÔÜи Ø »ÀÈ´ÁÇÖÁÑ´²ÑµµÀÈÙØÁÑ´ÔÖÓÒиÓݸ½¸²Ñ¸Ä˸²ÑݵÀÈÙØÊØ´ÔÖÓ¸ÓݸѺÛظѺصÖØÙÖÒ´ÀÅËÌÊ͵Figure 6.10: A typical application of ÀÈÙØÊØ: Grabbinganimage.Note, that ÀÖÇ (see section 5.4.1) creates an object with empty region. In many situationsthe default area of definition for a new image will be the full image domain which is a rectangle.In this situation the use of ÀÈÙØÊØ is very convenient.6.2.3 ÀÙÔÇÀÙÔÇ (see Fig. 6.8) is a combination/simplification of ÀØÇ (see section 5.1.1) andÀÓÔÝÇ (see section 5.4.2). It duplicates iconic input objects (images, regions, XLD) inorder to pass them directly to the first output object parameter. The objects to be duplicated arespecified by their index Ó ÒÜ within the first input object parameter. Note, that this indexcorresponds to Ó ÒÜ as defined for the loop macros (ÀÐÐ) in section 6.1. ÀÙÔÇ istypically used for operators that examine objects and select them by a given criteria. SomeHALCON operators of this kind are ×ÐØ ×Ô, × ×Ô, or×ÐØ ÖÝ.Fig. 6.11 shows an application of ÀÙÔÇ: ÁÈÍ×ÖËÐØ computes the length of the contourof each input region (in parameter 1). All regions with a contour of at least the minimal lengthÑÒ are passed to the output.Since ÀÙÔÇ only increases the number of references to a data base object instead of copyingit physically, its memory costs and computational costs are neglectable. In contrast, e.g.,ÀÆÛÊÓÒ and ÀÐÐÐØÖ always allocate new memory for the output objects. So wheneverpossible, ÀÙÔÇ should be used.HALCON 6.0

98 CHAPTER 6. SPECIAL ROUTINES FOR TYPICAL SUPPLY PROCEDURESÀÖÖÓÖ ÁÈÍ×ÖËÐØ´ÀÔÖÓÒÐßÀÖÐÖÓÒ ÖÓÒÀÖÐÖÓÒ ÖÓÒÒÛÓÙÐ ÐÒØÀÔÖ ÑÒÁÆÌ ÔÖÓÒеÐÀØËÈÖ´ÔÖÓÒи½¸ÄÇÌÈʸ²ÑÒ¸½µ » Ø ÑÒº ÐÒØ »ÀÐÐÊ´ÔÖÓÒи²ÖÓÒ¸µ ß » ÐÐ ÖÓÒ× »ÀÈ´ÀÊÄÓÒØÄÒØ´ÔÖÓÒиÖÓÒ¸²ÐÒصµ » ÐÒØ » ´ÐÒØ ÑÒºÔÖºµ » ÐÒØ Óºº »ÀÙÔÇ´ÔÖÓÒиµ» ÙÔÐØ ÓØ»ÐÖØÙÖÒ´ÀÅËÌÊ͵Figure 6.11: A typical application of ÀÙÔÇ: Duplicate input regions that fulfill a specific criteria(length of contour).HALCON Extension Package Interface / 2000-11-16

Chapter 7Creating a New HALCON Package7.1 The HALCON Compiler ÓÑÔThe HALCON compiler ÓÑÔ is the most important tool for creating a new HALCON package.It automatically generates the interface code for the desired host language, the help files,and the documentation files. ÓÑÔ processes -files that contain descriptions of all operatorsas a basic resource, see chapter 2. The HALCON compiler uses the same mechanism forgenerating the original system operators and user-defined operators.The syntax of the ÓÑÔ command is as follows:ÓÑÔ ÓÔØÓÒ× Ð×Example:ÓÑÔ ¹Ù ¹ ¹ÔÔ ÅÝÍ×ÖÇÔ׺The parameter “¹Ù” signals that an interface for user-defined operators should be generated.This parameter can be omitted as it is the default 1 . One or more definition files that are separatedby blanks must be specified as files argument. The extension º may be omitted:ÓÑÔ ¹ ¹ÔÔ ÅÝÍ×ÖÇÔ×½ ÅÝÍ×ÖÇÔ×¾ ÅÝÍ×ÖÇÔ׿To generate the appropriate interface code, the correct option must specify the desired hostlanguage (for C as host language: ¹). Then, ÓÑÔ generates a couple of source files (inthe example above: ÀÔº and ÀÔº) for the package Ô. Their namesdepend on the host language and the specified package, not on the names of the input -file(s).7.1.1 Selection of the Host LanguageOne call of ÓÑÔ can always create only one interface, i.e, the options described as followscan only be switched on under mutual exclusion. Use1 Note, that ÓÑÔ also is used by MVTec to generate the interface code for the standard HALCON system.99

100 CHAPTER 7. CREATING A NEW HALCON PACKAGEÓÑÔ ¹ ¹ÔÔ℄ ¹Ð×to create interface code for . ÓÑÔ ¹ ¹ÔÔ creates the files ÀÔº (interfacecode) and ÀÔº (prototypes of operators).To create interface code for ·· useÓÑÔ ¹ ¹ÔÔ℄ ¹Ð×creating ÀÈÈÔºÔÔ, ÀÈÈÔÐÓкÔÔ, and ÀÈÈÔº (prototypes)providing the C++ interface to the new operators.The generated source files are the basis for the interface libraries, see section 7.2.7.1.2 Creating the ÐÔ-filesThese files are necessary for the online access to the operator knowledge base via HALCONoperators like Ø ÓÔÖØÓÖ ÒÓ. For example, ÀÚÐÓÔ uses their information to build upthe menu tree ’ÇÔÖØÓÖ’ (chapter and section structuring) and ’ËÙ×ØÓÒ×’ (alternatives,cross references, predecessor, successor, and keywords). The ÐÔ files are generated for thelanguage selected with the (optional) ¹Ð option. The default language is ÒÐ×.ÓÑÔ ¹Å ¹Ðlanguage℄ ¹Ð×creates the following files:FileDescriptionlanguageºÐÔ The operator description (text, value lists, ...).languageºÜ Index for every operator specifying the start address of its entry withinthe ºÐÔ file.languageºÝ List of keywords with the associated operators.languageºÒÙÑ Specification of the number of parameters per parameter class for everyoperator.languageº×Ø Specification of the parameter names and the chapter names for everyoperator.In addition to the option ¹Å¹TAGS-FILEcan be set in order to insert the source file and the line number of the supply procedure of theoperator into the ºÐÔ file. To do this, a TAGS-File (usually ÌË) must have been generatedby the Ø× command before.HALCON Extension Package Interface / 2000-11-16

7.1. THE HALCON COMPILER ’HCOMP’ 1017.1.3 Creating the ManualsÓÑÔ can generate L A TEX files containing the complete reference manuals (full text or shortversion) adapted to the different supported programming languages, i.e. the description of theoperators is provided in a specific syntax. UseÓÑÔ ¹Êplanguagespecification ¹Ðlanguage] ¹Ð×to create L A TEX files with planguage and specification as follows:planguage can be set to , ··, andØÖ× (corresponds basically to the ÀÚÐÓÔ-Syntax).ØÖ× is default and may therefore be omitted. The specification determines the extent of themanual by specifying the additional operator information that will be inserted into the manualbesides the operator header. Supported specifications are:SpecificationÐÐ×ÓÖØ℄×ÓÐDescriptionAll available information is presented in the manual.Only the short descriptions are inserted.A file is generated for each operator containing its complete description.By specifying ×ÓÐ afileoperatorºØÜ is created for every operator. Using any of the otherspecifications the file ÀÊÖÒºØÜ is generated.The generated L A TEX files use the package ÐÓÒ ÖÖÒº×ØÝ. This package resides inthe directory °ÀÄÇÆÊÇÇ̻ӻÑÖÓ× (UNIX notation). You must include this directory inthe environment variable ÌÁÆÈÍÌË, otherwise L A TEX will be unable to find it (typical errormessage: Ð ÐÓÒ ÖÖÒº×Øݳ ÒÓØ ÓÙÒ.The L A TEX file(s) can be transformed to PostScript files by using ÐØÜ, ÑÒÜ, andÚÔ×.Note, that ÐØÜ must be called several times to get the references right.7.1.4 Creating HTML FilesÓÑÔ can also generate HTML files. Thus, its easy to provide an online documentation of newoperators that can be accessed using an HTML browser. UseÓÑÔ ¹Äplanguagespecification ¹Ðlanguage℄ ¹Ð×to create HTML files. All things said above about the issues planguage and specification holdalso for this section — with the exception that ×ÓÐ is not supported. The following files aregenerated:HALCON 6.0

102 CHAPTER 7. CREATING A NEW HALCON PACKAGEFileØÐ Ó ÓÒØÒØ׺ØÑÐÒÜ Ý ÒѺØÑÐØÓ chapter subchapterºØÑÐoperatorºØÑÐDescriptionHome page containing the chapter structure and links to thedifferent (sub-)chapters (ØÓ chapter subchapterºØÑÐ).Alphabetic list of all operators with links to the correspondingoperator description pages (files operatorºØÑÐ).For every (sub-)chapter: A list of all operators within thechapter with links to the corresponding operator descriptionpages (files operatorºØÑÐ).A description page for each operator.7.1.5 MiscellaneousHere are some more options supported by ÓÑÔ:OptionÓÑÔ ¹ filename ¹Ð×ÓÑÔ ¹Ü filename ¹Ð×ÓÑÔ ¹Ñ ¹Ð×DescriptionConsider only the operators listed in filename.Do not consider the operators listed in filename.Generate a list of operators within the -files sortedby modules.7.2 Generating HALCON PackagesOnce the new operators have been described in -file(s) and implemented (supply and actionprocedures) a couple of dynamic objects (DLLs in Windows NT an Windows 2000, sharedlibraries in UNIX environments) must be created. Never change the name of a package orthe corresponding names of the libraries/DLLs contained in a package. These names areencoded within the libraries. If you change the names this information will not match anylonger. Thus, the loader of the operating system will fail to open the dynamic libraries. If youwant to rename a package, you must create the libraries/DLLs again.To activate a package, its complete path must be added to the environment variableÀÄÇÆÌÆËÁÇÆË , e.g.,±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×ÒÜØÒ×ÓÒ ÔÒÐÓÒÙ×ÖPlease note, that the package paths in ÀÄÇÆÌÆËÁÇÆË are separated by semicolons (WindowsNT/ 2000) or colons (UNIX), see also section 1.3.7.2.1 Creating the Operator LibrariesThe supply and action procedures must be encapsulated in a DLL or a shared library. The nameof this shared object has to be identical with the package name (plus file extension). For the useHALCON Extension Package Interface / 2000-11-16

7.2. GENERATING HALCON PACKAGES 103by Parallel HALCON, a second version of the library must be created, with the additional prefixÔÖ to the name. Please refer to section 7.2.5 and the documentation of your programmingenvironment for more details (also about the following sections).Under Windows NT or Windows 2000 the generated DLLs must be placed in the subdirectoryÒÒ±ÊÀÁÌÌÍʱ, the libraries in the subdirectory ÐÒ±ÊÀÁÌÌÍʱ. Under UNIX,the generated shared libraries must be placed in the subdirectory ÐÒ±ÊÀÁÌÌÍʱ, binariesin the subdirectory ÒÒ±ÊÀÁÌÌÍʱ of the package.7.2.2 Creating the C InterfaceTo access new HALCON operators inside a package within C programs or from ÀÚÐÓÔ youmust create a C interface library Ô residing in the subdirectory ÐÒ±ÊÀÁÌÌÍʱof the package. This library is based on a single C file ÀÔº which is generated viaÓÑÔ ¹ ¹ÔÔ ¹Ð´×µfrom the -file(s) of your new operators. Note, that ÓÑÔ simultanously generates the fileÀÔº containing the C prototypes of your new operators. Include this file in your Cprograms using these operators.7.2.3 Creating the C++ InterfaceTo access new HALCON operators inside a package within C++ programs you must create aC++ interface library ÔÔÔ residing in the subdirectory ÐÒ±ÊÀÁÌÌÍʱ of thepackage. This library is based on the files ÀÈÈÔºÔÔ and ÀÈÈÔÐÓкÔÔgenerated viaÓÑÔ ¹ ¹ÔÔ ¹Ð´×µfrom the -file(s) of your self developed operators. Note, that ÓÑÔ simultanously generatesthe file ÀÈÈÔº containing the C++ prototypes of your new operators. Include this filein your C++ programs using these operators.7.2.4 Creating New ApplicationsIn order to create new application programs (written in C or C++) based on your own HAL-CON operators you must link the corresponding language interface libraries Ô orÔÔÔ to your objects. Furthermore, you will need the HALCON library itself and theHALCON/C or HALCON/C++ library (as for any HALCON application).7.2.5 Additional Information for Specific ArchitecturesThe previous sections summarized the generation of HALCON extensions in general. Thissection contains additional information for specific architectures. The main differences concernthe name handling and the generation of shared libraries / DLLs.HALCON 6.0

104 CHAPTER 7. CREATING A NEW HALCON PACKAGE7.2.5.1 Generating Packages Under Windows NT or Windows 2000In order to activate a package, its complete path, e.g.±ÀÄÇÆÊÇÇ̱ÒÜÑÔÐ×ÒÜØÒ×ÓÒ ÔÒÐÓÒÙ×Ömust be included in the environment variable ÀÄÇÆÌÆËÁÇÆË . In the Windows NT / 2000version the package paths in ÀÄÇÆÌÆËÁÇÆË are separated by semicolons.Note, that DLLs must be stored in the subdirectory ÒÒ¹ÒØ of the package, thecorresponding libraries in the subdirectory ÐÒ¹ÒØ.¯ Exporting the supply procedures:The supply procedures (like ÁÈÍ×ÖÌÖ×Óдµ in ÔÙ×ÖØÖ×Óк) must beexplicitly exported by the operator DLL ÔºÐÐ containing your new operators.This is done by the macro ÀÍ×ÖÜÔÓÖØ, see e.g., Fig. 1.6.¯ Creating object files for the Parallel HALCON version:If you want to create a Parallel HALCON version of your package, a second set of objectfiles must be created from the source code files, using the compiler define »À ÈÊÄÄÄ.We recommend to place these object files into a separate directory to prevent confusingthem with the object files created for the standard HALCON version.¯ Creating the operator DLL ÔºÐÐ and the library ÔºÐ:To create the operator DLL ÔºÐÐ containing new HALCON operators and thecorresponding library ÔºÐ, the object files containing the corresponding supplyand action procedures and the HALCON library ÐÓҺРmust be linked.To create the libraries ÔÖÔºÐÐ and ÔÖԺРfor Parallel HALCON, thecorresponding object files compiled with the define »À ÈÊÄÄÄ must be linked to theParallel HALCON library ÔÖÐÓҺРinstead of ÐÓÒºÐ.¯ Creating the C interface DLL ÔºÐÐ and the library ÔºÐ:To create the libraries ÔºÐÐ and ԺРwhich provide the C interfaceto new HALCON operators, the object file ÀÔºÓ, the new operator libraryÔºÐ, the HALCON C-library ÐÓÒºÐ, and the HALCON libraryÐÓҺРmust be linked.To create the libraries ÔÖÔºÐÐ and ÔÖԺРfor Parallel HALCON,the corresponding object file compiled with the define »À ÈÊÄÄÄ must be linked tothe Parallel HALCON version of the libraries, i.e., ÔÖÔºÐ, ÔÖÐÓÒºÐ,and ÔÖÐÓÒºÐ.¯ Creating the C++ interface DLL ÔÔÔºÐÐ and the library ÔÔÔºÐ:To create the DLL ÔÔÔºÐÐ providing the C++ interface to new HALCON operatorsand the corresponding library ÔÔÔºÐ, the object files ÀÈÈÔºÓand ÀÈÈÔÐÓкÓ, the new operator lib ÔºÐ, the HALCON C++library ÐÓÒÔԺРand the HALCON library ÐÓҺРmust be linked.To create the libraries ÔÖÔÔÔºÐÐ and ÔÖÔÔԺРfor Parallel HAL-CON, the corresponding object files compiled with the define »À ÈÊÄÄÄ mustbe linked to the Parallel HALCON version of the libraries, i.e., ÔÖÔºÐ,ÔÖÐÓÒÔÔºÐ, andÔÖÐÓÒºÐ.HALCON Extension Package Interface / 2000-11-16

106 CHAPTER 7. CREATING A NEW HALCON PACKAGE¯ Creating object files for the Parallel HALCON version:If you want to create a Parallel HALCON version of your package, a second set of objectfiles must be created from the source code files, using the compiler define ¹À ÈÊÄÄÄ.We recommend to place these object files into a separate directory to prevent confusingthem with the object files created for the standard HALCON version.¯ Creating the operator library ÐÔº×Ó:To create the operator library ÐÔº×Ó containing new HALCON operators, theobject files containing the corresponding supply and action procedures must be linked.The linkage of shared libraries is done with Ð ¹×Ö. Specify the desired nameÐÔº×Ó and location of the library with the Ð option ¹Ó.To create the library ÐÔÖÔº×Ó for Parallel HALCON, the corresponding objectfiles compiled with the define ¹À ÈÊÄÄÄ must be linked.¯ Creating the C interface library ÐÔº×Ó:To create the C interface library ÐÔº×Ó providing the interface to newHALCON operators, the object file ÀÔºÓ and the new operator libraryÐÔº×Ó must be linked.To create the library ÐÔÖÔº×Ó for Parallel HALCON, the corresponding objectfile compiled with the define ¹À ÈÊÄÄÄ must be linked to the Parallel HALCONversion of the operator library, i.e., ÐÔÖÔº×Ó.¯ Creating the C++ interface library ÐÔÔÔº×Ó:To create the C++ interface library ÐÔÔÔº×Ó providing the interface to newHALCON operators, the object files ÀÈÈÔºÓ and ÀÈÈÔÐÓкÓ, andthe new operator lib ÐÔº×Ó must be linked.To create the library ÐÔÖÔÔÔº×Ó for Parallel HALCON, the correspondingobject files compiled with the define ¹À ÈÊÄÄÄ must be linked to the Parallel HAL-CON version of the operator library, i.e., ÐÔÖÔº×Ó.¯ Creating new applications:In order to create new application programs (written in C or C++) you must linkÐÔº×Ó and ÐÔº×Ó or ÐÔÔÔº×Ó to your objects (besidesÐÐÓÒº×Ó and ÐÐÓÒº×Ó or ÐÐÓÒÔÔº×Ó as for any HALCON application).Furthermore, you must add the package library subdirectory л¹ÐÒÙܾº¾to the environment variable ËÀÄÁ ÈÌÀ , otherwise the loader will fail to access the libraries.To create a Parallel HALCON version of your application, just link the objectfiles to the Parallel HALCON version of the libraries (e.g., ÐÔÖÔº×Ó,ÐÔÖÔº×Ó, ÐÔÖÐÓÒº×Ó, andÐÔÖÐÓÒº×Ó in case of a C application).You can use the same object files as for creating the standard HALCON application.The directory °ÀÄÇÆÊÇÇÌ»ÜÑÔÐ×»ÜØÒ×ÓÒ Ô»ÐÓÒÙ×Ö contains two examplemakefiles: ÑÐ creates the example package halconuser, both for standard HAL-CON and for Parallel HALCON. ÑÐ Ø×ØÔÖÓ creates the example applications basedon the package halconuser, again for both HALCON versions. Both makefiles include the fileѺ¹ÐÒÙܾº¾ which sets architecture-dependent variables.HALCON Extension Package Interface / 2000-11-16

7.2. GENERATING HALCON PACKAGES 1077.2.5.3 Generating Packages Under SolarisIn order to activate a package, its complete path, e.g.°ÀÄÇÆÊÇÇÌ»ÜÑÔÐ×»ÜØÒ×ÓÒ Ô»ÐÓÒÙ×Ömust be included in the environment variable ÀÄÇÆÌÆËÁÇÆË .IntheUNIXversionthepackage paths in ÀÄÇÆÌÆËÁÇÆË are separated by colons. Please see also the commentson installing a HALCON package on a Solaris system on page 8.¯ Compiling the source code:In order to generate shared libraries you must produce position independent code. For the» compiler this is done using the option ¹ÃÈÁ.¯ Creating object files for the Parallel HALCON version:If you want to create a Parallel HALCON version of your package, a second set of objectfiles must be created from the source code files, using the compiler define ¹À ÈÊÄÄÄ.We recommend to place these object files into a separate directory to prevent confusingthem with the object files created for the standard HALCON version.¯ Creating the operator library ÐÔº×Ó:To create the operator library ÐÔº×Ó containing new HALCON operators,the object files containing the corresponding supply and action procedures must belinked. The linkage of shared libraries is done with Ð ¹. Specify the desired nameÐÔº×Ó and location of the library with the Ð option ¹Ó.To create the library ÐÔÖÔº×Ó for Parallel HALCON, the corresponding objectfiles compiled with the define ¹À ÈÊÄÄÄ must be linked.¯ Creating the C interface library ÐÔº×Ó:To create the C interface library ÐÔº×Ó providing the interface to newHALCON operators, the object file ÀÔºÓ and the new operator libraryÐÔº×Ó must be linked.To create the library ÐÔÖÔº×Ó for Parallel HALCON, the corresponding objectfile compiled with the define ¹À ÈÊÄÄÄ must be linked to the Parallel HALCONversion of the operator library, i.e., ÐÔÖÔº×Ó.¯ Creating the C++ interface library ÐÔÔÔº×Ó:To create the C++ interface library ÐÔÔÔº×Ó providing the interface to newHALCON operators, the object files ÀÈÈÔºÓ and ÀÈÈÔÐÓкÓ, andthe new operator lib ÐÔº×Ó must be linked.To create the library ÐÔÖÔÔÔº×Ó for Parallel HALCON, the correspondingobject files compiled with the define ¹À ÈÊÄÄÄ must be linked to the Parallel HAL-CON version of the operator library, i.e., ÐÔÖÔº×Ó.¯ Creating new applications:In order to create new application programs (written in C or C++) you must linkÐÔº×Ó and ÐÔº×Ó or ÐÔÔÔº×Ó to your objects (besidesÐÐÓÒº×Ó and ÐÐÓÒº×Ó or ÐÐÓÒÔÔº×Ó as for any HAL-CON application). Furthermore, you must add the package library subdirectoryл×ÔÖ¹×ÙÒ¹×ÓÐÖ× to the environment variable Ä ÄÁÊÊ ÈÌÀ , otherwisethe loader will fail to access the libraries.HALCON 6.0

108 CHAPTER 7. CREATING A NEW HALCON PACKAGETo create a Parallel HALCON version of your application, just link the objectfiles to the Parallel HALCON version of the libraries (e.g., ÐÔÖÔº×Ó,ÐÔÖÔº×Ó, ÐÔÖÐÓÒº×Ó, andÐÔÖÐÓÒº×Ó in case of a C application).You can use the same object files as for creating the standard HALCON application.The directory °ÀÄÇÆÊÇÇÌ»ÜÑÔÐ×»ÜØÒ×ÓÒ Ô»ÐÓÒÙ×Ö contains two examplemakefiles: ÑÐ creates the example package halconuser, both for standard HAL-CON and for Parallel HALCON. ÑÐ Ø×ØÔÖÓ creates the example applications basedon the package halconuser, again for both HALCON versions. Both makefiles include the fileѺ×ÔÖ¹×ÙÒ¹×ÓÐÖ× which sets architecture-dependent variables.7.2.5.4 Generating Packages Under IRIXIn order to activate a package, its complete path, e.g.°ÀÄÇÆÊÇÇÌ»ÜÑÔÐ×»ÜØÒ×ÓÒ Ô»ÐÓÒÙ×Ömust be included in the environment variable ÀÄÇÆÌÆËÁÇÆË .IntheUNIXversionthepackage paths in ÀÄÇÆÌÆËÁÇÆË are separated by colons. Please see also the commentson installing a HALCON package on a IRIX system on page 8.¯ Creating the operator library ÐÔº×Ó:To create the operator library ÐÔº×Ó containing new HALCON operators theobject files containing the corresponding supply and action procedures must be linked.The linkage of shared libraries is done withÐ ¹Ö×ØÖÝ »Ù×ֻл×ÓÐÓØÓÒ× ¹×ÖSpecify the desired name ÐÔº×Ó and location of the library with the Ð option¹Ó. To allow the location of such a library 2 to be resolved by the operating system duringruntime (using Ä ÄÁÊÊ ÈÌÀ) also specify ¹×ÓÒÑ ÐÔº×Ó.¯ Creating the C interface library ÐÔº×Ó:To create the C interface library ÐÔº×Ó providing the interface to newHALCON operators, the object file ÀÔºÓ and the new operator libraryÐÔº×Ó must be linked.¯ Creating the C++ interface library ÐÔÔÔº×Ó:To create the C++ interface library ÐÔÔÔº×Ó providing the interface to newHALCON operators, the object files ÀÈÈÔºÓ and ÀÈÈÔÐÓкÓ, andthe new operator lib ÐÔº×Ó must be linked.¯ Creating new applications:In order to create new application programs (written in C or C++) you must linkÐÔº×Ó and ÐÔº×Ó or ÐÔÔÔº×Ó to your objects (besidesÐÐÓÒº×Ó and ÐÐÓÒº×Ó or ÐÐÓÒÔÔº×Ó as for any HAL-CON application). Furthermore, you must add the package library subdirectory2 Of course this has to be done for ÐÔº×Ó (¹×ÓÒÑ ÐÔº×Ó)andÐÔÔÔº×Ó(¹×ÓÒÑ ÐÔÔÔº×Ó) as well.HALCON Extension Package Interface / 2000-11-16

7.2. GENERATING HALCON PACKAGES 109лÑÔ×¹×¹Öܺ to the environment variable Ä ÄÁÊÊ ÈÌÀ , otherwise theloader will fail to access the libraries.The directory °ÀÄÇÆÊÇÇÌ»ÜÑÔÐ×»ÜØÒ×ÓÒ Ô»ÐÓÒÙ×Ö contains two examplemakefiles: ÑÐ creates the example package halconuser for standard HALCON.ÑÐ Ø×ØÔÖÓ creates the exampleapplications based on the package halconuser.Bothmakefiles include the file ѺÑÔ×¹×¹Öܺ which sets architecture-dependent variables.7.2.5.5 Generating Packages Under HP-UXIn order to activate a package, its complete path, e.g.°ÀÄÇÆÊÇÇÌ»ÜÑÔÐ×»ÜØÒ×ÓÒ Ô»ÐÓÒÙ×Ömust be included in the environment variable ÀÄÇÆÌÆËÁÇÆË .IntheUNIXversionthepackage paths in ÀÄÇÆÌÆËÁÇÆË are separated by colons. Please see also the commentson installing a HALCON package on a HP-UX system on page 8.¯ Compiling the source code:In order to generate shared libraries you must produce position independent code. For the» compiler this is done using the option ·.¯ Creating the operator library ÐÔº×Ð:To create the operator library ÐÔº×Ð containing new HALCON operators,the object files containing the corresponding supply and action procedures must belinked. The linkage of shared libraries is done with Ð ¹. Specify the desired nameÐÔº×Ð and location of the library with the Ð option ¹Ó. To allow the location ofsuch a library 3 to be resolved by the operating system during runtime (using ËÀÄÁ ÈÌÀ)also specify the Ð option ·×.¯ Creating the C interface library ÐÔº×Ð:To create the C interface library ÐÔº×Ð providing the interface to newHALCON operators, the object file ÀÔºÓ and the new operator libraryÐÔº×Ð must be linked.¯ Creating the C++ interface library ÐÔÔÔº×Ð:To create the C++ interface library ÐÔÔÔº×Ð providing the interface to newHALCON operators, the object files ÀÈÈÔºÓ and ÀÈÈÔÐÓкÓ, andthe new operator lib ÐÔº×Ð must be linked.¯ Creating new applications:In order to create new application programs (written in C or C++) you must linkÐÔº×Ð and ÐÔº×Ð or ÐÔÔÔº×Ð to your objects (besidesÐÐÓÒº×Ð and ÐÐÓÒº×Ó or ÐÐÓÒÔÔº×Ð as for any HAL-CON application). Furthermore, you must add the package library subdirectoryлÔÔ½º½¹Ô¹ÔÙܽ¼ to the environment variable ËÀÄÁ ÈÌÀ , otherwise the loaderwill fail to access the libraries.3 Of course this has to be done for ÐÔº×Ð and ÐÔÔÔº×Ð as well.HALCON 6.0

110 CHAPTER 7. CREATING A NEW HALCON PACKAGEIf you use or for linking specify the option ¹Ïи·× in order to allow the usage ofthe environment variable ËÀÄÁ ÈÌÀ for resolving the location of shared libraries by theloader.The directory °ÀÄÇÆÊÇÇÌ»ÜÑÔÐ×»ÜØÒ×ÓÒ Ô»ÐÓÒÙ×Ö contains two examplemakefiles: ÑÐ creates the example package halconuser for standard HALCON.ÑÐ Ø×ØÔÖÓ creates the example applications based on the package halconuser. Bothmakefiles include the file ѺÔÔ½º½¹Ô¹ÔÙܽ¼ which sets architecture-dependent variables.7.2.5.6 Generating Packages Under DIGITAL UNIX (Tru64 UNIX)In order to activate a package, its complete path, e.g.°ÀÄÇÆÊÇÇÌ»ÜÑÔÐ×»ÜØÒ×ÓÒ Ô»ÐÓÒÙ×Ömust be included in the environment variable ÀÄÇÆÌÆËÁÇÆË .IntheUNIXversionthepackage paths in ÀÄÇÆÌÆËÁÇÆË are separated by colons. Please see also the commentson installing a HALCON package on a DIGITAL UNIX (now called Tru64 UNIX) system onpage 8.¯ Creating the operator library ÐÔº×Ó:To create the operator library ÐÔº×Ó containing new HALCON operators, theobject files containing the corresponding supply and action procedures must be linked.The linkage of shared libraries is done withÐ ¹Ö×ØÖÝ »Ù×Ö»×л×ÓÐÓØÓÒ× ¹×Ö ¹ÐÐSpecify the desired name ÐÔº×Ó and location of the library with the Ð option¹Ó. In order to allow a checking of referenced symbols also include¹ÒÓÒ ¹Ð½½ ¹Ð ¹ÐÑ ¹ÐÐÓÒat the end of the Ð command (see the example makefile).¯ Creating the C interface library ÐÔº×Ó:To create the C interface library ÐÔº×Ó providing the interface to newHALCON operators, the object file ÀÔºÓ and the new operator libraryÐÔº×Ó must be linked. In order to allow a checking of referenced symbolsalso include¹ÒÓÒ ¹Ð½½ ¹Ð ¹ÐÑ ¹ÐÐÓÒ ¹ÐÐÓÒat the end of the Ð command (see the example makefile).¯ Creating the C++ interface library ÐÔÔÔº×Ó:To create the C++ interface library ÐÔÔÔº×Ó providing the interface to newHALCON operators, the object files ÀÈÈÔºÓ and ÀÈÈÔÐÓкÓ, andthe new operator lib ÐÔº×Ó must be linked. In order to allow a checking ofreferenced symbols also include¹ÒÓÒ ¹Ð½½ ¹ÐÜÜ ¹ÐÑ ¹ÐÐÓÒ ¹ÐÐÓÒÔÔHALCON Extension Package Interface / 2000-11-16

7.3. HALCON DIRECTORIES 111at the end of the Ð command (see the example makefile).¯ Creating new applications:In order to create new application programs (written in C or C++) you must linkÐÔº×Ó and ÐÔº×Ó or ÐÔÔÔº×Ó to your objects (besidesÐÐÓÒº×Ó and ÐÐÓÒº×Ó or ÐÐÓÒÔÔº×Ó as for any HAL-CON application). Furthermore, you must add the package library subdirectoryлÐÔ¹¹Ó׺¼ to the environment variable ËÀÄÁ ÈÌÀ , otherwise the loaderwill fail to access the libraries.The directory °ÀÄÇÆÊÇÇÌ»ÜÑÔÐ×»ÜØÒ×ÓÒ Ô»ÐÓÒÙ×Ö contains two examplemakefiles: ÑÐ creates the example package halconuser for standard HALCON.ÑÐ Ø×ØÔÖÓ creates the example applications based on the package halconuser. Bothmakefiles include the file ѺÐÔ¹¹Ó׺¼ which sets architecture-dependent variables.7.3 HALCON DirectoriesHALCON always presumes that the environment variable ÀÄÇÆÊÇÇÌ contains the path of theHALCON homedirectory. Starting at this homedirectory the following directories are importantfor creating a new system:ÜÑÔÐ×ÒÜØÒ×ÓÒ ÔÒÐÓÒÙ×Ö: Example for a HALCON extension package.ÒÐÙ: HALCON include files for compiling.ÐÒ±ÊÀÁÌÌÍʱ: HALCON libraries.ÒÒ±ÊÀÁÌÌÍʱ: HALCON compiler ÓÑÔ, under Windows NT/ 2000 also the HAL-CON DLLs.ÓÒÑÖÓ×: L A TEX files for generating PostScript reference files or manuals.HALCON 6.0

112 CHAPTER 7. CREATING A NEW HALCON PACKAGEHALCON Extension Package Interface / 2000-11-16

Appendix AHALCON Error CodesIn this section all HALCON error codes are summarized, see also section 3.6.Error Name Code DescriptionÀÊÊÏÁÈ̽ 1201 Wrong type of control parameter: 1ÀÊÊÏÁÈ̾ 1202 Wrong type of control parameter: 2ÀÊÊÏÁÈÌ¿ 1203 Wrong type of control parameter: 3ÀÊÊÏÁÈÌ 1204 Wrong type of control parameter: 4ÀÊÊÏÁÈÌ 1205 Wrong type of control parameter: 5ÀÊÊÏÁÈÌ 1206 Wrong type of control parameter: 6ÀÊÊÏÁÈÌ 1207 Wrong type of control parameter: 7ÀÊÊÏÁÈÌ 1208 Wrong type of control parameter: 8ÀÊÊÏÁÈÌ 1209 Wrong type of control parameter: 9ÀÊÊÏÁÈ̽¼ 1210 Wrong type of control parameter: 10ÀÊÊÏÁÈ̽½ 1211 Wrong type of control parameter: 11ÀÊÊÏÁÈ̽¾ 1212 Wrong type of control parameter: 12ÀÊÊÏÁÈ̽¿ 1213 Wrong type of control parameter: 13ÀÊÊÏÁÈ̽ 1214 Wrong type of control parameter: 14ÀÊÊÏÁÈ̽ 1215 Wrong type of control parameter: 15ÀÊÊÏÁÈ̽ 1216 Wrong type of control parameter: 16ÀÊÊÏÁÈν 1301 Wrong value of control parameter: 1ÀÊÊÏÁÈξ 1302 Wrong value of control parameter: 2ÀÊÊÏÁÈο 1303 Wrong value of control parameter: 3ÀÊÊÏÁÈÎ 1304 Wrong value of control parameter: 4ÀÊÊÏÁÈÎ 1305 Wrong value of control parameter: 5ÀÊÊÏÁÈÎ 1306 Wrong value of control parameter: 6ÀÊÊÏÁÈÎ 1307 Wrong value of control parameter: 7ÀÊÊÏÁÈÎ 1308 Wrong value of control parameter: 8ÀÊÊÏÁÈÎ 1309 Wrong value of control parameter: 9ÀÊÊÏÁÈν¼ 1310 Wrong value of control parameter: 10ÀÊÊÏÁÈν½ 1311 Wrong value of control parameter: 11ÀÊÊÏÁÈν¾ 1312 Wrong value of control parameter: 12ÀÊÊÏÁÈν¿ 1313 Wrong value of control parameter: 13ÀÊÊÏÁÈν 1314 Wrong value of control parameter: 14ÀÊÊÏÁÈν 1315 Wrong value of control parameter: 15113

114 APPENDIX A. HALCON ERROR CODESÀÊÊÏÁÈν 1316 Wrong value of control parameter: 16ÀÊÊÏÇÅÈ 1350 Wrong value of component (see reset obj db())ÀÊÊÏÇÅÈ 1351 Wrong value of gray value component (see resetobj db())ÀÊÊÏÁÈƽ 1401 Wrong number of values of control parameter: 1ÀÊÊÏÁÈƾ 1402 Wrong number of values of control parameter: 2ÀÊÊÏÁÈÆ¿ 1403 Wrong number of values of control parameter: 3ÀÊÊÏÁÈÆ 1404 Wrong number of values of control parameter: 4ÀÊÊÏÁÈÆ 1405 Wrong number of values of control parameter: 5ÀÊÊÏÁÈÆ 1406 Wrong number of values of control parameter: 6ÀÊÊÏÁÈÆ 1407 Wrong number of values of control parameter: 7ÀÊÊÏÁÈÆ 1408 Wrong number of values of control parameter: 8ÀÊÊÏÁÈÆ 1409 Wrong number of values of control parameter: 9ÀÊÊÏÁÈƽ¼ 1410 Wrong number of values of control parameter: 10ÀÊÊÏÁÈƽ½ 1411 Wrong number of values of control parameter: 11ÀÊÊÏÁÈƽ¾ 1412 Wrong number of values of control parameter: 12ÀÊÊÏÁÈƽ¿ 1413 Wrong number of values of control parameter: 13ÀÊÊÏÁÈƽ 1414 Wrong number of values of control parameter: 14ÀÊÊÏÁÈƽ 1415 Wrong number of values of control parameter: 15ÀÊÊÏÁÈƽ 1416 Wrong number of values of control parameter: 16ÀÊÊÁÇÆÌ 1500 Number of input objects too bigÀÊÊÏÁÇƽ 1501 Wrong number of values of object parameter: 1ÀÊÊÏÁÇƾ 1502 Wrong number of values of object parameter: 2ÀÊÊÏÁÇÆ¿ 1503 Wrong number of values of object parameter: 3ÀÊÊÏÁÇÆ 1504 Wrong number of values of object parameter: 4ÀÊÊÏÁÇÆ 1505 Wrong number of values of object parameter: 5ÀÊÊÏÁÇÆ 1506 Wrong number of values of object parameter: 6ÀÊÊÏÁÇÆ 1507 Wrong number of values of object parameter: 7ÀÊÊÏÁÇÆ 1508 Wrong number of values of object parameter: 8ÀÊÊÏÁÇÆ 1509 Wrong number of values of object parameter: 9ÀÊÊÇÇÆÌ 1510 Number of output objects too bigÀÊÊÏÆÈ 2000 Wrong specification of parameter (error in file: xxx.def)ÀÊÊÀÇÆÁ 2001 Initialize Halcon: resetobj db(Width,Height,Components)ÀÊÊÏÊÃÆÆ 2002 Used number of symbolic object names too bigÀÊÊÆÇÄÁÆË 2003 No license foundÀÊÊÆÇÄËËÊÎÊ 2004 Lost connection to license serverÀÊÊÆÇÅÇÍÄË 2005 No modules in license (no VENDOR STRING)ÀÊÊÆÇÄÁÇÈÊ 2006 No license for this operatorÀÊÊÄÄÅÌ 2007 Time zone offset from GMT is 24 hoursÀÊÊÄÄÅÈÄÌÇÊÅ 2008 Vendor keys do not support this platformÀÊÊÄÅÃÌ 2009 Bad vendor keysÀÊÊÄÄÅÎÆÇÊÌ 2010 Unknown vendor key typeÀÊÊÄÄÅÆÌÅÄÄÇ 2011 malloc() call failedÀÊÊÄÄÅÈÁÊÃË 2012 Vendor keys have expiredÀÊÊÄÄÅÍÆÆÇÌÎÁÄ 2013 Second call to lc init() (multiple jobs), and vendor keysdo not support multiple jobsÀÊÊÄÄÅÆÇÃÌ 2014 Vendor key data not suppliedHALCON Extension Package Interface / 2000-11-16

115ÀÊÊÄÄÅÄÁÊÊÅÁËÅÌÀ 2015 lmclient.h/liblmgr.a version mismatchÀÊÊÄÄÅÆÇÆÌÏÇÊÃ 2016 Networking software not available on this machineÀÊÊÄÄÅÇÄÎÆÇÊÌ 2017 Old vendor keys suppliedÀÊÊÄÄÅÇ 2018 License key in license file does not match other data infileÀÊÊÄÄÅÀÆËÀÃ 2019 Encryption handshake with daemon failedÀÊÊÄÄÅÈÊÅ 2020 ’key’ structure is incorrect type, or feature == NULL, ornum licenses == 0ÀÊÊÄÄÅËËÌ 2021 System clock has been set back. This error can only occurwhen the FEATURE line contains an expiration dateÀÊÊÄÄÅÎÊËÁÇÆ 2022 Version argument is invalid floating point formatÀÊÊÄÄÅÍËÆÏËÊÎ 2023 License server busy starting another copy of itself - retryÀÊÊÄÄÅÆÌÇÆÆÌ 2024 Cannot establish a connection with a license serverÀÊÊÄÄÅÌÉÍÍ 2025 Feature is queued. lc status will determine when it isavailableÀÊÊÄÄÅÍÆÆÇÌÎÁÄ 2026 Vendor keys do not support this functionÀÊÊÄÄÅÄÇÄÁÄÌÊ 2027 Checkout request filtered by the vendor-defined filterroutineÀÊÊÄÄÅÅÄÁÅÁÌ 2028 Checkout exceeds MAX specified in options fileÀÊÊÄÄÅÅÍËÊË 2029 All licenses in useÀÊÊÄÄÅÆÇËÊÎÊÁÆÁÄ 2030 No license server specified for counted licenseÀÊÊÄÄÅÆÇÌÍÊ 2031 Can not find feature in the license fileÀÊÊÄÄÅÆÇËÊÎËÍÈÈ 2032 Server has different license file than client - client’s licensehas feature, but server’s does notÀÊÊÄÄÅÇÄÎÊ 2033 License file does not support a version this newÀÊÊÄÄÅÈÄÌÆÇÌÄÁ 2034 This platform not authorized by license - runnign on platformnot included in PLATFORMS listÀÊÊÄÄÅËÊÎÍË 2035 License server busy - the request should be retried. (Thisis a rare occourence.)ÀÊÊÄÄÅÆÇÇÆÁÄ 2036 could not find license.datÀÊÊÄÄÅÁÄ 2037 Invalid license file syntaxÀÊÊÄÄÅÆÇËÊÎÊ 2038 Cannot connect to a license serverÀÊÊÄÄÅÆÇËÊÎÁ 2039 No TCP license service existsÀÊÊÄÄÅÆÇËÇÃÌ 2040 No socket connection to license manager serverÀÊÊÄÄÅÆÇÌÌÀÁËÀÇËÌ 2041 Invalid hostÀÊÊÄÄÅÄÇÆÇÆ 2042 Feature has expiredÀÊÊÄÄÅÌ 2043 Invalid date format in license fileÀÊÊÄÄÅÇÅÅ 2044 Invalid returned data from license serverÀÊÊÄÄÅÀÇËÌ 2045 Cannot find SERVER hostname in network databaseÀÊÊÄÄÅÆÌÊ 2046 Cannot read data from license serverÀÊÊÄÄÅÆÌÏÊÁÌ 2047 Cannot write data to license serverÀÊÊÄÄÅËÄÌÊÊ 2048 Error in select system callÀÊÊÄÄÅÀÃÁÆ 2049 Feature checkin failure detected at licenseÀÊÊÄÄÅÍËÊËÉÍÍ 2050 Users are queued for this featureÀÊÊÄÄÅËÊÎÄÇÆÇÆ 2051 License server does not support this version of thisfeatureÀÊÊÄÄÅÌÇÇÅÆ 2052 Request for more licenses than this feature supportsÀÊÊÄÄÅÆÌÊÃÅÅ 2053 Cannot read /dev/kmemÀÊÊÄÄÅÆÌÊÎÅÍÆÁ 2054 Cannot read /vmunixHALCON 6.0

116 APPENDIX A. HALCON ERROR CODESÀÊÊÄÄÅÆÌÁÆÌÀÊ 2055 Cannot find ethernet deviceÀÊÊÄÄÅÆÇÊÄÁ 2056 Cannot read license fileÀÊÊÄÄÅÌÇÇÊÄ 2057 Feature not yet available (wrong time/date set?)ÀÊÊÄÄÅÆÇËÍÀÌÌÊ 2058 No such attributeÀÊÊÄÄÅÄÇÃ 2059 Clock differecen too large between client and serverÀÊÊÄÄÅÌÇÊÊÍÈÌ 2060 Feature database corrupted in daemonÀÊÊÄÄÅÌÈÊÅ 2061 Duplicate selection mismatch for this featureÀÊÊÄÄÅÌÄÍ 2062 User/host on EXCLUDE list for featureÀÊÊÄÄÅÌÆÇÌÁÆÄÍ 2063 User/host not on INCLUDE list for featureÀÊÊÄÄÅÆÎÊÀÃÇÍÌ 2064 Feature was never checked outÀÊÊÄÄÅÃÌ 2065 Invalid FLEXlm key data suppliedÀÊÊÄÄÅÆÇÄÇÃÀÃ 2066 Clock setting check not available in daemonÀÊÊÄÄÅÌÌÇÇÁ 2067 Date too late for binary formatÀÊÊÄÄÅÆÇÄÄÅÁÆÁÌ 2068 FLEXlm not initializedÀÊÊÄÄÅÆÇËÊÎÊËÈ 2069 Server did not respond to messageÀÊÊÄÄÅÀÃÇÍÌÁÄÌÊ 2070 Request rejected by vendor-defined filterÀÊÊÄÄÅÆÇÌËÌ 2071 No FEATURESET line present in license fileÀÊÊÄÄÅÌËÌ 2072 Incorrect FEATURESET line in license fileÀÊÊÄÄÅÆÌÇÅÈÍÌÌËÌ 2073 Cannot compute FEATURESET lineÀÊÊÄÄÅËÇÃÌÁÄ 2074 socket() call failedÀÊÊÄÄÅËÌËÇÃÁÄ 2075 setsockopt() failedÀÊÊÄÄÅÀÃËÍÅ 2076 Message checksum failureÀÊÊÄÄÅËÊÎÆÇÊÄÁ 2077 Cannot read license file from serverÀÊÊÄÄÅÆÇÌÄÁÅÁÆ 2078 Not a license administratorÀÊÊÄÄÅÊÅÇÎÌÇÇËÇÇÆ 2079 lmremove request too soonÀÊÊÄÄÅÆÈÌÀ 2080 Attempt to read beyond the end of LF pathÀÊÊÄÄÅÎÅËËÌÁÅÊÁÄ 2081 SYS$SETIMR call failedÀÊÊÄÄÅÁÆÌÊÆÄÊÊÇÊ 2082 Internal FLEXlm Erro - Please report to GlobetrotterSoftwareÀÊÊÄÄÅÆÇÅÁÆÈÁ 2083 FLEXadmin API functions not avilableÀÊÊÄÄÅÈÃ 2084 Invalid PACKAGE line in license fileÀÊÊÄÄÅËÊÎÇÄÎÊ 2085 Server FLEXlm version older than client’sÀÊÊÄÄÅÍËÊË 2086 Incorrect number of USERS/HOSTS INCLUDED in optionsfile – see server logÀÊÊÄÄÅÆÇËÊÎÈ 2087 Server doesn’t support this requestÀÊÊÄÄÅÇÂÌÍË 2088 This license object already in useÀÊÊÏÇÇÈÁ 2100 Wrong index for output object parameterÀÊÊÏÁÇÈÁ 2101 Wrong index for input object parameterÀÊÊÏÇÁ 2102 Wrong index for image object (too big or too small)ÀÊÊÏÊÆ 2103 Wrong number region/image component (see:HGetComp)ÀÊÊÏÊÊÆ 2104 Wrong relation nameÀÊÊÍÁ 2105 Access to undefined gray value componentÀÊÊÏÁÏÁ 2106 Wrong image widthÀÊÊÏÁÀ 2107 Wrong image heightÀÊÊÁÍÆ 2108 Undefined gray value componentÀÊÊÁ 2200 Inconsistent data of data base (typing)ÀÊÊÏÁÈÁ 2201 Wrong index for input control parameterHALCON Extension Package Interface / 2000-11-16

Enquête sur la santé et la protection sociale 2012Renoncement et recours aux soins en 2012Irdes juin 2014G 1Répartition des motifs de renoncements,par types de soinsIl s’agit d’une répartition des motifs de renoncement. Une personne pouvantavoir renoncé à plusieurs types de soins, les effectifs bruts par type de soins 1sont supérieurs à celui des personnes ayant déclaré un renoncement.Autres soins/examens12,3 %Consultationsde médecin14,5 %Soinsdentaires47,1 %Lunettes,lentilles26,1 %1Soins dentaires : 1 513, Lunettes, lentilles : 881,Consultations de médecin : 455, Autres soins : 387.Source: ESPS 2012.123

118 APPENDIX A. HALCON ERROR CODESÀÊÊÌÅÈÆ 2869 Error while accessing temporary fileÀÊÊÈÌÀÊÊ 2970 creation of pthread failedÀÊÊÈÌÀÊÌ 2971 pthread-detach failedÀÊÊÈÌÀÊÂÇ 2972 pthread-join failedÀÊÊÈÌÀÊÅÁ 2973 initialization of mutex variable failedÀÊÊÈÌÀÊÅ 2974 deletion of mutex variable failedÀÊÊÈÌÀÊÅÄ 2975 Lock of mutex variable failedÀÊÊÈÌÀÊÅÍ 2976 unlock of mutex variable failedÀÊÊÈÌÀÊË 2977 failed to signal pthread condition variableÀÊÊÈÌÀÊÏ 2978 failed to wait for pthread condition variableÀÊÊÈÌÀÊÁ 2979 failed to init pthread condition variableÀÊÊÈÌÀÊ 2980 Tried to leave ’critical section’ without entering it beforeÀÊÊÈÌÀÊÀ 2981 failed to give free a handle via CloseHandleÀÊÊÄ 2985 ’Free list’ is empty while schedulingÀÊÊÅËÈÆÁ 2990 Communication partner not checked inÀÊÊÅËËÁ 2991 you can not start the communication system while runningitÀÊÊÅËËÆÁ 2992 Communication partner not checked inÀÊÊÊÇÇÁÅ 3011 Region (partially) outside of the definition range of theimageÀÊÊÊÁÁ 3012 Intersected definition range region / image emptyÀÊÊ 3013 Image with empty definition range (= no gray values)ÀÊÊÁÁÁ 3014 No common image point of two imagesÀÊÊÄÌË 3015 Wrong region for image (first row 0)ÀÊÊÄÄÌ 3016 Wrong region for image (column in last row = imagewidth)ÀÊÊÍÆÇÁ 3017 Number of images unequal in input parametersÀÊÊÀÌË 3018 Image height too smallÀÊÊÏÌË 3019 Image width too smallÀÊÊÀË 3020 Internal error: multiple call of HRLInitSeg()ÀÊÊÊÄ˽ 3021 Internal error: HRLSeg() not initializedÀÊÊÏÍËËÅ 3022 Wrong size of filter for GaussÀÊÊËÁË 3033 Filter size exceeds image sizeÀÊÊÊÇÏÌ 3040 Row value of a coordinate 2ˆ16ÀÊÊÊÇÏÌË 3041 Row value of a coordinate -2ˆ16ÀÊÊÇÄÌ 3042 Column value of a coordinate 2ˆ16ÀÊÊÇÄÌË 3043 Column value of a coordinate -2ˆ16ÀÊÊÏÊÌÀÊ 3100 Wrong segmentation thresholdÀÊÊÍÆà 3101 Unknown attribute of a regionÀÊÊÍÆà 3102 Unknown attribute of a gray valueÀÊÊÁÆ 3103 Internal error in HContCutÀÊÊÁÆȽ 3104 Error in HContToPol: distance of points too bigÀÊÊÁÆȾ 3105 Error in HContToPol: contour too longÀÊÊÌÅÊ 3106 Too many rows (IPImageTransform)ÀÊÊË 3107 Scaling factor = 0.0 (IPImageScale)ÀÊÊÇÇÊ 3108 Wrong range in transformation matrixÀÊÊÆ 3109 Internal error in IPvvf: no element freeÀÊÊÆÇÇ 3110 Number of input objects is zeroHALCON Extension Package Interface / 2000-11-16

119ÀÊÊÅÈÇ 3111 At least one input object has got an empty regionÀÊÊÆÈÇÌ 3112 Operation allowed for rectangular images 2**n onlyÀÊÊÌÅÈ 3113 Too many relevant points (IPHysterese)ÀÊÊÄÌ 3114 Number of labels in image too bigÀÊÊÆÆÄ 3115 No labels with negative values allowedÀÊÊÏË 3116 Wrong filter size (too small ?)ÀÊÊÁÏË 3117 Images with different image sizeÀÊÊÁÏÌÄ 3118 Target image too wide or too far on the rightÀÊÊÁÏÌË 3119 Target image too narrow or too far on the leftÀÊÊÁÀÌÄ 3120 Target image too high or too far downÀÊÊÁÀÌË 3121 Target image too low or too far upÀÊÊÆÇ 3122 Number of channels in the input parameters are differentÀÊÊÇÏÌË 3131 Coocurrence Matrix: too little columns for quantisationÀÊÊÇÀÌË 3132 Coocurrence Matrix: too little rows for quantisationÀÊÊÆÍÅÇÄÅÆ 3133 Wrong number of columnsÀÊÊÆÍÅÄÁÆË 3134 Wrong number of rowsÀÊÊÇÎÄ 3135 Number has too many digitsÀÊÊÆÇÌËÅ 3136 Matrix is not symmetricÀÊÊÆÍÅÇÄË 3137 Matrix is too bigÀÊÊËÆÌ 3138 Wrong structure of fileÀÊÊÅÁËËÁÆ 3139 Lesser than 2 matricesÀÊÊÇÇÅÅ 3140 Not enough memoryÀÊÊÆÇÁÄ 3141 Can not read the fileÀÊÊÁÄÏÊ 3142 Can not open file for writingÀÊÊÆÍÅÄÍÇÄË 3143 Too many lookup table colorsÀÊÊÏÆÇÄÁ 3145 Too many Hough points (lines)ÀÊÊÁÌË 3146 Target image has got wrong height (not big enough)ÀÊÊÏÁÆÌÅ 3147 Wrong interpolation modeÀÊÊÌÀÁÃÆÃ 3148 Region not compact or not connectedÀÊÊÏÁÆ¿ 3170 Wrong filter index for filter size 3ÀÊÊÏÁÆ 3171 Wrong filter index for filter size 5ÀÊÊÏÁÆ 3172 Wrong filter index for filter size 7ÀÊÊÏÄÏËË 3173 Wrong filter size; only 3/5/7ÀÊÊÏÆ 3200 Different number of entries/exits in HContCutÀÊÊÄÏÌ 3250 Wrong XLD typeÀÊÊÄÌÄ 3251 Internal error: contour too long for representationÀÊÊÄÊÈ 3252 Internal error: border point is set to FGÀÊÊÄÅÄ 3253 Internal error: maximum contour length exceededÀÊÊÄÅÆ 3254 Internal error: maximum number of contours exceededÀÊÊÄÌË 3255 Contour too short for fetch angle xldÀÊÊÄÊ 3256 Regression parameters of contours already computedÀÊÊÄÊÆ 3257 Regression parameters of contours not yet entered!Please compute them by calling regress cont xldÀÊÊ 3258 Data base: XLD object has been deletedÀÊÊÏÁ 3259 Data base: object has no XLD-IDÀÊÊÄÏÆÈ 3260 Internal error: wrong number of contour points allocatedÀÊÊÄÆ 3261 Contour attribute not definedHALCON 6.0

120 APPENDIX A. HALCON ERROR CODESÀÊÊÁÌÄÄÁÈË 3262 Ellipse fitting failedÀÊÊÁÌÁÊÄ 3263 Circle fitting failedÀÊÊÆÏ 3275 No ARC/INFO world fileÀÊÊÆÁ 3276 No ARC/INFO generate fileÀÊÊÄÁËÇÄÈÇÁÆÌ 3290 Isolated point while contour mergingÀÊÊËË 3300 Syntax error in file for trainingÀÊÊÌÅ 3301 Maximum number of attributes per example exceededÀÊÊÇÈË 3302 Not possible to open file for trainingÀÊÊÌÅËË 3303 Too many data sets for trainingÀÊÊÏËà 3304 Wrong key for data for trainingÀÊÊÌÅËÅ 3305 Too many examples for one data set for trainingÀÊÊÌÅÄË 3306 Too many classesÀÊÊÌÅÇ 3307 Maximum number of cuboids exceededÀÊÊÇÈ 3308 Not possible to open classifikator’s fileÀÊÊËÄ 3309 Error while saving the classificatorÀÊÊÇÈ 3310 Not possible to open protocol fileÀÊÊÄ 3311 Classificator with this name is already existentÀÊÊÌÅÄ 3312 Maximum number of classificators exceededÀÊÊÆÌÄ 3313 Name of classificator is too long, =20ÀÊÊÄÆÆ 3314 Classificator with this name is not existentÀÊÊÆÄ 3315 Current classificator is not definedÀÊÊÄË˾Á 3316 Wrong id in classification fileÀÊÊÄË˾ÎÊË 3317 Wrong verion number in classification fileÀÊÊÊÇÌÆÊ 3401 Wrong rotation numberÀÊÊÇÄ 3402 Wrong letter for Golay elementÀÊÊ 3403 Wrong reference pointÀÊÊÁÌÊ 3404 Wrong number of iterationsÀÊÊÅÇËË 3405 Mophology: system errorÀÊÊÊÌ 3406 Wrong type of boundaryÀÊÊÇÂÁ 3407 Morphology: wrong number of input objectsÀÊÊÇÂÇ 3408 Morphology: wrong number of output objectsÀÊÊÈÊÁ 3409 Morphology: wrong number of input control parameterÀÊÊÈÊÇ 3410 Morphology: wrong number of output control parameterÀÊÊËÄ 3411 Morphology: structuring element is infiniteÀÊÊÏÊÆË 3412 Morphology: wrong name for structuring elementÀÊÊÏÊÊÄƽ 3500 Wrong number of run length rows (chords): smaller than0ÀÊÊÏÊÊÄÄ 3502 Run length row with negative lengthÀÊÊÊÄÄÌ 3503 Run length row = image heightÀÊÊÊÄÄÌË 3504 Run length row 0ÀÊÊÊÄÌ 3505 Run length column = image widthÀÊÊÊÄÌË 3506 Run length column 0ÀÊÊÀÄÌ 3507 For CHORD TYPE: Number of row too bigÀÊÊÀÄÌË 3508 For CHORD TYPE: Number of row too smallÀÊÊÀÌ 3509 For CHORD TYPE: Number of column too bigÀÊÊÅÊÄ 3510 Exceeding the maximum number of run lengths while automaticalexpansionHALCON Extension Package Interface / 2000-11-16

121ÀÊÊÁÇÅÈÄ 3511 Internal error: Region-compl neither TRUE/FALSEÀÊÊÊÄÅ 3512 Internal error: Region-max num Region-numÀÊÊÏÊÊÄÆ¿ 3513 Internal error: number of chords too big for num maxÀÊÊÏÁÅϽ 3520 Image width 0ÀÊÊÏÁÅϾ 3521 Image width =MAXFORMATÀÊÊÏÁÅÀ½ 3522 Image height 0ÀÊÊÏÁÅÀ¾ 3523 Image height =MAXFORMATÀÊÊÏÁÅÏ¿ 3524 Image width =0ÀÊÊÏÁÅÀ¿ 3525 Image height =0ÀÊÊÌÅË 3550 Too many segmentsÀÊÊËÁÆ 3850 The light source positions are linearly dependentÀÊÊÏÁÅ 3851 No sufficient image indicationÀÊÊÊÆÇË 3852 Internal error: Function has equal signs in HZBrentÀÊÊÁÅà 3900 Kalman: Dimension n,m or p has got a undefined valueÀÊÊÆÇÁÄ 3901 Kalman: File does not existÀÊʽ 3902 Kalman: Error in file (row of dimension)ÀÊʾ 3903 Kalman: Error in file (row of marking)ÀÊÊ¿ 3904 Kalman: Error in file (value is no float)ÀÊÊÆÇ 3905 Kalman: Matrix A is missing in fileÀÊÊÆÇ 3906 Kalman: Matrix C is missing in fileÀÊÊÆÇÉ 3907 Kalman: Matrix Q is missing in fileÀÊÊÆÇÊ 3908 Kalman: Matrix R is missing in fileÀÊÊÆÇÍ 3909 Kalman: G or u is missing in fileÀÊÊÆÇÌËÅÅ 3910 Kalman: Covariant matrix is not symmetricÀÊÊËÁÆÍ 3911 Kalman: Equation system is singularÀÊÊÇÁÌ 4050 Image data management: object is a object tupelÀÊÊÇ 4051 Image data management: object has been deleted alreadyÀÊÊÏÇÁ 4052 Image data management: wrong object-IDÀÊÊÌ 4053 Image data management: object tupel has been deletedalreadyÀÊÊÏÌÁ 4054 Image data management: wrong object tupel-IDÀÊÊÌÁÇ 4055 Image data management: object tupel is a objectÀÊÊÁÆÍÄÄ 4056 Image data management: object-ID is NULL (0)ÀÊÊÏÁ 4057 Image data management: object-ID outside the validrangeÀÊÊÁ 4058 Image data management: access to deleted imageÀÊÊÏÁÁ 4059 Image data management: access to image with wrong keyÀÊÊÊ 4060 Image data management: access to deleted regionÀÊÊÏÊÁ 4061 Image data management: access to region with wrongkeyÀÊÊÏÀÆ 4062 Image data management: wrong value for image channelÀÊÊÁÌÄ 4063 Image data management: index too bigÀÊÊÁÍÆ 4064 Image data management: index not definedÀÊÊÏÌ 4065 internal error image data management: wrong clear typeÀÊÊÏËÆ 5100 Wrong (logical) window numberÀÊÊËÇ 5101 Error while opening the windowÀÊÊÏÏ 5102 Wrong window coordinatesÀÊÊÆÏ 5103 It is not possible to open another windowHALCON 6.0

122 APPENDIX A. HALCON ERROR CODESÀÊÊÆ 5104 Device resp. operator not availableÀÊÊÍÇÄ 5105 Unknown colorÀÊÊÆÏÇ 5106 No window has been opened for desired actionÀÊÊÏÅ 5107 Wrong filling mode for regions (fill or margin)ÀÊÊÏÎ 5108 Wrong gray value (0..255)ÀÊÊÏÈÎ 5109 Wrong pixel value (use value of get pixel(P) only)ÀÊÊÏÄÏ 5110 Wrong line width (see: query line width(Min,Max))ÀÊÊÏÍÊ 5111 Wrong name of cursor (see: query mshape(Name))ÀÊÊÏÄÍÌ 5112 Wrong color table (see: query lut(Name)ÀÊÊÏÅ 5113 Wrong representation mode (see: query insert(Mode))ÀÊÊÏÊÇ 5114 Wrong representation color (see: query color(List))ÀÊÊÏÊÅ 5115 Wrong dither matrix (binary image representation)ÀÊÊÏÊÁÌ 5116 Wrong image transformation (name or image size)ÀÊÊÁÈÁÌ 5117 Unsuitable image type for image transformationÀÊÊÏÊË 5118 Wrong zooming factor for image transformationÀÊÊÏÊË 5119 Wrong representation modeÀÊÊÏÊÎ 5120 Wrong code of deviceÀÊÊÏÏÁÆ 5121 Wrong number for father windowÀÊÊÏÌ 5122 Wrong window sizeÀÊÊÏÏÌ 5123 Wrong window typeÀÊÊÏÆ 5124 No current window has been setÀÊÊÏÊ 5125 Wrong color combination or range (RGB)ÀÊÊÏÈÆË 5126 Wrong number of pixels setÀÊÊÏÅ 5127 Wrong value for comprise (object or image)ÀÊÊÆ 5128 set fix with 1/4 image levels and static not validÀÊÊÄÆË 5129 set lut not valid in child windowsÀÊÊÄÇÄ 5130 Number of concurrent used color tables is too bigÀÊÊÏÁÌ 5131 Wrong device for window dumpÀÊÊÏÏË 5132 Wrong window size for window dumpÀÊÊÆÎË 5133 System variable DISPLAY (setenv) not definedÀÊÊÏÏ 5134 Wrong thickness for window marginÀÊÊÏÎË 5135 System variable DISPLAY has been set wrong(host:0.0)ÀÊÊÌÅ 5136 Too many fonts loadedÀÊÊÏÆ 5137 Wrong font nameÀÊÊÏÈ 5138 No valid cursor postionÀÊÊÆÌÏ 5139 Window is not a textual windowÀÊÊÆÈÏ 5140 Window is not a image windowÀÊÊËÌÄ 5141 String too long or too highÀÊÊÆËË 5142 Too little space in the window rightwardsÀÊÊÆÅË 5143 Window is not suitable for the mouseÀÊÊÏÆ 5144 Here Windows on a equal machine is permitted onlyÀÊÊÏÇÅ 5145 Wrong mode while opening a windowÀÊÊÏÏÅ 5146 Wrong window mode for operationÀÊÊÄÍÌ 5147 Operation not possible with fixed pixelÀÊÊÄÍÌÆ 5148 Color tables for 8 image levels onlyÀÊÊÏÌÅ 5149 Wrong mode for pseudo real colorsHALCON Extension Package Interface / 2000-11-16

123ÀÊÊÏÁÌÄ 5150 Wrong pixel value for LUTÀÊÊÏËÇÁ 5151 Wrong image size for pseudo real colorsÀÊÊÀÊÄÍÌ 5152 Error in procedure HRLUTÀÊÊÏÈËÄ 5153 Wrong number of entries in color table for set lutÀÊÊÏÈÎË 5154 Wrong values for image areaÀÊÊÏÄÈÆ 5155 Wrong line patternÀÊÊÏÄÈÄ 5156 Wrong number of parameters for line patternÀÊÊÏÆÇ 5157 Wrong number of colorsÀÊÊÏÈËÌ 5158 Wrong value for mode of area creation (0,1,2)ÀÊÊËÏÆ 5159 Spy window is not set (set spy)ÀÊÊÆËÇ 5160 No file for spy has been set (set spy)ÀÊÊÏËÈÆ 5161 Wrong parameter output depth (set spy)ÀÊÊÏÁ 5162 Wrong window size for window dumpÀÊÊÏÄÍÌ 5163 Wrong color table: wrong file name or query lut()ÀÊÊÏÄÍÌ 5164 Wrong color table: empty string ?ÀÊÊÏÄÍÌ 5165 Using this hardware set lut(’default’) is allowed onlyÀÊÊÆÈ 5166 Error while calling online helpÀÊÊÄÆÈÊ 5167 Row can not be projectedÀÊÊÆË 5168 Operation is unsuitable using a computer with fixed colortableÀÊÊÆ 5169 Computer represents gray scales only (no colors)ÀÊÊÄÍÌÇ 5170 LUT of this display is fullÀÊÊÏ 5171 Internal error: wrong color codeÀÊÊÏÏÌÌÊÌ 5172 Wrong type for window attributeÀÊÊÏÏÌÌÊÆ 5173 Wrong name for window attributeÀÊÊÏÊËÈÊÌ 5174 negativ height of area (or 0)ÀÊÊÏËÈÊÌ 5175 negativ width of area (or 0)ÀÊÊÏÆÎ 5176 Window not completely visibleÀÊÊÀ¿ 5180 Internal error: only RGB-ModeÀÊÊÆÅÏ 5181 No more (image-)windows availableÀÊÊÆ 5200 File not foundÀÊÊÏÁ 5201 Error while writing image data (sufficient memory ?)ÀÊÊÏÁ 5202 Error while writing image descriptor (sufficient memory?)ÀÊÊÊÁ½ 5203 Error while reading image data (format of image toosmall ?)ÀÊÊÊÁ¾ 5204 Error while reading image data (format of image too big?)ÀÊÊÊÁ½ 5205 Error while reading image descriptor: file too smallÀÊÊÁÁË 5206 Inconsistent image formatÀÊÊÀÆ 5207 Help file not found (setenv HALCONROOT Halcon-Homedirectory)ÀÊÊÆ 5208 Help index not found (setenv HALCONROOT Halcon-Homedirectory)ÀÊÊÆËÁ 5209 File standard input can not be closedÀÊÊÆËÇ 5210 standard output/error can not be closedÀÊÊÆ 5211 File can not be closedÀÊÊÏ 5212 Error while writing to fileHALCON 6.0

124 APPENDIX A. HALCON ERROR CODESÀÊÊÆ 5213 Exceeding of maximum number of filesÀÊÊÏÁÆ 5214 Wrong file nameÀÊÊÆÇ 5215 Error while opening the fileÀÊÊÏÅÇ 5216 Wrong file modeÀÊÊÏÈÌ 5217 Wrong type for pixel (e.g. byte)ÀÊÊÏÁÏ 5218 Wrong image width (too big ?)ÀÊÊÏÁÀ 5219 Wrong image height (too big ?)ÀÊÊÌ˽ 5220 File already exhausted before reading an imageÀÊÊÌ˾ 5221 File exhausted before terminating the imageÀÊÊÏÈÁ 5222 Wrong value for resolution (dpi)ÀÊÊÏÆÇÏ 5223 Wrong output image size (width)ÀÊÊÏÆÇÀ 5224 Wrong output image size (height)ÀÊÊÏÆÈ 5225 Wrong number of parameter values: format descriptionÀÊÊÏÈÆ 5226 Wrong parameter name for operatorÀÊÊÏËÆ 5227 Wrong slot name for parameterÀÊÊÆÈ 5228 Operator class is missing in help fileÀÊÊÏÀÁ 5229 Wrong or inconsistent help/*.idx or help/*.staÀÊÊÀÁÆ 5230 File help/*.idx not found (setenv HALCONROOTHalcon-Homedirectory)ÀÊÊÀËÆ 5231 File help/*.sta not found (setenv HALCONROOTHalcon-Homedirectory)ÀÊÊÁË 5232 Inconsistent file help/*.staÀÊÊÆ 5233 No explication file (.exp) foundÀÊÊÆÏà 5234 No file found in known graphic formatÀÊÊÏÁÌ 5235 Wrong graphic formatÀÊÊÁÆ 5236 Inconsistent file halcon.numÀÊÊÏÌÁ 5237 File with extension ’tiff’ is no Tiff-fileÀÊÊÏ 5238 Wrong file formatÀÊÊÆÇÈÈÊÇ 5239 gnuplot could not be startedÀÊÊÆÇÈÁÄ 5240 Output file for gnuplot could not be openedÀÊÊÆÇÈÇÍÌ 5241 Not a valid gnuplot output streamÀÊÊÆÇÈÆÅ 5242 No PNM formatÀÊÊÁÇ 5243 Inconsistent or old help file ($HALCONROOT/help)ÀÊÊÏÁ 5244 Wrong file handleÀÊÊÆÇ 5245 File not openÀÊÊÆÇÁÄË 5246 No files in use so far (none opened)ÀÊÊÏËÁ 5250 Invalid handle for a serial connectionÀÊÊËÆÇ 5251 Serial port not openÀÊÊÆË 5252 No serial port availableÀÊÊÆÇË 5253 Could not open serial portÀÊÊÆË 5254 Could not close serial portÀÊÊÆË 5255 Could not get serial port attributesÀÊÊÆËË 5256 Could not set serial port attributesÀÊÊÏÊËÊ 5257 Wrong baud rate for serial connectionÀÊÊÏÊË 5258 Wrong number of data bits for serial connectionÀÊÊÏÊË 5259 Wrong flow control for serial connectionÀÊÊÆË 5260 Could not flush serial portHALCON Extension Package Interface / 2000-11-16

125ÀÊÊÏË 5261 Error during write to serial portÀÊÊÊË 5262 Error during read from serial portÀÊÊÆË 5300 No frame grabber openedÀÊÊÏ 5301 Frame grabber: wrong color depthÀÊÊÏ 5302 Frame grabber: wrong deviceÀÊÊÎ 5303 Frame grabber: determination of video format notpossibleÀÊÊÆÎ 5304 Frame grabber: no video signalÀÊÊÍ 5305 Unknown frame grabberÀÊÊ 5306 Frame grabber: failed grabbing of an imageÀÊÊÏÊ 5307 Frame grabber: wrong resolution chosenÀÊÊÏÈ 5308 Frame grabber: wrong image part chosenÀÊÊÏÈÊ 5309 Frame grabber: wrong pixel ratio chosenÀÊÊÏÀ 5310 Frame grabber: handle not validÀÊÊÄ 5311 Frame grabber: instance not valid (already closed?)ÀÊÊÆÁ 5312 Frame grabber cannot be initializedÀÊÊÌ 5313 Frame grabber: external triggering not supportedÀÊÊÄÁ 5314 Frame grabber: wrong camera input line (multiplex)ÀÊÊË 5315 Frame grabber: wrong color spaceÀÊÊÈÌ 5316 Frame grabber: wrong portÀÊÊÌ 5317 Frame grabber: wrong camera typeÀÊÊÌÅ 5318 Frame grabber: maximum number of frame grabberclasses exceededÀÊÊÎ 5319 Frame grabber: device busyÀÊÊËÆ 5320 Frame grabber: asynchronous grab not supportedÀÊÊÈÊÅ 5321 Frame grabber: unsupported parameterÀÊÊÌÁÅÇÍÌ 5322 Frame grabber: timeoutÀÊÊÁÆ 5323 Frame grabber: invalid gainÀÊÊÁÄ 5324 Frame grabber: invalid fieldÀÊÊÈÊÌ 5325 Frame grabber: invalid parameter typeÀÊÊÈÊÎ 5326 Frame grabber: invalid parameter valueÀÊÊÆË 5327 Frame grabber: function not supportedÀÊÊÁÎÊË 5328 Frame grabber: incompatible interface versionÀÊÊÄÁÁÄÄÇË 5500 Error while closing the image fileÀÊÊÄÁÁÄÇÈÆ 5501 Error while opening the image fileÀÊÊÄÁÍÆÈÌÇ 5502 Premature end of the image fileÀÊÊÈÆÇÈÁÄ 5510 File is no PCX-FileÀÊÊÈÍÆÃÆÇÏÆÆÇÁÆ 5511 PCX: unknown encodingÀÊÊÈÅÇÊÌÀÆÈÄÆË 5512 PCX: More than 4 image plainsÀÊÊÈÇÄÇÊÅÈËÁÆÌÍÊ 5513 PCX: Wrong magic in color tableÀÊÊÈÊÈÌÇÍÆÌËÈÆË 5514 PCX: Wrong number of bytes in spanÀÊÊÈÌÇÇÅÍÀÁÌËÈÁÄ 5515 PCX: Wrong number of bits/pixelsÀÊÊÈÈÃÈÁÄË 5516 PCX: Wrong number of plainsÀÊÊÁÆÇÁÈÁÌÍÊ 5520 File is no GIF-FileÀÊÊÁÎÊËÁÇÆ 5521 GIF: Wrong version (not 87a/89a)ÀÊÊÁËÊÆËÊÁÈÌÇÊ 5522 GIF: Wrong descriptorÀÊÊÁÇÄÇÊÅÈ 5523 GIF: Wrong color tableHALCON 6.0

126 APPENDIX A. HALCON ERROR CODESÀÊÊÁÊÊÊÇÊÇ 5524 GIF: Premature end of fileÀÊÊÁÆÇÌÆÇÍÀÁÅË 5525 GIF: Wrong number of images ’;’ÀÊÊÁÊÊÇÊÇÆÌÆËÁÇÆ 5526 GIF: Wrong image extension ’!’ÀÊÊÁÄÌÌÇÈÏÁÌÀ 5527 GIF: Wrong left top widthÀÊÊÁÁÊÍÄÊÌÄÆÌÊ 5528 GIF: Cyclic index of tableÀÊÊÁÁÅÌ 5529 GIF: Wrong image dataÀÊÊËÍÆÊËÌÊÁÄÌÈ 5530 File is no Sun-Raster-FileÀÊÊËÍÆÊËÌÊÁÄÀÊ 5531 SUN-Raster: Wrong headerÀÊÊËÍÆÇÄË 5532 SUN-Raster: Wrong image widthÀÊÊËÍÆÊÇÏË 5533 SUN-Raster: Wrong image heightÀÊÊËÍÆÇÄÇÊÅÈ 5534 SUN-Raster: Wrong color mapÀÊÊËÍÆÊËÌÊÁÄÁÅ 5535 SUN-Raster: Wrong image dataÀÊÊËÍÆÁÅÈÇËËÁÄÌ 5536 SUN-Raster: Wrong type of pixelÀÊÊÏÁÅÈÇËËÁÄÌ 5540 XWD: Wrong type of pixelÀÊÊÏÎÁËÍÄÄËË 5541 XWD: Wrong visual classÀÊÊϽ¼ÀÊ 5542 XWD: Wrong X10 headerÀÊÊϽ½ÀÊ 5543 XWD: Wrong X11 headerÀÊÊϽ¼ÇÄÇÊÅÈ 5544 XWD: Wrong X10 colormapÀÊÊϽ½ÇÄÇÊÅÈ 5545 XWD: Wrong X11 colormapÀÊÊϽ½ÈÁÅÈ 5546 XWD: Wrong pixmapÀÊÊÏÍÆÃÆÇÏÆÎÊËÁÇÆ 5547 XWD: unknown versionÀÊÊÏÊÁÆÁÅ 5548 XWD: Error while reading an imageÀÊÊÌÁÁÆÈÍÌÌ 5550 TIFF: Error while reading a fileÀÊÊÌÁÇÄÇÊÅÈ 5551 TIFF: Wrong colormapÀÊÊÌÁÀÆÆÄÇÄÇÊ 5552 TIFF: Wrong number of color channelsÀÊÊÌÁÌÇÇÅÆÇÄÇÊË 5553 TIFF: Too many colorsÀÊÊÌÁÈÀÇÌÇÅÌÊÁ 5554 TIFF: Wrong photometric interpretationÀÊÊÌÁÈÀÇÌÇÅÌÊÁÈÌÀ 5555 TIFF: Wrong photometric depthÀÊÊÌÁÈÀÇÌÇÅÌÊÁÅËà 5556 TIFF: Wrong photometric maskÀÊÊÌÁËÅÈÄÌÇÇÄÊ 5557 TIFF: Number of samples too largeÀÊÊÌÁÆÇÊÁÇÆ 5558 TIFF: Image is no binary fileÀÊÊÅÈÆÇÅÈÈÁÌÍÊ 5560 File is no BMP-FileÀÊÊÅÈÊÊÊÇÊÇ 5561 BMP: Premature end of fileÀÊÊÅÈÁÆÇÅÈÄÌÀÊ 5562 BMP: Incomplete headerÀÊÊÅÈÍÆÃÆÇÏÆÇÊÅÌ 5563 BMP: Unknown bitmap formatÀÊÊÅÈÍÆÃÆÇÏÆÇÅÈÊËËÁÇÆ 5564 BMP: Unknown compression formatÀÊÊÅÈÇÄÇÊÅÈ 5565 BMP: Wrong color tableÀÊÊÅÈÏÊÁÌÊÊÇÊ 5566 BMP: Write error on outputÀÊÊÅÈÆÇÊÁÇÆ 5567 BMP: File does not contain a binary imageÀÊÊÂÈÇÅÈÆÍÅ 5570 JPEG: wrong number of components in imageÀÊÊÂÈÄÁÍÆÃÆÇÏÆ 5571 JPEG: unknown error from libjpegÀÊÊÂÈÄÁÆÇÌÁÅÈÄ 5572 JPEG: no implementet feature in libjpegÀÊÊÂÈÄÁÁÄ 5573 JPEG: file access error in libjpegÀÊÊÂÈÄÁÌÅÈÁÄ 5574 JPEG: tmp file access error in libjpegÀÊÊÂÈÄÁÅÅÇÊ 5575 JPEG: memory error in libjpegÀÊÊÂÈÄÁÁÆÇÊÅÌ 5576 JPEG: error in input imageÀÊÊËÇÃÌÄÇà 5600 Socket can not be set to blockHALCON Extension Package Interface / 2000-11-16

127ÀÊÊËÇÃÌÍÆÄÇÃ 5601 Socket can not be set to unblockÀÊÊËÇÃÌÆÇÈÊ 5602 Received data is no tupleÀÊÊËÇÃÌÆÇÁÅ 5603 Received data is no imageÀÊÊËÇÃÌÆÇÊÄ 5604 Received data is no regionÀÊÊËÇÃÌÆÇÄ 5605 Received data is no xld objectÀÊÊËÇÃÌÊÌÁÄ 5606 Error while reading from socketÀÊÊËÇÃÌÏÊÁÌÌÁÄ 5607 Error while writing to socketÀÊÊËÇÃÌÏÊÇÆÌÆÍÅÊ 5608 Illegal number of bytes with get rlÀÊÊËÇÃÌÍÊÇÎÊÄÇÏ 5609 Buffer overflow in read dataÀÊÊËÇÃÌÆÌËËÁÆ 5610 Socket can not be createdÀÊÊËÇÃÌÆÌÁÆ 5611 Bind on socket failedÀÊÊËÇÃÌÆÌÌÈÇÊÌÆÍÅÊ 5612 Socket information is not availableÀÊÊËÇÃÌÆÌÄÁËÌÆ 5613 Socket cannot listen for incoming connectionsÀÊÊËÇÃÌÆÌÈÌ 5614 Connection could not be acceptedÀÊÊËÇÃÌÆÌÇÆÆÌ 5615 Connection request failedÀÊÊËÇÃÌÌÀÇËÌÆÅ 5616 Hostname could not be resolvedÀÊÊËÇÃÌÊÎÁËÆ 5617 No data on socketÀÊÊËÇÃÌÁÄÄÄÌÍÈÄÌÈ 5618 Unknown tuple type on socketÀÊÊÄÁÆÃÏÊÁÌÌÁÄ 5650 Error while writing to virtual (EPX-) connection.ÀÊÊÄÁÆÃÊÌÁÄ 5651 Error while reading from virtual (EPX-) connectionÀÊÊÄÁÆÃÆÇÊÄ 5652 Received data is no HrlregionÀÊÊÄÁÆÃÆÇÁÅ 5653 Received data is no HimageÀÊÊÆÈ 6000 Access to undefined memory areaÀÊÊÅÅ 6001 not enough memory availableÀÊÊÁÅ 6002 Memory partition on heap has been overwrittenÀÊÊÏÅË 6003 HAlloc: 0 bytes requestedÀÊÊÆÇÌÅÈ 6004 Tmp-memory management: Call freeing memory althoughnothing had been allocatedÀÊÊÌÅÈÆÍÄÄ 6005 Tmp-memory management: Null pointer while freeingÀÊÊÆÅÅ 6006 Tmp-memory management: could not find memoryelementÀÊÊÁ 6040 System parameter for memory-allocation inconsistentÀÊÊÆÊ 6041 No memory block allocated at lastÀÊÊÏÇÈÁ 7000 Wrong index for output control parameterÀÊÊÏÇÈÎÆ 7001 Wrong number of values: output control parameter (see:HPut*ParÀÊÊÏÇÈÌ 7002 Wrong type: output control parameter (see: HPut*Par)ÀÊÊÏÃÌ 7003 Wrong data type for object key (input objects)ÀÊÊÁÇÇÊ 7004 Range for integer had been passedÀÊÊÁÀÎ 7005 Inconsistent Halcon versionÀÊÊÆÁËË 7006 Not enough memory for strings allocatedÀÊÊÈÊÇÆÍÄÄ 7007 Internal error: Proc is NULLÀÊÊÏÄËÌ 7100 Wrong list structure using input objectsÀÊÊÏÁÇÈ 7101 Wrong input object parameter (not bound)ÀÊÊÏÁÈ 7102 Wrong input control parameter (not bound)ÀÊÊÏÇÇÈ 7103 Wrong output object parameter (already bound)ÀÊÊÏÇÈ 7104 Wrong output control parameter (already bound)ÀÊÊÍÆÃÆ 7105 Unknown symbolic object key (input objects)HALCON 6.0

128 APPENDIX A. HALCON ERROR CODESÀÊÊÏÇÇÆ 7200 Wrong number of output object parameterÀÊÊÏÆÇÁÈ 7300 Wrong number of input parameterÀÊÊÇÌË 7400 System error: output type string expectedÀÊÊÇÌÄ 7401 System error: output type long expectedÀÊÊÇÌ 7402 System error: output type float expectedÀÊÊÇÈÁÆÈ 7403 Object parameter is a zero pointer (’ ’ not allowed)ÀÊÊÌÏ 7404 Tupel had been deleted; values are not valid any moreÀÊÊÈÈÏÇÅ 7430 CPP-interface internal error: wrong object modeÀÊÊÈÈÏÆÇÊ 7431 Wrong number of regions ( 1) for type HRegionÀÊÊÈÈÏÆÇÁ 7432 Wrong number of images ( 1) for type HImageÀÊÊÌÆÇÎÄ 7433 Tupel with undefined valuesÀÊÊÊÈË 7500 No contact to RPC serverÀÊÊÊÈ 7501 Error in remote procedure callÀÊÊËÏÁÆÇÄÁËÌ 7600 Parameter value is neither a list nor a atomÀÊÊÏÈÊÆ 8000 Unknown operator nameÀÊÊÊÆ 8001 register comp used is not activated (see set system)ÀÊÊÏÈ 8002 Unknown operator classÀÊÊÇÊÅ 8101 convol/Maske: error while opening the fileÀÊÊÇÊÅ 8102 convol/Maske: premature end of fileÀÊÊÎÌÊÅ 8103 convol/Maske: conversion errorÀÊÊÄÆÊÅ 8104 convol/Maske: wrong row-/column numberÀÊÊÏÇÎÊÅ 8105 convol/Maske: mask size overflowÀÊÊÆÇÊÅ 8106 convol/Maske: too many elements enteredÀÊÊÏÊÊ 8107 convol: wrong margin typeÀÊÊÅƼ 8108 convol: no mask object has got empty regionÀÊÊƼ 8109 convol: no filter object has got empty regionÀÊÊϼ 8110 convol: Weight factor is 0ÀÊÊÆÏ 8111 convol: inconsistent number of weightsÀÊÊÏÊÊÎ 8112 rank: wrong rank valueÀÊÊÊÇÎÄ 8113 convol/rank: error while handling marginÀÊÊÏÆÍÅÅ 8120 Wrong number of coefficients for convolution (sigma toobig?)ÀÊÊÏÆ 8200 No valid ID for data setÀÊÊÆ 8201 No data set active (set bg esti)ÀÊÊÆÍ 8202 ID already used for data set (is not poosible)ÀÊÊÆÌ 8203 Maximum number of data sets exceededÀÊÊÆ 8204 No data set created (create bg esti)ÀÊÊÆÌÅ 8205 Not possible to pass an object listÀÊÊÏÁË 8206 Image has other size than the backgroud image in data setÀÊÊÍÆËË 8207 Up-date-region is bigger than background imageÀÊÊËÆÌË 8208 Number of statistic data sets is too smallÀÊÊÏÅ 8209 Wrong value for adapt modeÀÊÊÏÅ 8210 Wrong value for frame modeÀÊÊÇÊÅŽ 8300 Maximum number of fonts exceededÀÊÊÇÊÏÁ 8301 Wrong ID (Number) for fontÀÊÊÇʽ 8302 OCR internal error: wrong IDÀÊÊÇÊÆÆÁ 8303 OCR not initialised: no font was read inHALCON Extension Package Interface / 2000-11-16

129ÀÊÊÇÊÆÁ 8304 No font aktivatedÀÊÊÇÊÏÌÈ 8305 OCR internal error: wrong threshold in angledeterminationÀÊÊÇÊÏ 8306 OCR internal error: wrong attributeÀÊÊÇÊÊ 8307 OCR: Error during reading fileÀÊÊÇÊÆÇË 8308 OCR File: inconsistent number of nodesÀÊÊÇÊÇ 8309 OCR File: File too shortÀÊÊÇÊÁƽ 8310 OCR: internal error 1ÀÊÊÇÊÁƾ 8311 OCR: internal error 2ÀÊÊÏÇÊÌÈ 8312 Wrong type of OCR tool (no ’box’ or ’net’)ÀÊÊÇÎÆÁ 8350 OCV system not initializedÀÊÊÏÇÎÌÈ 8351 Wrong type of OCV featuresÀÊÊÇÎÆÇÁ 8352 No more free OCV handles availableÀÊÊÇÎÏÆÅ 8353 Wrong name for an OCV objectÀÊÊÇÎÁÁ 8354 Training has already been appliedÀÊÊÇÎÆÇÌÌÊ 8355 No training has been applied to the characterÀÊÊÏÄÆÌÀ 8370 Wrong number of function pointsÀÊÊÆÇÍÆÌÁÇÆ 8371 List of values is not a functionÀÊÊÆÇÌËÆÁÆ 8372 Wrong ordering of values (not ascending)ÀÊÊÁÄÄÄÁËÌ 8373 Illigal distance of function pointsÀÊÊÄÄÄÈ 8400 You have to indicate at least 3 calibration pointsÀÊÊÄÈÌ 8401 Calibration table is too bigÀÊÊÄÆÈ 8402 No calibration table foundÀÊÊÄÊÈ 8403 Error while reading calibration table description fileÀÊÊÄÄÌÅÌÀ 8404 Minimum threshold while searching for ellipsesÀÊÊÄÊÈ 8405 Read error / format error in calibration table descriptionfileÀÊÊÄÈÊÇ 8406 Error in projection: s x=0orsy=0orz=0ÀÊÊÄÍÆÈÊÇ 8407 Error in inverse projectionÀÊÊÄÊÁÈ 8408 Not possible to open camera parameter fileÀÊÊÄÁȽ 8409 Format error in file: no colonÀÊÊÄÁȾ 8410 Format error in file: 2. colon is missingÀÊÊÄÁÈ¿ 8411 Format error in file: semiocolon is missingÀÊÊÄÊÈÇË 8412 Not possible to open camera parameter (pose) fileÀÊÊÄÇÈÇË 8413 Format error in camera parameter (pose) fileÀÊÊÄÇÈ 8414 Not possible to open calibration target description fileÀÊÊÄÇÈÈË 8415 Not possible to open postscript file of calibration targetÀÊÊÄÎÆ 8416 Error while norming the vectorÀÊÊÄÆÈÄÆ 8417 Fitting of calibration target failedÀÊÊÄÆÆÅÊ 8418 No next mark foundÀÊÊÄÆÆÉÍ 8419 Normal equation system is not solvableÀÊÊÄÉÌÀÅ 8420 Average quadratic error is too big for 3D position of markÀÊÊÄÆÇÄÄ 8421 Non elliptic contourÀÊÊÄÏÈÊÎ 8422 Wrong parameter value slvand()ÀÊÊÄÏÊË 8423 Wrong function results slvand()ÀÊÊÄÈÁ 8424 Distance of marks in calibration target description file isnot possibleÀÊÊÄÏÄ 8425 Specified flag for degree of freedom not validHALCON 6.0

130 APPENDIX A. HALCON ERROR CODESÀÊÊÄÆÇÅÊ 8426 Minimum error did not fall belowÀÊÊÄÏÈÌÈ 8427 Wrong type in Pose (rotation / translation)ÀÊÊÄÏÁÅË 8428 Image size does not match the measurement in cameraparametersÀÊÊÆÇÈ 8500 Not a pattern fileÀÊÊÏÈÎ 8501 wrong pattern file versionÀÊÊÅÌÀÅÇ 8502 Error during changing the file mode (t/b)ÀÊÊÅÌÀÇÇÊ 8503 Inconsistent match file: coordinates out of rangeÀÊÊÅÌÀÇÊÊ 8504 Pattern too near the image borderÀÊÊÆÇÌÈ 8505 The image(s) is not a pyramid (wrong zooming factor?)ÀÊÊÆÌÈÌË 8510 Number of shape model points too smallÀÊÊÅËÍÊÆ 8550 No more measure objects availableÀÊÊÅËÍÊÆÁ 8551 Measure object is not initializedÀÊÊÅËÍÊÇÇÊ 8552 Invalid measure objectÀÊÊÅËÍÊÁË 8553 Measure object is NULLÀÊÊÅËÍÊÏË 8554 Measure object has wrong image sizeÀÊÊÄÇÈÆ 8600 Dynamic library could not be openedÀÊÊÄÄÇË 8601 Dynamic library could not be closedÀÊÊÄÄÇÇÃÍÈ 8602 Symbol not found in dynamic libraryÀÊÊÊÍÆÃÆÇÏÆ 8700 Unkown bar codeÀÊÊÊÏÆÇÅ 8701 Wrong number of modulesÀÊÊÊÏÆÇ 8702 Wrong number of elementsÀÊÊÊÍÆÀÊ 8703 Unknown character (for this code)ÀÊÊÊÏÊÇÆËÊ 8705 wrong name for attribute in barcode descriptorÀÊÊÊÄÄÆÌÀ 8706 Wrong thickness of elementÀÊÊÊÆÇÊ 8707 No region foundÀÊÊÊÍÆÀʼ½ 8720 The 1st character is unknown (for this code)ÀÊÊÊÍÆÀʼ¾ 8721 The 2nd character is unknown (for this code)ÀÊÊÊÍÆÀʼ¿ 8722 The 3rd character is unknown (for this code)ÀÊÊÊÍÆÀʼ 8723 The 4th character is unknown (for this code)ÀÊÊÊÍÆÀʼ 8724 The 5th character is unknown (for this code)ÀÊÊÊÍÆÀʼ 8725 The 6th character is unknown (for this code)ÀÊÊÊÍÆÀʼ 8726 The 7th character is unknown (for this code)ÀÊÊÊÍÆÀʼ 8727 The 8th character is unknown (for this code)ÀÊÊÊÍÆÀʼ 8728 The 9th character is unknown (for this code)ÀÊÊÊÍÆÀʽ¼ 8729 The 10th character is unknown (for this code)ÀÊÊÊÍÆÀʽ½ 8730 The 11th character is unknown (for this code)ÀÊÊÊÍÆÀʽ¾ 8731 The 12th character is unknown (for this code)ÀÊÊÊÍÆÀʽ¿ 8732 The 13th character is unknown (for this code)ÀÊÊÊÍÆÀʽ 8733 The 14th character is unknown (for this code)ÀÊÊÊÍÆÀʽ 8734 The 15th character is unknown (for this code)ÀÊÊÊÍÆÀʽ 8735 The 16th character is unknown (for this code)ÀÊÊÊÍÆÀʽ 8736 The 17th character is unknown (for this code)ÀÊÊÊÍÆÀʽ 8737 The 18th character is unknown (for this code)ÀÊÊÊÍÆÀʽ 8738 The 19th character is unknown (for this code)ÀÊÊÊÍÆÀʾ¼ 8739 The 20th character is unknown (for this code)ÀÊÊʾÍÆÃÆÇÏÆÌÈ 8800 Specified code type is not supportedHALCON Extension Package Interface / 2000-11-16

131ÀÊÊʾÏÊÇÆÇÊÊÇÍÆ 8801 Wrong foreground specifiedÀÊÊʾÏÊÇÆËÁ 8802 Wrong matrix size specifiedÀÊÊʾÏÊÇÆËÀÈ 8803 Wrong symbol shape specifiedÀÊÊʾÏÊÇÆÈÊÅÆÅ 8804 Wrong generic parameter nameÀÊÊʾÏÊÇÆÈÊÅÎÄ 8805 Wrong generic parameter valueÀÊÊʾÏÊÇÆÅÇ 8806 Wrong symbol printing modeÀÊÊʾËÅÇÄÇÆÇÊÊ 8807 Symbol region too near to image borderÀÊÊʾÅÇÍÄÇÆÌÆÍÅ 8808 No rectangular modul boundings foundÀÊÊʾËÅÇÄÁÆÊ 8809 Couldn’t identify symbol finderÀÊÊʾËÅÇÄÁÅÆËÁÇÆ 8810 Symbol region with wrong dimensionÀÊÊʾÄËËÁÁÄ 8811 Classification failedÀÊÊʾÇÁÆÁÄ 8812 Decoding failedÀÊÊʾÇÁÆÊÊ 8813 Reader programing not supportedÀÊÊÆÇÌÁÅÈÄ 9000 Function not implemented on this machineÀÊÊÏÁÌ 9001 Image to process has wrong gray value typeÀÊÊÏÁ 9002 Wrong image component (see:get system(obj images,H))ÀÊÊÍÆÁ 9003 Undefined gray valuesÀÊÊÏÁË 9004 Wrong image format for operation (too big or too small)ÀÊÊÏÆ 9005 Wrong number of image components for image outputÀÊÊËÌÊÌÄ 9006 String is too long (max. 255 characters)ÀÊÊÏÁÌÇ 9007 Wrong pixel type for this operationÀÊÊÆÁÁÌ 9008 Operation not realized yet for this pixel typeÀÊÊÆÇÁÅ 9009 Image is no color image with three channelsÀÊÊÅÇÆÇ 9010 Frame grabbers are not supported in the demo versionÀÊÊÅÇÆÇÈ 9011 Packages are not supported in the demo versionÀÊÊËÌÍÇÈÆ 9050 Operator is not available in the student version ofHALCONÀÊÊËÌÍÈÆ 9051 Packages are not available in the student version ofHALCONÀÊÊËÌÍÆ 9052 The selected frame grabber is not available in the studentversion of HALCONÀÊÊÌÅÍ 9100 Too many unknown variables in linear equationÀÊÊÆÍË 9101 No (unique) solution for the linear equationÀÊÊÆ 9102 Too little equations in linear equationÀÊÊÅÆÁ 9200 No inversion of matrix possibleÀÊÊËÎÆÎÊ 9201 Singular value decomposition did not convergeÀÊÊËÎÏÊÇÏ 9202 Matrix has too little rows for singular value partitionÀÊÊÌÉÄÁÆÎÊ 9203 Eigenvalue computation did not convergeÀÊÊÂÇÁÆÎÊ 9204 Eigenvalue computation did not convergeÀÊÊÅÌÊÁËÁÆ 9205 Matrix is singularÀÊÊÅÌÀÆÎÊ 9206 Function matching did not convergeÀÊÊÅÌÍÆ 9207 Input matrix undefinedÀÊÊÅÌÏÁÅ 9208 Input matrix with wrong dimensionÀÊÊÅÌÆËÉÊ 9209 Input matrix is not quadraticÀÊÊÅÌÁÄ 9210 Matrix operation failedÀÊÊÅÌÆÈ 9211 Matrix is not positive definiteÀÊÊÏËÈÎÈ 9300 Eye point and reference point coincideHALCON 6.0

132 APPENDIX A. HALCON ERROR CODESHALCON Extension Package Interface / 2000-11-16