Home

HALCON Extension Package Programmer`s Manual

1. HALCON 6 0 CHAPTER 4 HALCON DATA TYPES 56 Names HCopyXLDCont HCopyXLDContPart Synopsis include Halcon h Herror HCopyXLDCont Hproc handle proc handle Hcont cont in Hcont cont out Herror HCopyXLDContPart Hproc handle proc handle Hcont cont in INT4_8 min_index INT4_8 max_index Hcont cont out Figure 4 8 Auxiliary routines for contours of type Hcont Names HAddXLDContAttrib HLookupXLDContAttrib HAddXLDContGlobalAttrib HLookupXLDContGlobalAttrib Synopsis include Halcon h HAddXLDContAttrib Hproc handle HLookupXLDContAttrib HAddXLDContGlobalAttrib HLookupXLDContGlobalAttrib Hcont char INT4 Hcont char INT4 Hproc_handle Hcont char INT4 Hcont char INT4 indx proc_handle cont name index cont name index proc handle cont name indx cont name Figure 4 9 Handling attributes of contour pixels within Hcont HALCON Extension Package Interface 2000 11 16 4 4 CONTROL PARAMETERS HPAR HCPAR 57 typedef struct lin seg type float row col a control point of the polygon row y and column x coordinate float length length of the line from the current to the next point float phi orientation rad of this line Hkey ref data base key of the underlying contour INT4 first
2. 2 3 14 23s 8 e ac hae et te ww eB 2 3 16 multichannel Do TEXt IM Ger Gotz te ody dee NT NUT SOS X 3 Style Guide for Programming 3 1 Basic Numeric Data Types 3 1 1 Local Variables Temporary Results 3 1 2 Procedure 8 a vg Meat og 2 GAELA 3 2 Memory Management 5 204 0 a EROR a 3 2 1 Temporary Data 3 2 2 Permanent Datas a 0 e qe e POP s 3 2 3 JDeBUDVIH S u a unde a e a a en eet ee a 3 3 Structuring Programs 3 4 Name Conventions for Procedures Dot put Outputs quos d Duon soe S Sor Ie oor Ir CER p J0 gt ric Se No See rutru ons x 3 7 Notes on Image Processing Operators 4 HALCON Data Types 41 Pixel Data Himage 4 2 Region Data Hrlregioh 43 XLDs 4 4 Control Parameters 5 Handling Iconic Objects and Control Parameters 5 Basic Access to Iconic Input Sil HGetOb oes ue eet xke es 5 12 HOSIGOIBD o renren RE 4 5 13 gee oe eedem T
3. 103 7 3 HALCON Directories 642684 9 XX 40x S ERR EA OS 111 A HALCON Error Codes 113 HALCON Extension Package Interface 2000 11 16 Chapter 1 Introduction HALCON can be extended by up to 99 additional operator packages During the initializa tion of the system all packages indicated by the environment variable HALCONEXTENSIONS are automatically loaded A package typically contains libraries with the new operators their pro totypes 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 from the HALCON data base Furthermore the operators provided by HALCON itself are also based on the functionality of the Extension Package Interface Thus the Extension Package Interface is both the interface be tween application programs and the operator layer of the the HALCON system and the interface between the operator layer and the object data base A reason why to extend the capabilities of HALCON by using the Extension Package Interface might be one of the following e Extension of the pool of image processing operators e Integration of special image processing hardware e Integration of a special graphics software package Once the user has extended HALCON by a package containing his her own ope
4. first get the number of values HGetCParNum proc_handle 3 amp num now num second allocate memory for the values and read them HCkP HA1locTmp proc handle void amp par3 size_t num sizeof HGetSPar proc_handle 3 FLOAT_PAR par3 num for i20 i lt num i par3 i par f 0 5 1 7 4 4 Figure 5 29 Use HGetCParNum to get the number of control values before reading the control parameter values of the operator call demo 5 Text 0 5 1 7 4 4 parameter values of the input control parameter number par_num 1 7 It is an alternative to HGetCPar see page 78 However HGetPPar is much more efficient in terms of memory overhead because it just returns pointers to the values instead of copying them Thus the caller needs not to allocate any memory before calling HGetPPar On the other hand the parameter values may only be read and must not be modified Note that for every parameter value its type LONG PAR FLOAT PAR STRING PAR is also stored within the Hcpar structure This is necessary because the same control parameter may contain values of different control data types The current number of parameter values is returned in num Figure 5 30 shows the usage of HGetPPar based on the example which was also used for HGetCPar compare figure 5 27 on page 80 5 5 5 HPutCPar HPutCPar see Fig 5 26 writes control data to the output control parameter number par num
5. H ERR WIPT2 wrong type of values control param 2 H ERR WION1 wrong number of objects in input object parameter 1 H ERR wrong image type H MSG FAIL procedure failed H_MSG_TRUE no error supply procedure H_MSG_OK no error any other procedure All HALCON procedures return an error code So this code has to be checked after calling any HALCON procedure This is done by using the following macro to call a procedure HCkP It checks the return value and exits the actual procedure if an error occurred a detailed de scription of the macro is given in the section 5 6 1 Please note that some of the Extension Package Interface macros described in chapter 5 and 6 e g HGetCPar perform similar tests automatically and return a proper error code implicitly 3Within this call the error text is reset to No error message available again to ensure that the user defined error text is up to date HALCON 6 0 48 CHAPTER 3 STYLE GUIDE FOR PROGRAMMING 3 7 Notes on Image Processing Operators e HALCON images are variable in their size format Therefore no constants should be used for image formats except MAX FORMAT for the maximum format The actual format of an image can be extracted from the structure Himage cf Fig 4 1 e 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 th
6. 2 3 DESCRIBING THE PARAMETERS 33 2 3 14 value number value number boolean expression This slot contains a boolean expression that determines how the number of passed or returned values of a parameter is absolutely or relatively connected to the number of values in other parameters or some absolute values The operators and functions listed in table 2 1 may appear within the expression Unary Operators Binary Operators i logical OR emi not equal Eee multiplication 7 Functions oaa Table 2 1 Operators and functions used for the slots value number and assertion Examples Parami Param2 amp amp Param2 gt 0 This means that the same number of values and at least one value must be passed with parameter 1 and parameter 2 Param2 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 parame ters e g RegionOut lt RegionIn in connection with the HALCON operator select shape expresses the fact that the number of output regions does not exceed the number of input re gions HALCON 6 0 34 CHAPTER 2 OPERATOR DESCRIPTION DEF FILES 2 3 15 assertion assertion boolean expression This slot contains a boolean expression that determines how the passed or returned values of parameters are absolut
7. For both HNewImage and HNewImagePtr the pixel type of the raw data within image is specified by the parameter kind Please see Fig 4 2 on page 50 for the supported values HAllocXLDCont allocates an XLD contour of type Hcont see section 4 3 including memory for num points contour points Internally this routine is based on HAlloc HFreeXLDCont is used to deallocate a contour again inluding all the points and all attributes defined for cont see page 53 Names HAllocRL HAllocRLNum HReallocRLNum HFreeRL Synopsis include Halcon h Herror HAllocRL Hproc handle proc handle Hrlregion HAllocRLNum _ 1 proc handle Hrlregion region size t len Herror HReallocRLNum Hproc handle proc handle Hrlregion region size_t len Hrlregion new region Herror HFreeRL Hproc handle proc handle Hrlregion region Figure 3 4 General memory management for region data The convenience routines HAllocRL HAllocRLNum HReallocRLNum and HFreeRL see Fig 3 4 are used for handling permanent region data based on HAlloc Otherwise their be haviour is similar to HAllocRLTmp etc see page 40 Note that it is possible to change the size of regions i e the number of chords using HReallocRLNum In contrast to HNewImage and HNewImagePtr HA11ocXLDCont also allocates memory for the structure Hcont itself not only for the data inside that structure HALCON Extension Packa
8. INT par num Hkey obj key HCopy0bj Hproc handle proc handle Hkey obj key INT par num Hkey obj key HPutDRL Hproc handle proc handle Hkey obj key Hrlregion region Hkey rl key Herror HCrXLD Hproc handle INT par num XLD xld INT xld type Hkey used xlds INT num used xlds DBFreeProc free proc Hkey obj key proc_handle Figure 5 18 Basic routines for creating new iconic objects and writing output object parameters to be continued 5 4 2 HCopyObj HCopy0bj see Fig 5 18 creates a new iconic object image region or XLD in the HALCON data base containing the same components as an already existing object specified by its data base key obj_key The new object is appended to the list of objects in the output object parameter with the number par_num The data base key of the new image object is returned in obj key Similar to HCrObj the components of a new image object can be reassigned using HDef0bj etc HCopy0bj is especially useful when output objects hardly differ from the corresponding input objects HALCON Extension Package Interface 2000 11 16 5 4 CREATING OBJECTS AND WRITING OUTPUT OBJECT PARAMETERS Names 73 HPut Image HDefO0bj HPutDImage HCrImage include Halcon h HPut Image Hproc_handle Himage HBOOL Hkey HDef0bj Hproc handle Hkey Hkey INT HPutDImage Hproc handle Herror HCrImage Hkey INT Himage HBOOL Hkey Hproc
9. amp region HGet Obj proc_handle par_num obj_num amp obj_key HGetDRL proc handle obj key region processing in general this should be done calling an action proc area 0 for i 0 i lt region gt num 1 area region gt rl i ce region rl i cb 1 HCkP HFreeRLTmp proc handle region Figure 5 10 Application of HGetDRL HGetDRL see Fig 5 9 combines HGetComp section 5 1 2 and HGetRL section 5 1 3 It reads the chord encoding of a region type Hrlregion see section 4 2 specified by the data base key ob j key of an image object The region data is copied to region that must have been allocated before with a suitable size e g by using HAllocRLTmp see section 3 2 1 Therefore this region data can be overwritten without side effects On the other hand the memory must be deallocated at the end of the supply procedure e g by using HFreeRLTmp Fig 5 10 shows an example application of HGetDRL 5 2 2 HGetFDRL In contrast to HGetDRL only a pointer to the region data is returned by HGetFDRL see Fig 5 9 So there is no need to allocate memory for the data On the other hand only read access to the data is allowed An example application of HGetFDRL can be seen in Fig 5 11 5 2 3 HGetURL HGetURL see Fig 5 9 reads all regions passed in the input object parameter with number par num computes the union of all these regions and returns the resulting region in region The Hrlregion data r
10. e lib VAARCHITECTUREX In this subdirectory the libraries encapsulating the new opera tors package and the corresponding language interfaces packagec and packagecpp reside Note that neither the name of these libraries nor their position within the package should be changed Otherwise the HALCON system cannot load the package The environment variable ARCHITECTURE is set during the installation of HALCON it describes the platform HALCON is running on The following table gives an overview of the currently supported platforms and the corresponding values of ARCHITECTURE hppai i hp hpux10 HP UX 10 x on Workstations at least PA 1 1 processors alpha dec osf4 0 DIGITAL UNIX 4 0 on Alpha processors 1586 1 2 2 Linux 2 2 on Intel Pentium or compatible e bin AARCHITECTUREA For Windows NT and Windows 2000 this subdirectory has to contain the DLLs package d11 packagec d11l and packagecpp dll corresponding to the above libraries We also recommend to place compiled example programs or addi tional utilities of a package in this subdirectory For UNIX systems the prefix 111 has to be added to the libraries resulting in libpackage libpackagec and libpackagecpp 5or Windows 2000 Snow called Tru64 UNIX HALCON 6 0 6 CHAPTER 1 INTRODUCTION e help This subdirectory contains files with data for the online access to the knowledge base They must be generated and placed in this directory in order to use a package inside of HDe
11. interface library libpackagecpp so providing the interface to new HALCON operators the object files HCPPpackage o and HCPPpackageGlobal o and the new operator lib libpackage so must be linked To create the library libparpackagecpp so for Parallel HALCON the corresponding object files compiled with the define DH PARALLEL must be linked to the Parallel HAL CON version of the operator library i e libparpackage so Creating new applications In order to create new application programs written in C or C you must link libpackage so and libpackagec so or libpackagecpp so to your objects be sides libhalcon so and libhalconc so or libhalconcpp so as for any HAL CON application Furthermore you must add the package library subdirectory lib sparc sun solaris7 to the environment variable LD_LIBRARY_PATH otherwise the loader will fail to access the libraries HALCON 6 0 108 CHAPTER 7 CREATING A NEW HALCON PACKAGE To create a Parallel HALCON version of your application just link the object files to the Parallel HALCON version of the libraries e g libparpackage so libparpackagec so libparhalcon so and libparhalconc so in case of a C ap plication You can use the same object files as for creating the standard HALCON appli cation The directory HALCONROOT examples extension_package halconuser contains two ex ample makefiles makefile creates the example package halconuser both for standard HAL CON and for Parallel HAL
12. 0 input output procedure or DB data base procedure The rest of the name describes the task performed by the procedure in english language beginning with a capital letter In case of filters an additional token might be inserted between these two parts of the name encoding the pixel type s of images to be processed e g HBYTE 14 INT4 or float Examples IPBLowpas IPI4Threshold IODispRegion DBGetTuple Basic routines performing a small task that might be used by many other routines should start with for Help The leading should be followed by a string encoding the data the routine works on e g RL for an auxiliary routine processing region data or XLD for routines working on XLDs Examples HRLUnion HXLDContLen HXLDContRegress Names of supply procedures start with C this stands for Core The rest is determined by the name of the underlying action procedure if there is only one If there are several action procedures whith names differing only by the symbols for different pixel types the pixel type is left out in the name of the supply procedure Examples CIPLowpas CIPThreshold CIO00penWindow 3 5 Input Output Except explicit IO routines HALCON procedures should not contain any input output com mands especially no print commands Any interaction should be done either via parameters HALCON Extension Package Interface 2000 11 16 3 6
13. 2 2 4 Header The operator description starts with the header extern operator name InternCProcedure InputObjects OutputObjects InputCtrlParams OuputCtrlParams Note that in contrast to the short version described in section 2 the header doesn t contain any information about the types of the control parameters e g and does not end with a semicolon 3 The following example is a short version of the operator description for the dynamic threshold operator dyn_threshold For better legibility there should be a comment at the beginning of every operator description like 1 yn dyn threshold CIPDynThreshold OrigImage ThresholdImage RegionDynThresh Offset LightDark Comments within def files are indicated according to the C syntax There are a couple of conventions restrictions concerning the names of parameters All word parts should begin with a capital letter e g RegionDynThresh They are directly concate nated without any separating character Especially they must not contain any underscore _ The external operator name exclusively consists of lower case characters with word parts sep arated by underscores This operator name is used within C programs low level calls of the operator in C or within HDevelop The four parameter classes input output object
14. 3137 3138 3139 3140 3141 3142 3143 3145 3146 3147 3148 3170 3171 3172 3173 3200 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 119 At least one input object has got an empty region Operation allowed for rectangular images 2 n only Too many relevant points IPHysterese Number of labels in image too big No labels with negative values allowed Wrong filter size too small Images with different image size Target image too wide or too far on the right Target image too narrow or too far on the left Target image too high or too far down Target image too low or too far up Number of channels in the input parameters are different Coocurrence Matrix too little columns for quantisation Coocurrence Matrix too little rows for quantisation Wrong number of columns Wrong number of rows Number has too many digits Matrix is not symmetric Matrix is too big Wrong structure of file Lesser than 2 matrices Not enough memory Can not read the file Can not open file for writing Too many lookup table colors Too many Hough points lines Target image has got wrong height not big enough Wrong interpolation mode Region not compact or not connected Wrong filter index for filter size 3 Wrong filter index for filter size 5 Wrong filter index for filter size 7 Wrong filter size only 3 5 7 Different number of entries exits in HContCut Wrong XLD type Internal error contour too long for repre
15. However instead of copying the num values like HPutCPar does HPutPPar directly stores the pointer to the array of Hcpar structures val Thus it causes less overhead As HPutPPar directly uses the passed Hcpar array without copying this array has to be allocated permanently i e it must be allocated by using HA11oc see section 3 2 2 on page 42 Furthermore the array must not be given free after passing it to HPutPPar Figure 5 32 shows how to write output control data with HPutPPar Note again that the types of the parameter values LONG PAR FLOAT PAR STRING PAR are stored with each Hcpar structure so that every data element may use a different type 5 5 7 HAllocStringMem In case of string parameters additional memory for the parameter values has to be allocated because the Hcpar structure only contains a pointer to char The easiest way to do this is to use HALCON Extension Package Interface 2000 11 16 5 6 AUXILIARY MACROS AND PROCEDURES 83 Hcpar HCkP HA110c proc handle size_t sizeof 2 VOIDP amp par par 0 par 1 6 par 0 type LONG PAR par 1 par f 4 4 1 FLOAT PAR HPutPPar proc_handle 1 par 2 Figure 5 32 Write the control parameter values 6 4 4 using HPutPPar HAllocStringMem see Fig 5 26 specifying the expected number of characters for all input strings parameter size at the begin of a supply procedure see Fig 5 27 and 5
16. It contains a copy of region It is common to call an image object region when only its region component is used HUserExport Herror CIPConvex Hproc handle proc_handle 1 Hrlregion region Hrlregion region new HCkP HAllocRLTmp proc handle amp region new allocate memory HAllReg proc handle amp region i 1 all regions HCkP HRLConvex2 proc handle region region new create an output region object first output param HNewRegion proc handle region new HCkP HFreeRLTmp proc_handle region_new free memory return H MSG TRUE Figure 6 9 A typical application of HNewRegion The region transformation convex hull Typically HNewRegion is used within segmentation procedures see Fig 6 4 and region trans forming procedures such as the procedure CIPConvex shown in Fig 6 9 CIPConvex corre sponds to a hypothetical operator trans convex which might be defined like trans_convex lt CIPConvex Region RegionConvex In the example all regions within Region are provided in region by 11 see section 6 1 1 one after the other The HALCON procedure HRLConvex2 computes the convex hull for HALCON Extension Package Interface 2000 11 16 6 2 OBJECT GENERATION 97 each region and writes it to region new Furthermore a new region object in the HALCON data base is created and added to the output object parameter RegionConvex Note that HNewRegion was also used in the exam
17. Maximum number of fonts exceeded Wrong ID Number for font OCR internal error wrong ID OCR not initialised no font was read in HALCON Extension Package Interface 2000 11 16 HERR OCR NAT H_ERR_OCR_WTP H_ERR_OCR_WF H_ERR_OCR_READ H_ERR_OCR_NODES H_ERR_OCR_EOF H_ERR_OCR_INC1 H_ERR_OCR_INC2 H_ERR_WOCRTYPE H_ERR_OCV_NI H_ERR_WOCVTYPE H_ERR_OCV_NOFID H_ERR_OCV_WNAME H_ERR_OCV_II H_ERR_OCV_NOTTR H_ERR_WLENGTH H_ERR_NO_FUNCTION H_ERR_NOT_ASCEND ING H_ERR_ILLEGAL_DIST H_ERR_CAL_LCALP H_ERR_CAL_CPTB H_ERR_CAL_NCPF H_ERR_CAL_RECPF H_ERR_CAL_LTMTH H_ERR_CAL_FRCP H_ERR_CAL_PROJ H_ERR_CAL_UNPRO H_ERR_CAL_RICPF H_ERR_CAL_FICP1 H_ERR_CAL_FICP2 H_ERR_CAL_FICP3 H_ERR_CAL_REPOS H_ERR_CAL_FOPOS H_ERR_CAL_OCPDF H_ERR_CAL_OCPPS H_ERR_CAL_EVECN H_ERR_CAL_NPLAN H_ERR_CAL_NNMAR H_ERR_CAL_NNEQU H_ERR_CAL_QETHM H_ERR_CAL_NOELL H_ERR_CAL_WPARV H_ERR_CAL_WFRES H_ERR_CAL_ECPDI H_ERR_CAL_WEFLA 8304 8305 8306 8307 8308 8309 8310 8311 8312 8350 8351 8352 8353 8354 8355 8370 8371 8372 8373 8400 8401 8402 8403 8404 8405 8406 8407 8408 8409 8410 8411 8412 8413 8414 8415 8416 8417 8418 8419 8420 8421 8422 8423 8424 8425 129 No font aktivated OCR internal error wrong threshold in angle determination OCR internal error wrong attribute OCR Error during reading file OCR File inconsistent number of nodes OCR File File too short OCR internal error 1 OCR interna
18. WW H ERR AG WA HERR AG WE HERR AG NU HERR AG NE HERR AG RR H_ERR_AG_CR H_ERR_AG_RN H_ERR_AG_TILT H_ERR_WRT H_ERR_WRS H_ERR_UNKPT H_ERR_UNKPARVAL H_ERR_CTRL_WPP H_ERR_GETTI H_ERR_GETCPUNUM 2202 2203 2204 2205 2206 2207 2830 2831 2832 2835 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2867 2868 117 Data of data base not defined internal error Number of operators too big System error in CORE2 wrong setting of H UNDEFINED User extension not properly installed Number of packages too large No such package installed Wrong access to global variable Used global variable does not exist Used global variable not accessible via GLOBAL ID Halcon server to terminate is still working on a job No such HALCON software agent Hardware check for parallelization not possible on a single processor machine Seq HALCON does not support parallel hardware check use Parallel HALCON instead Initialization of agent failed Termination of agent failed Inconsistent hardware description file Inconsistent agent information file Inconsistent agent knowledge file The file with the parallelization information does not match to the currently HALCON version revision The file with the parallelization information does not match to the currently used machine Inconsistent kn
19. index of the first point of the underlying contour belonging to current side of the polygon INT4 last index of the last contour point Hline_seg typedef struct poly_type INT4 num_line number of lines INT4 len_line maximum number of lines size of the array lines Hline seg lines control points of the polygon Hpoly Figure 4 10 The XLD data type Hpoly for subpixel polygons typedef union 1 INT4 1 4 byte integer float f 4 byte real char s string Hpar typedef struct Hpar INTL type Hcpar Figure 4 11 Data types Hpar and Hcpar for control parameters HALCON 6 0 58 CHAPTER 4 HALCON DATA TYPES HALCON Extension Package Interface 2000 11 16 5 Handling Iconic Objects and Control Parameters The HALCON Extension Package Interface provides a large set of procedures and macros for handling control parameters and iconic objects It supports tasks like e Accessing iconic input objects in the HALCON data base e Accessing single iconic objects within a tuple of objects e Accessing specific components regions gray value channels of image objects e Accessing XLDs e Creating iconic output objects in the HALCON data base based on the computed results Reading input control parameters e Writing output control parameters The routines of the Extension Package Interface described in this and the fol
20. is used for creating output images especially in the context of filter operations 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 their area of definition that is in their region component but not in their gray values Such objects have different data base keys and different regions but contain references to the same gray value channels Obviously it is very desirable to propagate this relation to the resulting output image objects as well HCrImage allocates memory for the image matrix within the Himage structure image out similar to HNewImage in section 3 2 2 The parameters type BYTE IMAGE LONG IMAGE FLOAT IMAGE etc see Fig 4 2 on page 50 width and height allow to specify the pixel type 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 HNewImage in section 3 2 2 for details Furthermore HCrImage creates a new data base object encapsulating this image data and returns the corresponding data base key in image key out similar to HPut Image in section 5 4 4 Finally HCrImage establishes a link between the original input image data referenced by the data base key image key in and this new object to avoid the allocation of multiple output gt This is necessary if the pixel dat
21. key Within the loop image in key is set to the data base key of the current image object and the corresponding image data is delivered in image in Using HA11Comp is equivalent to programming an explicit loop over all channels of an image object using HGetDImage 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 image_in So please restrict yourself to reading this data Any write access to the image matrix will cause unpredictable side effects Note that HA11Comp 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 will process the same region again and again for each channel Hkey obj in Hkey obj out Hkey image in key INTA4 8 comp index Himage image in image out HA110bj proc handle 1 0bj in j 1 HCr0bj proc handle 1 amp obj out HAllComp proc handle obj in image in key image in comp index HCkP HCrImage proc handle image in key 1 BYTE IMAGE image in height image in width amp im out key amp image out HCkP IPBRot90 image in pixel b image in width region in image out pixel b width height HDef0bj proc handle obj out im out key comp index Figure 5 17 Application of HA11Comp rotate all channels of all image objects of the first input object parameter Fig 5 17 shows an examp
22. num points par l cont gt num HPutCPar proc_handle 1 amp num_points 1 Figure 5 8 Example for HGetXLD Return the number of points of the contour with number obj_nun within input object parameter par_num Names HGetDRL HGetFDRL HGetURL HGetDImage HGetObjNum Synopsis include HGetDRL HGetFDRL HGetURL Halcon h Hproc handle Hkey Hrlregion Hproc handle Hkey Hrlregion Hproc handle INT Hrlregion HGetDImage Hproc handle Hkey INT Himage HGet b jNum Hproc handle Figure 5 9 Additional routines for accessing input image objects INT INT4_8 proc_handle obj_key region proc handle obj key proc handle par num region proc handle obj key channel image proc handle par_num num HALCON 6 0 66 CHAPTER 5 HANDLING ICONIC OBJECTS AND CONTROL PARAMETERS 5 2 Additional Routines for Accessing Input Image Ob jects This section introduces some routines that ease the programming of supply procedures in many applications see Fig 5 9 Basically they are combinations of the routines described in the previous section These additional routines only require the data base keys of the input objects that can be extracted by using the routines HGetObj se section 5 1 1 or HA110bj see section 5 3 1 For HGetURL even this step can be omitted 5 2 1 HGetDRL Hrlregion Hkey obj key HCkP HAllocRLTmp proc handle
23. of a HALCON operator The num values in the Hcpar structure val are copied by this routine Note that the types of the parameter values LONG PAR FLOAT PAR STRING PAR are stored with each Hcpar structure This allows to use a different type for every data element see Fig 5 31 HALCON 6 0 82 CHAPTER 5 HANDLING ICONIC OBJECTS AND CONTROL PARAMETERS Hcpar ctrl vali array of Hcpar structures INT4_8 num number of values of parameter 1 Hcpar xctrl_val2 Hcpar ctrl_val3 read all values of parameter number 1 HGetPPar proc_handle 1 amp ctrl_val1i amp num now ctrl vali O par 1 read a string in parameter number 2 HGetPPar proc_handle 2 amp ctrl_val2 amp num now ctrl_val2 0 par s Text read a tuple of float values in parameter number 3 may be any number of values HGetPPar proc_handle 3 amp ctrl_val3 amp num for i20 i lt num i ctrl val3 i par f 0 5 1 7 4 4 Figure 5 30 Read the control parameter values of the operator call demo 5 Text 0 5 1 7 4 4 using HGetPPar Hcpar par 2 par 0 par 1 6 par 0 type LONG PAR par 1 par f 4 4 1 FLOAT PAR HPutCPar proc_handle 1 par 2 Figure 5 31 Write the control parameter values 6 4 4 using HPutCPar 5 5 6 HPutPPar HPutPPar see Fig 5 26 is an alternative to HPutCPar and writes control data to the output control parameter number par_num
24. 1 HImageFD image out h mult 1 return H_MSG_OK HUserExport Herror CIPScaleNew Hproc_handle proc handle mult Hrlregion region Himage image in image out INT4_8 i HGetSPar proc_handle 1 FLOAT_PAR amp mult 1 HAllFilter proc handle amp region amp image in amp image out 1 i HCkP IPScaleNew region amp image in mult par f amp image out return H_MSG_TRUE Figure 6 5 A typical application of HA11Filter A filter operator 1 The simplest method is to implement the operator just for the most common pixel type BYTE IMAGE and return an error message HERR WIT for any other pixel type 2 Another way is to provide several action procedures one for every pixel type and call the appropriate procedure via switch image in kind 3 The third generic method makes use of the macros HDFImage and HImageFD see Fig 6 6 They encapsulate the access to gray values by buffering them in a double variable By writing pixel values via HImageFD the double value val is converted into the current pixel type of image in and therefore may be clipped and stored in the pixel specified by the linear coordinate 1in coord see section 4 1 The other way around the specified pixel value is converted to double and returned in val when using HDFImage to read image data The third method has been used in our example as it allows a very compact source code But this variant natur
25. 28 It is not necessary to deallocate this memory explicetly this is done automatically at the end of the supply procedure 5 6 Auxiliary Extension Package Interface Macros and Procedures In this section a couple of auxiliary routines are described that facilitate the programming of supply or action procedures see Fig 5 33 5 6 1 HCkP The macro HCkP see Fig 5 33 checks the result state of a procedure call Most of the HAL CON procedures are of the type Herror For internal HALCON procedures the result code H_MSG_OK is returned if no error occurred see also section 3 6 exits the current procedure if the encapsulated procedure returns any other error code Moreover this error code is returned to the caller of the current procedure The macro is used to make source code more compact but still safe with respect to error han dling see Fig 5 34 Here the call of the procedure HRLDecomp is encapsulated within the macro If any error occurs the procedure exits with an appropriate error number Otherwise the processing is continued Be aware that all memory permanently allocated within a procedure will not be deal located in case of an error if you exit the procedure using HCkP This will lead to memory leaks 8 All interface routines called in the examples in this chapter without being encapsulated by HCkP have func tionality comparable to HCkP i e they exit the current procedure returning an appropriate error
26. 7006 7007 7100 7101 7102 7103 7104 7105 127 Socket can not be set to unblock Received data is no tuple Received data is no image Received data is no region Received data is no xld object Error while reading from socket Error while writing to socket Illegal number of bytes with get_rl Buffer overflow in read_data Socket can not be created Bind on socket failed Socket information is not available Socket cannot listen for incoming connections Connection could not be accepted Connection request failed Hostname could not be resolved No data on socket Unknown tuple type on socket Error while writing to virtual EPX connection Error while reading from virtual EPX connection Received data is no Hrlregion Received data is no Himage Access to undefined memory area not enough memory available Memory partition on heap has been overwritten HAlloc 0 bytes requested Tmp memory management Call freeing memory al though nothing had been allocated Tmp memory management Null pointer while freeing Tmp memory management element could not find memory System parameter for memory allocation inconsistent No memory block allocated at last Wrong index for output control parameter Wrong number of values output control parameter see HPut Par Wrong type output control parameter see HPut Par Wrong data type for object key input objects Range for integer had been passed Inconsistent Halcon version
27. Creating the operator library 1ibpackage so To create the operator library libpackage so containing new HALCON operators the object files containing the corresponding supply and action procedures must be linked The linkage of shared libraries is done with ld check registry usr shlib so locations shared 11 Specify the desired name libpackage so and location of the library with the 1d option o In order to allow a checking of referenced symbols also include none 1X11 lc 1m lhalcon at the end of the 1d command see the example makefile e Creating the C interface library libpackagec so To create the C interface library libpackagec so providing the interface to new HALCON operators the object file HCpackage o and the new operator library libpackage so must be linked In order to allow a checking of referenced symbols also include none 1X11 lc 1m lhalcon lhalconc at the end of the 1d command see the example makefile e Creating the C interface library libpackagecpp so To create the C interface library libpackagecpp so providing the interface to new HALCON operators the object files HCPPpackage o and HCPPpackageGlobal o and the new operator lib libpackage so must be linked In order to allow a checking of referenced symbols also include none 1X11 lcxx lm lhalcon lhalconcpp HALCON Extension Package Interface 2000 11 16 7 3 HALCON DIRECTORIES 111 at the end of the 1d command see the exampl
28. HGet Image Average gray value of first channel raw data in image pixel This is much more efficient but means that only read access to the image matrix is recommended otherwise you will encounter unpredictable side effects Fig 5 7 shows an application of HGet Image 5 1 5 HGetXLD HGetXLD see Fig 5 1 is used to access XLD objects in the HALCON data base The object of interest is specified by the data base key obj key The parameter x1d type allows to specify the kind of XLD data to be accessed It has to be set to XLD CONTOUR ID in case of a contour and to XLD POLYGON ID in case of a polygon Corresponding to the selected type HGetXLD expects a pointer to Hcont or a pointer to Hpoly in the parameter x1d In both cases not the underlying data within the structures Hcont or Hpoly but only the pointers to the data are copied from the data base Thus please avoid any write access to this data Otherwise you will encounter unpredictable side effects changing other HALCON objects Fig 5 8 shows simple example for how to use HGetXLD HALCON Extension Package Interface 2000 11 16 5 2 ADDITIONAL ROUTINES FOR ACCESSING INPUT IMAGE OBJECTS 65 Hkey obj key Hcpar num points Hcont cont HGet Obj proc handle par num obj num amp obj key HGetXLD proc handle obj key XLD CONTOUR ID VOIDP cont processing in general this should be done calling an action proc num points type LONG PAR
29. R C image width 49 50 CHAPTER 4 HALCON DATA TYPES typedef union HBYTE 0 255 BYTE IMAGE Z 0 255 mod 256 CYCLIC_IMAGE HBYTE d orientation 0 180 DIR_IMAGE INT1 i 127 126 INT1 IMAGE INT4 l 4 byte integer LONG_IMAGE float f 4 byte real FLOAT_IMAGE HXYPixel Xy displacement vector field XY IMAGE x HComplexPixel c complex image COMPLEX IMAGE HLutPixel lut byte with LUT LUT IMAGE HInt2Pixel 5 2 bytes with sign INT2_IMAGE HPixellmage typedef struct INT kind pixel type HPixellmage pixel pixel data INT width image width INT height image height time of creation of image UINT2 msec milliseconds 0 999 UINT1 sec seconds 0 59 UINT1 min minutes 0 59 UINT1 hour 0 23 UINT1 day 1 81 UINT2 yday 1 366 UINT1 mon 1 12 UINT2 year starting at 1900 Himage Figure 4 1 Data type Himage for images define BYTE IMAGE INT 1 1 byte per pixel 0 255 define LONG IMAGE INT 2 4 byte per pixel INT4 define FLOAT IMAGE INT 4 4 byte per pixel float define DIR IMAGE INT 8 edge orientation 0 180 define CYCLIC IMAGE INT 16 0 255 cyclic define INT1 IMAGE INT 32 127 126 define XY IMAGE INT 64 2 byte images with sign define COMPLEX IMAGE INT 128 2 float
30. The minimal form of the extended operator def file includes A short description short the HALCON module module the operator belongs to the mapping to a chapter chapter of the manual the mapping to an object functionality and for every parameter its semantic type sem type In addition the type default type and number multivalue must be specified for control parameters Our operator user thresh has got the following parameters e one input object parameter Image e one output object parameter Region HALCON Extension Package Interface 2000 11 16 1 4 AN EXAMPLE 11 e one input control parameter Threshold of type int with exactly one value and e no output control parameter hcomp u C phalconuser threshold def Figure 1 5 Call of hcomp for HALCON C The operator definition within the def file now is used by hcomp to generate the appropriate interface code Fig 1 5 shows the call of hcomp Note that within this manual halconuser is used as name of the HALCON package to be created By calling hcomp with this options the files HChalconuser c interface code and HChalconuser h prototype of the new HALCON operator are created In the next step one has to program the new HALCON operator This is done by implementing the supply and action procedure This results in the typical structure of HALCON operators as illustrated in Fig 1 6 action procedure Herror IPBThreshold proc_handle region image w
31. about the parameter class input output object control about the parameter type etc The syntax and semantics of the definition file is explained in chapter 2 1 2 HALCON Packages Similar to the standard HALCON system a programmer has to provide at least two libraries DLLs in Windows NT 2000 shared libraries in UNIX environments in order to extend HALCON by a new operator package see chapter 7 e A library containing the new operators written in C Most of this manual is about how to write such operators based on internal data structures procedures of the HALCON system This library has the same name as the package itself in our example halconuser e Libraries encapsulating the generated interface code for C and C These libraries 1 the operator library and one of the interface libraries have to be linked to new applications in order to provide the interface of the new operators to the host language of your choice Most of the work concerning these libraries is done by the HALCON compiler hcomp see section 7 1 for details In the example package these libraries are called hal conuserc and halconusercpp The names of all these libraries are derived from the name of the package itself A package package contains the libraries package packagec and packagecpp HDevelop uses the C language interface that is the library halconuserc during initialization to integrate the new operators in its runtime environment
32. and pixel data of each image object so that they can work on the data within the loop Some also create output image objects The macros return the index of the current object obj index 1 within the input object parameter Thus obj index can be seen as a reference parameter of the macro and therefore is notated with amp obj_index The following table contains an overview of all loop macros their areas of application and the provided image data Their syntax is defined in Fig 6 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 PROCEDURES Application Image Data Provided HA11Reg region features region data Hrlregion of input region transformation image object binary morphology HA11Segm gray value features region and image data Hrlregion segmentation and Himage of input image object HAllFilter filter region and image data Hrlregion image transformations and Himage of input image object image data structure Himage for image output object HA11Filter2 filter intersection of the regions of both segmentation input image objects Hrlregion arithmetics with two input images the image data of both objects and a image data structure Himage for the image output object The macros return all regions as pointers to the original region data within the HALCON data base So the programmer is only allowed to read
33. be modified see sec tions 1 3 and 7 2 5 8 Linking of the generated libraries together with the HALCON library to the image anal ysis application cf chapter 7 For this you have to modify additional environment variables depending on the operating system see below Please note that HDevelop is able to access the new operators dynamically without linkage 1 3 Installing a HALCON Package In order to install HALCON package you have to copy the package to your hard disk and add the complete path of the package to the environment variable HALCONEXTENSIONS e g AHALCONROOT examples Vextension package Mhalconuser Note that the delimiter between paths in an environment variable is a semicolon on Windows NT or Windows 2000 systems and a colon on UNIX systems Never change the name of a package or the corresponding names of the li braries or DLLs contained in a package These names are encoded within the libraries DLLs If you change the names this information will not match any longer Thus the loader of the operationg system will fail to open the dynamic libraries In order to use the new package within HDevelop you have to restart the program For generating a standalone application using the package you have to link the C or C 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 in clude the corresponding
34. connection Serial port not open No serial port available Could not open serial port Could not close serial port Could not get serial port attributes Could not set serial port attributes Wrong baud rate for serial connection Wrong number of data bits for serial connection Wrong flow control for serial connection Could not flush serial port HALCON Extension Package Interface 2000 11 16 H ERR EDWS H_ERR_EDRS H_ERR_NFS H_ERR_FGWC H_ERR_FGWD H_ERR_FGVF H_ERR_FGNV H_ERR_UFG H_ERR_FGF H_ERR_FGWR H_ERR_FGWP H_ERR_FGWPR H_ERR_FGWH H_ERR_FGCL H_ERR_FGNI H_ERR_FGET H_ERR_FGLI H_ERR_FGCS H_ERR_FGPT H_ERR_FGCT H_ERR_FGTM H_ERR_FGDV H_ERR_FGASYNC H_ERR_FGPARAM H_ERR_FGTIMEQUT H_ERR_FGGAIN H_ERR_FGFIELD H_ERR_FGPART H_ERR_FGPARV H_ERR_FGFNS H_ERR_FGIVERS H_ERR_LIB_FILE_CLOSE H_ERR_LIB_FILE_OPEN H_ERR_LIB_UNEXPECTED_EOF H_ERR_PCX_NO_PCX_FILE H_ERR_PCX_UNKNOWN_ENCODING H_ERR_PCX_MORE_THAN_4_PLANES H_ERR_PCX_COLORMAP_SIGNATURE H_ERR_PCX_REPEAT_COUNT_SPANS H_ERR_PCX_TOO_MUCH_BITS_PIXEL H_ERR_PCX_PACKED_PIXELS H_ERR_GIF_NO_GIF_PICTURE H_ERR_GIF_BAD_VERSION H_ERR_GIF_SCREEN_DESCRIPTOR H_ERR_GIF_COLORMAP 5261 5262 5300 5301 5302 5303 5304 5305 5306 5307 5308 5309 5310 5311 5312 5313 5314 5315 5316 5317 5318 5319 5320 5321 5322 5323 5324 5325 5326 5327 5328 5500 5501 5502 5510 5511 5512 5513 5514 5515 5516 5520 5521 5522 5523 125 Error during write to serial p
35. ea 5 14 JAG ase 42624 RUE eee RUE ORAE G 9 125 qeu cre autore ete de ire S 5 2 Additional Routines for Accessing Input Image Objects Du Le TAG CUR Sok ot ades rata de RS 5 22 GGT eta Seo Ning eng RT Sou dou p DC ente ort e ed ee pedo oen HALCON Extension Package Interface 2000 11 16 Contents Contents SZA eHOSLUDIIABE a Qut SAI EUR II EAS EVAP ER eS 5 2 5 HGetObJNUM a eux MORS 5 3 Loop Macros for Accessing Single Input Objects 5 3 1 9 302 o oone E o Ret EP X 5 4 Creating Objects and Writing Output Object Parameters 2441 HCtTOD iid edi eode ede eoe edes 5 4 2 HCopyObj SA3 HPUODRD eae 5 4 4 HPutImage 54S arat uot n rete Od etd bes 5 4 6 HPutD mage SAT HOrnmudee au son amp ofa ese ee 540 HEX as A US Go 5 5 Reading and Writing Control Parameters HOE PIE auc toe X ENS xx 309 27 L sie san y SOS we BSR See BS MUS 5 33 HGetCParN ni vue ur dor ae ew Ex 054 e e Rte ome 339 GHPUICPSE cd ae tae Gow 5 5 6 enc oo RO EORR
36. edge amplitude of subpixel edge points or the orientation of the local gra dient Finally an arbitrary number of additional global attributes i e attributes valid for the entire contour can be included global e g the individual parameters of a regrssion line to the 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 typedef struct union 1 HFeatureFlags single a bitfield long all def UINT1 shape SHAPE x HBOOL is_convex HBOOL is_filled HBOOL is_connected4 is_connected8 HBOOL is_thin float circularity float compactness float contlength float convexity float phi float float float anisometry bulkiness structure faktor float mii m20 m02 ia ib float row col INT4 area INT2 rowi coli row2 col2 float row_rect col_rect phi_rect lengthi length2 float row_circle col_circle radius INT2 min_chord max_chord INT2 min_chord_gap max_chord_gap HRegFeature Figure 4 5 Data type HRegFeature for region features Please see section 3 2 2 for routines to allocate deallocate contours Two important auxiliary routines to copy contours are listed in Fig 4 8 HCopyXLDCont copies a contour including all attributes whereas HCopyXLDContPart copies only a part of the original contours specified by two indices min_index and max_index They refer to the first and the
37. file mode t b Inconsistent match file coordinates out of range Pattern too near the image border The image s is not a pyramid wrong zooming factor Number of shape model points too small No more measure objects available Measure object is not initialized Invalid measure object Measure object is NULL Measure object has wrong image size Dynamic library could not be opened Dynamic library could not be closed Symbol not found in dynamic library Unkown bar code Wrong number of modules Wrong number of elements Unknown character for this code wrong name for attribute in barcode descriptor Wrong thickness of element No region found The 1st character is unknown for this code The 2nd character is unknown for this code The 3rd character is unknown for this code The 4th character is unknown for this code The 5th character is unknown for this code The 6th character is unknown for this code The 7th character is unknown for this code The 8th character is unknown for this code The 9th character is unknown for this code The 10th character is unknown for this code The 11th character is unknown for this code The 12th character is unknown for this code The 13th character is unknown for this code The 14th character is unknown for this code The 15th character is unknown for this code The 16th character is unknown for this code The 17th character is unknown for this code The 18th character is unknown for t
38. from Hrlregion get_contour_global_attrib_xld See the Reference Manuals for details Within HALCON a specific attribute of a contour can be accessed using HLookupXLDCont Attrib while a spe cific global attribute can be accessed using HLookupXLDContGlobalAttrib These routines return the index of the desired attribute within attribs or global of cont or the error code H_ERR_XLD_CAND as result of the procedure call if no attribute with the specified name is de fined The XLD data type Hpoly displayed in Figure 4 10 encodes subpixel accurate polygons Basically it contains an array of control points In many applications such polygons are derived from contours Thus the data structure can also hold a reference to the underlying part of a contour specified by a HALCON data base key 4 4 Control Parameters Hpar Hcpar The HALCON data types Hpar and Hcpar are used within the Extension Package Interface to pass control parameters to supply procedures Fig 4 11 shows the corresponding definitions Hpar encodes a single parameter value of one of the basic types integer real or string see section 2 3 In addition to that Hcpar also encodes the corresponding type Thus it is possible to combine different types within an array of Hcpar values The selector type can be set to LONG PAR FLOAT PAR or STRING PAR The Extension Package Interface procedures HGetCPar HGetSPar HGetPPar HPutCPar and HPutPPar section 5 5 are based on Hcpar
39. given input image image key in If there is any only a reference to it is returned in image_out and image key out instead of creating a new matrix Without this mechanism a new matrix would be created again and again within the loop over all input objects HA110bj The parameter index is only of importance if more than one output matrix per input matrix is needed This is necessary for example if an edge filter is performed in x and y direction independently In this case HCrImage must be called several times for every input component one time for each output matrix to be created Assign increasing numbers 1 2 3 to the parameter index to indicate a new output matrix If there is only one matrix to create for the output image set index to 1 Fig 5 23 shows an exemplary application of HCrImage 5 4 8 HCrXLD HCrXLD see Fig 5 18 is used for creating XLD objects in the HALCON data base The parameter xld type allows to specify the kind of XLD to be created It has to be set to XLD CONTOUR ID in case of a contour and to XLD POLYGON ID in case of a polygon Corre sponding to the selected type HCrXLD expects a pointer to Hcont or a pointer to Hpoly in the HALCON Extension Package Interface 2000 11 16 5 4 CREATING OBJECTS AND WRITING OUTPUT OBJECT PARAMETERS 77 parameter x1d In both cases not the underlying XLD data but only the pointers to the data are copied to the data base Thus you must not deallocate or overwrit
40. handle Hkey INT INT INT Hkey Himage proc handle image copy obj key proc_handle obj_key comp_key comp proc_handle obj_key comp image image key proc handle image key in index type width height image key out image out Figure 5 19 Basic routines for creating new iconic objects and writing output object parameters continued 5 4 3 HPutDRL HPutDRL see Fig 5 18 stores region data encoded in the Hrlregion structure region in the HALCON data base and returns the data base key of the new object In addition to that the region object is assigned to the image object specified by the data base key obj key as the region component The latter might have been created before by using HCr0bj or HCopyObj see Figs 5 20 and 5 21 5 4 4 HPutImage HPutImage see Fig 5 19 stores the gray value channel image matrix image in the data base 3HPutDRL actually copies the data itself not only a pointer to the data HALCON 6 0 74 CHAPTER 5 HANDLING ICONIC OBJECTS AND CONTROL PARAMETERS Hkey obj_key_in obj_key_out reg_key_out Hrlregion _ Hrlregion region_out INT4 num_objs par_in 1 number of input parameter par_out 1 number of output parameter HReadGVA proc_handle HGnum_obj num objs par in for 1 o num objs HGet0bj proc handle par in o amp obj key in HGetFDRL proc handle obj key in amp regi
41. image JPEG unknown error from libjpeg JPEG no implementet feature in libjpeg JPEG file access error in libjpeg JPEG tmp file access error in libjpeg JPEG memory error in libjpeg JPEG error in input image Socket can not be set to block HALCON Extension Package Interface 2000 11 16 HERR SOCKET UNBLOCK H ERR SOCKET NO CPAR HERR SOCKET NO IMAGE HERR SOCKET NO RL HERR SOCKET NO XLD H ERR SOCKET READ DATA FAILED H ERR SOCKET WRITE DATA FAILED HERR SOCKET WRONG BYTE NUMBER H ERR SOCKET BUFFER OVERFLOW H ERR SOCKET CANT ASSIGN FD H ERR SOCKET CANT BIND HERR SOCKET CANT GET PORTNUMBER HERR SOCKET CANT LISTEN HERR SOCKET CANT ACCEPT HERR SOCKET CANT CONNECT HERR SOCKET GETHOSTBYNAME HERR SOCKET RECV IS NEG H ERR SOCKET ILLEGAL TUPLE TYPE H ERR LINK WRITE DATA FAILED H ERR LINK READ DATA FAILED H ERR LINK NO RL H ERR LINK NO IMAGE H ERR NP H ERR MEM H ERR ICM H_ERR_WMS H_ERR_NOTMP H_ERR_TMPNULL H_ERR_CNFMEM H_ERR_IAD H_ERR_NRA H_ERR_WOCPI H_ERR_WOCPVN H_ERR_WOCPT H_ERR_WKT H_ERR_IOOR H_ERR_IHV H_ERR_NISS H_ERR_PROC_NULL H_ERR_WLST H_ERR_WIOP H_ERR_WICP H_ERR_WOOP H_ERR_WOCP H_ERR_UNKN 5601 5602 5603 5604 5605 5606 5607 5608 5609 5610 5611 5612 5613 5614 5615 5616 5617 5618 5650 5651 5652 5653 6000 6001 6002 6003 6004 6005 6006 6040 6041 7000 7001 7002 7003 7004 7005
42. images define LUT_IMAGE INT 256 0 255 with color table define INT2 IMAGE INT 512 2 bytes with sign Figure 4 2 Definitions of pixel types There are two additional macros for computing rows and columns R C HRow L image width HCol L image width HALCON Extension Package Interface 2000 11 16 4 2 REGION DATA HRLREGION 51 typedef struct 1 float re real image part float im imaginary image part HComplexPixel typedef struct INT2 p pixel INT1 num_bits number of used bits HInt2Pixel typedef struct INT1 rOW y direction INT1 col x direction HXYPixel typedef struct HBYTE b 0 255 INT num lut length of color table HBYTE red 256 HBYTE green 256 HBYTE blue 256 HLutPixel Figure 4 3 Data types for Himage Please see section 3 2 2 for routines to allocate image data within Himage 4 2 Region Data Hrlregion In HALCON region data is represented by a special variant of the runlength encoding a chord encoding For every line chord of a region its row index coordinate line number and the column index x coordinate of its start and end point is stored Both the start point and the end point belong to the region Chord data must fulfill the following conditions e achord is limited to one row e chords may not overlap e chords are sorted in ascending order If a region
43. in chapters 5 to 6 Chapter 5 Handling Iconic Objects and Control Parameters has replaced the chapter Convenience Interface Macros and chapter 6 Special Routines for Typical Supply Procedures has replaced the chapter Elementary Interface Macros Chapter 7 Creating a New HALCON Package has been extended concerning UNIX systems The semantics of HAllocRL HAllocRLNum and HFreeRL has been changed These routines are now based on HAlloc and thus provide permanent memory The old semantics memory for temporary data is used for the new routines HAllocRLTmp HAllocRLNumTmp and HFreeRLTmp Note that the new names better reflect the behaviour of the routines Refer to section 3 2 for a detailed discussion A mechanism for providing a user defined error text for new operators has been included see HSetErrText in section 3 6 Do not use older HALCON versions together with packages based on HALCON 5 1 and vice versa Please update re compile all old packages e 2 7 Edition November 1997 The extension concept of the HALCON system has been generalized Instead of one user extension up to 99 extension packages can be handled by the new concept This results ba sically in a new arrangement of the generated files and a modified use of the environment variable HALCONEXTENSIONS Please re read chapter 1 Structure of HAL CON Packages and the Extension Package Interface and chapter 7 Creating a New HALCON Packag
44. in the environment variable HALCONEXTENSIONS In the Windows NT 2000 version the package paths in HALCONEXTENSIONS are separated by semicolons Note that DLLs must be stored in the subdirectory bin i586 nt4 of the package the corresponding libraries in the subdirectory 1ib i586 nt4 e Exporting the supply procedures The supply procedures like CIPUserThreshold in cipuserthreshold c must be explicitly exported by the operator DLL package d11 containing your new operators This is done by the macro HUserExport see e g Fig 1 6 e Creating object files for the Parallel HALCON version If you want to create a Parallel HALCON version of your package a second set of object files must be created from the source code files using the compiler define DH PARALLEL We recommend to place these object files into a separate directory to prevent confusing them with the object files created for the standard HALCON version e Creating the operator DLL package d11 and the library package lib To create the operator DLL package d11 containing new HALCON operators and the corresponding library package lib the object files containing the corresponding supply and action procedures and the HALCON library halcon 1ib must be linked To create the libraries parpackage d11 and parpackage 1ib for Parallel HALCON the corresponding object files compiled with the define DH PARALLEL must be linked to the Parallel HALCON library parhalcon 1ib instead
45. it is possible to buffer the global setting of this flag set the flag to FALSE prior to HNewImage and restore the old value afterwards if you would like to prevent an initialization in any case HNewImagePtr does not allocate memory for the image data but inserts the pointer data in the Himage structure image instead For this routine the initialization of the image data is controlled via the parameter initImg Note that you will encounter program crashes during deallocation of image objects if you insert a memory block that has not been allocated via HA11oc in the underlying Himage structure see e g HPutImage in section 5 4 However in specific situations for example while doing a frame grabber integration it might be desirable to use existing buffers allocated by some other procedures In that case you have to provide your own deallocation routine UserClearProcedure using DBSetClearImage for the image data when creating a HALCON image object in a supply procedure HPutImage proc handle image FALSE amp image key HCkP DBSetClearImage proc handle image key DBFreeImageProc UserClearProcedure where DBFreeImageProc is defined as typedef void DBFreeImageProc void mem that means the deallocation routine has got one parameter of type void and no return value If you pass a NULL pointer instead of UserClearProcedure the image data will not be deallocated So HNewImage does not allocate memory for the Himage structure
46. itself HALCON Extension Package Interface 2000 11 16 3 2 MEMORY MANAGEMENT Names 43 HAlloc HRealloc HFree HNewImage HNewImagePtr HAllocXLDCont HFreeXLDCont Synopsis include Halcon h Herror HAlloc Herror HRealloc Herror HFree Herror HNewImage Herror HNewImagePtr Herror HAllocXLDCont Herror HFreeXLDCont Hproc_handle size_t void Hproc_handle void size_t void Hproc_handle void Hproc_handle Himage INT INT INT Hproc_handle Himage INT INT INT void HBOOL Hproc_handle Hcont size_t Hproc_handle Hcont proc_handle size pointer proc handle pointer size new pointer proc handle pointer proc handle image kind width height proc handle image kind width height data initImg proc_handle cont num points proc handle cont Figure 3 3 General memory management within HALCON during the deallocation of the HALCON image object containing image Note that this might lead to a memory leak Note further that inserting image data in HALCON image objects using HNewImagePtr can cause undesirable side effects By overwriting the underlying data you HALCON 6 0 44 CHAPTER 3 STYLE GUIDE FOR PROGRAMMING might implicitly change one or more HALCON objects Be aware that you have to take care about such problems if you decide not to use the standard HALCON memory management that is HNewImage
47. line present in license file Incorrect FEATURESET line in license file Cannot compute FEATURESET line socket call failed setsockopt failed Message checksum failure Cannot read license file from server Not a license administrator Imremove request too soon Attempt to read beyond the end of LF path SYSSSETIMR call failed Internal FLEXIm Erro Please report to Globetrotter Software FLEXadmin API functions not avilable Invalid PACKAGE line in license file Server FLEXIm version older than client s Incorrect number of USERS HOSTS INCLUDED in op tions file see server log Server doesn t support this request This license object already in use Wrong index for output object parameter Wrong index for input object parameter Wrong index for image object too big or too small Wrong number HGetComp Wrong relation name region image component see Access to undefined gray value component Wrong image width Wrong image height Undefined gray value component Inconsistent data of data base typing Wrong index for input control parameter HALCON Extension Package Interface 2000 11 16 H_ERR_DBDU H_ERR_PNTL H_ERR_WUNDI H_ERR_UEXTNI H_ERR_NPTL H_ERR_NSP H_ERR_GV_WA H_ERR_GV_NC H_ERR_GV_NG H_ERR_HM_NT H_ERR_HM_NA H_ERR_AG_CN H_ERR_AG_NC H_ERR_AG_IN H_ERR_AG_NT H_ERR_AG_HW H ERR AG II H ERR AG IK H ERR AG WV H ERR AG HERR AG KC HERR AG CT HERR AG MT HERR AG HERR AG
48. lt 0 For CHORD _TYPE Number of row too big For CHORD TYPE Number of row too small For CHORD TYPE Number of column too big Exceeding the maximum number of run lengths while au tomatical expansion HALCON Extension Package Interface 2000 11 16 H_ERR_ICCOMPL H_ERR_RLEMAX H_ERR_WRRLN3 H_ERR_WIMAW1 H_ERR_WIMAW2 H_ERR_WIMAH1 H_ERR_WIMAH2 H_ERR_WIMAW3 H_ERR_WIMAH3 H_ERR_TMS H_ERR_SING H_ERR_FEWIM H_ERR_ZBR_NOS H_ERR_DIMK H_ERR_NOFILE H ERR FF1 H ERR FF2 H ERR FF3 H ERR NO A H_ERR_NO_C H_ERR_NO_Q H_ERR_NO_R H_ERR_NO_GU H_ERR_NOTSYMM H_ERR_SINGU H_ERR_DBOIT H_ERR_DBOC H_ERR_DBWOID H_ERR_DBTC H_ERR_DBWTID H_ERR_DBTIO H_ERR_DBIDNULL H_ERR_WDBID H_ERR_DBIC H_ERR_DBWIID H_ERR_DBRC H_ERR_DBWRID H_ERR_WCHAN H_ERR_DBITL H_ERR_DBIUNDEF H_ERR_DBWCT H_ERR_WSCN H_ERR_DSCO H_ERR_WWC H_ERR_NWA 3511 3512 3513 3520 3521 3522 3523 3524 3525 3550 3850 3851 3852 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 5100 5101 5102 5103 121 Internal error Region compl neither TRUE FALSE Internal error gt num lt Region gt num Internal error number of chords too big for num max Image width 0 Image width gt MAX_FORMAT Image height lt 0 Image height gt MAX_FORMAT Image width lt 0 Image height lt 0 Too many segments The light sou
49. new operators within C programs But they are not yet available within HDevelop because the online help files have not been generated so far There is also still missing any kind of documentation such as the HTML manual pages hcomp u M threshold def Figure 1 7 Calling the HALCON compiler hcomp to create the help files The generation of the online help files as they are used e g by HDevelop can also be done with the help of the HALCON compiler hcomp see Fig 1 7 However to do so an extended version of the def file must be available The generated help files must be placed in the subdirectory help of the package threshold def HALCONROOT bin ARCHITECTURE hcomp DEF SOURCES HCOMP all hdevelop c cpp hdevelop DEF SOURCES HCOMP L t all DEF SOURCES mv html doc html reference hdevelop c DEF SOURCES HCOMP L c all DEF SOURCES mv html doc html reference c cpp DEF SOURCES HCOMP 1 11 DEF SOURCES mv html doc html reference cpp Figure 1 8 Makefile for generating HTML references The help files generated by now are used to access information about the new operators by calling specific HALCON operators like get operator info This is of importance especially for constructing graphical user interfaces like HDevelop For the user a more convenient way to access information online is to browse through HTML documents The HTML documentation of HALCON operators can be g
50. number in case of an error HALCON 6 0 84 CHAPTER 5 HANDLING ICONIC OBJECTS AND CONTROL PARAMETERS Names HCkP HCkNoObj HRLDecomp HNumOfChannels Synopsis include Halcon h HCkP HCkNoObj Herror HRLDecomp HNumO0fChannels Hproc handle Herror Hproc handle Hproc handle Hrlregion INT Hrlregion Hrlregion Hproc handle INT4_8 INT proc_handle proc proc_handle proc_handle reg_in c reg inner reg outer proc handle obj index num channels Figure 5 33 Auxiliary Extension Package Interface Macros and Procedures Herror err without HCkP err HRLDecomp proc handle reg in ri1 c1 r2 c2 reg inner reg outer if err H_MSG_OK return err with HCkP HCkP HRLDecomp proc handle reg in ri c1 r2 c2 reg inner reg outer Figure 5 34 Error handling with HCkP 5 6 2 HCkNo0bj The macro HCkNoOb j see Fig 5 33 is used to check whether all iconic input parameters of an operator contain at least one object Otherwise the supply procedure is exited with a return code depending on the current setting of no object result accessible by the HALCON operators set system and get system see the Reference Manu als for details The default setting for no object result is MSG TRUE that means HCkNo0bj HALCON Extension Package Interface 2000 11 16 5 6 AUXILIARY MACROS AND PROCEDURES 85 reports error in ca
51. of gravity for all input regions in the first input object parameter nels of an object within the first input image object parameter are accessed within a loop Thus HA11Segm is a combination modification of HA110bj see section 5 3 1 HGetFDRL see section 5 2 2 and HA11Comp see section 5 3 2 It is especially useful for segmentation op erators transition of gray value channels to regions Some typical HALCON operators that make use of HA11Segm are threshold regiongrowing auto thresholdi1 class ndim1 or label_to_region A HALCON image object in short a HALCON image consists of one region that specifies its area of definition and of one or more channels gray value components containing the pixel data All channels of an image are of the same size but may have different pixel types The data contained in a channel pixel type the image matrix etc is stored in a structure of type Himage see section 4 1 If the image has only one channel the address of a variable of the type Himage is passed to HA11Segm For multichannel images an array of the type Himage max_channels must be passed to it The maximal number of channels to be accessed by HA11Segm is specified by the parameter max channels see Fig 6 3 Himage images 3 HA11Segm proc_handle region images 3 i Himage image HAllSegm proc handle region image 1 i Figure 6 3 The parameters image and max channels of HA11Segm The parameter max channels only specif
52. one can assign a list of keywords to an operator They are used e g by HDevelop to support the search for the proper operators for a given problem keywords english Threshold Gray Value Threshold Dynamic Threshold Local Threshold 2 2 8 predecessor successor alternatives The following slots also support interactive development of image processing applica tion with HALCON They are used to define potential convenient or necessary pre decessor predecessor and successor operators successor or to define alternatives alternatives All operators within these lists are referenced by their name 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 predecessor mean image smooth image gauss image successor connection select shape reduce domain select gray rank region dilationi opening alternatives highpass threshold background seg 2 2 9 see also The slot see a1so contains a list of operators that are used for similar tasks or help to under stand how an operator works see also mean image smooth image gauss image connection rank region dilationi 2 2 10 attention The slot attention contains hints for using the operator or specific limitations attention english If ParRef Offset is chosen from 1 1 1 1 dotsi e usually a very noisy region is generated req
53. one has to create a definition file file extension def as illustrated in Fig 1 3 and Fig 1 4 Fig 1 3 shows only the absolute minimum of information that a definition file must contain in order to call a new operator within C programs When using C or HDevelop an extended version is necessary as described in section 2 2 The minimal form of such an extended definition is illustrated in Fig 1 4 The def file specifies e the name of the operator user thresh 8 use it within C basically the same steps are necessary see section 7 HALCON 6 0 10 CHAPTER 1 INTRODUCTION user thresh CIPUserThreshold Image Region Threshold short german Schwellwertoperator short english Selection of gray values by thresholding module basic chapter german BenutzerErweiterungen chapter english UserExtensions functionality image parameter Image input object sem type image parameter Region output object sem type region parameter Threshold input control default type integer multivalue false sem type number Figure 1 4 An example for an extended def file of the operator user thresh minimal form cf AHALCONROOT examples Vc interface V halconuserMdef threshold def e the name of the supply procedure that has to be implemented in C CIPUserThreshold e names and types of the operator s parameter s The names of the parameters are only important for the manuals and within HDevelop
54. parallelization tuple channel and domain of course there should only be one string per level If none is specified in this case no other string should be spec ified no postprocessing is done on every parallelization level This means that the overall result value of the corresponding output control parameter is directly determined by the result value of the first parallelized operator instance e g the instance which worked on the first tuple element Alltogether Parallel HALCON currently supports the following postprocessing steps e none no postprocessing adopt first value e tuple add overall result value is the sum of the single result values of the tuple paral lelization e tuple min overall result value is the minimum of the single result values of the tuple parallelization e tuple max overall result value is the maximum of the single result values of the tuple parallelization e tuple concat overall result value is a tuple which contains all the result values of the tuple parallelization concatenation e channel add overall result value is the sum of the single result values of the channel parallelization e channel min overall result value is the minimum of the single result values of the chan nel parallelization e channel max overall result value is the maximum of the single result values of the chan nel parallelization e channel concat overall result value is a tuple which contai
55. parameter Wrong value of control parameter Wrong value of control parameter Wrong value of control parameter Wrong value of control parameter Wrong value of control parameter Wrong value of control parameter Wrong value of control parameter Wrong value of control parameter Wrong value of control parameter Wrong value of control parameter Wrong value of control parameter 113 114 APPENDIX A HALCON ERROR CODES H ERR WIPV16 1316 Wrong value of control parameter 16 H_ERR_WCOMP 1350 Wrong value of component see reset_obj_db H_ERR_WGCOMP 1351 Wrong value of gray value component see re set obj db H ERR WIPN1 1401 Wrong number of values of control parameter 1 H ERR WIPN2 1402 Wrong number of values of control parameter 2 H ERR WIPN3 1403 Wrong number of values of control parameter 3 H ERR WIPNA 1404 Wrong number of values of control parameter 4 H_ERR_WIPN5 1405 Wrong number of values of control parameter 5 H_ERR_WIPN6 1406 Wrong number of values of control parameter 6 H ERR WIPN7 1407 Wrong number of values of control parameter 7 H ERR WIPN8 1408 Wrong number of values of control parameter 8 H ERR WIPN9 1409 Wrong number of values of control parameter 9 H ERR WIPN10 1410 Wrong number of values of control parameter 10 H ERR WIPN11 1411 Wrong number of values of control parameter 11 H ERR WIPN12 1412 Wrong number of values of control parameter 12 H ERR WIPN13 1413 Wrong number of
56. region HAllFilter2 proc handle region amp image ini amp image in2 image out 1 i HCkP IPAddNew proc handle region amp image ini amp image in2 amp image out HCkP HFreeRLTmp proc_handle region return H_MSG_TRUE Figure 6 7 A typical application of HA11Filter2 6 2 Object Generation This section describes the convenience routines HNewRegion HPutRect and HDupObj for cre ating new image objects see Fig 6 8 HNewRegion creates a new image object in the HALCON data base encapsulating the specified region and adds this object to the first output object parameter HPutRect inserts a rectangular region as area of definition into an already existing output image object Finally HDupObj adds an iconic input object to the object list of the first output object parameter 6 2 1 HNewRegion HNewRegion see Fig 6 8 is used to create a new image object in the HALCON data base which is also added to the first output object parameter Only the region component area of HALCON 6 0 96 CHAPTER 6 SPECIAL ROUTINES FOR TYPICAL SUPPLY PROCEDURES Names HNewRegion HPutRect HDupObj Synopsis include Halcon h HNewRegion Hproc handle proc handle Hrlregion region HPutRect Hproc handle proc handle Hkey obj key INT width height HDupO0bj Hproc handle proc handle INT4_8 obj_index Figure 6 8 Convenience routines for creating output objects definition of the new object is defined
57. span PCX Wrong number of bits pixels PCX Wrong number of plains File is no GIF File GIF Wrong version not 87a 89a GIF Wrong descriptor GIF Wrong color table HALCON 6 0 126 HERR GIF READ ERROR EOF H ERR GIF NOT ENOUGH IMAGES H ERR GIF ERROR ON EXTENSION H ERR GIF LEFT TOP WIDTH H ERR GIF CIRCULAR TABL ENTRY H ERR GIF BAD IMAGE DATA H ERR SUN RASTERFILE TYPE H ERR SUN RASTERFILE HEADER HERR SUN COLS HERR SUN ROWS H_ERR_SUN_COLORMAP H_ERR_SUN_RASTERFILE_ IMAGE H_ERR_SUN_IMPOSSIBLE_DATA H_ERR_XWD_IMPOSSIBLE_DATA H_ERR_XWD_VISUAL_CLASS H_ERR_XWD_X10_HEADER H_ERR_XWD_X11_HEADER H_ERR_XWD_X10_COLORMAP H_ERR_XWD_X11_COLORMAP H_ERR_XWD_X11_PIXMAP HERR XWD UNKNOWN VERSION H ERR XWD READING IMAGE H ERR TIF BAD INPUTDATA H ERR TIF COLORMAP H ERR TIF BAD CHANNEL COLOR H ERR TIF TOO MANY COLORS H ERR TIF BAD PHOTOMETRIC H ERR TIF PHOTOMETRIC DEPTH H ERR TIF PHOTOMETRIC MASK H ERR TIF SAMPLE TOO LARGE H ERR TIF NO REGION H ERR BMP NO BMP PICTURE H ERR BMP READ ERROR EOF H ERR BMP INCOMPLETE HEADER H ERR BMP UNKNOWN FORMAT H ERR BMP UNKNOWN COMPRESSION H ERR BMP COLORMAP H ERR BMP WRITE ERROR H ERR BMP NO REGION HERR JPG COMP NUM H ERR JPGLIB UNKNOWN H ERR JPGLIB NOTIMPL HERR JPGLIB FILE H ERR JPGLIB TMPFILE H ERR JPGLIB MEMORY H ERR JPGLIB INFORMAT HERR SOCKET BLOCK
58. the options described as follows can only be switched on under mutual exclusion Use Note that hcomp also is used by MVTec to generate the interface code for the standard HALCON system 99 100 CHAPTER 7 CREATING A NEW HALCON PACKAGE hcomp C ppackage def files to create interface code for C C ppackage creates the files HOpackage c interface code and HCpackage h prototypes of operators To create interface code for use hcomp D ppackagel def files creating HCPPpackage cpp HCPPpackageGlobal cpp and HCPPpackage h prototypes providing the 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 help files These files are necessary for the online access to the operator knowledge base via HALCON operators like get operator info For example HDevelop uses their information to build up the menu tree Operator chapter and section structuring and Suggestions alternatives cross references predecessor successor and keywords The help files are generated for the language selected with the optional 1 option The default language is english hcomp M llanguage def files creates the following files language The operator description text value lists language i Index for every operator specifying the start address of its entry within the hlp file language List of keywords with the associ
59. 1ib i586 linux2 2 to the environment variable SHLIB_PATH otherwise the loader will fail to access the li braries To create a Parallel HALCON version of your application just link the object files to the Parallel HALCON version of the libraries e g libparpackage so libparpackagec so libparhalcon so and libparhalconc so in case of a C ap plication You can use the same object files as for creating the standard HALCON appli cation The directory HALCONROOT examples extension_package halconuser contains two ex ample makefiles makefile creates the example package halconuser both for standard HAL CON and for Parallel HALCON makefile_testprog creates the example applications based on the package halconuser again for both HALCON versions Both makefiles include the file make i586 linux2 2 which sets architecture dependent variables HALCON Extension Package Interface 2000 11 16 7 2 GENERATING HALCON PACKAGES 107 7 2 5 3 Generating Packages Under Solaris In order to activate a package its complete path e g HALCONROOT examples extension package halconuser must be included in the environment variable HALCONEXTENSIONS In the UNIX version the package paths in HALCONEXTENSIONS are separated by colons Please see also the comments on 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 cc CC compi
60. 2 5 2 Generating Packages Under Linux In order to activate a package its complete path e g HALCONROOT examples extension package halconuser must be included in the environment variable HALCONEXTENSIONS In the UNIX version the package paths in HALCONEXTENSIONS are separated by colons Please see also the comments on installing a HALCON package on a Linux system on page 8 e Compiling the source code In order to generate shared libraries you must produce position independent code For the gcc g compiler version gcc 2 95 this is done using the option fPIC For the gcc we also recommend the options march pentium mcpu pentiumpro ansi fno strict prototype HALCON 6 0 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 object files must be created from the source code files using the compiler define DH PARALLEL We recommend to place these object files into a separate directory to prevent confusing them with the object files created for the standard HALCON version Creating the operator library libpackage so To create the operator library libpackage so containing new HALCON operators the object files containing the corresponding supply and action procedures must be linked The linkage of shared libraries is done with 1d shared Specify the desired name libpackage so and location of the lib
61. 5 5 7 HAllocString Mem 5 6 Auxiliary Macros and Procedures 526 1 THORP S eue re oe eeu oe ee ded 5 06 2 HCKNGOD e 45928 dA bo RAS Sua PAS 2 05 HRLED CODD ES 5 6 4 HN mOfChannels 6 Special Routines for Typical Supply Procedures Goll Loop Macros sod So uei eras xui at De dta SR NOS AMIR GS EINST P RAUS gt JLAIDSEDHE vu EE bevor eo ERR 6 13 OA HAUFE es 6 2 6 2 1 HNewRe gIOm 2439949 sew a eae rS 6 22 HPUtREGb cache ara IER a ee ae Egi 6 2 3 HDu upObj eek exem ees 7 Creating a New HALCON Package 7 1 The HALCON Compiler hoomp 7 1 1 Selection of the Host Language 7 1 2 Creating the help files 7 1 3 Creating the 7 1 4 Creating HTMIZFPieS 2 oom Room aaa TAS Miscellaneous cosy rex EVE EEAR EE 7 2 Generating HALCON Packages 7 2 1 Creating the Operator Libraries 7 2 2 Creating the C Interface HALCON 6 0 Contents iv 7 2 3 103 7 2 4 Creating New 103 7 2 5 Additional Information for Specific Architectures
62. 5524 5525 5526 5527 5528 5529 5530 5531 5532 5533 5534 5535 5536 5540 5541 5542 5543 5544 5545 5546 5547 5548 5550 5551 5552 5553 5554 5555 5556 5557 5558 5560 5561 5562 5563 5564 5565 5566 5567 5570 5571 5572 5573 5574 5575 5576 5600 APPENDIX A HALCON ERROR CODES GIF Premature end of file GIF Wrong number of images GIF Wrong image extension GIF Wrong left top width GIF Cyclic index of table GIF Wrong image data File is no Sun Raster File SUN Raster Wrong header SUN Raster Wrong image width SUN Raster Wrong image height SUN Raster Wrong color map SUN Raster Wrong image data SUN Raster Wrong type of pixel XWD Wrong type of pixel XWD Wrong visual class XWD Wrong X10 header XWD Wrong X11 header XWD Wrong X10 colormap XWD Wrong X11 colormap XWD Wrong pixmap XWD unknown version XWD Error while reading an image TIFF Error while reading a file TIFF Wrong colormap TIFF Wrong number of color channels TIFF Too many colors TIFF Wrong photometric interpretation TIFF Wrong photometric depth TIFF Wrong photometric mask TIFF Number of samples too large TIFF Image is no binary file File is no BMP File BMP Premature end of file BMP Incomplete header BMP Unknown bitmap format BMP Unknown compression format BMP Wrong color table BMP Write error on output BMP File does not contain a binary image JPEG wrong number of components in
63. 7 5228 5229 5230 5231 5232 5233 5234 5235 5236 5237 5238 5239 5240 5241 5242 5243 5244 5245 5246 5250 5251 5252 5253 5254 5255 5256 5257 5258 5259 5260 APPENDIX A HALCON ERROR CODES Exceeding of maximum number of files Wrong file name Error while opening the file Wrong file mode Wrong type for pixel e g byte Wrong image width too big Wrong image height too big File already exhausted before reading an image File exhausted before terminating the image Wrong value for resolution dpi Wrong output image size width Wrong output image size height Wrong number of parameter values format description Wrong parameter name for operator Wrong slot name for parameter Operator class is missing in help file Wrong or inconsistent help idx or help sta File help idx not found setenv HALCONROOT lt Halcon Homedirectory gt File help sta not found setenv HALCONROOT lt Halcon Homedirectory gt Inconsistent file help sta No explication file exp found No file found in known graphic format Wrong graphic format Inconsistent file halcon num File with extension tiff is no Tiff file Wrong file format gnuplot could not be started Output file for gnuplot could not be opened Not a valid gnuplot output stream No PNM format Inconsistent or old help file SHALCONROOT help Wrong file handle File not open No files in use so far none opened Invalid handle for a serial
64. CON makefile testprog creates the example applications based on the package halconuser again for both HALCON versions Both makefiles include the file sparc sun solaris7 which sets architecture dependent variables 7 2 5 4 Generating Packages Under IRIX In order to activate a package its complete path e g HALCONROOT examples extension_package halconuser must be included in the environment variable HALCONEXTENSIONS In the UNIX version the package paths in HALCONEXTENSIONS are separated by colons Please see also the comments on installing a HALCON package on a IRIX system on page 8 e Creating the operator library libpackage so To create the operator library libpackage so containing new HALCON operators the object files containing the corresponding supply and action procedures must be linked The linkage of shared libraries is done with ld check registry usr lib so locations shared Specify the desired name libpackage so and location of the library with the 1d option o To allow the location of such a library to be resolved by the operating system during runtime using LD_LIBRARY_PATH also specify soname libpackage so e Creating the C interface library libpackagec so To create the C interface library libpackagec so providing the interface to new HALCON operators the object file HCpackage o and the new operator library libpackage so must be linked e Creating the C interface library libpackagecpp so To cr
65. CRIPTION DEF FILES The information specified up to now is already sufficient to integrate an operator within the HALCON Extension Package Interface by using hcomp It describes the operator properly and may be specified as a one line short version of the def file according to the following syntax extern operator name lt InternCProcedure InputObjects OutputObjects InputCtrlParams uputCtrlParams Chapter 2 2 explains the meaning of the single identifiers and the name convention Please note that in contrast to the header mentioned there the short version header must be finished by a semicolon and that the default type and the number of values is specified together with the name of a control parameter InputCtrlParams and OuputCtrlParams This is done by concatenating a dollar sign and an additional character to the name encoding the type and number of values cf the example in Fig 2 1 user inside lt CIPUserSelect Regions RegionSelected Row i Column i Figure 2 1 Short version of the definition of the operator user inside cf AHALCONROOT examples Vc interface MhalconuserMdef regionfeatures def The following table shows how to code types and number of values into a character Lower case characters stand for exactly one value in the specified parameter This corresponds to assigning multivalue false in the extended version Capital letters specify parameters that contain more than one value passed as a tuple mul
66. ERROR HANDLING 47 or via Extension Package Interface in output procedures Error messages should be encoded by proper error numbers returned by the procedure see next section 3 6 Error Handling Error messages are represented by integer constants the error numbers of type Herror If an error occurs the corresponding error number should be returned by the procedure The file 4HALCONROOT A include Hconst h contains predefined error messages for all typical errors 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 than 10 000 to avoid re using an already allocated number or a number reserved for future extensions of the HALCON system If the user defined operator returns a user defined error the error will be reported as No error message available for this error code error number In order to provide user defined errors with error messages the function Herror HSetErrText char error_text can be called immediately before the operator returns the error code with return H ERR In this case the error message error text will be displayed by the next call of the HALCON operator get error text Error numbers are specified via define and are called XYZ Examples H_ERR_WIPN1 wrong number of values in input control parameter 1 H ERR WIPV3 wrong parameter value control param 3
67. HALCON Version 6 0 MVTec Software GmbH HALCON Extension Package Interface Programmer s Manual This manual shows how to create HALCON extension packages based on new operators written in C All rights reserved No part of this publication may be reproduced stored in a retrieval system or transmitted in any form or by any means electronic mechanical photocopying recording or otherwise without prior written permission of the publisher Edition July 1997 Edition November 1997 Edition March 1998 Edition April 1999 Edition October 2000 LE a om EC Copyright 1997 2000 by MVTec Software GmbH M nchen Germany Microsoft Windows Windows NT and Windows 2000 are either trademarks or registered trademarks of Microsoft Corporation Linux is a trademark of Linus Torvalds Sun and Solaris are either trademarks or registered trademarks of Sun Microsystems HP HP UX and PA RISC are either trademarks or registered trademarks of Hewlett Packard Company Silicon Graphics SGI and IRIX are either trademarks or registered trademarks of Silicon Graphics Inc DIGITAL UNIX Alpha AXP and Tru64 are either trademarks or registered trademarks of Compaq Computer Corporation other nationally and internationally recognized trademarks and tradenames are hereby rec ognized More information about HALCON can be found at http www mvtec com halcon About This Manual This manual describes how to
68. IX version the package paths in HALCONEXTENSIONS are separated by colons Please see also the comments on installing a HALCON package on a HP UX system on page 8 e Compiling the source code In order to generate shared libraries you must produce position independent code For the cc CC compiler this is done using the option 7 e Creating the operator library libpackage s1 To create the operator library libpackage sl containing new HALCON operators the object files containing the corresponding supply and action procedures must be linked The linkage of shared libraries is done with 1d b Specify the desired name libpackage s1 and location of the library with the 1d option o To allow the location of such a library to be resolved by the operating system during runtime using SHLIB PATH also specify the 1d option s e Creating the C interface library libpackagec s1 To create the C interface library libpackagec sl providing the interface to new HALCON operators the object file HCpackage o and the new operator library libpackage s1 must be linked e Creating the C interface library 1libpackagecpp s1 To create the C interface library libpackagecpp s1 providing the interface to new HALCON operators the object files HCPPpackage o and HCPPpackageGlobal o and the new operator lib 1 51 must be linked e Creating new applications In order to create new application programs written in C or you must link libpacka
69. LM USERSQUEUED H ERR FLEX LM SERVLONGGONE H ERR FLEX LM TOOMANY H ERR FLEX LM CANTREADKMEM H ERR FLEX LM CANTREADVMUNIX 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 115 Imclient h liblmgr a version mismatch Networking software not available on this machine Old vendor keys supplied License key in license file does not match other data in file Encryption handshake with daemon failed key structure is incorrect type or feature NULL or num licenses System clock has been set back This error can only occur when the FEATURE line contains an expiration date Version argument is invalid floating point format License server busy starting another copy of itself retry Cannot establish a connection with a license server Feature is queued lc status will determine when it is available Vendor keys do not support this function Checkout request filtered by the vendor defined filter routine Checkout exceeds MAX specified in options file licenses in use No license server specified for counted license Can not find feature in the license file Server has different license file than client client s li cense has feature but server s does not License file does not support a version this new This
70. LTmp and HAllocRLNumTmp are convenience routines that are based on HAllocTmp HAllocRLTmp allocates as much memory as is necessary for the largest region actually stored in HALCON data base the minimal size is DEF RL LENGTH 50000 chords HAllocRLNumTmp allows to determine the size of memory to be allocated by specifying the number of chords Furthermore HAllocRLTmp and HA1locRLNumTmp initialize the data struc ture Hr1region for the new region see section 4 2 for a description of Hrlregion Note that since these routines are based on HAllocTmp the corresponding memory blocks are interleaved with the blocks allocated directly via HAllocTmp This has to be considered while deallocating the corresponding memory Temporary data on arbitrary heap positions The temporary data management routines described so far use a stack This is of advantage concerning runtime but it lecks flexibility if you do not want to deallocate memory in a fixed order again Therefore HALCON also provides routines for allocating temporary memory on an arbitrary position of the heap see Fig 3 2 Memory blocks allocated by HAllocLocal can be deallocated by HFreeLocal in an arbitrary order However similar to the stack based temporary data management all these blocks are automatically deallocated at the end of HALCON operator Again this mainly aims on preventing memory leaks in case of errors As usual the routine HReallocLocal is used to allocate a new memory bl
71. Not enough memory for strings allocated Internal error Proc is NULL Wrong list structure using input objects Wrong input object parameter not bound Wrong input control parameter not bound Wrong output object parameter already bound Wrong output control parameter already bound Unknown symbolic object key input objects HALCON 6 0 128 HERR WOON H_ERR_WNOIP H_ERR_OTSE H_ERR_OTLE H_ERR_OTFE H_ERR_OPINP H_ERR_TWC H_ERR_CPPWOM H_ERR_CPPWNOR H_ERR_CPPWNOI H_ERR_TNOVAL H_ERR_RPCS H_ERR_RPC H_ERR_SWI_NOLIST H_ERR_WPRN H_ERR_RCNA H_ERR_WPC H_ERR_ORMF H_ERR_EOFRMF H_ERR_CVTRMF H_ERR_LCNRMF H_ERR_WCOVRMF H_ERR_NEOFRMF H_ERR_WRRA H_ERR_MCNO H_ERR_FCNO H_ERR_WFO H_ERR_NWC H_ERR_WRRV H_ERR_ROVFL H_ERR_WNUMM H_ERR_WBEDN H_ERR_NBEDA H_ERR_BEDNAU H_ERR_BEDNTB H_ERR_NBEDC H_ERR_NTM H_ERR_WISBE H_ERR_UDNSSBE H_ERR_SNBETS H_ERR_WAMBE H_ERR_WFMBE H_ERR_OCR_MEM1 H_ERR_OCR_WID H_ERR_OCR1 H_ERR_OCR_NNI 7200 7300 7400 7401 7402 7403 7404 7430 7431 7432 7433 7500 7501 7600 8000 8001 8002 8101 8102 8103 8104 8105 8106 8107 8108 8109 8110 8111 8112 8113 8120 8200 8201 8202 8203 8204 8205 8206 8207 8208 8209 8210 8300 8301 8302 8303 APPENDIX A HALCON ERROR CODES Wrong number of output object parameter Wrong number of input parameter System error output type lt string gt expected System error output type long expected System error output type float expect
72. OCKETFAIL H ERR FLEX LM SETSOCKFAIL H ERR FLEX LM BADCHECKSUM H ERR FLEX LM SERVNOREADLIC H ERR FLEX LM NOTLICADMIN H ERR FLEX LM REMOVETOOSOON H ERR FLEX LM ENDPATH H ERR FLEX LM VMS SETIMR FAILED H ERR FLEX LM INTERNAL ERROR H ERR FLEX LM NOADMINAPI H ERR FLEX LM BADPKG H ERR FLEX LM SERVOLDVER H ERR FLEX LM USER BASED H ERR FLEX LM NOSERVCAP H ERR FLEX LM 0BJECTUSED H_ERR_WOOPI H_ERR_WIOPI H ERR WOI H_ERR_WRCN H_ERR_WRRN H_ERR_AUDI H_ERR_WIWI H_ERR_WIHE H_ERR_ICUNDEF H_ERR_IDBD H_ERR_WICPI 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2100 2101 2102 2103 2104 2105 2106 2107 2108 2200 2201 APPENDIX A HALCON ERROR CODES Cannot find ethernet device Cannot read license file Feature not yet available wrong time date set No such attribute Clock differecen too large between client and server Feature database corrupted in daemon Duplicate selection mismatch for this feature User host on EXCLUDE list for feature User host not on INCLUDE list for feature Feature was never checked out Invalid FLEXIm key data supplied Clock setting check not available in daemon Date too late for binary format FLEXIm not initialized Server did not respond to message Request rejected by vendor defined filter No FEATURESET
73. PR H_ERR_NFSC H_ERR_NACD H_ERR_LUTO H_ERR_WCC H_ERR_WWATTRT H_ERR_WWATTRN H_ERR_WRSPART H_ERR_WCSPART H_ERR_WNCV H_ERR_CHA3 H_ERR_NMWA H_ERR_FNF H_ERR_DWI H_ERR_DWID H_ERR_DRI1 H_ERR_DRI2 H_ERR_DRID1 H_ERR_IIS H_ERR_HNF H_ERR_XNF H_ERR_CNCSI H_ERR_CNCSO H_ERR_CNCF H_ERR_EDWF 5150 5151 5152 5153 5154 5155 5156 5157 5158 5159 5160 5161 5162 5163 5164 5165 5166 5167 5168 5169 5170 5171 5172 5173 5174 5175 5176 5180 5181 5200 5201 5202 5203 5204 5205 5206 5207 5208 5209 5210 5211 5212 123 Wrong pixel value for LUT Wrong image size for pseudo real colors Error in procedure HRLUT Wrong number of entries in color table for set lut Wrong values for image area Wrong line pattern Wrong number of parameters for line pattern Wrong number of colors Wrong value for mode of area creation 0 1 2 Spy window is not set set spy No file for spy has been set set spy Wrong parameter output depth set spy Wrong window size for window dump Wrong color table wrong file name or query_lut Wrong color table empty string Using this hardware set lut default is allowed only Error while calling online help Row can not be projected Operation is unsuitable using a computer with fixed color table Computer represents gray scales only no colors LUT of this display is full Internal error wrong color code Wrong type for window attribute Wrong name for wi
74. RM 2008 Vendor keys do not support this platform H ERR LM BADKEYDATA 2009 Bad vendor keys H ERR FLEX LM BADVENDORDATA 2010 Unknown vendor key type H ERR FLEX LM CANTMALLOC 2011 malloc call failed H ERR FLEX LM EXPIREDKEYS 2012 Vendor keys have expired H ERR FLEX LM FUNCNOTAVAIL 2013 Second call to Ic_init multiple jobs and vendor keys do not support multiple jobs H ERR FLEX LM NOKEYDATA 2014 Vendor key data not supplied HALCON Extension Package Interface 2000 11 16 H ERR FLEX LM LIBRARYMISMATCH H ERR FLEX LM NONETWORK H ERR FLEX LM OLDVENDORDATA H ERR FLEX LM BADCODE H ERR FLEX LM BADHANDSHAKE H ERR FLEX LM BADPARAM H ERR FLEX LM BADSYSDATE H ERR FLEX LM BAD VERSION H ERR FLEX LM BUSYNEWSERV H ERR FLEX LM CANTCONNECT H ERR FLEX LM FEATQUEUE H ERR FLEX LM FUNC NOT AVAIL H ERR FLEX LM LOCALFILTER H ERR FLEX LM MAXLIMIT H ERR FLEX LM MAXUSERS H ERR FLEX LM NO SERVER IN FILE H ERR FLEX LM NOFEATURE H ERR FLEX LM NOSERVSUPP H ERR FLEX LM OLDVER H ERR FLEX LM PLATNOTLIC H ERR FLEX LM SERVBUSY H ERR FLEX LM NOCONFFILE H ERR FLEX LM BADFILE H ERR FLEX LM NOSERVER H ERR FLEX LM NOSERVICE HERR FLEX LM NOSOCKET H ERR FLEX LM NOTTHISHOST H ERR FLEX LM LONGGONE H ERR FLEX LM BADDATE H ERR FLEX LM BADCOMM H ERR FLEX LM BADHOST H ERR FLEX LM CANTREAD H ERR FLEX LM CANTWRITE HERR FLEX LM SELECTERR H ERR FLEX LM CHECKINBAD H ERR FLEX
75. They are used to access control parameters of HALCON operators HALCON Extension Package Interface 2000 11 16 4 4 CONTROL PARAMETERS HPAR HCPAR typedef enum cont class cont unknown cont no junc cont start junc cont end junc cont both junc cont closed Hcont class typedef struct cont attrib 1 char float Hcont_attrib name val unknown neither start nor end point points are junctions start point is a junction start point is a junction both start and end point are junctions closed contour name of the attribute value of the attribute per point typedef struct cont global attrib char float global typedef struct cont type 1 INT4 float float Hcont_class INT4 Hcont_attrib INT4 name val attrib num row col cont class num attrib attribs num global Hcont_global_attrib global INT4 Hcont h name of the global attribute value of the attribute per contour number of points along the contour points row indices y coordinates points column indices x coord contour class number of additional attributes additional attributes for each point number of additional global attributes additional attributes per contour auxiliary temporary Figure 4 7 The XLD data type Hcont for subpixel contours 55
76. Wrong generic parameter value Wrong symbol printing mode Symbol region too near to image border No rectangular modul boundings found Couldn t identify symbol finder Symbol region with wrong dimension Classification failed Decoding failed Reader programing not supported Function not implemented on this machine Image to process has wrong gray value type Wrong image get system obj images H component see Undefined gray values Wrong image format for operation too big or too small Wrong number of image components for image output String is too long max 255 characters Wrong pixel type for this operation Operation not realized yet for this pixel type Image is no color image with three channels Frame grabbers are not supported in the demo version Packages are not supported in the demo version Operator is not available in the student version of HALCON Packages are not available in the student version of HALCON The selected frame grabber is not available in the student version of HALCON Too many unknown variables in linear equation No unique solution for the linear equation Too little equations in linear equation No inversion of matrix possible Singular value decomposition did not converge Matrix has too little rows for singular value partition Eigenvalue computation did not converge Eigenvalue computation did not converge Matrix is singular Function matching did not converge Input matrix undefined Input
77. _ERR_TMR H_ERR_SFZ H_ERR_OOR H_ERR_NEF H_ERR_NOOB 2869 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2985 2990 2991 2992 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3033 3040 3041 3042 3043 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 APPENDIX A HALCON ERROR CODES Error while accessing temporary file creation of pthread failed pthread detach failed pthread join failed initialization of mutex variable failed deletion of mutex variable failed Lock of mutex variable failed unlock of mutex variable failed failed to signal pthread condition variable failed to wait for pthread condition variable failed to init pthread condition variable Tried to leave critical section without entering it before failed to give free a handle via CloseHandle Free list is empty while scheduling Communication partner not checked in you can not start the communication system while run ning it Communication partner not checked in Region partially outside of the definition range of the image Intersected definition range region image empty Image with empty definition range gt no gray values No common image point of two images Wrong region for image first row 0 Wrong region for image column in last row gt image width Number of images unequal in input parameters Image height too small Image width too small Internal error mu
78. a was stored in temporary memory or if it will be modified later on 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 Hkey obj key image key in image key out key out Hrlregion Himage image in image out HGetSPar proc handle 1 LONG PAR Rows 1 height filter mask HGetSPar proc_handle 2 LONG_PAR amp Cols 1 width filter mask HA110bj proc_handle 1 obj_key i 4 all imput images HGetFDRL proc handle obj key amp region get region data HGetComp proc handle obj key IMAGE1 amp image key in if image key in UNDEFINED return H ERR UNDI undefined image HGetImage proc handle image key in image in get image data HCkP HCrImage proc handle image key in 1 image in kind image in width image in height amp image key out amp image out HCkP IPFilter peration amp image in region Rows Cols amp image out HCopy0bj proc handle obj key 1 amp key out create result obj HDef0bj proc handle key out image key out IMAGE1 insert the result image in output object Figure 5 23 A typical example for using HCrImage Providing an empty image matrix for a filter operation matrices per input matrix HOrImage checks whether there already exists an output matrix with the specified index index see below for a
79. ace To access new HALCON operators inside a package within programs you must create a C interface library packagecpp residing in the subdirectory 1libVAARCHITECTURE of the package This library is based on the files HCPPpackage cpp and HCPPpackageGlobal cpp generated via hcomp D ppackage def file s from the def file s of your self developed operators Note that hcomp simultanously generates the file HCPPpackage h containing the C prototypes of your new operators Include this file in your C programs using these operators 7 2 4 Creating New Applications In order to create new application programs written in C or based on your own HAL CON operators you must link the corresponding language interface libraries packagec or packagecpp to your objects Furthermore you will need the HALCON library itself and the HALCON C or HALCON C library as for any HALCON application 7 2 5 Additional Information for Specific Architectures The previous sections summarized the generation of HALCON extensions in general This section contains additional information for specific architectures The main differences concern the name handling and the generation of shared libraries DLLs HALCON 6 0 104 CHAPTER 7 CREATING A NEW HALCON PACKAGE 7 2 5 1 Generating Packages Under Windows NT or Windows 2000 In order to activate a package its complete path e g AHALCONROOTA V examples extension packageMhalconuser must be included
80. ally shows drawbacks in terms of computation time Two type conversions have to be computed with every pixel access and all pixel arithmetic has to be done in double HALCON 6 0 94 CHAPTER 6 SPECIAL ROUTINES FOR TYPICAL SUPPLY PROCEDURES Names HDFImage HImageFD Synopsis include Halcon h HDFImage double amp val Himage image INT4_8 lin_coord HImageFD Himage image double val INTA4 8 lin_coord Figure 6 6 Auxiliary macros for generic access to pixel data amp denotes an output parameter of HDFImage This is only a special notation to make clear that this parameter is changed by the macro So do not pass a pointer to double but the double variable itself to the macro 6 1 4 HAllFilter2 The macro HA11Filter2 see Fig 6 1 is a variation of HA11Filter introduced in the previous section It facilitates the implementation of filters with two input object parameters Exam ples for this technique are the HALCON operators add image mult image bit and and max 2 images HAllFilter2 extends HAllFiter so that with every image object of the first input object pa rameter also the corresponding image object with the same object index obj index of the second input object parameter is provided Moreover it checks the image sizes of both im age objects for equality If the sizes are equal the images are provided in the loop variables image in1 and image in2 otherwise an error is returned Moreover HA11Filter2 c
81. arameters and the ing of output control parameters see below HALCON Extension Package Interface 2000 11 16 2 3 DESCRIBING THE PARAMETERS 27 2 3 1 Name parameter Name input object output object input control output control This defines the name and the class of a parameter The parameters must be described in the same order as in their definition within the header of the operator description 2 3 2 default type default type integer real string Only for control parameters This slot specifies what C type to use in general It must have exactly one of the three above values 2 3 3 sem type sem type class spec This slot determines the semantics and specifies the class of data passed as parameters when using an object oriented language Names of classes within the def file are only symbolic The mapping to the actual class names is is provided by the HALCON compiler hcomp HDevelop also uses the semantic types e g in order to provide specific inspection routines like for frame grabber handles For complex classes it must be defined by spec which aspect of the class is represented by the parameter By this one can pass complex objects that are described by several parameters of the C procedure as one logical parameter The following semantic types classes are availabe at the moment e Iconic data object parameters object any iconic object images regions XLDs image i
82. ated operators language Specification of the number of parameters per parameter class for every operator language Specification of the parameter names and the chapter names for every operator In addition to the option M cTAGS FILE can be set in order to insert the source file and the line number of the supply procedure of the operator into the h1p file To do this a TAGS File usually TAGS must have been generated by the etags command before HALCON Extension Package Interface 2000 11 16 7 1 THE HALCON COMPILER HCOMP 101 7 1 3 Creating the Manuals hcomp can generate IATEX files containing the complete reference manuals full text or short version adapted to the different supported programming languages i e the description of the operators is provided in a specific syntax Use hcomp Rplanguage specification 1language def files to create IATEX files with planguage and specification as follows planguage can be set to c c and trias corresponds basically to the HDevelop Syntax trias is default and may therefore be omitted The specification determines the extent of the manual by specifying the additional operator information that will be inserted into the manual besides the operator header Supported specifications are All available information is presented in the manual Only the short descriptions are inserted A file is generated for each operator containing its complete description B
83. ccess in two respects e The expected type can be specified by type This also includes type combinations such as LONG PAR FLOAT PAR e The expected number of values can be specified by the interval min max whereas max should not exceed the number of allocated Hcpar elements within the array val If the specified number or types of values are violated HGetCPar exits the supply procedure with an appropriate error message Fig 5 27 shows an application of HGetCPar Note that in case of string parameters memory has to be allocated for vallil par s The easiest way to do this is to use HAllocStringMem specifying the expected number of characters for all input strings see section 5 5 7 5 5 2 HGetSPar HGetSPar see Fig 5 26 is a simplified version of HGetCPar In contrast to the latter a fixed number of parameter values is read see Fig 5 28 Therefore the routine does not return the actual number of values This number is fixed If more or less values are passed to the HALCON operator HGetSPar exits the supply HALCON Extension Package Interface 2000 11 16 Names 5 5 READING AND WRITING CONTROL PARAMETERS HGetCPar HGetSPar HGetPPar HGetCParNum HPutCPar HPutPPar HAllocStringMem Synopsis include Halcon h HGetCPar Hproc handle proc handle INT par num INT type Hcpar val INT4_8 min max INT4_8 num HGetSPar Hproc handle proc handle INT par_num INT type Hcpar val INT4_8 num HG
84. ce 2000 11 16 Chapter 7 Creating a New HALCON Package 7 1 The HALCON Compiler ncomp The HALCON compiler hcomp is the most important tool for creating a new HALCON pack age It automatically generates the interface code for the desired host language the help files and the documentation files hcomp processes def files that contain descriptions of all opera tors as a basic resource see chapter 2 The HALCON compiler uses the same mechanism for generating the original system operators and user defined operators The syntax of the hcomp command is as follows hcomp options files Example hcomp u C ppackage MyUser ps def The parameter u signals that an interface for user defined operators should be generated This parameter can be omitted as it is the default One or more definition files that are separated by blanks must be specified as files argument The extension def may be omitted hcomp C ppackage 0 0 0 0 2 MyUser ps3 To generate the appropriate interface code the correct option must specify the desired host language for C as host language C Then hcomp generates a couple of source files in the example above HCpackage c and HCpackage h for the package package Their names depend on the host language and the specified package not on the names of the input def file s 7 1 1 Selection of the Host Language One call of hcomp can always create only one interface i e
85. cedure where they are passed to the generated interface that returns them to the calling system Any supply procedure returns an error code of type Herror Thus it is necessary to return an error code which 15 H MSG TRUE if no error occurred In Windows NT and Windows 2000 the supply procedures like CIPUserThreshold O in cipuserthreshold c must be explicitly exported by the operator DLL package dll This is done by the macro HUserExport as a prefix to Herror see Fig 1 6 In UNIX environments HUserExport may be omitted but in this case the package will not run on Windows NT and Windows 2000 sys tems Only one parameter a so called procedure handle is passed to a supply procedure other input 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 the supply procedure is done with the help of several internal buffers as illustrated in Fig 1 1 Application Programs Input Output HALCON C or Interface Database Buffer Control Iconic Control Iconic Parameter Objects Parameter Objects Supply Procedure I A Action Procedure Figure 1 1 Data flow within HALCON The buffer contains input data as well as output data Control parameter
86. ckage Otherwise the loader will fail to access the interface library libpackagec so or libpackagecpp so linked to the application see section 72 5 Note that it is not necessary to modify LD_LIBRARY_PATH in order to use the package within HDevelop 1 3 4 Additional Information for IRIX On UNIX workstations running IRIX you have to include the package library subdirectory lib mips sgi irix6 5 in the environment variable LD_LIBRARY_PATH in order to run stand alone applications based on the package Otherwise the loader will fail to access the interface library libpackagec so or libpackagecpp so linked to the application see section 7 2 5 Note that it is not necessary to modify LD_LIBRARY_PATH in order to use the package within HDevelop 1 3 5 Additional Information for HP UX On UNIX workstations running HP UX you have to include the package library subdirectory lib hppai1 1 hp hpux10 in the environment variable SHLIB PATH in order to use a package This has to be done in case regardless whether you plan to use a package within HDevelop only or you want to create stand alone applications Otherwise the operating system will fail to open the interface library libpackagec sl or libpackagecpp sl needed to access the package 1 3 6 Additional Information for DIGITAL UNIX Tru64 UNIX On UNIX workstations running DIGITAL UNIX now called Tru64 UNIX you have to in clude the package library subdirectory lib alpha dec osf4 0 in t
87. control are separated by colons One class is described by a list of all parameter names within the class separated by commas If there is no member of a class for an operator the list remains empty The example described above defines the following mapping between parameters and parameter classes keyword cf page 27 parameter in the example Origfmage Thresholdlmage output iconic objects output object RegionDynThresh input control parameters input ctrl Offset LightDark output control parameters output ctrl Within the HALCON C class hierarchy corresponding methods use slightly different conventions extern operator name is transformed into Extern peratorName HALCON 6 0 18 CHAPTER 2 OPERATOR DESCRIPTION DEF FILES It is helpful to follow certain conventions when choosing names for parameters They should be meaningful i e one should avoid names like and consequently should be given in English It is convention to denote parameters that specify a position within an image matrix by Row s not Line and Column s or Col s Parameters defining a dimension are called Width and Height 2 2 2 short The keyword short starts the short description of the operator in our example short english Segment an image using a local threshold As all slots specified by the keyword english this slot contains purely textual information Text can be written in different languages and can contain I4IEX comma
88. d keep that in mind when applying a sequence of filters to restricted regions of interest 5 6 4 HNumOfChannels HNumOfChannels see Fig 5 33 returns for the first input object parameter of a HALCON operator the number of channels of the image object with number obj index Thus this routine is just a shortcut for using HPNumOfChannels as defined in Fig 5 5 with par num 1 HALCON Extension Package Interface 2000 11 16 6 Special Routines for Typical Supply Procedures In the previous chapter the basic routines for handling iconic objects object parameters and contol parameters of a HALCON operator have been introduced Based on these this chapter describes a set of convenience routines that facilitate the programming of supply procedures in typical situations 6 1 Loop Macros A frequently needed task is to process all image objects images or regions passed to an oper ator by one or two input object parameters This is true for example for most filter and many segmentation operators Loop macros provide a framework for this problem see also section 9 3 macros described in this section have in common that they implement a loop over all image objects within the first input object parameter HA11Filter2 also includes a parallel loop over all objects within the second input object parameter It is assumed that the operator does not have any more input object parameters The macros provide users with the region
89. data base object using HPutImage Furthermore a new image object is created by HCr0b j This new object does not contain any gray value channels see section 5 4 1 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 75 Using HDef0bj the previously stored image data is assigned as default gray value component 1 IMAGE INDEX of the new image object 5 4 6 HPutDImage HPutDImage see Fig 5 19 combines HPut Image and HDefObj It stores the gray value chan nel image matrix image in the HALCON data base and returns the corresponding data base key in image key The parameter copy FALSE or TRUE is used as in HPutImage and speci fies whether the pixel data is copied or only a pointer to the data is passed to the data base Moreover the gray value channel is inserted into the image object obj key as component comp 1 m Fig 5 22 shows a typical application of this routine Hkey obj key k Himage image Hrlregion region image processed gray value data region region data HCr0bj proc handle par num ob j key HPutDImage proc_handle obj_key IMAGE_INDEX amp image FALSE amp k HPutDRL proc handle obj key region k Figure 5 22 Creating a new image object using HPutDImage and HPutDRL 5 4 7 HCrImage HCrImage see Fig 5 19
90. directory e g images within the package in the environment variable HALCONIMAGES to access those images without specifying a complete path For UNIX architectures you have to modify additional environment variables in order to use a HALCON package see below 1 3 1 Additional Information for Windows NT and Windows 2000 To be able to link the package DLL to your application program the complete DLL file path of the new package e g AHALCONROOT A examples extension package MhalconuserVMbinVi586 nt4 has to be added to the environment variable PATH Do not copy a package DLL into the Windows system directories as it would be loaded twice in this case HALCON 6 0 8 CHAPTER 1 INTRODUCTION 1 3 2 Additional Information for Linux On UNIX PCs running Linux you have to include the package library subdirectory lib i586 linux2 2 in the environment variable LD LIBRARY PATH in order to use a pack age This has to be done in case regardless whether you plan to use a package within HDevelop only or you want to create stand alone applications Otherwise the operating system will fail to open the interface library libpackagec so or libpackagecpp so needed to access the package 1 3 3 Additional Information for Solaris On UNIX workstations running Solaris you have to add the package library subdirectory lib sparc sun solaris7 to the environment variable LD_LIBRARY_PATH in order to run stand alone applications based on the pa
91. dle INT num Herror HFreeUpToTmp Hproc_handle proc_handle void pointer Herror HFreeAllTmp Hproc handle proc handle Herror HAllocRLTmp Hproc handle proc handle Hrlregion HAllocRLNumTmp Hproc_handle proc handle Hrlregion region size_t len Herror HFreeRLTmp Hproc_handle proc_handle Hrlregion region Figure 3 1 HALCON stack management for temporary data HALCON 6 0 40 CHAPTER 3 STYLE GUIDE FOR PROGRAMMING Fig 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 reverse order of it s allocation There are two major advantages of using these routines e The underlying stacks are initialy allocated as large blocks of memory Thus the memory is not fragmented and memory allocation is fast for subsequent calls e Anautomatic garbage collection deallocates all temporary data after a HALCON operator was executed This is especially of importance in case of an error during the execution of the operator otherwise the data should have been deallocated anyway HAllocTmp is used for arbitrary data with the corresponding deallocation routine HFreeTmp HFreeNTmp deallocates the last num blocks allocated by HAllocTmp HFreeUpToTmp deallocates all recently allocated blocks up to and including the specified block HFreeA11Tmp deallocates all temporary blocks HAllocR
92. e carefully Contents 1 Introduction 1 Ll HALCON Operators 2 1 1 1 Using HALCON Operators and C 0 2 1 1 2 Internal Structure of HALCON Operators 2 1 2 HALCON 3 2 arae redeo eme RA e RR E 4 1 2 1 Packages and Parallel HALCON 5 1 2 3 Directory Structure ofa HALCON Package 3 1 2 3 How to Create and Use a HALCON Package 6 1 3 Installing a HALCON 7 1 3 1 Windows NT 2000 7 132 ENUS aiya h s ale ap d p notat e tency ce Qeon ds 8 doeii ae esr EB E 8 134 IRIX a Sa Mg a MOMS A EON a AARON 8 HP UX uoi ne eae ae fe vats LS Ape aon C ah a Oi EC Seo 8 1 3 6 DIGITAL UNIX Tru64 UNIX 8 A AT ed V aea wes US RDA 9 1 5 Additional Sources of Information 13 2 Operator Description def files 15 2 1 Short Operator 15 2 2 Extended Operator 16 2 Header wA aera EEA em T ATELA A as 17 22 29 SNOG Bent A BON Re ONG NU BU VE NUR 18 2 29 3aDSEGIE D Seca RIRs S CARE IR cR 18 OO ae So ee ah tee eb E tu to sU trs gU be 19 2 2 0 re tese ene Su
93. e discussion in section 6 1 3 If an operator can only process a reduced set of types this can be specified in the def file with type list cf page 31 An operator should reject all images that it can not process by returning _ ERR WIT wrong image type e In many cases an operator might receive more than one iconic object as input i e the supply procedure must contain a loop over all iconic objects e g using HA11Reg and HA11Segm described in section 6 1 or HA110bj in section 5 3 1 This is true for regions as well as images or XLDs Furthermore images may contain more than one channel So a second loop over all channels components within an image is needed see HA11Comp section 5 3 2 e procedures should only work within the image s area of definition especially when performing feature extraction filter or segmentation tasks HALCON Extension Package Interface 2000 11 16 Chapter 4 HALCON Data Types The HALCON Extension Package Interface provides special data types to handle iconic ob jects 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 the Extension 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 such an object Furthermore data structures for contol parameters ar
94. e makefile e Creating new applications In order to create new application programs written in C or you must link libpackage so and libpackagec so or libpackagecpp so to your objects be sides libhalcon so and libhalconc so or libhalconcpp so as for any HAL CON application Furthermore you must add the package library subdirectory lib alpha dec osf4 0 to the environment variable SHLIB PATH otherwise the loader will fail to access the libraries The directory HALCONROOT examples extension_package halconuser contains two ex ample makefiles makefile creates the example package halconuser for standard HALCON makefile testprog creates the example applications based on the package halconuser Both makefiles include the file make alpha dec osf4 0 which sets architecture dependent vari ables 7 3 HALCON Directories HALCON always presumes that the environment variable HALCONROOT contains the path of the HALCON homedirectory Starting at this homedirectory the following directories are important for creating a new system examples extension_package halconuser Example for a HALCON extension package include HALCON include files for compiling libV4ARCHITECTURE HALCON libraries bin ARCHITECTUREZ HALCON compiler hcomp under Windows NT 2000 also the HAL CON DLLs doc macros BIEX files for generating PostScript reference files or manuals HALCON 6 0 112 CHAPTER 7 CREATING A NEW HALCON PACKAGE HALCON Extension Pac
95. e objects are added to the list of objects for the first output object parameter here ImageScaled Their underlying image matrices are accessable via image out Those are also passed to the action procedure IPScaleNew within the loop IPScaleNew calculates the new gray values for all pixels within the area of definition of the input image and writes them into the provided image components image out The regions of the image objects remain unmodified so that all pixels of output objects lying outside the region are undefined Note that HA11Filter creates all necessary image matrices combines them with the input regions to new image objects and returns those in the first output object parameter So the programmer of the supply procedure needs not to bother about the handling of image objects etc To access the input control parameter HGetSPar see section 78 is used in the example The structure image in may contain different pixel types There are several ways to handle this within an operator Note that image_out contains a pointer to a pixel matrix with the same size and pixel type as image in HALCON Extension Package Interface 2000 11 16 6 1 LOOP MACROS 93 Herror IPScaleNew Hrlregion region Himage image in Himage image out 1 INT4_8 i l end double h for i20 i lt region gt num i end CE region rl i image in width for 1 CB region gt rl i image_in gt width l end 1 1 HDFImage h image in
96. e provided data types de scribed in the following sections are defined in the files 4 HALCONROOT include IPtype h 4 HALCONROOT include HBase hi 4 1 Pixel Data Himage Gray value images are represented by a rectangular image matrix Several matrices called components can be combined to a multi channel image Each channel can be accessed sepa rately i e the components are not interleaved The structure Himage contains size pixel type and pixel data of one component Furthermore a time stamp is included Fig 4 1 shows the corresponding type declaration The maximum for width and height MAX FORMAT is currently set to 32768 The origin of an image matrix is at position 0 0 Row coordinates range from 0 to height 1 column coordinates from 0 to width 1 The image pointer HPixelImage refers to the first pixel of the matrix index 0 0 Different pixel types are supported They are distinguished by a selector kind see Fig 4 2 The pixel types include basic types like HBYTE INT1 INT4 and float 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 The indices of the array range from 0 to width height 1 A linear coordinate L within an image is derived from the row index R and column index C as follows 1 R image width C This transformation is performed by the following macro L HLinCoor
97. e standard routines of the operating system like malloc and free since the HALCON routines provide a caching mechanism garbage collection for temporary data and debugging facilities We strongly recommend not do use global variables within HALCON operators If they are not avoidable at least make them static within the file of usage If even this is undesirable group them into structures to keep the number of global names small HALCON Extension Package Interface 2000 11 16 3 2 MEMORY MANAGEMENT 39 If you use static variables be aware that they are shared between multiple threads Please note that Parallel HALCON uses multithreading to exploit multi processor hardware see the manual Getting Started with HALCON for more information This means that if you use Parallel HALCON either by linking the corresponding libraries to your program or by using Parallel 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 that HALCON is a very large system enfolding hundreds of operators 3 2 1 Temporary Data Names HAllocTmp HFreeTmp HFreeNTmp HFreeUpToTmp HFreeAllTmp HAllocRLTmp HAllocRLNumTmp HFreeRLTmp Synopsis include Halcon h Herror HAllocTmp Hproc handle proc handle void pointer size_t size Herror HFreeTmp Hproc_handle proc_handle void pointer Herror HFreeNTmp Hproc_handle proc_han
98. e the XLD structures after calling HCrXLD Hcpar rows 99 cols 99 INTA 8 i num points Hkey key out Hcont cont HGetCPar proc_handle 1 FLOAT_PAR rows 1 99 amp num_points HGetCPar proc_handle 2 FLOAT_PAR cols 1 99 amp num_points create a contour in general this should be done calling an appropriate action procedure HCkP HAllocXLDCont proc_handle amp cont num_points for 1 0 i lt num points i cont row i rows il par f cont col i cols i par f cont gt num num_points HCrXLD proc id 1 cont XLD CONTOUR ID NULL O DBFreeProc HXLDFreeContour amp key out Figure 5 24 A typical example for using HCrXLD Create an XLD contour from a list of points Hkey obj key key out Hcont cont Hpoly poly HA110bj proc handle 1 0bj key i HGetXLD proc id key XLD CONTOUR ID void amp cont HCkP HA110c proc handle size_t sizeof Hpoly amp 1 approximate cont by poly HCkP HXLDPolygon proc handle cont amp poly HCrXLD proc handle 1 poly XLD POLYGON ID amp obj key 1 DBFreeProc HXLDFreePolygon amp key_out Figure 5 25 Another typical example for using HCrXLD Create XLD polygons based on XLD contours XLD polygons contain a reference to the underlying contours if any see the definition of Hpoly in Fig 4 10 section 4 3 Such a dependency between XLDs can be specified in HCrXLD by passing an array of data base keys i
99. eate the C interface library libpackagecpp so providing the interface to new HALCON operators the object files HCPPpackage o and HCPPpackageGlobal o and the new operator lib libpackage so must be linked e Creating new applications In order to create new application programs written in C or C you must link libpackage so and libpackagec so or libpackagecpp so to your objects be sides libhalcon so and libhalconc so or libhalconcpp so as for any HAL CON application Furthermore you must add the package library subdirectory Of course this has to be done for 1 soname libpackagec so and libpackagecpp so soname libpackagecpp so as well HALCON Extension Package Interface 2000 11 16 7 2 GENERATING HALCON PACKAGES 109 lib mips sgi irix6 5 to the environment variable LD LIBRARY PATH otherwise the loader will fail to access the libraries The directory HALCONROOT examples extension_package halconuser contains two ex ample makefiles makefile creates the example package halconuser for standard HALCON makefile testprog creates the exampleapplications based on the package halconuser Both makefiles include the file make mips sgi irix6 5 which sets architecture dependent vari ables 7 2 5 5 Generating Packages Under HP UX In order to activate a package its complete path e g HALCONROOT examples extension package halconuser must be included in the environment variable HALCONEXTENSIONS In the UN
100. ed Object parameter is a zero pointer _ not allowed Tupel had been deleted values are not valid any more CPP interface internal error wrong object mode Wrong number of regions gt 1 for type HRegion Wrong number of images gt 1 for type HImage Tupel with undefined values No contact to RPC server Error in remote procedure call Parameter value is neither a list nor a atom Unknown operator name register comp_used is not activated see set system Unknown operator class convol Maske error while opening the file convol Maske premature end of file convol Maske conversion error convol Maske wrong row column number convol Maske mask size overflow convol Maske too many elements entered convol wrong margin type convol no mask object has got empty region convol no filter object has got empty region convol Weight factor is 0 convol inconsistent number of weights rank wrong rank value convol rank error while handling margin Wrong number of coefficients for convolution sigma too big No valid ID for data set No data set active set bg esti ID already used for data set is not poosible Maximum number of data sets exceeded No data set created create bg esti Not possible to pass an object list Image has other size than the backgroud image in data set Up date region is bigger than background image Number of statistic data sets is too small Wrong value for adapt mode Wrong value for frame mode
101. ede ee Ste ut eo ONT UT E 19 2 20 functionality se Sau gos tesa ue os BP RS X 20 DD Tix ette Pg EN ad n SN rti 20 2 2 8 predecessor successor alternatives 20 2 250 cadavere at eS 21 X2 TU attention oot ae the sate od IA PELA OE Xe boa eee oe 21 2 22 11 SxgSult sEate Sora yt et eee ae EXE 21 2 2 12 parallelization s 2 2 RR aud ur 22 2 2213 complexity sa uus eds deed eb deu hse 24 2 214 example ko eb eee SAAR ARREARS 25 2 203 oo a eos eic hem ceu e e e e eS M es 25 2 3 Describing the Parameters 25 2 5 1 uuum ue Res ae Rex dE Wd dew dew ede 27 2 30 27 ee IR SPI a rk SE 2 909 Bleek B 2 3 4 2 3 5 costs weight 2 3 6 pOstproc ssing oe oine ni Breed ee a 2 3 7 descnpt om ec eoe E Bae 2 3 8 lista uo uode eem oe Renee 2 3 9 default value 2 LAT Sov a RH 2 910 3 ablie be es uda s rate Seu 2 3 12 value min value max 2 3 13 step rec step min value_function
102. eferenced by region must have been allocated before with a suitable size HALCON Extension Package Interface 2000 11 16 5 2 ADDITIONAL ROUTINES FOR ACCESSING INPUT IMAGE OBJECTS 67 Hkey obj key Hrlregion HGetFDRL proc handle obj key amp region processing in general this should be done calling an action proc area 0 for i 0 i lt region gt num 1 area region gt rl i ce region rl i cb 1 Figure 5 11 Application of HGetFDRL e g by using HAllocRLTmp see section 3 2 1 Therefore this region data can be overwritten without side effects On the other hand the memory must be deallocated at the end of the supply procedure e g by using HFreeRLTmp Fig 5 12 shows an application of HGetURL Note that the area calculated in the example may differ from the sum of the areas of all single regions because the single regions may overlap Hrlregion HCkP HAllocRLTmp proc handle amp region HGetURL proc handle par num region processing in general this should be done calling an action proc area 0 for 1 0 i lt region gt num i area region gt rl i ce region gt r1l i cb 1 HCkP HF reeRLTmp proc handle region Figure 5 12 Application of HGet URL 5 2 4 HGetDImage HGetDImage see Fig 5 9 combines HGetComp section 5 1 2 and HGet Image section 5 1 4 It reads the data of the gray value component channel of the image ob
103. el _ channel2 RS px Y HGetlmage image x Hrlregion E HGetRL oe Figure 5 2 Direct access to input image objects INT2 inp_pars INT4 num_objs Hkey key get number of input object parameters note This number is known in general it is specified by the operator header in the corresponding def file of the operator HReadGV proc handle HGinp obj amp inp pars for p 1 p lt inp_pars p get number of input objects per input obj parameter HReadGVA proc handle HGnum ob j num objs p for 1 o num objs HGet bj proc handle p o amp key get key of object further processing Figure 5 3 Example for Data base keys of all iconic objects of all input object param eters The number of input object parameters for an operator is specified in the corresponding def file but the number of objects within an input object parameter is dynamic This value is accessible via the Extension Package Interface routine HReadGVA HReadGVA proc handle HGnum obj num objs p where p denotes the parameter number and num objs is the desired number of objects There So this number is actually known by the programmer However using HReadGV it can be read from the operator context as well see Fig 5 3 HALCON 6 0 62 CHAPTER 5 HANDLING ICONIC OBJECTS AND CONTROL PARAMETERS is an alternative for
104. ely or relatively connected to the values of other parameters or some absolute values The same expressions may appear as described above for value_number see table 2 1 Examples Parami Param2 amp amp Param2 gt 0 This means that parameter and 2 must have the same value and this value is greater than 0 0 lt Param2 amp amp Param2 lt 255 This means that parameter 2 must have a value between 0 and 255 Parami lt number ImageIn This means that the value of parameter must be less or equal the number of input images Param2 lt width ImageIn amp amp Param2 gt 0 amp amp odd Param2 This means that the value of parameter 2 must be between 0 and the width of the input image and must be an even number 2 3 16 multichannel multichannel true false optional This slot is only used in connections with image objects It contains an assertion about the necessary or supported number of channels of an image If set to false the processing is done only on the first channel all others are ignored if set to true a multichannel image must be passed optional specifies operators that can work on more than one channel but can also work on only one channel as well 2 4 Text in def files Within a def file the semicolon is used to separate the single slots So when using a semi colon within a text it must be quoted with a backslash V def files are not only used to create interface code but also allow t
105. enerated by hcomp as well see Fig 1 8 In this example HTML documents are generated in Trias HDevelop syntax L t a11 in C syntax L c al1 and in C syntax L c a11 The HTML files have to be placed in the corresponding subdirectories doc html reference Mhdevelop c or cpp of the package If you now add the package path to HALCONEXTENSIONS and start HDevelop the user extensions e g user thresh are automatically available in the specified menu HALCON Extension Package Interface 2000 11 16 1 5 ADDITIONAL SOURCES OF INFORMATION 13 i e chapter In our example this menu is called UserExtensions as specified in HALCONROOT examplesVc interface M halconuserMdef threshold def You can se lect and execute the user defined operators like all the built in operators of the HALCON sys tem The HTML documentation is available via the Help button within the operator window Examples of how to use the user defined extensions in HDevelop can be found in the subdi rectory examples of 4HALCONROOTA examples Vextension package Mhalconuser dev Furthermore the dev programs have been exported as programs The cpp files can be found in the subdirectory source You can compile the C files using the al ready mentioned makefiles These cpp files also serve as an example for the integra tion of user defined operators into the host language C Note that before compiling the exported code containing operators f
106. er image object obj num of parameter par num is accessible via HPNumOfChannels see Fig 5 4 and 5 5 HPNum0fChannels proc handle par num ob j num amp obj channels See also HNumOf Channels in section 5 6 4 for a convenience version of this routine when deal ing with the first input object parameter More examples of how to use HGetComp can be found in Fig 5 6 and 5 7 HALCON Extension Package Interface 2000 11 16 5 1 BASIC ACCESS TO ICONIC INPUT OBJECTS 63 Names HPNumO0fChannels Synopsis include Halcon h Herror HPNum0fChannels Hproc handle proc handle INT par num INT4_8 obj_num INT chn_num Figure 5 5 Auxiliary routine HPNum0f Channels 5 1 3 HGetRL HGetRL see Fig 5 1 reads the chord encoding of a region type Hrlregion see section 4 2 denoted by the data base key region key from the HALCON data base Hrlregion Hkey obj key Hkey region key HCkP HAllocRLTmp proc handle amp region HGet0bj proc handle p o amp obj key HGetComp proc handle obj key REGION amp region key HGetRL proc handle region key region processing in general this should be done calling an action proc area 0 for 1 0 i lt region gt num i area region gt rl i ce region gt r1l i cb 1 HCkP HF reeRLTmp proc handle region Figure 5 6 Example for HGetRL Calculate the area of a region Since the region data is copied to region it might be overwrit
107. er to exploit specific hardware features of a framegrabber board e HALCON HDevelop HALCON C HALCON C HALCON COM The reference manuals for all HALCON operators versions for HDevelop C C and COM l UserExtensions is integrated into the menu Operator of HDevelop HALCON 6 0 14 CHAPTER 1 INTRODUCTION All these manuals are available as PostScript ps and Acrobat Reader pdf docu ments The reference manuals are available as HTML documents as well For the latest version of the manuals please check http www mvtec com halcon Please see also the example package AHALCONROOT examples extension package Mhalconuser which will be referenced many times within this manual HALCON Extension Package Interface 2000 11 16 Chapter 2 Operator Description def files The following chapters give a detailed description of the steps mentioned in section 1 This is done with respect to the examples within the directory AHALCONROOT VexamplesVextension packageMhalconuser as well as system defined HALCON operators We start with the generation of an operator description 2 1 Short Operator Description Before implementing an operator the author should think about the task of the operator and what kind of user interface is best for calling the operator This specification is used to automatically generate the interface code for the desired host language with the HALCON compiler hcomp To do this it is necessary to describe at lea
108. es of the corresponding channels e the same image size and e the same area of definition region Thus HA11Filter is a combination modification of HA110bj see section 5 3 1 HGetFDRL see section 5 2 2 HAllComp see section 5 3 2 HCopyObj see section 5 4 2 and HPutDImage see section 5 4 6 It has been designed for filter operators that typically create a modified result image for every input image The region remains unmodified Typical examples for this functionality are HALCON operators sobel amp mean image fft scale max or laws byte Fig 6 5 shows a typical application of HA11Filter a hypothetical operator scale_new that multiplies all gray values of the input objects within the first input object parameter with a constant The corresponding def file short version might look like scale_new lt CIPScaleNew Image ImageScaled Mult f The operator has one input object parameter Image that contains one or more input image objects 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 region and image in see also HA11Segm in section 6 1 2 These components are passed to the action procedure IPScaleNew In this example only the first channel of each input object is used HA11Filter also creates output objects in the HALCON data base to return the modified data Furthermore thes
109. es the extent of the overlapping regions Thus the slot domain split is set to 2 for eliminate min max The example below shows the whole parallelization slot for eliminate min max parallelization process_exclusively false process locally false process mutual false method Split tuple split channel split domain domain split 2 If method contains split domain the slot domain split must be filled in In all other cases the slot should be omitted Though we recommend to specify the whole slot parallelization it is also possible to completely leave it out in an operator s description In this case it is assumed that the operator is reentrant i e it is not processed under complete or mutual exclusion and that it must be processed locally The latter also means that no parallelization is used when processing the operator This assumption corresponds exactly to those which are used in the case of missing single subslots see descriptions above 2 2 13 complexity The slot complexity describes the complexity of the operation in terms of number of points along a contour the area of an image region etc complexity english Let F be the area of the input region Then the runtime complexity is 0 F HALCON Extension Package Interface 2000 11 16 2 3 DESCRIBING THE PARAMETERS 25 2 2 14 example It is possible to describe an example under the keyword example in order to illustrate the usage of a
110. etPPar Hproc_handle proc_handle INT par_num val INT4_8 num HGetCParNum Hproc handle proc handle INT par num INT4_8 num HPutCPar Hproc handle proc handle INT par num Hcpar val INT4_8 num HPutPPar Hproc_handle proc_handle INT par_num Hcpar val INT4_8 num 79 HAllocStringMem Hproc_handle proc_handle size_t size Figure 5 26 Routines for handling control parameters 5 5 3 HGetCParNum HGetCParNum see Fig 5 26 returns the number of single control values of the input control procedure with an error HALCON 6 0 80 CHAPTER 5 HANDLING ICONIC OBJECTS AND CONTROL PARAMETERS Hcpar pari par2 Hcpar par3 10 allocate memory for strings HAllocStringMem proc_handle 1000 read a short int long value in parameter number 1 HGetCPar proc_handle 1 LONG_PAR amp par1 1 1 amp num now 1 1 read a string in parameter number 2 HGetCPar proc_handle 2 STRING_PAR amp par2 1 1 amp num now par2 par s Text read a tuple of float values in parameter number 3 max 10 values HGetCPar proc_handle 3 FLOAT_PAR par3 1 10 amp num for i20 i lt num i par3lil par f 0 5 1 7 4 4 Figure 5 27 Read the control parameter values of the operator call demo 5 Text 0 5 1 7 4 4 using HGetCPar Hcpar pari par2 Hcpar par3 3 allocate memory for strings HAllocStringMem proc_handle 1000
111. eters 2 3 5 costs weight costs weight an unsigned integer value This slot must only be used for input control parameters of operators which are suitable for being automatically parallelized i e for operators for that the parallelization subslot method does not contain none see page 23 Here it assigns whether the time for processing the operator directly depends on the content value of the corresponding input control parameter If costs weight is set to 0 the duration of the operator processing does not directly depend on the content of the corresponding input control parameter In this case the parameter will not be taken into account when Parallel HALCON decides whether an operator should be parallelized for a given allocation of input parameters or not This also means that this parameter will not be checked during the hardware training compare the description of check par hw potential in the Reference Manuals This helps to speed up the training If costs weight contains a value greater than 0 this assigns that there is a direct dependency between the content of the corresponding input control parameter and the computation time of the operator In this case Parallel HALCON will take into account this parameter during its hardware check check par hw potential in order to determine its influence on the operator s processing time Note that the slot costs weight must be filled in for every input control parame
112. eve a useful structuring of HALCON operators they are all arranged in a hierarchy of chapters and sections The assignment defined in the slot chapter is reflected in the reference manuals and in the menu Operator of HDevelop HALCON 6 0 20 CHAPTER 2 OPERATOR DESCRIPTION DEF FILES chapter english Segmentation The structuring can be refined by specifying a section chapter section e g chapter english Filter Edges Note that it is not allowed to insert operators and sections into the same chapter at the same level of hierarchy So if you decide to use sections within a chapter all operators within this chapter must be assigned to one of these sections Furthermore the chapter names may not contain spaces If you need multi word chapter names please use a dash between each word e g Affine Transformations 2 2 6 functionality functionality image This slot denotes the class of which the operator should become a method within an object oriented programming language like C Generally this corresponds to the semantic type of the first parameter e g an image object image The specified name is only a symbolic one The actual class name depends on the programming language and is provided by the HALCON compiler hcomp Possible values for functionality in the current version are any window image region object xld_cont xld poly xld para 1 mod para and x1ld ext para 2 2 7 keywords Furthermore
113. extend HALCON by additional operators encapsulated in HAL CON packages using the Extension Package Interface Before starting to use the Extension Package Interface strongly recommends that the user should be familiar with the stan dard HALCON system This manual is written for the expert HALCON user who wants to extend the system for spe cific requirements Thus the reader should be familiar with the standard HALCON system Furthermore C programming skills are required Finally the reader should know about his her programming environment that is how to invoke the compiler linker etc This manual is divided into the following parts Introduction This chapter provides a short overview of HALCON packages and their creation Fur thermore an example showing the integration of a simple operator is presented Operator Description def files This chapter summarizes the minimum required operator description used by the HAL CON compiler hcomp as well as the complete operator description which is needed to provide a full integration of new operators in HDevelop and to generate documentation files Style Guide for Programming This chapter introduces basic style guides for how to program HALCON operators Espe cially the HALCON memory management is explained HALCON Data Types In this chapter the most important HALCON data structures to handle iconic data and control parameters are presented Handling Iconic Objects and Co
114. for many applications When using complex procedures that need more than one value per parameter data is transfered within tuples Htuple Iconic objects are always represented as tuples Hobject so that one image object can contain several images regions or XLDs There exists a special interface for 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 and the 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 class hierarchy Thus these operators are integrated in as C functions using the generic data type Hobject in order to pass arguments to and from the operator This kind of integration is also used if you export your HDevelop program as code For further information please take a look at the corresponding manuals 1 1 2 Internal Structure of HALCON Operators HALCON operators like the new operators in halconuser typically consist of two proce dures 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 processi
115. g when working with multi processor hardware The slot parallelization consists of several sub slots each starting with a characteristic keyword followed by a colon and finishing with a semicolon The example below shows the slot for the operator dyn threshold which is not local needs neither complete nor mutual exclusion and is parallelized on tuple level The single subslots and their meaning will be described in the following sections parallelization process exclusively false process locally false process mutual false method Split tuple process exclusively true false This subslot of parallelization assigns whether an operator is processed completely exclusively true by the main HALCON process thread or not An exclusive processing means that no other operator will be processed by Parallel HALCON while the exclusive operator is running If an exclusive operator is started and other operators are still run ning 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 the main HALCON thread process Note that even if Parallel HALCON is reentrant for most of the operators there are still some operators that have to be processed exclusively due to reasons of their implementation If no subslot process exclusively is filled in with an operator it is assumed that the ope
116. ge Interface 2000 11 16 3 8 STRUCTURING PROGRAMS 45 3 2 3 Debugging The HALCON memory management provides debugging mechanisms Every time a memory block is deallocated a couple of consistency checks is performed automatically Moreover the consistency of memory blocks can be checked for debugging reasons at any time using specific Extension Package Interface routines see Fig 3 5 Names HTestMem HTestPtr HTestAllTmp HTestTmp Synopsis include Halcon h Herror HTestMem void Herror HTestPtr void pointer Herror HTestAllTmp Hproc handle proc handle Herror HTestTmp Hproc handle proc handle void pointer Figure 3 5 HALCON memory management Check of consistency HTestMem checks all the memory allocated with HAlloc or HAllocLocal whereas HTestPtr checks only the specified memory block Similar to that HTestA11Tmp checks all the memory allocated via HAllocTmp and HTestTmp checks the specified block With any failure of the consistency check the routines return an error number H_ERR_ICM inconsistent memory Furthermore if the global variable HDoLowError is set to TRUE they display a description of the error either on stderr UNIX or within an alert box Windows NT 2000 This variable can be set in an application with the operator set system do low error true false or used directly inside the newly written operator 3 3 Structuring Programs HALCON operators are typically implemented by at leas
117. ge sl and libpackagec sl or libpackagecpp sl to your objects be sides libhalcon sl and libhalconc so or libhalconcpp sl as for any HAL CON application Furthermore you must add the package library subdirectory 1lib hppai 1 hp hpux10 to the environment variable SHLIB_PATH otherwise the loader will fail to access the libraries course this has to be done for 1 51 and libpackagecpp s1 as well HALCON 6 0 110 CHAPTER 7 CREATING A NEW HALCON PACKAGE If you use cc or CC for linking specify the option W1 s in order to allow the usage of the environment variable SHLIB PATH for resolving the location of shared libraries by the loader The directory HALCONROOT examples extension package halconuser contains two ex ample makefiles makefile creates the example package halconuser for standard HALCON makefile testprog creates the example applications based on the package halconuser Both makefiles include the file make hppa1 1 hp hpux10 which sets architecture dependent vari ables 7 2 5 6 Generating Packages Under DIGITAL UNIX Tru64 UNIX In order to activate a package its complete path e g HALCONROOT examples extension package halconuser must be included in the environment variable HALCONEXTENSIONS In the UNIX version the package paths in HALCONEXTENSIONS are separated by colons Please see also the comments on installing a HALCON package on a DIGITAL UNIX now called Tru64 UNIX system on page 8 e
118. gt This is true for the Windows NT 2000 version For UNIX systems the prefix lib is added to the libraries resulting in libpackage libpackagec and libpackagecpp HALCON Extension Package Interface 2000 11 16 1 2 HALCON PACKAGES 5 1 2 1 Packages and Parallel HALCON Extension packages can also be used in Parallel HALCON What s more Parallel HALCON will automatically parallelize your new operators if you add the corresponding information in the definition file see section 2 2 12 Similar to the HALCON libraries which exist in two versions e g halcon dll and parhalcon d11 you must provide separate versions of your package libraries to be used together with Parallel HALCON The names of these libraries must start with the pre fix par e g the Parallel HALCON version of the example package halconuser consists of the libraries parhalconuser dll parhalconuserc dll and parhalconusercpp dll under Windows NT 2000 or libparhalconuser so libparhalconuserc so and libparhalconusercpp so under UNIX The Parallel HALCON version of the libraries is created analogously to the standard HALCON version with only small differences See section 7 2 for details 1 2 2 Directory Structure of a HALCON Package A HALCON package resides in a directory with the same name as the package itself In our example this is the directory halconuser 4HALCONROOTAVexamples Vc interface This directory must at least contain the following subdirectories
119. he Reference Manuals for details HALCON 6 0 parameter OrigImage description english sem_type type_list multivalue parameter ThresholdImage description english sem type type list multivalue parameter RegionDynThresh description english sem type multivalue parameter Offset description english sem_type type_list default_type default_value values multivalue assertion costs weight parameter LightDark description english sem type type list default type default value value list multivalue costs weight CHAPTER 2 OPERATOR DESCRIPTION DEF FILES input object Image to be segmented image byte int2 int4 real optional input object Image containing the local thresholds image byte int2 int4 real optional output object Segmented regions region optional input control Offset added to ThresholdImage number integer real real 5 0 0 ONES ODE false 255 lt Offset amp amp Offset 255 0 10 0 20 0 30 0 input_control Extract light dark or similar areas string string string light dark light equal not equal false 0 The minimum of information needed for every parameter is its name and type its default type its semantic type the number of values allowed multivalue and if the operator should be automatically parallelized the costs weight of input control p
120. he environment variable LD_LIBRARY_PATH in order to run stand alone applications based on the package Otherwise the loader will fail to access the interface library libpackagec so or libpackagecpp so linked to the application see section 7 2 5 HALCON Extension Package Interface 2000 11 16 1 4 AN EXAMPLE 9 Note that it is not necessary to modify LD_LIBRARY_PATH in order to use the package within HDevelop 1 4 An Example The following example illustrates the steps described in section 1 2 Assume one wants to implement a new operator named user thresh to extract all pixels with a gray value larger than a threshold value specified in an input parameter The use of user thresh within a C program is illustrated in Fig 1 2 main 1 Hobject Image Region int Thresh read image Image monkey Thresh 100 user thresh Image amp Region Thresh Figure 1 2 Calling the operator user thresh in C A more detailed example is provided in AHALCONROOT examples Vc interface MhalconuserMsource M testthreshold c To use user_thresh in this way within C programs The new operator must be implemented The corresponding HALCON interface code must be generated e The corresponding package must be created especially containg the operator and interface libraries The application must be linked user thresh lt CIPUserThreshold Image Region Threshold i Figure 1 3 Defining a new operator user thresh First of all
121. he generation of the manuals the HTML documentation and the help files used to access operator knowledge via HALCON operators like get operator info For the online help and the HTML files an ASCII version of each text is needed whereas the manuals are produced compiling a BIEX file generated from the def files To avoid the necessity of writing two text blocks for one operator ASCII and both versions are generated by using one text Therefore the following conventions must be observed HALCON Extension Package Interface 2000 11 16 2 4 TEXT IN DEF FILES 35 Umlauts German umlauts are written in IATEX typical notation a s Quotation marks There are two kinds of quotation marks string This notation signals that the quoted text is a string as used within programming languages So hcomp treats string as a string parameter Text This notation must be used in all other cases particularly when quoting a word or text segment because of its content So hcomp treats Text as a quoted section of a text Please do not forget or permute the quotation marks starting with and ending with Underscores An underscore can be used without the necessity of prefixing a backslash as necessary in IATEX N so that the text is easier to read The backslashes are inserted automatically in the generated IZIEX version of the text Note that this mechanism is only active within the ASCII part
122. his code The 19th character is unknown for this code The 20th character is unknown for this code Specified code type is not supported HALCON Extension Package Interface 2000 11 16 H ERR BAR2D WRONG FOREGROUND HERR BAR2D WRONG SIZE H ERR BAR2D WRONG SHAPE H ERR BAR2D WRONG PARAM NAME H ERR BAR2D WRONG PARAM VAL H ERR BAR2D WRONG MODE H ERR BAR2D SYMBOL ON BORDER H ERR BAR2D MODULE CONT NUM H ERR BAR2D SYMBOL FINDER H ERR BAR2D SYMBOL DIMENSION H ERR BAR2D CLASSIF FAILED H ERR BAR2D DECODING FAILED H ERR BAR2D DECODING READER H ERR NOT IMPL H ERR WIT HERR WIC H ERR UNDI H ERR WIS H_ERR_WCN H_ERR_STRTL H_ERR_WITFO H_ERR_NIIT H_ERR_NOCIMA H_ERR_DEMO_NOFG H_ERR_DEMO_NOPA H_ERR_STUD_OPNA H_ERR_STUD_PANA H_ERR_STUD_FGNA H_ERR_TMU H_ERR_NUS H_ERR_NEE H_ERR_MNI H_ERR_SVD_CNVRG H_ERR_SVD_FEWROW H_ERR_TQLI_CNVRG H_ERR_JACOBI_CNVRG H_ERR_MATRIX_SING H_ERR_MATCH_CNVRG H_ERR_MAT_UNDEF H_ERR_MAT_WDIM H_ERR_MAT_NSQR H_ERR_MAT_FAIL H_ERR_MAT_NPD H_ERR_WSPVP 8801 8802 8803 8804 8805 8806 8807 8808 8809 8810 8811 8812 8813 9000 9001 9002 9003 9004 9005 9006 9007 9008 9009 9010 9011 9050 9051 9052 9100 9101 9102 9200 9201 9202 9203 9204 9205 9206 9207 9208 9209 9210 9211 9300 131 Wrong foreground specified Wrong matrix size specified Wrong symbol shape specified Wrong generic parameter name
123. i arc center y arc center x circle center arc angle rad angle stretched by the circular arc in radians arc begin y arc begin x starting point of circular arc e Numerical region descriptions control parameters coordinates y coordinates x coordinates contour y contour x points of a contour chord y chord x1 chord x2 runlength code polygon y polygon x polygoneal representation chain begin y chain begin x chain code chain code e Miscellaneous control parameters angle rad or angle deg angle in radians or degrees filename named file name HALCON Extension Package Interface 2000 11 16 2 3 DESCRIBING THE PARAMETERS 29 Please note e y coordinates correspond to rows x coordinates to columns in the image e Please use the above semantic types for characterizing parameters whenever they are applicable e For control parameters characterizing a composed object like a circle etc Please use the specific order of parameters like indicated above 2 3 4 multivalue multivalue true false optional 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 slots mentioned so far must appear in any extended operator description Moreover the following optional slots are recommended to provide further information about param
124. idth threshold region_out supply procedure always with this parameter HUserExport Herror CIPUserThreshold Hproc handle proc handle HGetCPar amp Threshold get control parameter HAllSegm proc_handle amp region amp image 1 i work on all input images HCkP proc handle IPBThreshold call action procedure HNewRegion proc_handle region_out store result region return H MSG TRUE Figure 1 6 Sample source code of supply CIPUserThreshold and action IPBThreshold procedure Compiling the source code generates an object file in the example cipuserthreshold o that should be integrated into the user extension library halconuser Moreover the gen erated interface code must be converted to the corresponding language dependent interface library In case of a C application this is halconuserc containing HChalconuser o The see section 7 1 for a complete description 10 1 uses the C version as well HALCON 6 0 12 CHAPTER 1 INTRODUCTION file makefile in the directory 4HALCONROOT N examples V extension package halconuser contains a makefile for generating the example package itself under UNIX makefile nt is the corresponding file to be used via nmake under Windows NT and Windows 2000 The make files nakefile testprog and makefile testprog nt generate example applications using the new operators Now we can use our
125. ies the maximum number of channels If an image HALCON Extension Package Interface 2000 11 16 6 1 LOOP MACROS 91 contains less channels the corresponding Himage elements in the image array are undefined The actual number of channels can be accessed e g using HNumO0f Channels see section 5 6 4 An image must contain at least one channel Otherwise HA11Segm returns an error If the number of channels exceeds max channels the remaining channels are ignored Furthermore the size of all channels is checked for equality Herror IPSegm Hproc handle proc handle HALCON proc handle Hrlregion region area of definition Himage image input image 1 1 out segmentation result compute region out from 1 and image return H MSG OK HUserExport Herror CIPSegm Hproc handle proc handle x INTA4 8 i Hrlregion new region Himage image HCkP HAllocRLTmp proc handle amp new region allocate memory HAllSegm proc handle amp region amp image 1 i all inp images HCkP IPSegm region image new region HNewRegion proc handle new region allocate new region HCkP HFreeRLTmp proc_handle new_region free memory return H MSG TRUE Figure 6 4 A typical application of HA11Segm A segmentation operator Fig 6 4 shows a framework for a supply procedure for a segmentation operator using HA11Segm The corresp
126. indow coordinates It is not possible to open another window HALCON 6 0 122 H ERR DNA H_ERR_UCOL H_ERR_NWO H_ERR_WFM H_ERR_WGV H_ERR_WPV H_ERR_WLW H_ERR_WCUR H_ERR_WLUT H_ERR_WDM H_ERR_WRCO H_ERR_WRDM H_ERR_WRIT H_ERR_IPIT H_ERR_WRZS H_ERR_WRDS H_ERR_WRDV H_ERR_WWINF H_ERR_WDEXT H_ERR_WWT H_ERR_WND H_ERR_WRGB H_ERR_WPNS H_ERR_WCM H_ERR_FNA H_ERR_LNFS H_ERR_LOFL H_ERR_WIDT H_ERR_WWDS H_ERR_NDVS H_ERR_WBW H_ERR_WDVS H_ERR_TMF H_ERR_WFN H_ERR_WCP H_ERR_NTW H_ERR_NPW H_ERR_STL H_ERR_NSS H_ERR_NMS H_ERR_DWNA H_ERR_WOM H_ERR_WWM H_ERR_LUTF H_ERR_LUTN8 H_ERR_WTCM 5104 5105 5106 5107 5108 5109 5110 5111 5112 5113 5114 5115 5116 5117 5118 5119 5120 5121 5122 5123 5124 5125 5126 5127 5128 5129 5130 5131 5132 5133 5134 5135 5136 5137 5138 5139 5140 5141 5142 5143 5144 5145 5146 5147 5148 5149 APPENDIX A HALCON ERROR CODES Device resp operator not available Unknown color No window has been opened for desired action Wrong filling mode for regions fill or margin Wrong gray value 0 255 Wrong pixel value use value of get pixel P only Wrong line width see query line width Min Max Wrong name of cursor see query mshape Name Wrong color table see query lut Name Wrong representation mode see query insert Mode Wrong representation color see query color List Wrong dither matrix binary image representation Wrong image transformation
127. ing failed No ARC INFO world file No ARC INFO generate file Isolated point while contour merging Syntax error in file for training Maximum number of attributes per example exceeded Not possible to open file for training Too many data sets for training Wrong key for data for training Too many examples for one data set for training Too many classes Maximum number of cuboids exceeded Not possible to open classifikator s file Error while saving the classificator Not possible to open protocol file Classificator with this name is already existent Maximum number of classificators exceeded Name of classificator is too long gt 20 Classificator with this name is not existent Current classificator is not defined Wrong id in classification file Wrong verion number in classification file Wrong rotation number Wrong letter for Golay element Wrong reference point Wrong number of iterations Mophology system error Wrong type of boundary Morphology wrong number of input objects Morphology wrong number of output objects Morphology wrong number of input control parameter Morphology wrong number of output control parameter Morphology structuring element is infinite Morphology wrong name for structuring element Wrong number of run length rows chords smaller than 0 Run length row with negative length Run length row gt image height Run length row lt 0 Run length column gt image width Run length column
128. ing the Operator Libraries The supply and action procedures must be encapsulated in a DLL or a shared library The name of this shared object has to be identical with the package name plus file extension For the use HALCON Extension Package Interface 2000 11 16 7 2 GENERATING HALCON PACKAGES 103 by Parallel HALCON a second version of the library must be created with the additional prefix par to the name Please refer to section 7 2 5 and the documentation of your programming environment for more details also about the following sections Under Windows NT or Windows 2000 the generated DLLs must be placed in the subdirectory bin ARCHITECTUREA the libraries in the subdirectory 13b VA4ARCHITECTUREX Under UNIX the generated shared libraries must be placed in the subdirectory 1ib ARCHITECTURE4 bina ries in the subdirectory bin ARCHITECTUREY of the package 7 2 2 Creating the C Interface To access new HALCON operators inside a package within C programs or from HDevelop you must create a C interface library packagec residing in the subdirectory 1ib ZARCHITECTURE of the package This library is based on a single C file HCpackage c which is generated via hcomp C ppackage def file s from the def file s of your new operators Note that hcomp simultanously generates the file HCpackage h containing the C prototypes of your new operators Include this file in your C programs using these operators 7 2 8 Creating the Interf
129. is read from the HALCON data base its representation fulfills all the conditions above When writing a region condition 2 and 3 need not to be sufficed in all cases as the Extension 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 Hrun where num is the current and num max the maximum allowed number of chords depending on the size of the region specified at its creation see also sections 3 2 The flag is_comp1 allows an HALCON 6 0 52 CHAPTER 4 HALCON DATA TYPES typedef struct INT2 1 line number row of chord INT2 cb column index of beginning of chord INT2 ce column index of ending of chord Hrun typedef struct HBOOL is compl region is complement INT4 num number of chords INT4 num max maximal number of chords HRegFeature feature already processed features Hrun rl RL LENGTH array of chords Hrlregion Figure 4 4 Data type Hrlregion for region encoding easy transformation of a region in its complement Operators that work on regions must consider this flag and react according to its value The structure HRegFeature see Fig 4 5 contains all features extracted so far to avoid repeating a computation HFeatureFlags encodes which features already have been extracted Do not forget to reset these flags if you modify a region N
130. ject specified by the data base key obj and returns it in the Himage structure image For the sake of efficiency only a pointer to the image matrix is copied to image instead of copying the data itself So only read access to the image data is recommended in order to avoid unpredictable side effects Fig 5 13 shows an application of HGetDImage 5 2 5 HGetObjNum HGetObjNum see Fig 5 9 returns the number of iconic objects which are stored in the input object parameter denoted by its index par_num from 1 to It is an alternative to the usage of HReadGVA compare page 61 By using HGetObjNum 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 Himage image Hcpar row col gray HGetSPar proc handle 1 LONG PAR amp row 1 row HGetSPar proc handle 2 LONG PAR amp col 1 column coord HLinCoor row par 1 col par 1 image width HGetDImage proc_handle obj_key IMAGE_INDEX amp image processing in general this should be done calling an action proc switch image kind case BYTE_IMAGE gray par 1 image pixel b coord gray type LONG_PAR break case FLOAT_IMAGE gray par f image pixel f coord gray type FLOAT_PAR break default return H ERR WIT wrong image type HPutCPar proc handle 1 amp gray 1 Figure 5 13 Application of HGetDImage Return the gray value at p
131. kage Interface 2000 11 16 Appendix HALCON Error Codes In this section all HALCON error codes are summarized see also section 3 6 Error Name H ERR WIPT1 H_ERR_WIPT2 H_ERR_WIPT3 H_ERR_WIPT4 H_ERR_WIPT5 H_ERR_WIPT6 H_ERR_WIPT7 H_ERR_WIPT8 H_ERR_WIPT9 H_ERR_WIPT10 H_ERR_WIPT11 H_ERR_WIPT12 H_ERR_WIPT13 H_ERR_WIPT14 H_ERR_WIPT15 H_ERR_WIPT16 H_ERR_WIPV1 H_ERR_WIPV2 H_ERR_WIPV3 H_ERR_WIPV4 H_ERR_WIPV5 H_ERR_WIPV6 H_ERR_WIPV7 H_ERR_WIPV8 H_ERR_WIPV9 H_ERR_WIPV10 H ERR WIPV11 H ERR WIPV12 H_ERR_WIPV13 H_ERR_WIPV14 H_ERR_WIPV15 Code 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 Description Wrong type of control parameter Wrong type of control parameter Wrong type of control parameter Wrong type of control parameter Wrong type of control parameter Wrong type of control parameter Wrong type of control parameter 1 2 3 4 Wrong type of control parameter 5 6 7 8 9 Wrong type of control parameter Wrong type of control parameter Wrong type of control parameter Wrong type of control parameter Wrong type of control parameter Wrong type of control parameter Wrong type of control parameter Wrong type of control parameter Wrong value of control parameter Wrong value of control parameter Wrong value of control parameter Wrong value of control
132. l error 2 Wrong type of OCR tool no box or net system not initialized Wrong type of OCV features No more free OCV handles available Wrong name for an OCV object Training has already been applied No training has been applied to the character Wrong number of function points List of values is not a function Wrong ordering of values not ascending Illigal distance of function points You have to indicate at least 3 calibration points Calibration table is too big No calibration table found Error while reading calibration table description file Minimum threshold while searching for ellipses Read error format error in calibration table description file Error in projection s_x 0 or s_y 0 orz 0 Error in inverse projection Not possible to open camera parameter file Format error in file no colon Format error in file 2 colon is missing Format error in file semiocolon is missing Not possible to open camera parameter pose file Format error in camera parameter pose file Not possible to open calibration target description file Not possible to open postscript file of calibration target Error while norming the vector Fitting of calibration target failed No next mark found Normal equation system is not solvable Average quadratic error is too big for 3D position of mark Non elliptic contour Wrong parameter value slvand Wrong function results slvand Distance of marks in calibration target descri
133. last point along the contour to be copied starting with index 0 For closed contours a negative value might be specified for min_index This will lead to a wrap around that is the part of the contour to be copied starts at cont_in gt num min_index Both HCopyXLDCont and HCopyXLDContPart allocate the output contour themselves So just pass a pointer to Hcont without allocating any memory for cont_out The routines provided for handling attributes of contour points are summarized in Fig 4 9 HAddXLDContAttrib is used to add a new class of attributes to a given contour cont Note that this 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 name The index of the new attribute within the attribs array in cont is returned in index and can be used to ad dress the values by cont gt attribs index val The same holds for global attributes HAddXLDContGlobalAttrib is used to add new global attributes which can be accessed by cont gt global index val Note that these values can be accessed within the HALCON system that is on the application layer using the operators get_contour_attrib_xld and HALCON 6 0 54 CHAPTER 4 HALCON DATA TYPES Names CB CE Synopsis include HALCON h INT4_8 CB Hrun rl INT4_8 index INT width INT4_8 CE Hrun rl INT4_8 index INT width Figure 4 6 Linear coordinates
134. le of how to use HA11Comp Within the HA110bj loop for each input image object an output image object is created and added to the object list of the first output object parameter HCr0bj see section 5 4 1 After that a loop over all gray value channels of the current image object is performed HA11Comp Within this loop for every gray value So in contrast to the routines described in section 6 1 HA110bj allows to specify the desired parameter by its number HALCON Extension Package Interface 2000 11 16 5 4 CREATING OBJECTS AND WRITING OUTPUT OBJECT PARAMETERS 71 channel a new image matrix is created HCrImage see section 5 4 1 and filled with the rotated input matrix IPBRot90 Finally this matrix is installed as a new gray value channel of the output image object HDef0bj 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 image object via HDef0bj is omitted in this example 5 4 Creating Objects and Writing Output Object Pa rameters This section describes routines for creating new iconic objects in the HALCON data base and for 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 definitio
135. ler this is done using the option KPIC Creating object files for the Parallel HALCON version If you want to create a Parallel HALCON version of your package a second set of object files must be created from the source code files using the compiler define DH PARALLEL We recommend to place these object files into a separate directory to prevent confusing them with the object files created for the standard HALCON version Creating the operator library libpackage so To create the operator library libpackage so containing new HALCON operators the object files containing the corresponding supply and action procedures must be linked The linkage of shared libraries is done with 1d G Specify the desired name libpackage so and location of the library with the 1d option o To create the library libparpackage so for Parallel HALCON the corresponding object files compiled with the define DH PARALLEL must be linked Creating the C interface library libpackagec so To create the C interface library libpackagec so providing the interface to new HALCON operators the object file HCpackage o and the new operator library libpackage so must be linked To create the library libparpackagec so for Parallel HALCON the corresponding ob ject file compiled with the define DH PARALLEL must be linked to the Parallel HALCON version of the operator library i e libparpackage so Creating the C interface library libpackagecpp so To create the C
136. lit tuple split channel split domain This subslot of parallelization can contain one or more of the strings above and specifies which type of automatic parallelization the operator is suitable for e split tuple Parallel HALCON does not automatically parallelize the operator e split tuple Parallel HALCON parallelizes the operator by splitting every input image tuple into several subsets of the tuple the tuple subsets are then processed in parallel e split channel Parallel HALCON parallelizes by splitting every multichannel input image into several subsets of the channels the subsets are then processed in parallel e split domain Parallel HALCON parallelizes by splitting the domain of every input image into several parts the parts are then processed in parallel If method is set to anything other but none the parameter slot costs weight must be filled in for every input control parameter and the parameter slot postprocessing must be filled in for every output control parameter of the operator see page 29 If method is set to split domain the slot domain split see below must also be set correctly and may not be omitted If the slot process 10ocally is set to true method should be set to none because the operator won t be parallelized then see description of process locally above HALCON 6 0 24 CHAPTER 2 OPERATOR DESCRIPTION DEF FILES Note that the slot method may contain any combination of
137. lowing chapter especially facilitate the programming of support procedures that is the access of the HALCON data base and all the parameter handling In this chapter the low level interface routines are introduced They allow a straightforward access to all parameters of an operator to iconic objects and their components and to control parameters Moreover some routines for creating objects and writing output object parameters and control parameters are introduced Based on these low level routines a set of convenience routines are presented in chapter 6 They are designed to further facilitate the programming of very typical support procedures 5 1 Basic Access to Iconic Input Objects This section introduces some basic routines for accessing iconic objects regions gray value channels XLDs see Fig 5 1 They form a basic interface to the HALCON data base Fig 5 2 illustrates how they are used to read image and region data from input object parameters 59 60 Names HGetO0bj HGetComp HGetRL HGetImage HGetXLD CHAPTER 5 HANDLING ICONIC OBJECTS AND CONTROL PARAMETERS BUDUHSES include Halcon h HGetObj Hproc handle proc handle INT par num INT4 obj_num Hkey obj_key HGetComp Hproc_handle proc handle Hkey obj key INT comp Hkey comp key HGetRL Hproc handle proc handle Hkey region key Hrlregion region HGetImage Hproc handle proc handle Hkey image key Himage image HGetXLD Hproc ha
138. ltiple call of HRLInitSeg Internal error HRLSeg not initialized Wrong size of filter for Gauss Filter size exceeds image size Row value of a coordinate gt 216 Row value of a coordinate lt 216 Column value of a coordinate gt 216 Column value of a coordinate lt 216 Wrong segmentation threshold Unknown attribute of a region Unknown attribute of a gray value Internal error in HContCut Error in HContToPol distance of points too big Error in HContToPol contour too long Too many rows IPImageTransform Scaling factor 0 0 IPImageScale Wrong range in transformation matrix Internal error in IPvvf no element free Number of input objects is zero HALCON Extension Package Interface 2000 11 16 _ _ H_ERR_NPOT H_ERR_TMEP H_ERR_LTB H_ERR_NNLA H_ERR_WFS H_ERR_IWDS H_ERR_IWTL H_ERR_IWTS H_ERR_IHTL H_ERR_IHTS H_ERR_DNOC H_ERR_COWTS H_ERR_COHTS H_ERR_NUM_COLMN H_ERR_NUM_LINES H_ERR_OVL H_ERR_NOT_SYM H_ERR_NUM_COLS H_ERR_SYNTAX H_ERR_MISSING H_ERR_COOC_MEM H_ERR_NO_FILE H_ERR_FILE_WR H_ERR_NUM_LUCOLS H_ERR_WNOLI H_ERR_DITS H_ERR_WINTM H_ERR_THICK_NK H_ERR_WIND3 H_ERR_WIND5 H_ERR_WIND7 H_ERR_WLAWSS H_ERR_WNEE H_ERR_XLDWT H_ERR_XLD_CTL H_ERR_XLD_RPF H_ERR_XLD_MCL H_ERR_XLD_MCN H_ERR_XLD_CTS H_ERR_XLD_CRD H_ERR_XLD_CRND H_ERR_DBXC H_ERR_DBWXID H_ERR_XLD_WNP H_ERR_XLD_CAND 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3131 3132 3133 3134 3135 3136
139. macros to access iconic objects amp denotes output parameters of the macros This is only a special notation to make clear that these parameters are changed by the macros So do not pass pointers to variables but the variables itself to the macro 5 3 1 HA110bj HA110bj see Fig 5 15 performs a loop over all iconic objects of a specified input object parameter and returns their data base keys Hkey obj key Hrlregion Himage image INT4_8 index HA110bj proc_handle 1 obj_key index HGetFDRL proc handle obj key amp region HGetDImage proc handle obj key IMAGE INDEX amp image Figure 5 16 Application of HA110bj Get the area of definition and the first gray value channel of all input objects of the first input object parameter HALCON 6 0 70 CHAPTER 5 HANDLING ICONIC OBJECTS AND CONTROL PARAMETERS Within the loop all iconic objects contained in the input object parameter number par num are accessed one by one index is set to the number of the current iconic object to be processed and obj key is set to the corresponding data base key Thus using HA110bj is equivalent to programming an explicit loop over all objects contained in a parameter and determining the data base keys via HGetObj see also Fig 5 3 Fig 5 16 shows an application of HA110bj 5 3 2 HAllComp HA11Comp performs a loop over all gray value channels components of the image object de noted by the data base key obj
140. mages region regions 1 any XLDs lines in eXtended Line Description xld cont xld poly xld para xld mod para xld ext para e Elementary data control parameters number unspecific integer real string grayval gray value channel channel number e Handles control parameters frame grabber HALCON 6 0 28 CHAPTER 2 OPERATOR DESCRIPTION DEF FILES file ocr OCR classifier bg estimation see HALCON operator create bg esti class box general classifier window id HALCON window e Arrays control parameters histogram values gray value histogram distribution values distribution e Geometric data control parameters point x point y position extent x extent y dimensioning circle center y circle center x circle radius circle line begin y line begin x line end y line end x line rectangle origin y rectangle origin x rectangle upper left corner rectangle corner y rectangle corner x lower right corner or rectangle extent x rectangle extent y expansion as alternative to spec ifying the 2 corner rectangle2 center y rectangle2 center x rectangle with arbitrary orien tation center rectangle2 angle rad orientation in radians rectangle2 hwidth rectangle2 hheigth half the size ellipse center y ellipse center x ellipse centre ellipse angle rad orientation in radians ellipse radiusi ellipse radius2 radi
141. matrix with wrong dimension Input matrix is not quadratic Matrix operation failed Matrix is not positive definite Eye point and reference point coincide HALCON 6 0 132 APPENDIX HALCON ERROR CODES HALCON Extension Package Interface 2000 11 16
142. n Therefore in order to return iconic objects as the result of a HALCON operator you have to e store the computed regions channels and XLDs in HALCON data base objects e combine regions and channels to image objects e and add the appropriate iconic objects to the corresponding output object parameters 5 4 1 HCrObj HCr0bj see Fig 5 18 creates a new image object in the HALCON data base and adds it to the list of objects in the output object parameter with the number par num Note that more than one image object can be returned in the same output parameter by iterating calls of HCr0bj using the same par num Each call appends the data base key of the new object at the end of the object list for the parameter The new image object contains the following default components e The region component specifying the area of definition is set to the empty region This component can be changed using HPutDRL see section 5 4 3 or HPutRect see section 6 2 2 e All channels are marked as undefined that is the new image object contains no gray value components Channels can be added to the object using HPut Image see section 5 4 4 and HDef0bj see section 5 4 5 or HPutDImage see section 5 4 6 Fig 5 17 and 5 21 show examples for how to use HCrOb j HALCON 6 0 72 CHAPTER 5 HANDLING ICONIC OBJECTS AND CONTROL PARAMETERS Names HCrO0bj HCopy0bj HPutDRL HCrXLD BXBODSES include Halcon h HCr0bj Hproc handle proc handle
143. n operator An extension of the keyword specifies the programming language of the example example trias Looking for regions with the diameter D mean image Imaged Mean D 2 D 2 gt dyn threshold Image Mean Seg 5 light gt connection Seg 0bjects The extension trias denotes the image processing language Trias that uses a syntax basically equal to the notation within HDevelop Moreover the extensions c and c can be used The text of the example is processed unmodified so it must not contain any IATEX special characters The only exception is the semicolon that needs a prefixed backslash because it would signal the end of the example text otherwise This must be considered especially for C and examples 2 2 15 references The slot references not specified in the dyn threshold example is used to insert references to literature into the documentation e g references Haralick K G Shapiro Computer and Robot Vision N Vol 1 Addison Wesley Publishing Company 1992 2 3 Describing the Parameters Again the definition of dyn threshold is used as an example Every description of a single parameter starts with the keyword parameter and contains several slots A slot begins with a characteristic keyword followed by a colon and is finished by a semicolon AII slots specified for the parameters of an operator are accessible online within the HALCON system using the operator get param info see t
144. n used x1ds and the corresponding number of keys in num_used_xlds For contours these parameters typically are set to NULL and 0 HCrXLD expects an appropriate deallocation routine for the XLD data in the parameter free proc Please use HALCON 6 0 78 CHAPTER 5 HANDLING ICONIC OBJECTS AND CONTROL PARAMETERS DBFreeProc HXLDFreeContour for XLD contours and DBFreeProc HXLDFreePolygon for XLD polygons allocated based on HA11oc Finally HCrXLD not only creates a new data base object but also appends this object to the output object parameter with number par num Fig 5 24 and 5 25 show two typical applications of HCrXLD 5 5 Reading and Writing Control Parameters This section describes routines for reading and writing in output control parameters see Fig 5 26 Interchanging control data with the host language is done via the data type Hcpar see section 4 4 5 5 1 HGetCPar HGetCPar see Fig 5 26 reads the parameter values of the input control parameter number par num 1 and writes them to the array val of Hcpar structures that must has been allocated before with a suitable size note that Note that for every input value its type LONG PAR FLOAT PAR STRING PAR is also stored within the Hcpar structure Thus it is possible to pass different control data types within one control parameter of a HALCON operator The current number of values is returned in num HGetCPar allows to restrict the parameter a
145. name or image size Unsuitable image type for image transformation Wrong zooming factor for image transformation Wrong representation mode Wrong code of device Wrong number for father window Wrong window size Wrong window type No current window has been set Wrong color combination or range RGB Wrong number of pixels set Wrong value for comprise object or image set fix with 1 4 image levels and static not valid set lut not valid in child windows Number of concurrent used color tables is too big Wrong device for window dump Wrong window size for window dump System variable DISPLAY setenv not defined Wrong thickness for window margin System variable DISPLAY has been set wrong lt host gt 0 0 Too many fonts loaded Wrong font name No valid cursor postion Window is not a textual window Window is not a image window String too long or too high Too little space in the window rightwards Window is not suitable for the mouse Here Windows on a equal machine is permitted only Wrong mode while opening a window Wrong window mode for operation Operation not possible with fixed pixel Color tables for 8 image levels only Wrong mode for pseudo real colors HALCON Extension Package Interface 2000 11 16 H ERR WIFTL H ERR WS0I H ERR HRLUT H_ERR_WPFSL H_ERR_WPVS H_ERR_WLPN H_ERR_WLPL H_ERR_WNOC H_ERR_WPST H_ERR_SWNA H_ERR_NSFO H_ERR_WSPN H_ERR_WIFFD H_ERR_WLUTF H_ERR_WLUTE H_ERR_WLUTD H_ERR_CNDP H_ERR_LN
146. ndle proc handle Hkey obj key INT xld type XLD x1d Figure 5 1 Basic routines for accessing iconic input objects 5 1 1 HGetObj HGetObj see Fig 5 1 returns the data base key type Hkey of an iconic object corresponding to the input object parameter number num of the HALCON operator The iconic object can either be a region object that contains only a region component an image object object that contains a region component and one or more image channels or an XLD object that contains a contour or a polygon For the sake of simplicity we will refer to all of them using the term object The parameters of a HALCON operator are numbered consecutively from 1 to n not from 0 to n 1 for each parameter class input output object control The parameter par_num of HGetObj refers to this number thus specifying the desired input object parameter All objects passed within a single input object parameter are numbered from 1 to m with the first object in the list having the number 1 The parameter ob j of HGetOb j denotes the index of a desired object within this list 1 lt obj num lt m HALCON Extension Package Interface 2000 11 16 5 1 BASIC ACCESS TO ICONIC INPUT OBJECTS 61 operator call 1st input object parameter 2nd input object parameter parameter number HGetObj T Sobi key Hke comp key Himage HGetComp T T region chann
147. ndow attribute negativ height of area or 0 negativ width of area or 0 Window not completely visible Internal error only RGB Mode No more image windows available File not found Error while writing image data sufficient memory Error while writing image descriptor sufficient memory Error while reading image data format of image too small Error while reading image data format of image too big Error while reading image descriptor file too small Inconsistent image format Help file not found setenv HALCONROOT lt Halcon Homedirectory gt Help index not found setenv HALCONROOT lt Halcon Homedirectory gt File lt standard_input gt can not be closed lt standard_output error gt can not be closed File can not be closed Error while writing to file HALCON 6 0 124 H_ERR_NFA H_ERR_WFIN H_ERR_CNOF H_ERR_WFMO H_ERR_WPTY H_ERR_WIW H_ERR_WIH H_ERR_FTS1 H_ERR_FTS2 H_ERR_WDPI H_ERR_WNOW H_ERR_WNOH H_ERR_WNFP H_ERR_WPNA H_ERR_WSNA H_ERR_NPCF H_ERR_WHIF H_ERR_HINF H_ERR_HSNF H_ERR_ICSF H_ERR_EFNF H_ERR_NFWKEF H_ERR_WIFT H_ERR_ICNF H_ERR_WTIFF H_ERR_WFF H_ERR_NOGPPROC H_ERR_NOGPFILE H_ERR_NOGPOUT H_ERR_NOPNM H_ERR_ICODB H_ERR_WFID H_ERR_FNO H_ERR_NO_FILES H_ERR_WSID H_ERR_SNO H_ERR_NSA H_ERR_CNOS H_ERR_CNCS H_ERR_CNGSA H_ERR_CNSSA H_ERR_WRSBR H_ERR_WRSDB H_ERR_WRSFC H_ERR_CNFS 5213 5214 5215 5216 5217 5218 5219 5220 5221 5222 5223 5224 5225 5226 522
148. nds according to special syntactic rules that are defined in section 2 4 2 2 3 abstract A more detailed description of the operator is given within the slot abstract The description of the example is here shown as a shortened version HALCON Extension Package Interface 2000 11 16 2 2 EXTENDED OPERATOR DESCRIPTION 19 abstract english NXOpRef dyn threshold selects from the input image those regions in which the pixel fulfill a threshold condition Let g o g_ ParRef OrigImage and g im g_ ParRef ThresholdImage Then the condition for ParRef LightDark ValRef light is a g o gt g_m Offset 1 g_ o ge g_ m ParRef Offset e For ParRef LightDark ValRef dark the condition is a g o lt g_m Offset 1 g_ o Me g_ m ParRef Offset e Finally for ParRef LightDark ValRef equal it is a g m Offset lt g_o lt g_m Offset 1 g_ m ParRef 0ffset Me g o Me g_ m ParRef Offset M Qe This means that all points in ParRef OrigImage for which the gray value is larger or equal to the gray value in ParRef ThresholdImage plus an offset are aggregated into the resulting region Again refer to section 2 4 for the special syntax of text 2 2 4 module module basic This slot denotes the module inside HALCON the operator should belong to For user exten sions the module basic is recommended 2 2 5 chapter To achi
149. ned for the loop macros HA11 in section 6 1 HDupObj is typically used for operators that examine objects and select them by a given criteria Some HALCON operators of this kind are select shape has shape or select gray Fig 6 11 shows an application of HDup0bj CIPUserSelect computes the length of the contour of each input region in parameter 1 All regions with a contour of at least the minimal length min are passed to the output Since HDupObj only increases the number of references to a data base object instead of copy ing it physically its memory costs and computational costs are neglectable In contrast e g HNewRegion and HAllFilter always allocate new memory for the output objects So when ever possible HDupOb j should be used HALCON 6 0 98 CHAPTER 6 SPECIAL ROUTINES FOR TYPICAL SUPPLY PROCEDURES Herror CIPUserSelect Hproc handle proc handle 1 Hrlregion Hrlregion _ new double length Hcpar min INT4_8 25 HGetSPar proc handle 1 FLOAT PAR amp min 1 get min length HAllReg proc handle amp region i all regions HCkP HRLContLength proc_handle region amp length length if length gt min par f length o k HDupObj proc handle i duplicate object return H MSG TRUE Figure 6 11 A typical application of HDupObj Duplicate input regions that fulfill a specific criteria length of contour HALCON Extension Package Interfa
150. ng If the input data contains any composed objects e g image tuples the supply procedure has to extract the single parts An object key can represent an unlimited number of iconic objects and every image object may consist of several components one region and an unlimited num ber of gray value channels see also Fig 5 2 on page 61 Generally a user may assume that a HALCON operator is able to handle single iconic objects as well as composed objects i e multivalue optional is set see page 29 and that it can work on multi channel images i e multichannel optional is set see page 34 So the author of a new HALCON oper ator should implement appropriate mechanisms for extracting the needed data from composed The HALCON version that allows the usage of HALCON operators within C programs HALCON Extension Package Interface 2000 11 16 1 1 HALCON OPERATORS 3 objects or multi channel images within the supply procedure The name of this procedure designates the internal C procedure name specified in the def 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 re ceives only the already extracted single components e g regions of type Hrlregion channels of type Himage or pointers to the raw image data and parameter values The results are re turned to the supply pro
151. ns all the result values of the channel parallelization concatenation e domain add overall result value is the sum of the single result values of the paralleliza tion on domain level e domain min overall result value is the minimum of the single result values of the paral lelization on domain level e domain max overall result value is the maximum of the single result values of the paral lelization on domain level HALCON Extension Package Interface 2000 11 16 2 3 DESCRIBING THE PARAMETERS 31 e domain concat overall result value is a tuple which contains all the result values of the parallelization on domain level concatenation The example below shows the definition of postprocessing for the operator circularity which calculates the shape factor for the circularity similarity to a circle of input regions If circularity is tuple parallelized the overall result is a tuple of values of which the single elements contain the circularity of the single input regions Thus the postprocessing of the corresponding output control parameter is assigned by tuple concat parameter Circularity output control description english Roundness of the input region s sem type real type list real default type real multivalue optional assertion lt Circularity amp amp Circularity lt 1 0 postprocessing tuple concat Note that the slot postprocessing must be filled in for every output co
152. ntrol Parameters This chapters contains a set of routines to facilitate the programming of the operator inter face and accessing the basic HALCON data structures Special Routines for Typical Supply Procedures This chapter describes a set of convenience routines for standard situations Creating a New HALCON Package The last chapter explains how to use the HALCON compiler hcomp to generate HALCON packages for different architectures Release Notes Please note the latest updates of this manual e 5 Edition HALCON 6 0 October 2000 The name C Interface has been changed to Extension Package Interface in order to prevent its confusion with the programming language interfaces of HALCON The struc ture of the manual has been revised Sections concerned with creating and installing ex tension packages were updated In the chapter Operator Description the new entries used by Parallel HALCON have been added Furthermore the introduction of Parallel HALCON caused changes and extensions concerning data types routines and macros in the corresponding chapters e 4 Edition HALCON 5 2 March 1999 e 3 Edition HALCON 5 1 March 1998 The chapter About This Manual has been introduced A complete revision of the manual has been done Chapter 1 The Structure of HALCON Packages the Extension Pack age Interface has been extended by section 1 3 Installing a Package The handling of XLD structures has been included
153. ntrol parameter if the operator should be automatically parallelized i e if the operator s slot method does not contain none see page 23 2 3 7 description description english DITEX Ascii Text This slot contains a short description of the parameter The extension english refers to a English description In addition to that a German description might be given in description german For the syntax of DTEX Ascii Text see section 2 4 2 3 8 type list The slot type list is only used in connection with object parameters with sem type image and for control parameters For images sem type image type_list any byte int1 int2 int4 real cyclic direction complex For images this slot contains an enumeration of all supported pixel types Note that in many cases there will be more than one supported pixel type Thus type_list is a list separated by commas For control parameters type_list integer real string 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 value Default Value This slot defines the default value e g used by HDevelop to initialize the paramater in the opera tor window Suggesting default values can help the programmer to find suitable values of param eters Generally strings are unquoted in the description not theString but theString exceptions em
154. o do not pass pointers to variables but the variables itself to the macro Note that the Hcpar arrays Row and 1 are allocated with a fixed size on the stack using _0 PER PAR This define equals the maximum allowed number of objects per input object parameter of a HALCON operator Keep in mind that this number is quite large 100 000 in the current version Thus it might be better to allocate the arrays dynamically using HAllocTmp see section 3 2 1 with only as much elements as needed see HReadGVA on page 61 6 1 2 HAllSegm HA11Segm see Fig 6 1 extends HA11Reg Not only the region but also all gray value chan HALCON 6 0 90 CHAPTER 6 SPECIAL ROUTINES FOR TYPICAL SUPPLY PROCEDURES HUserExport Herror CIPCenter Hproc handle proc handle 1 Hcpar Row 0BJ PER PAR Co1 MAX OBJ PER PAR double row col INTA 8 area INT4_8 SER Hrlregion region get the regions of all input objects in the first param HAllReg proc_handle amp region i HCkP HRLArea proc_handle region amp area amp row amp col Row i 1 type FLOAT_PAR par type is float Row i 1 par f row resulting row Col i 1 type FLOAT PAR par type is float Col i 1 par f col resulting column HPutCPar proc_handle 1 Row i return result HPutCPar proc_handle 2 Col i return result return H_MSG_TRUE Figure 6 2 An application of HA11Reg Compute the center
155. ock with modified size while preserving the data of the original memory block The latter is deallocated So never try to access pointer subsequent to HReallocLocal use new pointer exclusively The convenience routines HAllocRLLocal HAllocRLNumLocal HReallocRLNumLocal and HFreeRLLocal are used for handling temporary region data based on HAllocLocal Oth erwise their behaviour is similar to HAllocRLTmp etc see above However note that it is possible to change the size of regions i e the number of chords using this set of routines HReallocRLNumLocal since the underlying memory blocks are not allocated within the in ternal stacks HALCON Extension Package Interface 2000 11 16 3 2 Names 41 HAllocLocal HReallocLocal HFreeLocal HFreeAllLocal HAllocRLLocal HAllocRLNumLocal HReallocRLNumLocal HFreeRLLocal Synopsis include Halcon h Herror HAllocLocal Herror HReallocLocal Herror HFreeLocal Herror HFreeAllLocal Herror HAllocRLLocal Herror HAllocRLNumLocal Herror HReallocRLNumLocal Herror HFreeRLLocal Hproc_handle size_t void Hproc_handle void size_t void Hproc_handle void Hproc_handle Hproc_handle Hrlregion Hproc_handle Hrlregion size_t Hproc_handle Hrlregion size_t Hrlregion Hproc_handle Hrlregion proc handle size pointer proc handle pointer size new pointer proc_handle pointer
156. of halcon 1ib e Creating the C interface DLL packagec d11 and the library packagec lib To create the libraries packagec d11 and packagec lib which provide the C inter face to new HALCON operators the object file HCpackage obj the new operator li brary package lib HALCON C library halconc lib and the HALCON library halcon lib must be linked To create the libraries parpackagec d11 and parpackagec 1ib for Parallel HALCON the corresponding object file compiled with the define DH PARALLEL must be linked to the Parallel HALCON version of the libraries i e parpackage lib parhalconc lib and parhalcon lib e Creating the C interface DLL packagecpp d11 and the library packagecpp 1lib To create the DLL packagecpp d11 providing the interface to new HALCON oper ators and the corresponding library packagecpp lib the object files HOPPpackage obj and HCPPpackageGlobal obj the new operator lib package 1lib the HALCON C library halconcpp 1lib and the HALCON library halcon 1ib must be linked To create the libraries parpackagecpp d11 and parpackagecpp 1ib for Parallel HAL CON the corresponding object files compiled with the define DH PARALLEL must be linked to the Parallel HALCON version of the libraries i e parpackage 1lib parhalconcpp lib and parhalcon lib HALCON Extension Package Interface 2000 11 16 7 2 GENERATING HALCON PACKAGES 105 Creating new applications In order to create new application pr
157. of the text Backslash backslashes X within the text are ignored while generating the ASCII version So the IXTEX linefeed symbol can be used without any problems Tilde To use the tilde e g as symbol for negation set_check clear the follow ing special notation must be used for the ITEX text set check V clear Formulas Short formulas can be bracketed by dollar symbols just as in BIEX These symbols are ignored for the ASCII version of the text To set an index of one character e g BIEX allows to simply write A_b This is not possible here because of the special underscore handling Therefore any index must be written exactly as any longer index within MITEX A bj HALCON The string HALCON is generated by Halcon Note that in the PostScript files derived from the generated IZTEX version of the def files no space is generated after the string HALCON Thus if you do not want to start the next character string without a blank that is concatenated to the string HALCON you should use 1 instead So Halcon XYZ results in HALCON XYZ and 1 XYZ results in HALCON XYZ With the ASCII version all backslashes are ignored see above Names of parameters and operators Any reference to HALCON parameters operators has to be written as ParRef parametername respectively as OpRef operator name These keywords and the brackets are ignored
158. ograms written in C or you must link packagec lib or packagecpp lib to your objects Furthermore you will need halconc lib or halconcpp lib as for any HALCON application To create a Parallel HALCON version of your application just link the object files to the Parallel HALCON version of the libraries e g 11 and parhalconc lib in case of a C application You can use the same object files as for creating the standard HALCON application To be able to link the package DLL to your application program the complete DLL file path of the new package e g AHALCONROOTA V examples Vextension packageMalconuserVbinM1586 nt4 has to be added to the environment variable PATH Do not copy a package DLL into the Windows system directories as it would be loaded twice in this case If you encounter program crashes check the stack size allocated by your application A stack size of 6 8 MB is recommended The directory 4HALCONROOT V examples Vextension package Mhalconuser contains two ex ample makefiles makefile nt creates the example package halconuser both for standard HALCON and for Parallel HALCON makefile testprog nt creates the example applica tions based on the package halconuser again for both HALCON versions You start the making process by calling nmake f makefile nt and nmake f makefile testprog nt Both makefiles include the file nake 1586 nt4 which sets architecture dependent variables 7
159. omputes a new input region region by intersecting the areas of definition of both input images Note that memory for this region must have been allocated before e g with HAllocRLTmp Furthermore region must be deallocated at the end of the supply procedure HFreeRLTmp Output image objects are created and returned in the first output object parameter in the same way as decribed for HA11Filter in section 6 1 3 Fig 6 7 shows a typical application of HA11Filter2 the implementation of an operator that adds the gray values of two input images As in procedure IPScaleNew in Fig 6 5 the macros HDFImage and HImageFD are used to read and write pixel values In this example that exhibits the additional advantage that the operator can even add the gray values of two images with different pixel types HALCON Extension Package Interface 2000 11 16 6 2 OBJECT GENERATION 95 Herror IPAddNew Hproc handle proc handle Hrlregion region Himage image in1 image in2 image out INT4_8 i l end double hi h2 for i20 i lt region gt num i end CE region rl i image in width for 1 CB region gt rl i image_in gt width l end 1 HDFImage hi1 image in1 1 HDFImage h2 image in2 1 HImageFD image out h1 h2 1 return H_MSG_OK HUserExport Herror CIPAddNew Hproc handle proc handle 1 1 region Himage image ini image in2 image out INT4_8 at HCkP HAllocRLTmp proc_handle amp
160. on in compute some region transormation transform region in region out HCopy0bj proc handle obj key in par out amp obj key out HPutDRL proc handle obj key out region out amp reg key out Figure 5 20 Create an image object with HCopy0bj and insert a region component and returns the corresponding data base key in the parameter obj key This key can be used to insert the gray value channel now encapsulated in a data base object as a component of an arbitrary number of image objects see HDef0bj in section 5 4 5 The parameter copy FALSE or TRUE specifies whether the pixel data is copied to the HALCON data base or only the address of the data 15 passed to the data base object Fig 5 21 shows a typical example for how to use HPut Image Himage image Hrlregion region Hkey image key obj key processed image data image processed region data region par num 1 HPut Image proc handle amp image TRUE image_key HCr0bj proc_handle par_num amp obj_key HDef0bj proc handle obj key image key IMAGE_INDEX HPutDRL proc handle obj key region amp region key Figure 5 21 Creating a new image object using basic Extension Package Interface routines 5 4 5 HDef0bj HDef0bj see Fig 5 19 reassigns the component comp 0 of an image object given by its data base key comp key A typical application of this routine is shown in Fig 5 21 Image data is stored in a
161. on reg in of the image to be processed is split into two parts reg inner and reg outer Note that both new regions must have been allocated before see section 3 2 1 reg inner is the original region reg in minus the pixels around the image border It contains all pixels within the rectangle specified by the upper left corner r1 c1 and the lower right r1 and r2 denote row coordinates c1 and c2 column coordinates HALCON 6 0 86 CHAPTER 5 HANDLING ICONIC OBJECTS AND CONTROL PARAMETERS corner r2 c2 These coordinates should be selected that way that the filter mask is completely within the image when placed on any pixel inside of the rectangle Thus no border treatment is necessary within reg in reg out is set to all remaining pixels within reg in For those pixels an appropriate and time consuming border treatment has to be done Fig 5 35 shows an application of HRLDecomp Note that the distinction of inner and outer area only refers to the image border but not to the border of the regions specifying the area of definition So it is only ensured that no memory access to positions outside the image matrix can happen but there is no guarantee that all pixel values covered by the filter mask when placed on pixels within reg inner are defined if they do not belong to reg in This means a filter might use undefined gray values along the border of the area of definition of the input images The HALCON user shoul
162. onding hypothetical operator segm has one input object parameter for input images containing at least one channel The def file short version might look like segm lt CIPSegm Image Region The macro HA11Segm used in CIPSegm performs a loop over all image objects within the first input object parameter Image of segm With every pass of the loop it returns the image data of the current input object in the variables region area of definition and image first gray value channel The results of the segmentation new region are stored via the macro HNewRegion see section 6 2 1 page 95 as new objects of the HALCON data base and returned in the first output object parameter Region Note that this simple operator has no control parameters A new region is allocated for the action procedure via HAllocRLTmp see section 3 2 1 before entering the loop This region is used as temporary memory for the computation result and must be deallocated via HFreeRLTmp before exiting the supply procedure 3Remember The sizes must be equal whereas the pixel types of different channels may vary HALCON 6 0 92 CHAPTER 6 SPECIAL ROUTINES FOR TYPICAL SUPPLY PROCEDURES 6 1 3 HAllFilter HAllFilter see Fig 6 1 further extends the loop macros introduced so far For every input image object a new output image object is created and added to the first output object parame ter with e the same number of channels components e the same pixel typ
163. ormally a variable of type Hrlregion is allocated with the procedure HAllocRLTmp or HAllocRLNumTmp see section 3 2 These routines initialize the data especially num max that is needed for tests of overflow When allocating a variable by hand the programmer must provide a suitable initialization by himself herself Whereas all coordinates within runlength codes are stored as row column linear coordinates are used to address HALCON image matrices Thus the macros CB and CE are very helpful especially when processing gray values in linear coordinates along a chord The programs on page 93 and 95 illustrate how to use them Their functionality can be seen in Fig 4 6 The first parameter r1 contains a pointer to the chords as it is used within Hrlregion index specifies the index of the chord to work on and width contains the image width CB returns the linear coordinate of the start point and CE that of the end point of the chord 4 3 XLDs Hcont Hpoly XLDs eXtended Line Descriptions are specific iconic HALCON objects to represent sub pixel accurate contours and polygons The corresponding data types are listed in Fig 4 7 and Fig 4 10 HALCON contours of type Hcont contain an array of subpixel points along a contour A con tour might be classified concerning to topological considerations cont_class Additionally an arbitrary number of additional attributes for each point along the contour can be included attribs e g the
164. ort Error during read from serial port No frame grabber opened Frame grabber Frame grabber Frame grabber possible Frame grabber wrong color depth wrong device determination of video format not no video signal Unknown frame grabber Frame grabber Frame grabber Frame grabber Frame grabber Frame grabber Frame grabber failed grabbing of an image wrong resolution chosen wrong image part chosen wrong pixel ratio chosen handle not valid instance not valid already closed Frame grabber cannot be initialized Frame grabber Frame grabber Frame grabber Frame grabber Frame grabber Frame grabber external triggering not supported wrong camera input line multiplex wrong color space wrong port wrong camera type maximum number of frame grabber classes exceeded Frame grabber Frame grabber Frame grabber Frame grabber Frame grabber Frame grabber Frame grabber Frame grabber Frame grabber Frame grabber device busy asynchronous grab not supported unsupported parameter timeout invalid gain invalid field invalid parameter type invalid parameter value function not supported incompatible interface version Error while closing the image file Error while opening the image file Premature end of the image file File is no PCX File PCX unknown encoding PCX More than 4 image plains PCX Wrong magic in color table PCX Wrong number of bytes in
165. osition row col in the first channel of the input object obj key INT2 inp pars INT4_8 num objs Hkey key INT get number of input object parameters note This number is known in general it is specified by the operator header in the corresponding def file of the operator HReadGV proc handle HGinp obj amp inp pars for p 1 p lt inp_pars get number of input objects per input obj parameter HGet bjNum proc handle p amp num objs for 1 o num objs HGet bj proc handle p o amp key get key of object further processing Figure 5 14 Application of HGetObjNum Get the number of iconic objects of an input object parameter HALCON Extension Package Interface 2000 11 16 5 8 LOOP MACROS FOR ACCESSING SINGLE INPUT OBJECTS 69 5 3 Loop Macros for Accessing Single Input Objects This section describes two macros that ease accessing all iconic objects and image components within an input object parameter see Fig 5 15 Please see also the additional loop macros in section 6 1 that further facilitate programming typical supply procedure Names HA110bj HAllComp Synopsis include Halcon h HA110bj Hproc handle proc handle INT par_num Hkey amp obj key INT4_8 amp index HAllComp Hproc handle proc_handle Hkey obj key Hkey amp image in key Himage amp image in INT4_8 amp index Figure 5 15 Basic loop
166. owledge base of HALCON software agent Unknown communication type Unknown message type for HALCON software agent Error while saving the parallelization knowledge Wrong type of work information Wrong type of application information Wrong type of experience information Unknown name of HALCON software agent Unknown name and communication address of HAL CON software agent cpu representative HALCON software agent not reachable cpu refuses work Description of scheduling resource not found Not accessible function of HALCON software agent Wrong type HALCON scheduling resource Wrong state HALCON scheduling resource Unknown parameter type HALCON scheduling resource Unknown parameter value HALCON scheduling resource Wrong post processing of control parameter Error while trying to get time time query Error while trying to get the number of processors HALCON 6 0 118 H_ERR_TMPFNF H_ERR_PTHRD_CR H_ERR_PTHRD_DT H_ERR_PTHRD_JO H_ERR_PTHRD_MI H_ERR_PTHRD_MD H_ERR_PTHRD_ML H_ERR_PTHRD_MU H_ERR_PTHRD_CS H_ERR_PTHRD_CW H_ERR_PTHRD_CI H_ERR_PTHRD_CD H_ERR_PTHRD_CH H_ERR_DCDG_FLE H_ERR_MSG_PNCI H_ERR_MSG_CSAI H_ERR_MSG_CSNI H_ERR_ROOIMA H_ERR_RIEI H_ERR_EDEF H_ERR_IIEI H_ERR_FLTS H_ERR_LLTB H_ERR_UENOI H_ERR_HTS H_ERR_WTS H_ERR_CHSEG H_ERR_RLSEG1 H_ERR_WGAUSSM H_ERR_FSEIS H_ERR_ROWTB H_ERR_ROWTS H_ERR_COLTB H_ERR_COLTS H_ERR_WRTHR H_ERR_UNKF H_ERR_UNKG H_ERR_EINCC H_ERR_EINCP1 H_ERR_EINCP2 H
167. platform not authorized by license runnign on plat form not included in PLATFORMS list License server busy the request should be retried This is a rare occourence could not find license dat Invalid license file syntax Cannot connect to a license server No TCP license service exists No socket connection to license manager server Invalid host Feature has expired Invalid date format in license file Invalid returned data from license server Cannot find SERVER hostname in network database Cannot read data from license server Cannot write data to license server Error in select system call Feature checkin failure detected at license Users are queued for this feature License server does not support this version of this feature Request for more licenses than this feature supports Cannot read dev kmem Cannot read vmunix HALCON 6 0 116 H ERR FLEX LM CANTFINDETHER H ERR FLEX LM NOREADLIC H ERR FLEX LM TOOEARLY H ERR FLEX LM NOSUCHATTR HERR FLEX LM CLOCKBAD H ERR FLEX LM FEATCORRUPT H ERR FLEX LM BADFEATPARAM H ERR FLEX LM FEATEXCLUDE H ERR FLEX LM FEATNOTINCLUDE H ERR FLEX LM NEVERCHECKOUT H ERR FLEX LM BADKEYDATA H ERR FLEX LM NOCLOCKCHECK H ERR FLEX LM DATE TOOBIG H ERR FLEX LM NOFLEXLMINIT H ERR FLEX LM NOSERVRESP H ERR FLEX LM CHECKOUTFILTERED H ERR FLEX LM NOFEATSET H ERR FLEX LM BADFEATSET H ERR FLEX LM CANTCOMPUTEFEATSET H ERR FLEX LM S
168. ple in Fig 6 4 on page 91 6 2 2 HPutRect HPutRect see Fig 6 8 inserts a rectangular region in an already existing output object with data base key key Mostly it is used in connection with operators that create new image objects like in the example in Fig 6 10 HUserExport Herror CIO0GrabImage Hproc handle proc handle Hkey obj key image key Himage image HCr bj proc handle 1 amp obj key HCkP HNewImage proc handle amp image BYTE IMAGE 640 480 grab an NTSC image 640 x 480 pixel 8 bit HCkP IOBGrabImage amp image HPutDImage proc handle obj key 1 amp image FALSE amp image key HPutRect proc id obj key image width image height return H MSG TRUE Figure 6 10 A typical application of HPutRect Grabbing an image Note that HCrObj see section 5 4 1 creates an object with empty region In many situations the default area of definition for a new image will be the full image domain which is a rectangle In this situation the use of HPutRect is very convenient 6 2 3 HbupObj HDupObj see Fig 6 8 is a combination simplification of HGetObj see section 5 1 1 and HCopyObj see section 5 4 2 It duplicates iconic input objects images regions XLD in order to pass them directly to the first output object parameter The objects to be duplicated are specified by their index obj index within the first input object parameter Note that this index corresponds to obj index as defi
169. proc handle proc handle proc handle region len proc handle region len new region proc handle region Figure 3 2 Temporary data on arbitrary heap positions HALCON 6 0 42 CHAPTER 3 STYLE GUIDE FOR PROGRAMMING 3 2 2 Permanent Data The HALCON Extension Package Interface also provides routines for permanently allocat ing deallocating memory see Fig 3 3 and 3 4 They work similar to the standard C procedures malloc and free but use a caching mechanism for small data blocks and provide additional debugging information Note that in contrast to HAllocLocal memory allocated by HA11oc is not deallocated auto matically after the execution of a HALCON operator Thus this routine should be used to allocate permanent data For example all the iconic objects stored in the HALCON data base are allocated with this routine see chapter 5 and 6 HNewImage allocates raw image data inside the data structure Himage see section 4 1 based on HAlloc Furthermore image is initialized and the timestamp is set to the current time The image matrix itself is initialized with 0 if init new image has been set to true using the HALCON operator set system This flag can be read inside HALCON using the Extension Package Interface call HReadGV proc handle HGInitNewImage amp init new img with init new img of type HBOOL and set HWriteGV proc handle HGInitNewImage TRUE FALSE Thus
170. ption file is not possible Specified flag for degree of freedom not valid HALCON 6 0 130 H ERR CAL NOMER H ERR CAL WPTYP H ERR CAL WIMSZ H_ERR_NOAP H_ERR_WPFV H_ERR_MATCH_MODE H_ERR_MATCH_OOR H_ERR_MATCH_BORDER H_ERR_NOTAP H_ERR_NTPTS H_ERR_MEASURE_NA H_ERR_MEASURE_NI H_ERR_MEASURE_OOR H_ERR_MEASURE_IS H_ERR_MEASURE_WS H_ERR_DLOPEN H_ERR_DLCLOSE H_ERR_DLLOOKUP H_ERR_BAR_UNKNOWN H_ERR_BAR_WNOM H_ERR_BAR_WNOE H_ERR_BAR_UNCHAR H_ERR_BAR_WRONGDESCR H_ERR_BAR_EL_LENGTH H_ERR_BAR_NO_REG H_ERR_BAR_UNCHARO1 H_ERR_BAR_UNCHARO2 H_ERR_BAR_UNCHARO3 H_ERR_BAR_UNCHARO4 H_ERR_BAR_UNCHARO5 H_ERR_BAR_UNCHARO6 H_ERR_BAR_UNCHARO7 H_ERR_BAR_UNCHARO8 H_ERR_BAR_UNCHAROQ H_ERR_BAR_UNCHAR10 H_ERR_BAR_UNCHAR11 H_ERR_BAR_UNCHAR12 H_ERR_BAR_UNCHAR13 H_ERR_BAR_UNCHAR14 H_ERR_BAR_UNCHAR15 H_ERR_BAR_UNCHAR16 H_ERR_BAR_UNCHAR17 H_ERR_BAR_UNCHAR18 H_ERR_BAR_UNCHAR19 H_ERR_BAR_UNCHAR20 H_ERR_BAR2D_UNKNOWN_TYPE 8426 8427 8428 8500 8501 8502 8503 8504 8505 8510 8550 8551 8552 8553 8554 8600 8601 8602 8700 8701 8702 8703 8705 8706 8707 8720 8721 8722 8723 8724 8725 8726 8727 8728 8729 8730 8731 8732 8733 8734 8735 8736 8737 8738 8739 8800 APPENDIX A HALCON ERROR CODES Minimum error did not fall below Wrong type in Pose rotation translation Image size does not match the measurement in camera parameters Not a pattern file wrong pattern file version Error during changing the
171. pty string and strings with special characters the string 2 3 10 values values List of some typical values This slot contains a collection of possible values This list does not have to be complete It just suggests some typical values the user might want to try 2 3 11 value list value list List of all values This slot contains a complete list of all allowed values So if a parameter can hold only a discrete number of specific values value list should be specified otherwise values might be used to provide some typical values 2 3 12 value min value max value min Number value max Number Instead 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 value min specifies the minimum of the allowed values value max the maximum 2 3 13 step rec step min value function Step rec Number Step min Number value function lin log quad If a range of values is possible for a parameter it might be a useful information to specify a suitable step width step rec between distinct values to be tested Based on this information a user interface might generate a list of suggestions for parameter values The corresponding minimum reasonable step width can be provided by step min The step width can also be modified by specifying a function in the slot value function HALCON Extension Package Interface 2000 11 16
172. rary with the 1d option o To create the library libparpackage so for Parallel HALCON the corresponding object files compiled with the define DH PARALLEL must be linked Creating the C interface library libpackagec so To create the C interface library libpackagec so providing the interface to new HALCON operators the object file HCpackage o and the new operator library libpackage so must be linked To create the library libparpackagec so for Parallel HALCON the corresponding ob ject file compiled with the define DH PARALLEL must be linked to the Parallel HALCON version of the operator library i e libparpackage so Creating the C interface library libpackagecpp so To create the C interface library libpackagecpp so providing the interface to new HALCON operators the object files HCPPpackage o and HCPPpackageGlobal o and the new operator lib 1ibpackage so must be linked To create the library libparpackagecpp so for Parallel HALCON the corresponding object files compiled with the define DH PARALLEL must be linked to the Parallel HAL CON version of the operator library i e libparpackage so Creating new applications In order to create new application programs written in C or you must link libpackage so and libpackagec so or libpackagecpp so to your objects besides libhalcon so and libhalconc so or libhalconcpp so as for any HALCON applica tion Furthermore you must add the package library subdirectory
173. rator needs no completely exclusive processing optimistic assumption process mutual true false This subslot of parallelization assigns whether Parallel HALCON processes an op erator under mutual exclusion true against itself or not Here a mutual exclusion means that the same operator may not run twice or more at the same time for example there will only run one instance of adapt template at a time whereas other operators may run concurrently to adapt template An exclusively processed operator is always processed without any parallelization by the main HALCON thread process If no subslot process mutual is filled in with an operator it is assumed that the operator needs no mutual exclusion optimistic assumption process locally true false This subslot of parallelization assigns whether an operator must be processed locally HALCON 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 without problems The slot is mainly important when programming multithreaded applications under Windows NT and Windows 2000 Here there exists a direct mapping between program threads and graphical elements such as windows dialog boxes or button con trols In short a graphical element only exists in the context of its associated thread This can cause severe problems for example hang the application if ano
174. rators they can be used within all supported host languages and the interactive tool HDevelop This chapter gives a short introduction to HALCON packages and operators in cluding an example describing the integration of a simple operator The follow ing chapters present detailed information that will allow you to write your own pack ages As a common example a package called halconuser will be used see AHALCONROOT A examples extension package Mhalconuser on HALCON CD Except of UNIX specific sections in this manual file paths and environment variables are printed in the Windows NT 2000 convention e g AHALCONROOTA V examples extension packageMhalconuser leXtended Line Description i e subpixel contours and polygons 2 CHAPTER 1 INTRODUCTION to denote the subdirectory halconuser containing an example package within the HALCON base directory referenced by the environment variable HALCONROOT The same expression in UNIX convention would look like HALCONROOT examples extension package halconuser 1 1 HALCON Operators This section describes the external interface of HALCON operators i e how to use them in a programming language and their internal structure 1 1 1 Using HALCON Operators in C and There are two different modes of calling operators from HALCON C One way is to call oper ators for simple applications with only one value per control parameter simple mode This is the easiest way and sufficient
175. rce positions are linearly dependent No sufficient image indication Internal error Function has equal signs in HZBrent Kalman Dimension n m or p has got a undefined value Kalman File does not exist Kalman Error in file row of dimension Kalman Error in file row of marking Kalman Error in file value is no float Kalman Matrix A is missing in file Kalman Matrix C is missing in file Kalman Matrix Q is missing in file Kalman Matrix R is missing in file Kalman G or u is missing in file Kalman Covariant matrix is not symmetric Kalman Equation system is singular Image data management object is a object tupel Image data management object has been deleted already Image data management wrong object ID Image data management object tupel has been deleted already Image data management wrong object tupel ID Image data management object tupel is a object Image data management object ID is NULL 0 Image data management object ID outside the valid range Image data management access to deleted image Image data management access to image with wrong key Image data management access to deleted region Image data management access to region with wrong key Image data management wrong value for image channel Image data management index too big Image data management index not defined internal error image data management wrong clear type Wrong logical window number Error while opening the window Wrong w
176. read a short int long value in parameter number 1 HGetSPar proc_handle 1 LONG_PAR amp par1 1 now 1 1 read a string in parameter number 2 proc handle 2 STRING PAR amp par2 1 now par2 par s Text read tuple of 3 float values in parameter number 3 HGetSPar proc handle 3 FLOAT PAR par3 3 for i20 i num i 1 par3 i par f 0 5 1 7 4 4 Figure 5 28 Read the control parameter values of the operator call demo 5 Text 0 5 1 7 4 4 using HGetSPar parameter number par_num 1 7 This makes it possible to allocate exactly as much memory for parameter values as needed for reading them for example via HGetSPar note that there is an alternative routine HGetPPar which needs no memory to be allocated 5 5 4 HGetPPar HGetPPar see Fig 5 26 returns the pointer to an array of Hcpar structures which contain the HALCON Extension Package Interface 2000 11 16 5 5 READING AND WRITING CONTROL PARAMETERS 81 Hcpar pari par2 Hcpar par3 INT4_8 num allocate memory for strings HAllocStringMem proc_handle 1000 read a short int long value in parameter number 1 HGetSPar proc_handle 1 LONG_PAR amp par1 1 now 1 1 read a string in parameter number 2 HGetSPar proc_handle 2 STRING_PAR amp par2 1 now par2 par s Text read tuple of float values in parameter number 3
177. reading the number of objects of an input object parameter which does not need the HReadGVA routine namely HGet0bjNum see page 67 Note that a loop over all objects passed to an operator within an input object parameter is a very common task Therefore HALCON provides a macro for this problem See HA110bj on page 69 5 1 2 HGetComp HGetComp see Fig 5 1 returns the data base key of a component image matrix image key or region region key of an image object that is stored under the key obj key in the HALCON data base INT2 obj_channels Hkey obj key Hkey region key Hkey image key get key of object HGet0bj proc handle p o amp obj key get key of region HGet Comp proc handle obj key REGION amp region key get number of channels HCkP HPNum0f Channels proc handle p o amp obj channels for i 1 i obj channels i get image matrix key HGetComp proc handle obj key i amp image key further processing Figure 5 4 Example for HGetComp Data base keys of all regions and channels within an input image object components of an object are consecutively numbered from 0 to n with 0 denoting the region and 1 denoting the channels image matrices To get a better legibility of program code the constants REGION 0 IMAGE_INDEX 1 IMAGE1 1 IMAGE2 2 etc have been defined globally and may be used as parameter values The number of channels p
178. rom the package halconuser the corresponding user extension libraries must have been created This can be done via the makefile in AHALCONROOT Nexamples V extension packageMhalconuser which will also generate the needed user extension library halconusercpp Please note that on some systems not all users have writing permissions in the directories mentioned above experiment with the example package we recommend to create a private copy in your working directory In such a case you must of course use the actual path to your copy when modifying environment variables 1 5 Additional Sources of Information For further information you may consult the following manuals e Getting Started with HALCON An introduction to HALCON in general including how to install and configure HALCON e HDevelop User s Manual An introduction to the graphical development environment of the HALCON system e HALCON C User s Manual How to use the HALCON library in your programs e HALCON C User s Manual How to use the HALCON library in your C programs e HALCON COM User s Manual How to use the HALCON library in your COM programs e g in Visual Basic e Frame Grabber Integration Programmer s Manual A guide on how to integrate a new frame grabber in the HALCON system Note that in some cases you might define new operators using the Extension Package Interface instead of using the standard HALCON Frame Grabber Integration Interface in ord
179. s They aim on portable code that should be easy to understand for other HALCON programmers One of the major topics is the memory management discussed in section 3 2 3 1 Basic Numeric Data Types This section describes the usage of basic numeric data types Since C makes no assumption about the size of integers the following types have been defined INT UTI INT UE nma ONT 8 INT onm Using these types ensures the portability of HALCON operators 3 1 1 Local Variables Temporary Results Types and sizes for local variables no arrays should be handled as follows 37 38 CHAPTER 3 STYLE GUIDE FOR PROGRAMMING CData Type Integer 3 byte INT4_8 or UINT4_8 4 byte Floating point Number 3 1 2 Procedure Parameters Parameters of procedures should be of the following types within HALCON Data Type Integer 3 byt INTA 8 Floating point Number 3 1 3 Arrays For arrays or structures i e larger sets always the smallest possible data type should be used CData Type 1 byte INT1 2 byte INT2 oder UINT2 Integer i Y INT4 oder UINT4 byte Floating point Number 3 2 Memory Management HALCON provides a sophisticated memory management not only to handle iconic objects but also to allocate deallocate arbitrary data Please use the corresponding HALCON Exten sion Package Interface routines exclusively Do not create destroy memory blocks on the heap with th
180. s containing all kind of 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 object keys The Extension Package Interface provides special procedures and macros for reading and writing elements of the parameter buffer within the supply procedure Every parameter belongs to one of the four classes HALCON 6 0 4 CHAPTER 1 INTRODUCTION e input object e output object e input control e output control that determines the name of the suitable procedures macros e g HGetCPar is used to get an input control value To identify a specific parameter within a class its number is passed to the procedure macro This is the number of the parameter within the parameter list of a HALCON operator counted for every parameter class e g to get the value of the second input control parameter the number 2 must be passed to HGetCPar The read write access on the buffer is done automatically by the generated interface The code of this interface is generated by the HALCON compiler hcomp see page 11 and section 7 1 from a so called definition file def file Any programmer of a new HALCON operator must provide such a definition file which contains all relevant information e g concerning in and output parameters information
181. s in one or more def file s cf chapter 2 2 Creation of a library called package containing the supply procedures in C and the corresponding action procedures cf chapter 3 6 This library has to be placed in the package subdirectory lib or 1ib ARCHITECTURE 3 Creation of a library containing the language dependent operator interface packagec and packagecpp based on the def file s with the help of hcomp cf section 7 1 These libraries have to be placed in the subdirectory lib or 1ib ARCHITECTURE of the package 4 Generation of files for online access to the knowledge base with the help of hcomp These files are used e g by HDevelop They have to be placed in the subdirectory help of the package 5 Generating the HTML reference files with the help of hcomp optional The generated files have to be placed in the subdirectory doc htm1 reference hdevelop c or cpp of the package In the Windows NT 2000 version the DLLs corresponding to the link libraries have to to be placed in bin or bin ARCHITECTURE HALCON Extension Package Interface 2000 11 16 1 3 INSTALLING HALCON PACKAGE 7 6 Generating PostScript manuals with the help of hcomp optional 7 Extension of the package list in the environment variable HALCONEXTENSIONS by the complete file path of the new package e g AHALCONROOT V examples Vextension package Mhalconuser For specific architectures additional environment variables have to
182. se of empty iconic input parameters Note that in this case all output parameters are also empty We recommend to call HCkNoObj proc handle at the beginning of the supply procedure for every operator with iconic input objects to guaran tee the existence of iconic data to be processed within the operator 5 6 3 HRLDecomp HRLDecomp see Fig 5 33 is an auxiliary procedure to ease border treatment within the action procedures of filter operators based on filter masks It s prototype is included in hlib HRLClip h Herror IPBFilter Hproc handle proc handle proc handle HBYTE in input image Hrlregion region area of def INT width height image size HBYTE out output image Hrlregion inner outer HCkP HA1locRLNumTmp proc_handle amp inner region gt num HCkP HA1locRLNumTmp proc handle amp outer region num 2 HCkP HRLDecomp proc handle region 1 1 height 2 width 2 amp inner amp outer filtering without border treatment for i20 i lt inner gt num i for k CB inner gt rl i width k lt CE inner gt rl i width k out k filtering with border treatment for i 0 i lt outer gt num i for k CB outer gt rl i width k lt CE outer gt rl i width k out k HCkP HFreeRLTmp proc handle outer HCkP HFreeRLTmp proc handle inner Figure 5 35 Border treatment for a 3 x 3 filter The region respectively area of definiti
183. sentation Internal error border point is set to FG Internal error maximum contour length exceeded Internal error maximum number of contours exceeded Contour too short for fetch_angle_xld Regression parameters of contours already computed Regression parameters of contours not yet entered Please compute them by calling regress_cont_xld Data base XLD object has been deleted Data base object has no XLD ID Internal error wrong number of contour points allocated Contour attribute not defined HALCON 6 0 120 H ERR FIT ELLIPSE H ERR FIT CIRCLE H ERR NWF H ERR NAIGF H ERR XLD ISOL POINT H_ERR_SESF H_ERR_TMFE H_ERR_OPSF H_ERR_TMSS H_ERR_WSKEY H_ERR_TMSAM H_ERR_TMCLS H_ERR_TMBOX H_ERR_OPCF H_ERR_SCLA H_ERR_OPF H_ERR_CLEX H_ERR_TMCLA H_ERR_CNTL H_ERR_CLNNF H_ERR_NCCLA H_ERR_CLASS2_ID H_ERR_CLASS2_VERS H_ERR_ROTNR H_ERR_GOL H_ERR_BEZ H_ERR_ITER H_ERR_MOSYS H_ERR_ART H_ERR_OBJI H_ERR_OBJO H_ERR_PARI H_ERR_PARO H_ERR_SELC H_ERR_WRNSE H_ERR_WRRLN1 H_ERR_WRRLL H_ERR_RLLTB H_ERR_RLLTS H_ERR_RLCTB H_ERR_RLCTS H_ERR_CHLTB H_ERR_CHLTS H_ERR_CHCTB H_ERR_MRLE 3262 3263 3275 3276 3290 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3500 3502 3503 3504 3505 3506 3507 3508 3509 3510 APPENDIX A HALCON ERROR CODES Ellipse fitting failed Circle fitt
184. st the following features beside the operator name in a def file e the name of the operator as used within the application programming language e the name of the C procedure supply procedure called by HALCON in order to start the processing this procedure must be implemented later on e all iconic objects and control parameters that are needed by the operator as input input parameters e all iconic objects and control parameters that are returned by the operator as result output parameters e the types of these parameters e the number of values per parameter there is only a distinction between parameters that need 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 parameters containing any other data so called control parameters By distinguishing input and output parameters we get four classes of parameters Input iconic object parameters output iconic object parameters input control parameters and output control parameters Basically speci fying the number of parameters per class would suffice to describe the operator The internal access in particular within the supply procedure on individual parameters works this way by using the parameter s position within its class But to refer to single parameters and add further information regarding a parameter it is useful to give it a name 15 16 CHAPTER 2 OPERATOR DES
185. t two routines one procedure supply procedure receives unpacks all input data and checks it s consistency Afterwards it calls the action procedure that performs the image processing In some cases it might be convenient to implement several action procedures dependent on special parameter values or pixel types of image data Generally these steps are performed within a loop over all input objects that may include further loops over different parameter values and over all image channels The results are collected and finally returned to the HALCON interface to the application HALCON 6 0 46 CHAPTER 3 STYLE GUIDE FOR PROGRAMMING Supply procedures are of type Herror and have only one parameter a handle of type Hproc handle for instances of HALCON operators HALCON threads Do not forget to return an appropriate value at the end of every supply procedure standard value H M G TRUE and every action procedure standard value H MSG OK Typically action procedures perform the image processing itself They should return an error code of type Herror as well It is convenient to implement an action procedure for each pixel type of image data 3 4 Name Conventions for Procedures To ease the interpretation of program code HALCON introduces some conventions for proce dure names The most important ones are summarized in the following section The names of action procedures typically begin with IP image processing procedure
186. ten with new values in contrast to HGetImage and HGetFDRL cf section 5 1 4 and 5 2 2 However this means that enough memory for region must be allocated before calling HGetRL see section 3 2 1 Fig 5 6 and 5 7 show exemplary applications of HGetRL 5 1 4 HGetImage HGet Image see Fig 5 1 reads the image data type Himage see section 4 1 of a specific gray value component channel of an image object referenced by its key in the HALCON data base The data structure Himage contains the gray values the gray value type and the size of the image matrix Instead of copying the image matrix HGetImage only returns a pointer to the HALCON 6 0 64 CHAPTER 5 HANDLING ICONIC OBJECTS AND CONTROL PARAMETERS Hkey obj key Hkey image key Hkey region key Himage image Hrlregion HGetComp proc handle obj key IMAGE INDEX amp image key HGetComp proc handle obj key REGION amp region key HGet Image proc handle image key amp image HGetRL proc handle region key region switch image kind case BYTE IMAGE processing in general this should be done calling an action procedure area sum 0 for 0 lt 1 gt for i CB region gt rl c image width i lt CE region gt rl c image width i sum image pixel b il average sum area break default return H ERR WIT wrong image type Figure 5 7 Example for
187. ter A list of all operators within the chapter with links to the corresponding operator description pages files operator html operator htm1 A description page for each operator 7 1 5 Miscellaneous Here are some more options supported by hcomp hcomp i filename def files Consider only the operators listed in filename hcomp x filename def files Do not consider the operators listed in filename hcomp m def files Generate a list of operators within the def files sorted by modules 7 2 Generating HALCON Packages Once the new operators have been described in def file s and implemented supply and action procedures a couple of dynamic objects DLLs in Windows NT an Windows 2000 shared libraries in UNIX environments must be created Never change the name of a package or the corresponding names of the libraries DLLs contained in a package These names are encoded within the libraries If you change the names this information will not match any longer Thus the loader of the operating system will fail to open the dynamic libraries If you want 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 HALCONEXTENSIONS e g AHALCONROOT examples extension package Mhalconuser Please note that the package paths in HALCONEXTENSIONS are separated by semicolons Win dows NT 2000 or colons UNIX see also section 1 3 7 2 4 Creat
188. ter if the operator should be automatically parallelized i e if the operator s slot method does not contain none see page 23 2 3 6 postprocessing postprocessing none tuple_add tuple_min tuple_max tuple_concat channel_add channel_min channel_max channel_concat domain_add domain_min domain_max domain_concat 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 be ing automatically parallelized i e for operators for that the parallelization subslot method does not contain none see page 23 Here postprocessing specifies which kind of post processing is 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 val ues of the parallel processed operator must be put into one output control object again the slot postprocessing should contain the keyword tuple_concat which means concatenate result values Or if an operator is parallelized by splitting the single channels of iconic input objects and the overall result value is the minimum of the single result values of the parallel processed operator postprocessing should contain the keyword channel minimum Obviously the slot postprocessing can contain several strings in order to define different postprocessing steps for different levels of
189. the strings split tuple split channel and split_domain because an operator may be parallelized by using any combination of those three methods However if none is specified with the slot method no other string should be specified with it in order to keep the description consistent If no slot method is filled in with an operator it is assumed that the operator is not suitable for being automatically parallelized pessimistic assumption domain split an unsigned integer value This subslot of parallelization must only be set for operators that are suitable for being parallelized by splitting the domain of iconic input objects i e slot method contains split domain For such operators the value of domain split assigns whether the input domain may be split disjunctively value 0 or not In the latter case the domain is split into several overlapping stripes note that the splitting of domain regions is always done row wise If the domain is split disjunctively the value gt 0 of domain split assigns the in dex 1 n of that input control parameter which determines the extent of the over lapping regions in number of pixels by its content For example for the operator eliminate min max the extent of the overlapping regions depends on the height of the filter mask Therefore the content of the second input control parameter compare the operator s description in the Reference Manuals directly determin
190. them The only exception is again HA11Filter2 that computes the intersection of the region data of both input images and stores it in a new region 6 1 1 HAl1Reg HA11Reg see Fig 6 1 implements a loop over all objects of the first input image object pa rameter For every object within this parameter it returns the region of the object in region All gray value channels are ignored HA11Reg is a combination of HA110bj see section 5 3 1 and HGetFDRL see section 5 2 2 It is typically used within feature extraction operators A list of input regions have to be examined concerning special features Some HALCON operators of this kind are e g circularity area center or contlength Moreover it is possible to return new region s by using the in terface macro HNewRegion see page 95 as it is done e g by select shape or shape trans Fig 6 2 illustrates the application of HA11Reg showing a complete supply procedure for a hypo thetical operator center that computes the center of gravity of all input regions The operator has one input object parameter that exclusively contains regions and two output control param eters for returning the results as tuples of floating point numbers the coordinates of the centers of gravity of all regions The corresponding def file short version might look like center lt CIPCenter Regions Rows F Columns F center may be called with one or more regions as input HA11Reg implements a loop o
191. ther thread tries to perform user interactions via graphical elements which belong to other threads For ex ample troubles might occur under Windows NT 2000 if one thread opens a window via open window and another thread tries to get input from this window via draw circle As it is not always obvious for all operators whether they work with critical graphical elements or not the slot process locally was introduced If process locally is set to true this signals the programmer that the corresponding operator must be used carefully within multithreaded Windows NT 2000 applications The most simple way to avoid any problems with such operators is to process them all under mutual exclusion within the main thread of the program As a side effect Parallel HALCON processes an operator without parallelization regard less the settings of the subslots method and domain split if process locally is set to true This avoids problems with local operators and multithreading and makes sense because local operators normally are responsible for graphical interaction and thus are not suitable for parallelization If no subslot process 1ocally is filled in with an operator it is assumed that the operator must be processed locally pessimistic assumption However this subslot should be filled in in any case because it contains a very useful information for programmers of multithreaded applications method none sp
192. tivalue true Type Unlimited Number Floating point Value The 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 ap plications To achieve this an extended version of the operator description must be generated This is described in the following section 2 2 Extended Operator Description An operator description within a def file must start with a header The following entries are variable in their order of these slots begin with a determined keyword and are finished by a semicolon Semicolons within the text not defining the end of a slot must be quoted with a backslash Some slots are language dependent For example short english contains a short description of the operator in English short german the same description in German The currently sup ported languages are English and German In order to allow an international usage of operators we strongly recommend always to provide all english slots HALCON Extension Package Interface 2000 11 16 2 2 EXTENDED OPERATOR DESCRIPTION 17 Note that all slots specified within the operator description are accessible online within the HALCON system using the operator get operator info see the Reference Manuals for de tails Describing the single parameters completes the operator description Section 2 3 explains how to do this
193. uiring large storage If ParRef Offset is chosen too large gt 60 say it may happen that no points fulfill the threshold condition i e an empty region is returned If ParRef Offset is chosen too small 60 say it may happen that all points fulfill the threshold condition i e a full region is returned 2 2 11 result state The slot result state defines the result value of an operator and the corresponding exception handling The syntactical rules for the text are again the same as described in section 2 4 result state english XOpRef dyn threshold returns TRUE if all parameters are correct The behavior with respect to the input images and output regions can be determined by setting the values of the flags ValRef no_object_result NWalRef empty region result and NWalRef store empty region with OpRef set_system If necessary an exception is raised HALCON 6 0 22 CHAPTER 2 OPERATOR DESCRIPTION DEF FILES 2 2 12 parallelization The slot parallelization contains information about the parallelization characteristics of an operator when used in Parallel HALCON see the manual Getting Started with HALCON for more information about Parallel HALCON On the one hand this regards the possibility of using the operator in a parallel for example multithreaded application and on the other hand this regards the automatic parallelization which Parallel HALCON uses to speed up the operator s processin
194. values of control parameter 13 H ERR WIPN14 1414 Wrong number of values of control parameter 14 H ERR WIPN15 1415 Wrong number of values of control parameter 15 H_ERR_WIPN16 1416 Wrong number of values of control parameter 16 H_ERR_IONTB 1500 Number of input objects too big H ERR WION1 1501 Wrong number of values of object parameter 1 H ERR WION2 1502 Wrong number of values of object parameter 2 H_ERR_WION3 1503 Wrong number of values of object parameter 3 H_ERR_WION4 1504 Wrong number of values of object parameter 4 H_ERR_WION5 1505 Wrong number of values of object parameter 5 H ERR WIONG 1506 Wrong number of values of object parameter 6 H ERR WION7 1507 Wrong number of values of object parameter 7 H ERR WIONS 1508 Wrong number of values of object parameter 8 H ERR WION9 1509 Wrong number of values of object parameter 9 H_ERR_OONTB 1510 Number of output objects too big H_ERR_WNP 2000 Wrong specification of parameter error in file xxx def H ERR HONI 2001 Initialize Halcon re set_obj_db Width Height Components H ERR WRKNN 2002 Used number of symbolic object names too big H ERR NO LICENSE 2003 No license found H ERR NO LS SERVER 2004 Lost connection to license server H ERR NO M DULES 2005 No modules in license VENDOR STRING H ERR NO LIC OPER 2006 No license for this operator H ERR FLEX LM BAD TZ 2007 Time zone offset from GMT is gt 24 hours H ERR FLEX LM BADPLATFO
195. velop Without these files HDevelop cannot retreive the information needed to access the operators of a package We also recommend to provide additional subdirectories e include In this directory the generated include files containing the prototypes for the operators of a package should be placed e doc In this directory the documentation of the package should be placed see also HALCONROOT doc for comparison Especially it is necessary to put the gener ated HTML files in doc html V reference Mhdevelop in order to enjoy the online help from the operator window of HDevelop e examples This directory might contain some typical example programs e g HDevelop dev files demonstrating the use of the new operators e images If the provided examples need specific images they should be placed in this directory In that case we recommend to include the path to this subdirectory in the environment variable HALCONIMAGES in order to allow access to these images without using an absolute file path in the programs 1 2 8 How to Create and Use a HALCON Package In summary the following steps are necessary to create a HALCON package with the name package integrating new operators into the HALCON system As noted in section 1 2 1 to create a Parallel HALCON package you must create a second version of the libraries A de tailed description of the steps can be found in the referenced sections of this manual 1 Description of the new operator
196. ver all of them sets the loop index i to the current index of the region 1 7 and passes a pointer to the region to the action procedure that performs the center of gravity In our case the action procedure is the internal HALCON procedure HRLArea The result values are written into two arrays of the type Hcpar and returned by HPutCPar see section 5 5 5 2 HALCON image objects consist of one region specifying the area of definition and an arbitrary number of gray value channels containing the pixel data HALCON Extension Package Interface 2000 11 16 6 1 LOOP MACROS Names 89 HAllReg HAllSegm HAllFilter HAllFilter2 Synopsis include HA11Reg HA11Segm HA11Filter HA11Filter2 Halcon h Hproc handle Hrlregion INT4_8 Hproc_handle Hrlregion Himage INT INT4_8 Hproc_handle Hrlregion Himage Himage INT INT4_8 Hproc_handle Hrlregion Himage Himage Himage INT INT4_8 proc_handle region amp obj index proc handle region image max channels amp obj index proc handle region image in image out max channels amp obj index proc handle region image_ini image in2 image out max channels amp obj index Figure 6 1 Convenience loop macros to access iconic objects amp denotes output parameters of the macros This is only a special notation to make clear that these parameters are changed by the macros S
197. when generating the ASCII version so that only parametername or operator remains in the ASCII file For the HTML documentation hyper links are generated from these references Parameter values specific value for a parameter should be written as WalRef parameter value For example the parameter ParRef LightDark of the operator OpRef dyn_threshold can hold one of the values NValRef light ValRef dark or ValRef equal The keyword ValRef and the brackets are ignored when generating the ASCII version so that only parameter value remains in the ASCII file Other commands If you would like to use additional command within a text seg ment two versions of this segment must be provided one for ASCII with a signalling HALCON 6 0 36 CHAPTER 2 OPERATOR DESCRIPTION DEF FILES the start of the ASCII section and another as pure IATEX text with 01 starting version and Qe ending the special section This technique is in particular necessary for tables and larger formulas Example Qa g o gt g m ParRef Offset 1 L g o ge g_ m ParRef Offset e This parenthesis can also be used for only one of the two text types text text 01 aSpecialLatexCommand text text HALCON Extension Package Interface 2000 11 16 Chapter 3 Style Guide for Programming The following chapter contains some recommendations for implementing new HALCON op erator
198. y specifying sol a file operator tex is created for every operator Using any of the other specifications the file HReference tex is generated The generated IATEX files use the package halcon reference sty This package resides in the directory HALCONROOT doc macros UNIX notation You must include this directory in the environment variable TEXINPUTS otherwise IATEX will be unable to find it typical error message File halcon_reference sty not found The IATEX file s can be transformed to PostScript files by using latex makeindex and dvips Note that latex must be called several times to get the references right 7 1 4 Creating HTML Files hcomp can also generate HTML files Thus its easy to provide an online documentation of new operators that can be accessed using an HTML browser Use hcomp Lplanguage specification 1language def files to create HTML files things said above about the issues planguage and specification hold also for this section with the exception that sol is not supported The following files are generated HALCON 6 0 102 CHAPTER 7 CREATING A NEW HALCON PACKAGE table of contents html Home page containing the chapter structure and links to the different sub chapters toc chapter subchapter htm1 index by name html Alphabetic list of all operators with links to the correspond ing operator description pages files operator htm1 toc chapter subchapter ntm1 For every sub chap

HALCON Extension Package Programmer`s Manual

Contents

Download Pdf Manuals

Related Search

Related Contents