Home

HALCON/C++ User`s Manual

1. of two images The advantage of the class HByteImage can be seen when accessing each pixel see figure 3 8 The class HPixVal is not necessary in this example Furthermore the member functions GetPixVal and SetPixVal are not used HByteImage allows to access pixel values in a nota tion like in the programming language C The result of the example in figure 3 8 is basically the same as in the example in figure 3 7 The program in figure 3 8 is shorter easy to read and has a better runtime performance 3 1 3 XLD Objects XLD is the abbreviation for eXtended Line Description This is a data structure used for describ ing areas e g arbitrarily sized regions or polygons or any closed or open contour 1 also lines In contrast to regions which represent all areas at pixel precision XLD objects provide subpixel precision There are two basic XLD structures contours and polygons Similarly to images HALCON C provides both a base class HXLD and a set of specialized classes derived from HXLD e g HXLDCont for contours or HXLDPoly for polygons For all classes there exists a corresponding container class e g HXLDArray In contrast to the classes described in the previous sections the XLD classes provide only member functions corresponding to HALCON operators see also section 2 1 2 3 1 4 Low Level Iconic Objects As could be seen in the examples in chapter 2 when calling operators in the procedural ap proach the class
2. oor RET ue Ses Seaweed 24 How to Combine Procedural and Object Oriented Code The HALCON Parameter Classes p IRL DIE uoce dos qus e ere ode comte Me aS o0 TP r See og Mounted eee hee TTET 215 1i ses ted tates eb be gees y BOE UY Sous 3 1 4 Low Level Iconic Objects 32 kontrol ee e ae Le Ge Se DR RS 3 2 1 The Basic Class for Control Parameters TAPER ME 3 2 3 Classes Encapsulating 3 3 Auxillary Classes usu go 39 Rx 3 9 8 9 9 59 x 8 Creating Applications With HALCON C Widows NT 2000 XP lt u eaa osag A Oe OR A OOS qi eg ane EMG sani aiai 97408 ee OE eoru Ses Typical Image Processing Problems 5 1 Thresholding an Image 34 Edge Detection oes cee ee a Pe wed ORE OS x E ad Deo Threshold e scc e om o9 aga gacka mt aca RC a aaa ii 5 4 Texture o2 Eliminating Small Objects s se o se s se ER ERR Ex 5 6 Selecting Oriented Objects 5 7 Smoothing Contours Index 53 Chapter 1 Introducing HALCON C HALCON C is the interface of the image analysis system HALCON to the programming lan guage Together with the HALCON library it allow
3. alpha lt lt 1 lt lt lt lt thresholds i LQ Hobject images image Hobject regions region long num HTuple thresholds gen empty obj amp images for int i 1 i lt 2 i 1 read image amp image HTuple alpha i concat obj images image amp images 1 char_threshold images image amp 2 95 amp thresholds count obj images amp num for int i20 i lt num i i select_obj images amp image i 1 disp_obj image window select_obj regions amp region i 1 disp_obj region window cout lt lt Threshold for alpha lt lt i 1 lt lt lt lt thresholds i LO i Figure 2 7 Using CharThreshold in tuple mode via HImageArray or in the procedural ap proach declaration and opening of window omitted the file name Therefore HALCON C allows to integrate your own error handling How to do this in the object oriented and in the procedural approach is described in the following sections Please note that you cannot mix object oriented and procedural error handling HALCON C 2005 02 01 2 2 ERROR HANDLING 15 class LIntExport HException public HException const HException amp except HException const char f long 1 const char p Herror e const char m HException const char f long 1 const char p const char m HException const char f long 1 const char p Herror static Handler
4. can be applied to all iconic objects in the same manner Three classes are derived from the root class HObject e Class HImage for handling images e Class HRegion for handling regions e Class HXLD for handling polygons These classes are described in more detail below 3 1 14 Regions A region is a set of coordinates in the image plane Such a region does not need to be connected and it may contain holes A region can be larger than the actual image format Regions are represented by the so called runlength coding in HALCON The class HRegion represents a region in HALCON C Besides those operators that can be called via HRegion see also section 2 1 2 HRegion provides the following member functions e HRegion void Default constructor It creates an empty region i e the area of this region is zero Not all operators can handle the empty region as input e g some shape property operators e HRegion const HDChord amp line Constructing a region from a chord A chord is a horizontal line e HRegion const HDPoint2D amp point Constructing a region from a discrete 2 dimensional point 20 CHAPTER 3 THE HALCON PARAMETER CLASSES HRegion const HRectanglei amp rect Constructing a region from a rectangle parallel to the coordinate axis The coordinates do not need to be discrete HRegion const HRectangle2 amp rect Constructing a region from an arbitrarily oriented rectangle The coordinates do not need to be discrete
5. 21 24 dilation_circle DilationCircle 13 20 24 do_ocr_multi DoOcrMulti 40 do_ocv_simple DoOcvSimple 40 domain area of definition 13 26 draw circle DrawCircle 39 draw_ellipse DrawEllipse 39 draw rectanglei DrawRectangle1 39 draw_rectangle2 DrawRectangle2 39 54 dyn threshold DynThreshold 27 eccentricity Eccentricity 22 edges image EdgesImage 50 elliptic_axis EllipticAxis 21 erosion circle ErosionCircle 20 24 fill_up FillUp 22 find 1d bar code FindidBarCode 7 9 40 find 2d bar code Find2dBarCode 40 find shape model FindShapeModel 40 gen 1d bar code descr GenidBarCodeDescr 9 10 17 41 gen_circle GenCircle 10 gen empty obj 12 34 gen imagei GenImage1 9 26 gen imagel extern GenImageiExtern 9 gen image const GenImageConst 9 26 gen rectangle2 GenRectangle2 10 get domain GetDomain 13 get error text l6 get_grayval GetGrayval 27 get_image_pointer1 GetImagePointer1 26 27 get_mbutton GetMbutton 38 get_mposition GetMposition 38 GetHandle 18 41 gnuplot plot funct 1 GnuplotPlotFunctid 40 grab image GrabImage 10 40 HALCON language interfaces HALCON COM 46 handle classes 10 11 40 cast operator 9 18 41 GetHandle 18 41 SetHandle 18 41 handles 6 9 34 window 6 HBarCode1d 8 10 40 41 HBarCode2d 40 HBgEsti 40 HALCON C 2005 02 01 Index HByteImage
6. HRegion const HCircle amp circle Constructing a region from a circle The radius and center do not need to be discrete HRegion const HEllipse amp ellipse Constructing a region from an arbitrarily oriented ellipse The radii and center do not need to be discrete HRegion const char file Constructing a region by reading the representation from file This file can be generated by the member function WriteRegion HRegion const HRegion amp reg Copy constructor HRegion amp operator const HRegion amp reg Assignment operator HRegion void Destructor In contrast to the primitive class Hobject this class handles the release of memory void Display const HWindow amp w const Output of the region in a window HRegion operator double scale const Zooming the region by an arbitrary factor The center of scaling is the origin 0 0 HRegion operator gt gt double radius const HRegion amp operator gt gt double radius Erosion of the region with a circle of radius radius see reference manual entry of erosion circle HRegion operator lt lt double radius const HRegion amp operator lt lt double radius Dilation of the region with a circle of radius radius see reference manual entry dilation_circle HRegion operator const HDPoint2D amp point const HRegion amp operator const HDPoint2D amp point Translating the region by a 2 dimensional point HRegion amp operator void Dilat
7. ReadImage 9 10 16 26 45 read serial ReadSerial 40 reduce domain ReduceDomain 27 region of interest ROI 26 regiongrowing Regiongrowing 39 roberts Roberts 50 robinson_amp RobinsonAmp 50 run bg esti RunBgEsti 40 scale image ScaleImage 27 select obj 12 34 send image SendImage 40 set check 16 set grayval SetGrayval 27 SetHandle 18 41 simple mode 11 Skeleton Skeleton 50 smallest rectangle1 SmallestRectangle1 22 sub_image SubImage 27 test_equal_region TestEqualRegion 21 test_region_point TestRegionPoint 22 test_sampset_box TestSampsetBox 40 texture_laws TextureLaws 50 HALCON C 2005 02 01 Index threshold Threshold 27 transpose_region TransposeRegion 21 tuple mode 5 8 11 tuple_add 36 37 tuple_concat 37 tuple_div 37 tuple_gen_const 36 tuple_mult 37 tuple_sub 37 tuple sum 36 unioni Union1 24 union2 Union2 21 24 vector_to_rigid 17 window handle 6 XLD 33
8. Windows The class HWindow provides constructors based on the operators open window and new extern window Note that the former is realized with default values for all parame ters thus becoming the default constructor i e all window instances are already opened upon construction Of course you can close a window using CloseWindow and then open it again using OpenWindow In contrast to the iconic parameter classes you can call the constructor like operator OpenWindow via an instance of HWindow in the intuitive way i e the call ing instance is modified in addition the corresponding handle is returned HWindow is described in more detail in section 3 2 3 1 Other Handle Classes The other classes encapsulating handles e g HBarCodeid or HFramegrabber pro vide constructors in a systematic way If a class appears as an output parameter in an operator there automatically exists a constructor based on this operator Thus in stances of HBarCode1d can be constructed based on gen 14 bar code descr as shown in figure 2 4 instances of HShapeModel based on create shape model instances of HFramegrabber based on open framegrabber and so on In contrast to the iconic parameter classes handle classes allow to call constructor like operators via instances of the class in the intuitive way i e the calling instance is modi fied For example you can create an instance of HBarCodetd with the default constructor and then initialize
9. e Array tuple indices Object oriented iconic arrays start with the index 0 the same is true for HTuple In con trast Hobject arrays start with the index 1 Most of the time you will call operators in tuple mode without noticing As soon as you divide a region into connected components via the operator Connection you end up with a HRegionArray thus any subsequent processing e g morphological operations like DilationCircle or the calculation of the region s position using AreaCenter is automati cally performed on all regions in the array i e in tuple mode Thus the tuple mode is a simple mode after all 2 2 Error Handling In case of a runtime error HALCON C by default prints a corresponding error message and terminates the program In some applications however it might be useful to slacken this rule for certain errors For example if an application allows the user to specify an image file to read interactively it would be inconvenient if the application terminates because the user misspelled HALCON 6 1 4 14 CHAPTER 2 BASICS OF THE HALCON C INTERFACE HImageArray images HRegionArray regions HTuple thresholds for int i 1 i lt 2 i t images i 1 HImage ReadImage HTuple alpha i jy regions images CharThreshold images 0 GetDomain 2 95 amp thresholds for int i 0 i lt images Num i 1 images i Display window regions i Display window cout lt lt Threshold for
10. e g using the operator DoOcvSimple HSerial accessing a serial interface e g using the operator ReadSerial HShapeModel shape based matching e g using the operator FindShapeModel HSocket accessing socket connections e g using the operator SendImage HTemplate gray value template matching e g using the operator BestMatchMg HALCON 2005 02 01 3 8 AUXILIARY CLASSES 41 e HVariationModel image comparison via variation model eg using the operator CompareVariationModel Besides the default constructor the classes typically provide additional constructors based on suitable operators as described in section 2 1 2 1 e g the class HBarCode1d provides a con structor based on the operator gen 1d bar code descr All handle classes listed above provide the methods SetHandle and GetHandle which allow to access the underlying handle furthermore the classes provide an operator that casts an instance of the class into the corresponding handle These methods are typically used when combining procedural and object oriented code for examples please refer to section 2 4 3 3 Auxiliary Classes In section 3 1 1 you already got a glimpse of additional classes provided by HALCON C Instances of HRegion can be constructed from classes like HDPoint2D or HRectanglei Cur rently these classes are not documented in any of the manuals We recommend to have a look at the header files in the directory includ
11. message cout lt lt HALCON error lt lt error num lt lt lt lt message 2 3 Memory Management All of HALCON s classes i e not only HImage HRegion HTuple HFramegrabber etc but also the class Hobject used when calling operators in the procedural approach release their allocated memory automatically in their default destructor see also section 2 1 2 2 Further more when constructing instances anew e g by calling Gen1dBarCodeDescr via an already initialized instance as mentioned in section 2 1 2 1 the already allocated memory is automati cally released before allocating it anew Thus there is no need to call the operator clear_obj in HALCON C what s more if you do use it HALCON will complain about already released memory The only occasion for explicit memory management on your part is when using handles in the procedural approach The memory allocated when creating a handle e g with open framegrabber is only released when calling the complementary operator in the ex ample close framegrabber or at the end of the program 2 4 How to Combine Procedural and Object Oriented Code As already noted we recommend to use the object oriented approach wherever possible How ever there are some reasons for using the procedural approach e g if you want to quickly integrate code that is exported by HDevelop which can only create procedural code Besides currently some operators are only avai
12. 6 1 4 24 CHAPTER 3 THE HALCON PARAMETER CLASSES long Num void Number of regions in the array largest index is Num 1 HRegion const amp operator long index const Reading the element i of the array The index is in the range 0 Num 1 HRegion amp operator long index Assigning a region to the element 7 of the array The index index can be gt Num HRegionArray operator long min long max const Selecting a subset between the lower min and upper max index HRegionArray amp Append const HRegion amp reg Appending another region to the region array HRegionArray amp Append const HRegionArray amp reg Appending another region array to the region array void Display const HWindow amp w const Display the regions of the array in a window HRegionArray operator lt lt double radius const Applying a dilation to all regions using a circular mask see reference manual entry of dilation circle HRegionArray operator gt gt double radius const Applying an erosion to all regions using a circular mask see reference manual entry of erosion circle HRegionArray operator const HRegion amp reg const Applying the Minkowsky addition to all regions using another region as mask see refer ence manual entry of ninkowski add1 HRegionArray operator const HRegion amp reg const Applying the Minkowsky subtraction to all regions using another region as mask see reference manual entry of mink
13. Both iconic and control parameters can appear as input and output parameters of a HALCON operator For example the operator mean image expects one iconic input parameter one iconic output parameter and two input control parameters see figure 2 1 figure 2 2 shows an oper ator which has all four parameter types Note how some parameters disappear from within the brackets if you call an operator via a class this mechanism is described in more detail in section 2 1 2 An important concept of HALCON s philosophy regarding parameters is that input param eters are not modified by an operator As a consequence they are passed by value e g Hobject Image in figure 2 1 or via a constant reference e g const HTuple amp MaskWidth This philosophy also holds if an operator is called via a class with the calling instance acting as an input parameter Thus in the following example code the original image is not modified by the call to MeanImage the operator s result i e the smoothed image is provided via the return value instead HALCON C 2005 02 01 2 1 CALLING HALCON OPERATORS 7 Herror find 1d bar code Hobject Image Hobject CodeRegion const HTuple amp BarCodeDescr const HTuple amp GenericName const HTuple amp GenericValue HTuple BarcodeFound HTuple BarCodeElements HTuple rientation HRegion HImage FindidBarCode const HTuple amp BarCodeDescr const HTuple amp GenericName const HTuple amp Gene
14. InstallHHandler Handler proc void PrintException void static Handler handler handler in use long line line number where error occured const char file file name where error occured const char proc Name of procedure operator Herror err error number char message error text Figure 2 8 Part of the declaration of the class HExcept ion 2 2 4 Object Oriented Approach If a runtime error occurs in an object oriented operator call an instance of the class HException is created see figure 2 8 for the declaration of the class This instance contains all information concerning the error The important members of an exception are line Number of the program line in which the error occurred file Name of the file in which the error occurred proc Name of the actual HALCON operator err Number of the error see below message Error text After the generation the instance of HException is passed to a so called exception handler HALCON s default exception handler prints the corresponding error message and terminates the program As an alternative you can implement and use your own exception handler In order to act as a HALCON exception handler a procedure must have the following signature typedef void Handler const HException amp exception You install your exception handler procedure via HException s class method InstallHHandler see figure 2 8 case of a runtime
15. entry of sub image e HImage operator const HImage amp mult const Multiplication of two images see reference manual entry of mult image e HImage operator void const Inverting the values of the image see reference manual entry of invert image e HImage operator double add const HImage operator double sub const HImage operator double mult const HImage operator double div const Arithmetic operators see reference manual entry of scale image e HRegion operator gt const HImage amp image const HRegion operator const HImage amp image const Selecting all pixel with gray values brighter than or equal to or darker than or equal to respectively those of the input image see reference manual entry of dyn threshold e HRegion operator gt double thresh const HRegion operator lt double thresh const HRegion operator double thresh const HRegion operator double thresh const Selecting all pixel with gray values brighter than or equal to or darker than or equal to or equal to or not equal to respectively a threshold see reference manual entry of threshold Figure 3 5 gives an example of the use of the class HImage HALCON 6 1 4 28 CHAPTER 3 THE HALCON PARAMETER CLASSES include HalconCpp h include iostream h main B HImage image mreut Aerial image HWindow w Output window image Display w Display image Returning the size of the image cout lt
16. error HALCON then calls your procedure passing the instance of the actual exception as a parameter The following example shows how to use a user specific exception handler together with the standard C exception handling mechanism try catch The cor responding program example errorhandling cpp can be found in the subdirectory AHALCONROOTANexamplesNcpp It realizes the application mentioned above You can type in image files to load if a file does not exist the program prints a corresponding message but continues nevertheless At the beginning of the program a user specific exception handler is installed with the folloing line HALCON 6 1 4 16 CHAPTER 2 BASICS OF THE HALCON C INTERFACE HException InstallHHandler amp MyHalconExceptionHandler The installed procedure simply hands the exception object to the exception handling via throw void MyHalconExceptionHandler const HException amp except 1 throw except The call to ReadImage is then encapsulated by a try block a possibly ensuing exception is then evaluated in a corresponding catch block iq 1 image HImage ReadImage filename n catch HException amp except 1 error num except err if error num MSG FAIL cout image not found endl else cout lt lt endl lt lt except message lt lt endl 2 2 2 Procedural Approach As can be seen in the extracts of the reference manual in section 2 1 in the procedura
17. 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 2 CHAPTER 1 INTRODUCING HALCON C instead of using the standard HALCON Frame Grabber Integration Interface in order to exploit specific hardware features of a frame grabber board e HALCON C HALCON HDevelop HALCON C HALCON COM The reference manuals for all HALCON operators versions for C HDevelop C and COM e Application Guide Multiple independent documents called Application Notes written from the point of view of developing machine vision applications with HALCON Each Note covers a specific topic e g how to use shape based matching to find and localize objects All these manuals are available as PDF documents The reference manuals are available as HTML documents as well For the latest version of the manuals please check http www mvtec com halcon 1 2 A First Example Let s start with a brief sample program before taking a closer look inside HALCON C Figure 1 1 The left side shows the input image a mandrill and the right side shows the result of the image processing the eyes of the monkey The input image is shown in figure 1 1 on the left side The task is to find the eyes of the monkey by segmentation The segmentation of the eyes is performed by the program listed in figure 1 2 the result of the segmentation process is shown in figur
18. is done by using shape properties of the regions the size and the anisometry This example shows how easy it is to integrate HALCON operators in any program Their use is very intuitive You don t have to care about the underlying data structures and algo rithms you can ignore specific hardware requirements if you consider e g input and output operators HALCON handles the memory management efficiently and hides details from you and provides an easy to use runtime system HALCON 6 1 4 4 CHAPTER 1 INTRODUCING HALCON C HALCON C 2005 02 01 Chapter 2 Basics of the HALCON C Interface In fact the HALCON C interface provides two different approaches to use HALCON s func tionality within your program a procedural and an object oriented approach The proce dural approach corresponds to calling HALCON operators directly as in C or HDevelop e g Hobject original image smoothed image read image amp original image monkey mean image original image amp smoothed image 11 11 Note that in comparison with HALCON C or HDevelop the operator names are prefixed with a double colon In the following we will leave out this prefix when referencing operators in the text In addition to the procedural approach HALCON C allows to call HALCON operators in an object oriented way i e via a set of classes For example the code from above can be translated into HImage original image monkey s
19. operator can be called For example FindidBarCode can be called via objects of the class HImage or HBarCodeid see figure 2 2 In both cases the corresponding input parameter Image or BarCodeDescr respectively does not appear within the brackets anymore as it is replaced by the calling instance of the class this There is a further difference to the procedural operator signature The first output parameter in the example the bar code region CodeRegion also disappears from within the brackets and HALCON 2005 02 01 2 1 CALLING HALCON OPERATORS 9 HImage image barcode ean13 ean1301 HBarCode1D barcode EAN 13 13 13 HRegion code_region HTuple isfound elements code_region barcode FindidBarCode image HTuple HTuple amp isfound amp elements HTuple _ code region image FindidBarCode barcode GetHandle HTuple HTuple amp isfound amp elements HTuple Hobject image HTuple barcode Hobject code_region HTuple isfound elements read image amp image barcode eani3 eani301 gen 1d bar code descr EAN 13 13 13 amp barcode find 1d bar code image amp code region barcode HTuple HTuple amp isfound amp elements HTuple Figure 2 4 Using FindidBarCode via HBarCode1d via HImage or in the procedural approach becomes the return value instead of the error code more about error handling can be found in section 2 2 Figure 2 4 depic
20. two regions are identical see reference manual entry of test equal region HBool operator gt const HRegion amp reg const HBool operator gt const HRegion amp reg const HBool operator lt const HRegion amp reg const HBool operator const HRegion amp reg const Boolean test if another region is included in the region by using the subset of the corre sponding coordinates double Phi void const Orientation of the region by using the angle of the equivalent ellipse see reference manual entry of elliptic axis double Ra void const Length of the major axis of the equivalent ellipse of the region see reference manual entry of elliptic axis double Rb void const Length of the minor axis of the equivalent ellipse of the region see reference manual entry of elliptic axis long Area void const Area of the region i e number of pixels see reference manual entry of area center double X void const double Y void const HALCON 6 1 4 22 CHAPTER 3 THE HALCON PARAMETER CLASSES Center point of the region see reference manual entry of area center e double Contlength void const Length of the contour of the region see reference manual entry of contlength e double Compactness void const Compactness of the actual region see reference manual entry of compactness e double Anisometry void const double Bulkiness void const double StructureFactor void const Shape factors see reference manual entry of
21. 000 XP respectively examples cpp make ARCHITECTUREZ macros mak rules mak Auxiliary makefiles included by the makefiles listed above 43 44 CHAPTER 4 CREATING APPLICATIONS WITH HALCON C examples cpp source Directory containing the source files of the example programs examples cpp bin ZARCHITECTUREZ Destination of the example programs when compiled and linked using the makefiles examples cpp i586 nt4 i586 nt4 dsw Visual Studio workspace containing projects for all examples the projects themselves are placed in subdirectories Windows NT 2000 XP only images Images used by the example programs help english Files necessary for online information doc pdf Various manuals in subdirectories There are several example programs in the HALCON C distribution To experiment with these examples we recommend to create a private copy in your working directory 1 1 reads image and demonstrates several graphics operators example2 cpp demonstrates the direct pixel access example3 cpp is an example for the usage of pixel iterators example4 cpp demonstrates the edge detection with a sobel filter example5 cpp solves a more complicated problem example6 cpp is a very simple test program example7 cpp demonstrates the generic pixel access example8 cpp is an example for the usage of the tuple mode example9 cpp introduces the XLD structure 1 10 demonstrates the us
22. 31 33 HClassBox 40 HCtrlVal 34 36 DO 35 It 35 LC 39 50 35 HFile 40 HFramegrabber 10 11 17 40 HFunctionid 40 HGnuplot 40 HImage 1 5 8 10 12 13 17 19 26 29 31 33 Display O 27 GetPixVal 27 Height O 27 operator 27 operator 27 operator 27 operator 27 operator 27 operator lt 27 operator 27 operator 27 operator gt 27 operator amp 27 PixTypeO 26 SetPixVal 27 WidthO 26 HImageArray 12 14 30 Append O 31 Num 31 HInt2Image 31 HMeasure 40 HObject 19 33 Hobject 11 13 17 20 33 34 HOCR 40 HOCV 40 HPixVal 29 HByte 30 HRegion 1 10 12 17 19 22 24 26 41 Anisometry 22 Area 21 Bulkiness 22 Display O 20 22 Ib 22 In 22 IsEmpty 22 Index M020 22 M11Q 22 M200 22 operator 21 operator 20 operator 20 operator 20 operator 20 operator 21 operator 21 operator 21 operator 21 operator 21 operator lt lt 20 operator 20 operator lt 21 operator lt 21 operator 21 operator gt 21 operator gt gt 20 operator gt gt 20 operator gt 21 operator amp 21 operator amp 21 operator 21 operator 21 Phi 21 RaQ 21 RbO 21 StructureFactor 22 XO 21 YO 21 HRegionArray 12 13 22 24 25 Append C 24 Display 24 Num 24 operator 24 operator 24 operator 24 operator 24 operator gt gt 24 opera
23. ALCON windows in a very convenient way The properties of HALCON windows can be easily changed images regions and poly gons can be displayed etc Besides those operators that can be called via HWindow see also section 2 1 2 HWindow provides the following member functions e HWindow int Row 0 int Column 0 int Width 1 int Height 1 int Father 0 const char Mode const char Host Default constructor The constructed window is opened HWindow void Destructor This closes the window void Click void const Waiting for a mouse click in the window HDPoint2D GetMbutton int button const HDPoint2D GetMbutton void const Waiting for a mouse click in the window It returns the current mouse position in the window and the number of the button that was pressed see the reference manual entry of get_mbutton HDPoint2D GetMposition int button const HDPoint2D GetMposition void const Returning the mouse position and the pressed button without waiting for a mouse click see the reference manual entry of get mposition HALCON C 2005 02 01 3 2 CONTROL PARAMETERS 39 HCircle DrawCircle void const Waiting for the user to draw a circle in the window see the reference manual entry of draw circle HEllipse DrawEllipse void const Waiting for the user to draw an ellipse in the window see the reference manual entry of draw ellipse HRectanglei DrawRectanglei void const Waiting for the user to draw
24. HALCON Version 6 1 4 MVTec Software GmbH HALCON C User s Manual How to use the image analysis tool HALCON Version 6 1 4 in your own programs 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 1 July 1997 Edition 2 November 1997 Edition 3 March 1998 HALCON 5 1 Edition 4 April 1999 HALCON 5 2 Edition 5 October 2000 HALCON 6 0 Edition 5a July 2001 HALCON 6 0 1 Edition 5b February 2002 HALCON 6 0 2 Edition 6 June 2002 HALCON 6 1 Edition 6a December 2002 HALCON 6 1 1 Edition 6b February 2005 HALCON 6 1 4 EC Copyright 1997 2005 by MVTec Software GmbH M nchen Germany ivre seare ombr Microsoft Windows Windows NT Windows 2000 Windows XP and Visual are either trademarks or registered trademarks of Microsoft 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 the interface of HALCON to the programming language It pro vides all necessary information to understand and use the provided classes in your own programs A set of example programs shows how to apply HALCON C to solve typica
25. HTuple void Default constructor Constructs an empty tuple e HTuple long 1 Constructing an array of length 1 from a discrete number long at index position 0 e HTuple int 1 Constructing an array of length 1 from a discrete number converted to the internal type long at index position 0 e HTuple HCoord c Constructing an array of length 1 from a coordinate at index position 0 e HTuple double d Constructing an array of length 1 from a floating number double at index position 0 e HTuple const char s Constructing an array of length 1 from a string char at index position 0 e HTuple const HTuple amp t Copying a tuple e HTuple int length const HTuple amp value Constructing an array of the specified length with a constant value similar to the operator tuple_gen_const e HTuple Destructor e HTuple amp operator const HTuple amp in Assignment operator e HTuple Sum void const Adding all elements in case they are numbers similar to the operator tuple_sum e HCtrlVal amp operator int i Setting the th element e HCtrlVal operator int i const Reading the th element e HTuple operator const HTuple amp val const Adding two tuples element by element similar to the operator tuple add The arrays have to be of the same size HALCON 2005 02 01 3 2 CONTROL PARAMETERS 37 HTuple operator double amp val const HTuple operator int amp val const Adding a num
26. Hobject is used for all iconic parameters be it an image a region or even an image array In fact the class Hobject is HALCON s basic class for accessing the internal data management 1 e it handles the keys of the database Furthermore Hobject serves as the basis for the class HObject and the derived classes e g HImage The class Hobject has the following member functions e Hobject void Default constructor e Hobject const Hobject amp obj Copy constructor HALCON 6 1 4 34 CHAPTER 3 THE HALCON PARAMETER CLASSES e virtual Hobject void Destructor e Hobject amp operator const Hobject amp obj Assignment operator e void Reset void Freeing the memory and resetting the corresponding database key As noted above an instance of Hobject can also contain a tuple array of iconic objects Unfortunately Hobject provides no special member functions to add objects or select them instead you must use the operators empty obj concat obj select obj and count obj as described in section 2 1 3 3 2 Control Parameters HALCON C can handle different types of alphanumerical control parameters for HALCON operators e discrete numbers long e floating point numbers doub1e and e strings char A special form of control parameters are the so called handles which provide access to more complex data structures like windows frame grabber connections or models for shape based matching Internall
27. ON is used on The following ta ble gives an overview of the currently supported platforms and the corresponding values of ARCHITECTURE ARCHITECTURE Operating System Platform Compiler Windows NT 4 0 Windows 2000 Windows XP i586 nt4 Visual Studio on Intel Pentium or compatible 1586 linux2 2 gcc 2 95 f Linux 2 2 2 4 on Intel Pentium or compatible 1586 11 0 2 2 32 gcc 3 2 3 3 Solaris 7 on Sparc Workstations mips sgi irix6 5 IRIX 6 5 on SGI Workstations Mips processors alpha compaq osf5 1 Tru64 UNIX 5 1 on Alpha processors If user defined packages are used the environment variable HALCONEXTENSIONS has to be set HALCON will look for possible extensions and their corresponding help files in the directories given in HALCONEXTENSIONS Two things are important in connection with the example programs The default directory for the HALCON operator read image to look for images is 4HALCONROOTANimages If the im ages reside in different directories the appropriate path must be set in read image or the de fault image directory must be changed using set system image dir This is also possible with the environment variable HALCONIMAGES It has to be set before starting the program The second remark concerns the output terminal under UNIX In the example programs no host name is passed to open window Therefore the window is opened on the machine that is specified in the environment varia
28. a rectangle parallel to the coordinate axis in the window see the reference manual entry of draw rectangle HRectangle2 DrawRectangle2 void const Waiting for the user to draw a rectangle with an arbitrary orientation and size in the win dow see the reference manual entry of draw rectangle2 include HalconCpp h main 1 HImage image control unit Reading an image from a file HWindow w Opening an appropiate window image Display w Display the image w SetLut change2 Set lookup table w ClickO Waiting for a mouse click w SetLut default Set the default lookup table w SetPart 100 100 200 200 Set a part of the window image Display w Wei od bates e Adapting the part to the image again w SetPart 0 0 bild Height O 1 bild Width 1 image Display w HRegionArray regs image Regiongrowing 1 1 4 100 w SetDraw margin w SetColored 6 regs Display w Wr ed bates e image Display w w SetShape rectanglei regs Display w Figure 3 10 Sample program for the use of the class HWindow Figure 3 10 shows the typical use of some member functions of the class HWindow and the different possibilities of displaying images and regions The window is opened after reading the image from a file This means the window is scaled to the size of the image The lookup table is changed afterwards and the program waits for a mouse click in the window A part of the image is zoome
29. ables of the class 1 are declared before passing the corresponding pointers using the operator amp HImage image barcode eani3 eani301 HBarCode1D barcode EAN 13 13 13 HRegion code_region HTuple isfound elements code_region barcode FindidBarCode image HTuple HTuple amp isfound amp elements HTuple _ The above example shows two other interesting aspects of output parameters When calling operators via classes one output parameter becomes the return value see section 2 1 2 for more details in the example FindidBarCode returns the bar code region Secondly a spe cial variable called _ was specified for the last parameter of FindidBarCode This variable is pre declared it tells the operator that it does not need to output the corresponding parameter HALCON 6 1 4 8 CHAPTER 2 BASICS OF THE HALCON C INTERFACE Herror info_framegrabber const HTuple amp Name const HTuple amp Query char Information char ValueList Herror info_framegrabber const HTuple amp Name const HTuple amp Query HTuple Information HTuple ValueList Namet npiteconttol string HTuple const char Query string HTuple const char informaiton OULPUL CONLIO string HTuple char ValueList output control string array HTuple char long do
30. age const HTuple amp MaskWidth const HTuple amp MaskHeight const HImageArray HImageArray MeanlImage const HTuple amp MaskWidth const HTuple amp MaskHeight const Image input object multichannel image array Hobject Hlmage Array byte int2 uint2 int4 real dvf ImageMean output object multichannel image array Hobject HImage Array byte int2 uint2 int4 real dvf Maskwidtchl inputecontrolgee extent x HTuple long MasktHestehtiinpubseontto Eee extent y HTuple long Figure 2 1 The head and parts of the parameter section of the reference manual entry for mean image 2 1 1 A Closer Look at Parameters HALCON distinguishes two types of parameters iconic and control parameters Iconic pa rameters are related to the original image images regions XLD objects whereas control parameters are all kinds of alphanumerical values such as integers floating point numbers or strings A special form of control parameters are the so called handles A well known representative of this type is the window handle which provides access to an opened HALCON window e g to display an image in it Besides handles are used when operators share complex data e g the operators for shape based matching which create and then use the model data or for accessing input output devices e g frame grabbers Classes encapsulating handles are described in detail in section 3 2 3
31. age AddImage 27 50 area center AreaCenter 13 21 22 bandpass_image BandpassImage 50 best match mg BestMatchMg 40 channel 26 char_threshold CharThreshold 11 13 classes auxiliary 41 handle classes 10 11 40 1 8 10 40 41 HBarCode2d 40 HBgEsti 40 HByteImage 31 33 HClassBox 40 HCtrlVal 34 36 HF ile 40 HFramegrabber 10 11 17 40 HFunctionid 40 HGnuplot 40 HImage 1 5 8 10 12 13 17 19 26 29 31 33 HImageArray 12 14 30 HInt2Image 31 HMeasure 40 HObject 19 33 Hobject 11 13 17 20 33 34 HOCR 40 HOCV 40 HPixVal 29 HRegion 1 10 12 17 19 22 24 26 41 HRegionArray 12 13 22 24 25 HSerial 40 HShapeModel 10 11 40 HSocket 40 HTemplate 40 HTuple 7 11 13 17 34 36 38 53 HVariationModel 41 HWindow 1 10 11 18 37 39 HXLD 10 19 33 HXLDArray 33 HXLDCont 10 33 HXLDPoly 33 iconic classes 17 19 clear_all_shape_models 11 18 clear_obj 17 clear_shape_model 11 18 close_framegrabber 11 17 18 close_window CloseWindow 10 11 COM 46 compactness Compactness 22 compare_variation_model CompareVariationModel 41 complement Complement 21 24 concat_obj 12 34 connection Connection 13 constructors 9 18 contlength Contlength 22 control parameters 6 34 count_obj 12 34 create_funct_ld_pairs CreateFunctidPairs 40 create_shape_model CreateShapeModel 10 destructors 11 difference Difference
32. age of several contour structures exampleii cpp is another simple example for the usage uf tuples example errorhandling cpp demonstrates the exception handling see section 2 2 1 bottle2 cpp recognizes on numbers on a beer bottle OCR ean13 cpp reads an EAN13 bar code ecc200 cpp reads a Data Matrix ECC200 code engraved2 cpp recognizes engraved characters OCR fuzzy measure pin cpp measures distances between pins using the fuzzy measure tool multi chars cpp performs optical character verification HALCON 2005 02 01 45 uses shape based matching and the variation model for print quality inspection xing cpp monitors traffic using background estimation by Kalman fil tering Additional examples for using HALCON C can be found in the subdirectories examples WMnfc and examples motif In the following we briefly describe the relevant environment variables see the manual Getting Started with HALCON for more information especially about how to set these vari ables Note that under Windows NT 2000 XP all necessary variables are automatically set during the installation While a HALCON program is running it accesses several files internally To tell HALCON where to look for these files the environment variable HALCONROOT has to be set HALCONROOT points to the HALCON home directory HALCONROOT is also used in the sample makefile The variable ARCHITECTURE describes the platform HALC
33. ages consist of a single channel color images of three channels Channels can not only contain the standard 8 bit pixels pixel type byte used to represent gray value images HALCON allows images to contain various other data e g 16 bit integers type int2 or 32 bit floating point numbers type real to represent derivatives Besides the pixel information each HALCON image also stores its so called domain in form of a HALCON region The domain can be interpreted as a region of interest i e HALCON operators with some exceptions restrict their processing to this region 3 1 2 1 Image Objects The class HImage is the root class for all derived image classes By using the class HImage all different pixel types can be handled in a unique way polymorphism The class HImage is not virtual thus it can be instantiated Besides those operators that can be called via HRegion see also section 2 1 2 HRegion provides the following member functions e HImage void Default constructor empty image e HImage const char file Constructing an image by reading from a file see reference manual entry of read image e HImage int width int height const char type Constructing an image of a defined size and a specific pixel type see reference manual entry of image const e HImage void ptr int width int height const char type Constructing an image of a defined size and a specific pixel type by copying memory see reference manual ent
34. alType const Type of a value operator int void const Conversion to int operator long void const Conversion to long operator double void const Conversion to double operator const char void const Conversion to char double D const Accessing a value and conversion to double long L const Accessing a value and conversion to long int const Accessing a value and conversion to int const char S const Accessing a value and conversion to char HCtrlVal operator const HCtrlVal amp val Adding two values HCtrlVal operator const HCtrlVal amp val Subtracting two values HCtrlVal operator const HCtrlVal amp val Multiplying two values HCtrlVal operator const HCtrlVal amp val Division of two values const const const const 35 HALCON 6 1 4 36 CHAPTER 3 THE HALCON PARAMETER CLASSES 3 2 2 Tuples The class HTuple is built upon the class HCtrlVal it implements an array of dynamic length for instances of the class HCtr1Val The default constructor constructs an empty ar ray Num 0 This array can dynamically be expanded via assignments The memory management i e reallocation freeing is also managed by the class The index for accessing the array is in the range between 0 and Num 1 The following member functions reflect only a small portion of the total For further information please refer to the file HTuple h HALCONROOT include cpp e
35. ample program in figure 3 5 3 1 2 2 Pixel Values include HalconCpp h include lt iostream h gt main HBytelmage in mreut Aerial image HWindow w Output window in Display w Displaying the image HByteImage out in Copying the image int width out Width Width of the image int height out Height Height of the image long end width height Number of pixel of the image 1 run linear accessing for long k 0 k lt end k int pix in GetPixVal k Reading the pixel out SetPixVal k 255 pix Setting the pixel ih Displaying the transformation cout lt lt Transformed lt lt endl out Display w wan Od cout lt lt Original lt lt endl in Display w w ClickO 2 run accessing the image via the coordiantes x y for int y 0 y lt height for int x20 x width 1 int pix in GetPixVal x y Reading the pixel out SetPixVal x y 255 pix Setting the pixel 1 Displaying the transformation cout lt lt Transformed lt lt endl out Display w w Click cout lt lt Original lt lt endl in Display w w Click Figure 3 7 Sample program for the use of the class HPixVal The class HPixVal is used for accessing the pixel values of the class HImage Gray values can be set and returned independent of their types e HPixVal void Default constructor e HPixVal const HComplex amp Val Co
36. andles p_barcode barcode e Converting iconic parameter classes into Hobject Hobject p code region o code 1 Iconic parameters can be converted from classes like HRegion back into Hobject via the method Id In contrast to the handle classes no cast operator is provided e Converting HWindov into a window handle long p window 0pen window 0 0 width 2 height 2 0 visible amp p window HWindow o_window 0 0 100 100 0 visible p_window o_window WindowHandle disp obj p code region p window In contrast to other handles procedural window handles cannot be converted into instances of the class HWindow However you can extract the handle from an instance of HWindow via the method WindowHand1le As already remarked in section 2 1 2 2 you must not use operators like clear shape model clear_all_shape_models or close framegrabber together with instances of the corre sponding handle classes HALCON C 2005 02 01 Chapter 3 The HALCON Parameter Classes 3 1 Iconic Objects The base class of the iconic parameter classes in is the abstract class HObject which manages entries in the database i e the copying or releasing of objects The entries themselves are represented by the class Hobject see also section 3 1 4 The classes HObject and Hobject can contain all types of iconic objects This has the advantage that important methods like Display
37. ber to each element of the tuple similar to the operator tuple add HTuple operator const HTuple amp val const Subtracting two tuples element by element similar to the operator tuple sub The arrays have to be of the same size HTuple operator double amp val const HTuple operator int amp val const Subtracting a number from each element of tuple similar to the operator tuple sub HTuple operator const HTuple amp val const Multiplying two tuples element by element similar to the operator tuple mult The arrays have to be of the same size HTuple operator double amp val const HTuple operator int amp val const Multiplying a number with each element of tuple similar to the operator tuple mult HTuple operator const HTuple amp val const Division of two tuples element by element similar to the operator tuple div The arrays have to be of the same size HTuple operator double amp val const HTuple operator int amp val const Division of each element of the tuple by a number similar to the operator tuple div HTuple Concat const HTuple amp t const Concatenating two tuples similar to the operator tuple_concat extern ostream amp operator lt lt ostream amp s const HTuple amp t Output of a tuple extern istream amp operator gt gt istream amp s HTuple amp t Input of a tuple Figure 3 9 shows a short sample how to use tuples i e the class HTuple The default const
38. ble DISPLAY If output on a different terminal is desired this can be done either directly in open window hostname or by specifying a host name in DISPLAY formerly called DIGITAL UNIX HALCON 6 1 4 46 CHAPTER 4 CREATING APPLICATIONS WITH HALCON C In order to link and run applications under UNIX you have to include the HALCON library path HALCONROOT 1ib ARCHITECTURE in the system variable LD_LIBRARY_PATH 4 1 Creating Applications Under Windows NT 2000 XP Your own C programs that use HALCON operators must include the file HalconCpp h which contains all user relevant definitions of the HALCON system and the declarations nec essary for the C interface Do this by adding the command include HalconCpp h near the top of your C file In order to create an application you must link the library halconcpp lib dll to your program The example projects show the necessary Visual settings For the examples the project should be of the WIN 32 ConsoleApplication type Please note that the Visual C compiler implicitly calls Update all dependencies if a new file is added to a project Since HALCON runs under UNIX as well as under Windows NT 2000 XP the include file HalconCpp h in cludes several UNIX specific headers as well if included under UNIX Since they don t exist under NT and the Visual compiler is dumb enough to ignore the operating system specific cases in the include files you will get a n
39. ction 3 2 2 for more information about this class In contrast to the control parameters the iconic parameters remain instances of the class Hobject in both modes as this class can contain both single objects and object arrays see also section 3 1 4 HALCON 6 1 4 12 CHAPTER 2 BASICS OF THE HALCON C INTERFACE Herror char threshold Hobject Image Hobject HistoRegion Hobject Characters const HTuple amp Sigma const HTuple amp Percent long Threshold Herror char threshold Hobject Image Hobject HistoRegion Hobject Characters const HTuple amp Sigma const HTuple amp Percent HTuple Threshold HRegion HImage CharThreshold const HRegion amp HistoRegion const HTuple amp Sigma const HTuple amp Percent long Threshold const HRegionArray HImageArray CharThreshold const HRegion amp HistoRegion const HTuple amp Sigma const HTuple amp Percent HTuple Threshold const Iimage nptutsobjeco 2 image array Hobject HImage Array byte Histohecaon nputsob cco PRIME region Hobject HRegion Characters output object region array Hobject HRegion Array number HTuple double Percent NPU COO number HTuple double long inlimsesnhoudi ouiputecontrol me integer array HTuple long Figure 2 5 The head and parts of t
40. d now and the program waits again for a mouse click in the window By applying a region growing algorithm from the HALCON library Regiongrowing regions are generated and displayed in the window Only the margin of the regions is displayed It is HALCON 6 1 4 40 CHAPTER 3 THE HALCON PARAMETER CLASSES displayed in 6 different colors in the window The example ends with another way of displaying the shape of regions The smallest rectangle parallel to the coordinate axes surrounding each region is displayed 3 2 3 2 Other Handle Classes Starting with version 6 1 HALCON C provides the following handle classes HBarCodeid reading 1 dimensional bar codes e g using the operator FindidBarCode HBarCode2d reading matrix bar code e g using the operator Find2dBarCode HBgEsti estimating the background of a scene e g using the operator RunBgEsti HClassBox classifying data e g using the operator TestSampsetBox HFile accessing disk files e g using the operator OpenFile HFramegrabber accessing frame grabbers e g using the operator GrabImage HFunctionid working with 1 dimensional functions e g using the operator CreateFunctidPairs HGnuplot using gnuplot e g using the operator GnuplotPlotFunct id HMeasure measuring distances along lines or arcs e g using the operator MeasurePairs HOCR optical character recognition e g using the operator DoOcrMulti HOCV optical character verification
41. e gen image gen 1 extern and gen image const HALCON 6 1 4 10 CHAPTER 2 BASICS OF THE HALCON C INTERFACE Please beware of the following pitfall when using the operators themselves via HImage Contrary to intuition the operators do not modify the instance they are called from in stead the created image is the return value of the operator Thus after the following code the image is still uninitialized HImage image image ReadImage barcode eani3 eani301 incorrect The correct way to call ReadImage is as follows image HImage ReadImage barcode eani3 eani301 correct Note that this pitfall concerns all operators where HImage appears as an output parameter e g GrabImage More information about HImage can be found in section 3 1 2 Regions The class HRegion provides constructors based on operators like gen rectangle2 or gen_circle However instead of the parameters of these operators the constructors expect instances of auxiliary classes like HRectangle2 or HCircle see section 3 3 for more information about these classes Please note that HRegion presents the same pitfall as HImage i e operators like GenRectangle2 do not modify the calling instance of HRegion but return the created region More information about HRegion can be found in section 3 1 1 XLDs The classes for XLDs HXLD HXLDCont etc see section 3 1 3 for more information do not provide constructors based on operators
42. e 1 1 on the right side The program is more or less self explaining The basic idea is as follows First all pixels of the input image are selected which have a gray value of at least 128 on the assumption that the image Mandrill is a byte image with a gray value range between 0 and 255 Secondly the connected component analysis is performed The result of the HALCON operator is an array of HALCON 2005 02 01 1 2 A FIRST EXAMPLE 3 include HalconCpp h main 1 HImage Mandrill monkey read image from file monkey HWindow w window with size equal to image Mandrill Display w display image in window Wi CLEO n wait for mouse click HRegion Bright Mandrill gt 128 select all bright pixels HRegionArray Conn Bright Connection get connected components select regions with a size of at least 500 pixels HRegionArray Large Conn SelectShape area and 500 90000 select the eyes out of the instance variable Large by using the anisometry as region feature HRegionArray Eyes Large SelectShape anisometry and 1 1 7 Eyes Display w display result image in window wait for mouse click Figure 1 2 This program extract the eyes of the monkey regions Each region is isolated in the sense that it does not touch another region according to the neighbourhood relationship Among these regions those two are selected which correspond to the eyes of the monkey This
43. e cpp Please note that the header files in include cpp include other classes which do not appear in this manual These classes are used by MVTec internally for testing purposes they should not be used an application HALCON 6 1 4 42 HALCON C 2005 02 01 CHAPTER 3 THE HALCON PARAMETER CLASSES Chapter 4 Creating Applications With HALCON C HALCON distribution contains examples for building an application with HALCON C Here is an overview of the relevant directories files relative to HALCONROOT Windows nota tion of paths include cpp HalconCpp h include file contains all user relevant definitions of the HALCON system and the decla rations necessary for the C interface bin i586 nt4 halcon lib halcon dll The HALCON library Windows NT 2000 XP bin i586 nt4 halconcpp lib halconcpp dll The HALCON C library Windows NT 2000 XP binMi586 nt4Nparhalcon lib parhalcon dll parhalconcpp lib parhalconcpp dll The corresponding libraries of Parallel HALCON Windows NT 2000 XP libVAARCHITECTURE Mlibhalcon so The HALCON library UNIX libVAARCHITECTURE Nlibhalconcpp so The HALCON C library UNIX libNAARCHITECTURE Mlibparhalcon so libparhalconcpp so The corresponding libraries of Parallel HALCON UNIX include cpp HProto h External function declarations examples cpp makefile makefile nt Example makefiles which can be used to compile the example programs UNIX and Win dows NT 2
44. eccentricity e double Mii void const double M20 void const double MO2 void const double Ia void const double Ib void const Moments of the region see reference manual entry of moments region 2nd e HRectanglei SmallestRectanglei void const Smallest surrounding rectangle parallel to the coordinate axis see reference manual entry of smallest rectangle1 e HBool In const HDPoint2D amp p const Boolean test if a point is inside a region see reference manual entry of test region point e HBool IsEmpty void const Boolean test if the region is empty i e the area of the region is zero A program shows the power of the class HRegion see figure 3 1 First an aerial image mreut tiff is read from a file All pixels with a gray value gt 190 are selected This results in one region region This region is transformed by the next steps All holes in the region are filled 110 small parts of the region are eliminated by two morphological operations first an erosion a kind of shrinking the region followed by a dilation a kind of enlarging the region The last step is the zooming of the region For that the region is first shifted by a translation vector 100 150 to the upper left corner and then zoomed by the factor two Figure 3 2 shows the input image and the result of the opening operation 3 1 1 1 Region Arrays The class HRegionArray serves as container class for regions Besides those operators that ca
45. es x y for int 0 y lt height y for int x 0 x lt width x out x y 255 out x y Reading and setting the pixel Displaying the transformation cout lt lt Transformed lt lt endl out Display w w Click cout lt lt Original lt lt endl in Display w w Click Figure 3 8 Sample program for accessing a pixel value using the class HByteImage e HByte amp operator long k Setting a pixel value by linear accessing e HByte operator long k const Reading a pixel value by linear accessing e HByte amp operator int x int y Setting a pixel value by accessing it via z y coordinates e HByte operator int x int y const Reading a pixel value by accessing it via x y coordinates e HBytelmage operator amp int i Applying the logical on each pixel with i e HBytelmage operator int i Applying a left shift on each pixel with i HALCON 2005 02 01 3 1 ICONIC OBJECTS 33 e HBytelmage operator gt gt int i Applying a right shift on each pixel with i e HBytelmage operator void Complement of each pixel e HBytelmage operator amp HBytelmage amp ima Pixel by pixel logical and operation of two images e HBytelmage operator HBytelmage amp ima Pixel by pixel logical of two images e HBytelmage operator HBytelmage amp ima Pixel by pixel logical
46. geArray const HImage amp reg Constructing an image array from a single image HImageArray const HImageArray amp arr Copy constructor HImageArray void Destructor HALCON C 2005 02 01 3 1 ICONIC OBJECTS 31 HImageArray amp operator const HImageArray amp arr Assignment operator long Num void const Returning the number of elements in the array HImage const amp operator long index const Reading the element 7 of the array The index is in the range 0 Num 1 HImage amp operator 1ong index Assigning an image to the element 7 of the array The index index can be gt Num HImageArray operator long min long max Selecting a subset between the lower min and upper max index HImageArray amp Append const HImage amp image Appending another image to the image array HImageArray amp Append const HImageArray amp images Appending another image array to the image array 3 1 2 4 Byte Images For each pixel type there exists a corresponding image class derived from HImage e g HByteImage for the pixel type byte standard 8 bit pixels or HInt2Image for the pixel type int2 unsigned 16 bit pixels The most important derived class is naturally HByteImage as this pixel type still covers the majority of all applications in the field of image processing The advantage of the class HByteImage in comparison to the class HImage is the simplified access to the pixel values This is because
47. gmentation is an arbitrary segmentation operator that results in an array of regions Seg e The size of the mask in this case the radius is 3 5 determines the size of the resulting objects e You can choose an arbitrary mask shape 5 6 Selecting Oriented Objects Another application of morphological operators is the selection of objects having a certain ori entation segmentation Image amp Seg HRectangle2 Rect 100 100 0 5 21 2 HRegionArray Res Seg Opening e Again segmentation leads to an array of regions Seg e The width and height of the rectangle determine the minimum size of the resulting regions The orientation of the rectangle determines the orientation of the regions e Lines with the same orientation as Rect are kept 5 7 Smoothing Contours The last example in this user s manual deals again with morphological operators Often the margins of contours have to be smoothed for further processing e g fitting lines to a contour Or small holes inside a region have to be filled segmentation Image amp Seg HCircle Circle 100 100 3 5 HRegionArray Res Seg Closing Circle e Again segmentation leads to an array of regions Seg e For smoothing the contour a circle mask is recommended e The size of the mask determines how much the contour is smoothed HALCON 6 1 4 52 CHAPTER 5 TYPICAL IMAGE PROCESSING PROBLEMS HALCON 2005 02 01 Index ad add im
48. grabber together with instances of the corresponding handle classes 2 1 3 The Tuple Mode As already mentioned in section 2 1 1 many HALCON operators can be called in the so called tuple mode In this mode you can e g apply an operator to multiple images or regions with a single call The standard case e g calling the operator with a single image is called the simple mode Whether or not an operator supports the tuple mode can be checked in the reference manual For example take a look at figure 2 5 which shows an extract of the reference manual entry for the operator char threshold In the parameter section the parameter Image is de scribed as an image array this signals that you can apply the operator to multiple images at once If you call char threshold with multiple images i e with an image tuple the output pa rameters automatically become tuples as well Consequently the parameters Characters and Threshold are described as region array and integer array respectively The head section of the reference entry in figure 2 5 shows how simple and tuple mode are reflected in the operator s signatures In the procedural approach the simple and tuple mode methods of calling char threshold differ only in the type of the output parameter Threshold a pointer to a long or to a HTuple of long values respectively Note that the class HTuple can also contain arrays tuples of control parameters of mixed type please refer to se
49. he parameter section of the reference manual entry for CharThreshold In the object oriented approach simple mode and tuple mode methods use different classes for the iconic parameters HImage and HRegion vs HImageArray and HRegionArray see sections 3 1 1 and 3 1 2 for more information about these classes As in the procedural ap proach control parameters can be of a basic type simple mode only or instances of HTuple simple and tuple mode After this rather theoretic introduction let s take a look at example code In figure 2 6 char threshold is applied in simple mode i e to a single image in figure 2 7 to two im ages at once Both examples are realized both in the object oriented and in the procedural approach The examples highlight some interesting points e Creation and initialization of iconic arrays In the object oriented approach the image array can be constructed very easily by as signing the individual images to certain positions in the array using the well known array operator In the procedural approach you must explicitely create an empty object using gen empty obj and then add the images via concat obj e Access to iconic objects As expected in the object oriented approach the individual images and regions are ac cessed via the array operator the number of objects in an array can be queried via the method Num In the procedural approach objects must be selected explicitely using the operator select
50. ing one HBytelmage Image file_xyz HRegion Threshold Image Threshold 0 120 HRegionArray ConnectedRegions Threshold Connection HRegionArray ResultingRegions ConnectedRegions SelectShape area and 10 100000 This short program performs the following e pixels are selected with gray values between the range 0 and 120 e Aconnected component analysis is performed e Only regions with a size of at least 10 pixel are selected This step can be considered as a step to remove some of the noise from the image 5 2 Edge Detection For the detection of edges the following sequence of HALCON C operators can be applied HByteImage Image file_xyz HByteImage Sobel Image SobelAmp sum_abs 3 HRegion Max Sobel Threshold 30 255 HRegion Edges Max Skeleton A brief explanation e Before applying the sobel operator it might be useful first to apply a low pass filter to the image in order to suppress noise 49 50 CHAPTER 5 TYPICAL IMAGE PROCESSING PROBLEMS e Besides the sobel operator you can also use filters like EdgesImage PrewittAmp RobinsonAmp KirschAmp Roberts BandpassImage or Laplace e The threshold in our case 30 must be selected appropiately depending on data e The resulting regions are thinned by a Skeleton operator This leads to regions with a pixel width of 1 5 3 Dynamic Threshold Another way to detect edges 15 e g the following sequence HBytelmage Image file_x
51. ion of the region with a cross containing five points HRegion operator const HRegion amp reg const HRegion amp operator const HRegion amp reg Minkowsky addition of the region with another region see reference manual entry of minkowski_addl HALCON C 2005 02 01 3 1 ICONIC OBJECTS 21 HRegion operator const HRegion amp reg const HRegion amp operator const HRegion amp reg Minkowsky subtraction of the region with another region see reference manual entry of minkowski sub1 HRegion amp operator void Erosion of the region with a cross containing five points HRegion operator void const Complement of the region see reference manual entry of complement HRegion operator void const Transpose the region at the origin see reference manual entry of transpose region HRegion operator amp const HRegion amp reg const HRegion amp operator amp const HRegion amp reg Intersection of the region with another region see reference manual entry of intersection HRegion operator const HRegion amp reg const HRegion amp operator const HRegion amp reg Union of the region with another region see reference manual entry of union2 HRegion operator const HRegion amp reg const HRegion amp operator const HRegion amp reg Subtract another region from the region see reference manual entry of difference HBool operator const HRegion amp reg const Boolean test if
52. it using GenidBarCodeDescr as follows HBarCode1D barcode barcode GenidBarCodeDescr EAN 13 13 13 HALCON C 2005 02 01 2 1 CALLING HALCON OPERATORS 11 If the instance was already initialized the corresponding data structures are automatically destroyed before constructing and initializing them anew see also section 2 1 2 2 The handle classes are described in more detail in section 3 2 3 2 2 1 2 2 Destructors All HALCON C classes provide default destructors which automatically free the correspond ing memory For some classes the destructors are based on suitable operators e Windows The default destructor of the class HWindow closes the window based on close window Note that the operator itself is no destructor i e you can close a window and then open it again using OpenWindow e Other Handle Classes The default destructors of the other classes encapsulating handles e g HShapeModel or HFramegrabber apply operators like clear shape model or close framegrabber re spectively In contrast to close window these operators cannot be called via instances of the class as can be seen in the corresponding reference manual entries the same holds for operators like clear all shape models In fact there is no need to call these operators as you can initialize instances anew as described in section 2 1 2 1 Please note that you must not use operators like clear shape model clear all shape models or close frame
53. l image processing tasks The reader of this user manual should be familar with basic concepts of image analysis and the programming language The manual is divided into the following chapters e Introducing HALCON C A first example shows how easy image processing becomes using HALCON C e Basics of the HALCON C Interface This chapter describes the basics of the HALCON C 4 e g how to call HALCON oper ators in the procedural and object oriented approach e The HALCON Parameter Classes This chapter lists the parameter classes of HALCON e Creating Applications Using HALCON C This chapter explains how to compile and link C programs with HALCON C e Typical Image Processing Problems This chapter contains example programs for typical image processing tasks Release Notes Please note the latest updates of this manual e Edition 6b HALCON 6 1 4 February 2005 Errors in the example for the class HRegion and in the member function lists of HRe gionArray and Hobject have been corrected e Edition 6a HALCON 6 1 1 December 2002 An error in the description of object oriented error handling was corrected Besides the manual now warns that the user must allocate memory for output string parameters him herself Finally the manual reflects the support of gcc 3 2 e Edition 6 HALCON 6 1 June 2002 The manual has been revised and extended significantly The basics of the HALCON C interface e g how to call o
54. l approach operators return a value of the type Herror This value can fall into two categories messages H_MSG_ and errors ERR There are four different messages MSG TRUE operator terminated without an error and the result value is the boolean value true H MSG FALSE The operator terminated without an error and the result value is the boolean value false H MSG VOID The operator terminated without an error and the result value void is returned H MSG FAIL operator terminated without an error and the result value means the op erator has not performed successfully This means e g an operator is not responsible or a specific situation has not occurred Typically HALCON operators return the message H MSG TRUE if no error occurs In case of an error HALCON by default prints the corresponding error message and termi nates the program You can deactivate and reactivate this reaction by calling the operator set_check The following example code checks whether a file could be opened successfully in case of an error it prints the corresponding error message which can be determined with the operator get_error_text HALCON C 2005 02 01 2 3 MEMORY MANAGEMENT 17 Herror error num char message MAX STRING long file Set check give error error num open file not existing file input amp file Set check give error if error num H_MSG_TRUE 1 get error text error num
55. lable in procedural form e g operators creating affine transformations like vector to rigid The least trouble is caused by the basic control parameters as both approaches use the elemen tary types long etc and the class HTuple Iconic parameters and handles can be converted as follows e Converting Hobject into iconic parameter classes Hobject p image read image amp p image barcode eani3 eani301 HImage o image p image HALCON 6 1 4 18 CHAPTER 2 BASICS OF THE HALCON C INTERFACE Iconic parameters can be converted from Hobject to e g HImage simply by calling the constructor with the procedural variable as a parameter e Converting handles into handle classes HTuple p_barcode gen_1d_bar_code_descr EAN 13 13 13 amp p barcode HBarCode1D o_barcode o_barcode SetHandle p_barcode o_code_region o_barcode FindidBarCode o_image HTuple HTuple amp isfound amp elements HTuple _ Handles cannot be converted directly via a constructor instead you call the method SetHandle with the procedural handle as a parameter e Converting handle classes into handles p_barcode barcode GetHandle decode 1d code elements p barcode HTuple _ amp result HTuple _ Similarly a handle can be extracted from the corresponding class via the method GetHandle You can even omit the method as the handle classes provide cast oper ators which convert them automatically into h
56. lt width lt lt image WidthO cout lt lt height lt lt image Height lt lt endl Interactive drawing of a region by using the mouse HRegion mask w DrawRegion Reduce the domain of the image to the mask HImage reduced image amp mask w ClearWindow Clear the window reduced Display w Display the reduced image Applying the mean filter in the reduced image HImage mean reduced MeanImage 61 61 mean Display w HRegion reg bild gt mean 3 reg Display w Figure 3 5 Sample program for the use of the class HImage Figure 3 6 On the left side the input image nreut tiff and on the right side the segmented regions in the selected image domain The example starts by reading a byte image from a file The aim is to extract bright parts from the image The used filter and the segmentation process itself is applied only in a pre chosen part of the image in order to accelerate the runtime This part is selected by drawing an arbitrary region with the mouse This region mask serves as input for reducing the domain of the original image operator amp The mean filter with a mask size of 61 x 61 is applied to the resulting region HALCON 2005 02 01 3 1 ICONIC OBJECTS 29 reduced Bright pixels are selected by applying the operator gt pixels brighter than the filtered part of the image reduced 4 3 are selected Figure 3 6 shows the result of the s
57. moothed image smoothed image original image MeanImage 11 11 This simple example already shows that the two approaches result in clearly different code Be sides the different operator names procedural small letters and underscores object oriented capitals the operator calls differ in the number and type of parameters Furthermore func tionality may be available in different ways for example images can be read from files via a constructor of the class HImage In general we recommend to use the object oriented approach Note however that HDevelop can export programs only into procedural code Section 2 4 shows how to combine procedural with object oriented code In the following sections we take a closer look at various issues regarding the use of the HAL CON C interface chapter 3 describes the provided classes in more detail 2 1 Calling HALCON Operators How a HALCON operator can be called via the HALCON C interface is described in detail in the HALCON C reference manual As an example figure 2 1 shows parts of the entry for the operator nean image Below we take a closer look at the parameters of an operator call describe how to call operators via classes and explain another special HALCON concept the tuple mode 5 6 CHAPTER 2 BASICS OF THE HALCON C INTERFACE Herror mean image Hobject Image Hobject ImageMean const HTuple amp MaskWidth const HTuple amp MaskHeight HImage HImage MeanlIm
58. n be called via HRegionArray see also section 2 1 2 HRegionArray provides the following member functions e HRegionArray void Constructor for an empty array Num is 0 e HRegionArray const HRegion amp reg Constructor with a single region HALCON 2005 02 01 3 1 ICONIC OBJECTS 23 include HalconCpp h include iostream h main B HImage image mreut Reading an aerial image HRegion region image gt 190 Calculating a threshold HWindow W Display window w SetColor red Set color for regions region Display w Display the region HRegion filled region FillUpO Fill holes in region filled Display w Display the region Opening erosion followed by a dilation with a circle mask HRegion open filled gt gt 4 5 lt lt 4 5 w SetColor green Set color for regions open Display w Display the region HDPoint2D trans 100 150 Vector for translation HRegion moved open trans Translation HRegion zoomed moved 2 0 Zooming the region 1 Figure 3 1 Sample program for the application of the class HRegion Ce WB Wo 2 AB Figure 3 2 On the left the input image mreut tiff and on the right the region after the opening open e HRegionArray const HRegionArray amp arr Copy constructor e HRegionArray void Destructor e HRegionArray amp operator const HRegionArray amp arr Assignment operator HALCON
59. nstructing a pixel value from a complex number HALCON 6 1 4 30 CHAPTER 3 THE HALCON PARAMETER CLASSES HPixVal int Val Constructing a pixel value from an integer int HPixVal long Val Constructing a pixel value from a long long HPixVal HByte Val Constructing a pixel value from a byte byte HPixVal double Val Constructing a pixel value from a double double HPixVal const HPixVal amp Val Copy constructor HPixVal amp operator const HPixVal amp grey Assignment operator operator HByte void const Converting a pixel value to byte 0 255 operator int void const Converting a pixel value to int operator long void const Converting a pixel value to long operator double void const Converting a pixel value to double operator HComplex void const Converting a pixel value to Complex The handling of the class HPixVal is explained by an example in figure 3 7 which inverts an input image The input image is a byte image First a copy is generated and the image size is determined In the first run the pixels are accessed linearly In the second run the pixel are accessed via the 2 y ccordinates 3 1 2 3 Image Arrays The same way which was used to define arrays of regions is used to obtain arrays of images The class is named HImageArray and contains the following member functions in addition to the operators e HImageArray void Default constructor empty array no element HIma
60. o your program The li brary libhalconcpp so contains the various components of the HALCON C interface libhalcon so is the HALCON library Please take a look at the example makefiles for suitable settings If you call gmake without further arguments the example application ean13 will be created To create the other example applications e g example2 call gmake example2 You can use the example makefiles not only to compile and link the example programs but also your own programs if placed in the subdirectory source For example to compile and link a source file called mnyprogram cpp call gmake myprogram You can link the program to the Parallel HALCON libraries by adding PAR 1 to the make command for example gmake myprogram PAR 1 Please note that within an application you can use only one HALCON language interface be it directly or indirectly e g by including a library that uses a second interface Thus you cannot use both HALCON C and the HALCON C interface in one and the same applica tion HALCON 6 1 4 48 HALCON C 2005 02 01 CHAPTER 4 CREATING APPLICATIONS WITH HALCON C Chapter 5 Typical Image Processing Problems This chapter shows the power the HALCON system offers to find solutions for image processing problems Some typical problems are introduced together with sample solutions 5 1 Thresholding an Image Some of the most common sequences of HALCON operators may look like the follow
61. obj the number of objects can be queried via count obj e Polymorphism of Hobject part I As already noted instances of Hobject can be used both in simple and in tuple mode In HALCON 2005 02 01 2 2 ERROR HANDLING 13 HImage image alphai HRegion region long threshold region image CharThreshold image GetDomain 2 95 amp threshold image Display window region Display window cout lt lt Threshold for alphal lt lt threshold Hobject image Hobject region long num long threshold read_image amp image alphai char threshold image image amp region 2 95 amp threshold disp obj image window disp obj region window cout lt lt Threshold for alphal lt lt threshold Figure 2 6 Using CharThreshold in simple mode via HImage or in the procedural approach declaration and opening of window omitted contrast you must use different classes when switching from simple to tuple mode in the object oriented approach e Polymorphism of Hobject part II The class Hobject is used for all types of iconic objects What s more image objects can be used for parameters expecting a region as in the call to char threshold in the examples in this case the domain of the image i e the region in which the pixels are valid is extracted automatically In the object oriented approach you must extract the domain explicitely via the operator GetDomain
62. olored 12 Set colors for regions regs Display w Display the regions HRegionArray rect New array for long i 0 i lt regs Num 1 For all regions in array Test size and shape of each region if regs i Area gt 1000 regs i Compactness lt 1 5 rect Append regs il lf test true append region image Display w Display the image rect Display w Display resulting regions Figure 3 3 Sample program for use of the class HRegionArray Figure 3 4 On the left side the input image control unit tiff and on the right side the selected rectangles The first step is to read an image In this case it shows a control unit in a manufacturing environment see figure 3 4 on the left side By applying a regiongrowing algorithm from the HALCON library the image is segmented into regions Each region inside the resulting region HALCON 6 1 4 26 CHAPTER 3 THE HALCON PARAMETER CLASSES array regs is now selected according to its size and its compactness Each region of a size larger than 1000 pixels and of a compactness value smaller than 1 5 is appended to the region array rect After the processing of the for loop only the regions showing on the right side of figure 3 4 are left 3 1 2 Images There is more to HALCON images than just a matrix of pixels In HALCON this matrix is called a channel and images may consist of one or more such channels For example gray value im
63. owski sub1 HRegionArray operator void const Applying the complement operator to each region of the array see reference manual entry of complement HRegionArray operator amp const HRegionArray amp reg const Intersection of each region of the actual array with the union of reg see reference manual entry of intersection HRegionArray operator const HRegionArray amp reg const Union of each region in the actual array with the union of reg see reference manual entry of union2 HRegionArray operator const HRegionArray amp reg const Difference of each region in the actual array with the union of reg see reference manual entry of difference Most HALCON operators expecting a region for an input parameter accept an instance of HRegionArray e g Unioni Intersection Difference etc The constructor instantiat ing the region array HRegionArray from a single region HRegion makes it possible to handle HALCON 2005 02 01 3 1 ICONIC OBJECTS 25 operators expecting a single region Without changing the data structure a HRegionArray can be used as input parameter even in the case of a single region Figure 3 3 shows a short example how to use the class HRegionArray include HalconCpp h include iostream h main 3t HImage image control unit Reading an image from file Segmentation by regiongrowing HRegionArray regs image Regiongrowing 1 1 4 100 HWindow W Display window w SetC
64. perators in the procedural and in the object oriented way or how to realize error handling are now described in detail in a new chapter The section Exception Handling has been extended by an example showing how to use the exception handling mechanism try catch together with the class HException Fur thermore the chapter describing the parameter classes has been updated and now also lists the new handle classes e Edition 5b HALCON 6 0 2 February 2002 Errors in the description of the class HException were corrected e Edition 5a HALCON 6 0 1 July 2001 Since HALCON 6 0 1 does not support HP UX anymore the corresponding references have been deleted from the manual e Edition 5 HALCON 6 0 October 2000 The manual has been restructured and revised slightly especially the chapter Creating Applications Using HALCON C Contents Introducing HALCON C 11 Additional Sources of Information L2 Pit Examples 2242x999 OSS SHR E Basics of the HALCON C Interface Al Calling HALCON Operators usus n Reo a ewe ooo xs 21d Look at Parameters o a o monec 2 565 2 1 2 Calling Operators via Classes 211 9 The Tople Mode 6 dw ko x so dae eae x 33 x 3 a G 2 Emor Henne 222 6222 9 9 9 SEE SEER SES PEE SS x 2 2 1 Object Oriented Approach 2 2 2 Procedural 2 3 Memory Management
65. ricValue HTuple BarcodeFound HTuple BarCodeElements HTuple rientation const HRegion HBarCodei1D FindidBarCode const HImage amp Image const HTuple amp GenericName const HTuple amp GenericValue HTuple BarcodeFound HTuple BarCodeElements HTuple rientation const image Hobject HImage byte uint2 vodehecston outputobjech region Hobject HRegion BarCodeDescr input control barcode 1d array HTuple const char long double GenericName input control string array gt HTuple const char GenericValue input control number array HTuple double long nM integer HTuple long BarCodeElements output control number array HTuple double rstencaiton oUtputscontrol uM angle rad HTuple double Figure 2 2 The head and parts of the parameter section of the reference manual entry for find 1d bar code HImage original image monkey smoothed image smoothed image original image MeanImage 11 11 In contrast to input parameters output parameters are always modified thus they must be passed by reference Note that operators expect a pointer to an already declared variable For exam ple when calling the operator FindidBarCode as in the following lines of code vari
66. ruc tor generates an empty tuple By assigning values to the tuple it is automatically expanded and the data types of the values are also stored For accessing the tuple the normal array notation can be used If the data type of a value is not known in advance an explicit type conversion has to be performed see figure 3 9 3 2 3 Classes Encapsulating Handles The perhaps most prominent handle class is HWindow which is described in section 3 2 3 1 Starting with version 6 1 HALCON C also provides classes for handles to files or function ality like frame grabber access measuring or shape based matching See section 3 2 3 2 for an overview HALCON 6 1 4 38 CHAPTER 3 THE HALCON PARAMETER CLASSES include HalconCpp h include lt iostream h gt main ii HTuple t cout lt lt t Num lt lt n The length of the tuple is 0 pOL 1058157 Assigning values to the tuple t 1 42 LA ETATE cout lt lt t Num lt lt n The length of the tuple is 3 cout lt lt Hiluple lt lt t lt lt 27 Using the lt lt operator double d t 0 Accessing the tuple if the long 1 11 the types of the elements se PIF are known Accessing the tuple if the types of the elements are known prints Values Ag ides wn pO 500 Figure 3 9 Sample for the use of the class HTuple 3 2 3 4 Windows The class HWindow provides the management of H
67. ry of gen 1 e HImage const HImage amp image Copy constructor e virtual HImage void Destructor e HImage amp operator const HImage amp arr Assignment operator e virtual const char PixType void const Return the pixel type of the image see reference manual entry of get image pointerl1 e int Width void const Return the width of the image see reference manual entry of get image pointer HALCON C 2005 02 01 3 1 ICONIC OBJECTS 27 e int Height void const Return the height of the image see reference manual entry of get image pointer1 e HPixVal GetPixVal int x int y const Access a pixel value via the coordinates see reference manual entry of get grayval e HPixVal GetPixVal long k const Linear access of a pixel value e virtual void SetPixVal int x int y const HPixVal amp val Set the pixel value via the x y coordinates see reference manual entry of set grayval e virtual void SetPixVal long k const HPixVal amp val Set the pixel value by linear access e virtual void Display const HWindow amp w const Display an image in a window e HImage operator amp const HRegion amp reg const Reduce the domain of an image see reference manual entry of reduce domain e HImage operator const HImage amp add const Adding two images see reference manual entry of add image e HImage operator const HImage amp sub const Subtracting two images see reference manual
68. s to use the image processing power of HALCON inside programs HALCON provides operators covering a wide range of ap plications e g factory automation quality control remote sensing aerial image interpretation medical image analysis and surveillance tasks After pointing out additional sources of information about HALCON we start with a first ex ample application The following chapters describe the use of the HALCON operators in programs in more detail Chapter 2 takes a closer look at the basics of the HALCON C inter face while chapter 3 gives an overview of the HALCON s parameter classes HImage HRegion HWindow etc Chapter 4 shows how to create applications based on HALCON C Finally chapter 5 presents typical image processing problems and shows how to solve them using HAL CON C 1 1 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 C programs e HALCON COM User s Manual How to use the HALCON library in your COM programs e Extension Package Programmer s Manual How to extend the HALCON system with your own operators e Frame Grabber Integration Programmer s Manual A guide on
69. the class HPixVal is not necessary Besides the member functions of HImage the class HByteImage contains the following extensions HBytelmage void Default constructor HBytelmage const char file Constructing a byte image by reading a file HBytelmage int width int height Constructing an empty byte image of a given size HBytelmage HByte ptr int width int height Constructing a byte image by copying memory HBytelmage const HBytelmage amp image Copy constructor virtual HByteImage void Destructor HByte amp operator long Setting a pixel value by linear accessing HByte operator long const Reading a pixel value by linear accessing HALCON 6 1 4 32 CHAPTER 3 THE HALCON PARAMETER CLASSES include HalconCpp h include lt iostream h gt main i HBytelmage in mreut Aerial image HWindow w Output window in Display w Displaying the image HImage out in Copying the image int width out Width Width of the image int height out Height Height of the image long end width height Number of pixel of the image 1 run linear accessing for long k 0 k lt end k out k 255 in k Reading and setting the pixel Displaying the transformation cout lt lt Transformed lt lt endl out Display w 7 cout lt lt Original lt lt endl in Display w w Click 2 run accessing the image via the coordinat
70. tor amp 24 operator 24 55 operator 36 37 operator 37 operator 37 Sum OQ 36 HVariationModel 41 HWindow 1 10 11 18 37 39 ClickO 38 HXLD 10 19 33 HXLDArray 33 HXLDCont 10 33 HXLDPoly 33 iconic classes 17 19 iconic parameters 6 image 26 channel image matrix 26 domain area of definition 13 26 pixel type 26 region of interest ROI 26 info_framegrabber 8 intersection Intersection 21 24 invert_image InvertImage 27 kirsch amp KirschAmp 50 language interfaces HALCON COM 46 laplace Laplace 50 mean_image MeanImage 5 6 8 50 measure_pairs MeasurePairs 40 methods constructors 9 18 destructors 11 GetHandle 18 41 operators 8 SetHandle 18 41 minkowski_add1 MinkowskiAdd1 20 24 minkowski_sub1 MinkowskiSub1 21 24 moments_region_2nd MomentsRegion2nd 22 HSerial 40 mult_image MultImage 27 50 HShapeModel 10 11 40 MultImage 27 HSocket 40 new_extern_window HTemplate 40 NewExternWindow 10 HTuple 7 11 13 17 34 36 38 operator 37 object oriented 5 HALCON 6 1 4 56 open file OpenFile 40 open framegrabber OpenFramegrabber 10 17 open window OpenWindow 10 11 45 Parallel HALCON 46 47 parameters zx control 6 34 handles 6 9 34 window 6 iconic 6 simple mode 11 tuple mode 5 8 11 pixel type 26 prewitt amp PrewittAmp 50 procedural 5 programming language COM 46 read image
71. ts code examples for the three ways to call FindidBarCode When comparing the object oriented and the procedural approach you can see that the calls to the operators read image and gen 1d bar code descr are replaced by special constructors for the classes HImage and HBarCode1d respectively This topic is discussed in more detail below Please note that the two object oriented methods seem to be asymmetric If you call FindidBarCode via HImage the reference manual seems to suggest that you must pass the handle instead of an instance of HBarCode1d In fact you can pass both a handle and a class in stance because the latter is automatically casted into a handle the signature was not changed to keep the HALCON C interface backward compatible as far as possible 2 1 2 1 Constructors As can be seen in figure 2 4 the HALCON C parameter classes provide additional con structors which are based on suitable HALCON operators The constructors for HImage and HBarCodetd used in the example are based on read image and gen 14 bar code descr re spectively Please note that in the current HALCON version constructors are provided inconsistently for the different classes Below we take a brief look at the most important classes A complete and up to date list of available constructors can be found in the corresponding header files in AHALCONROOT NincludeNcpp e Images The class HImage provides constructors based on the operators read imag
72. uble Figure 2 3 The head and parts of the parameter section of the reference manual entry for info framegrabber Many HALCON operators accept more than one value for certain parameters For example you can call the operator MeanImage with an array of images see figure 2 1 then an array of smoothed images is returned This is called the tuple mode see section 2 1 3 for more informa tion Please note that output parameters of the type string need special attention First of all you must allocate memory for them yourself e g by declaring them as character arrays secondly you don t pass them by reference because such parameters are pointers already In the following example code the operator info framegrabber see also figure 2 3 is called with two output string parameters to query the currently installed PicPort frame grabber board const char FGName PicPort char sInfo MAX STRING sValue MAX_STRING info framegrabber FGName info boards sInfo sValue Note that it isn t necessary to allocate memory for output string parameters in the already men tioned tuple mode i e when using instances of the class HTuple instead of plain strings also see sections 2 1 3 and 3 2 2 HTuple tInfo tValues info framegrabber FGName camera types amp tInfo amp tValues 2 1 2 Calling Operators via Classes As already described in the previous section the HALCON C reference manual shows via which classes an
73. umber of warning messages about missing header files These can safely be ignored Please assure that the stacksize is sufficient Some sophisticated image processing problems require up to 6 MB stacksize so make sure to set the settings of your compiler accordingly See your compiler manual for additional information on this topic If you want to use Parallel HALCON you have to link the libraries parhalcon lib d11 and parhalconcpp lib dll instead of 1 115 411 and halconcpp lib dll in your project Please note that within an application you can use only one HALCON language interface be it directly or indirectly e g by including a DLL that uses a second interface Thus you cannot use both the HALCON C and the HALCON COM interface in one and the same application 4 2 Creating Applications Under UNIX Your own C programs that use HALCON operators must include the file HalconCpp h which contains all user relevant definitions of the HALCON system and the declarations nec essary for the interface Do this by adding the command include HalconCpp h near the top of your C file Using this syntax the compiler looks for HalconCpp h in the current directory only Alternatively you can tell the compiler where to find the file giving it the I lt pathname gt command line flag to denote the include file directory HALCON C 2005 02 01 4 2 UNIX 47 To create an application you have to link two libraries t
74. y handles are almost always represented by discrete numbers long a notable exception is the handle to a bar code descriptor which is an HTuple as be seen in figure 2 2 For handles there exist corresponding classes which are described in section 3 2 3 With the class HTuple HALCON C provides a container class for control parameters What s more HTuple is polymorphic i e it can also contain arrays of control parameters of mixed type To realize this the auxiliary class HCtr1Val is introduced which is described in the next section 3 2 1 The Basic Class for Control Parameters The class HCtrlVal serves as the basis for the class HTuple and is normally hidden from the user because it is only used temporarily for type conversion The main point is that it can contain the three elementary types of control parameters i e discrete numbers long float ing point numbers double and strings char HCtrlVal provides the following member functions e HCtrlVal void Default constructor e HCtrlVal long 1 Constructing a value from long e HCtrlVal int 1 Constructing a value from int HALCON C 2005 02 01 3 2 CONTROL PARAMETERS HCtrlVal double d Constructing a value from double HCtrlVal const char s Constructing a value from char HCtrlVal const HCtrlVal amp v Copy constructor HCtr1Val void Destructor HCtrlVal amp operator const HCtrlVal amp v Assignment operator int V
75. yz HByteImage Mean Image MeanImage 11 11 HRegion Threshold Image DynThreshold Mean 5 light Again some remarks e The size of the filter mask in our case 11 x 11 is correlated with the size of the objects which have to be found in the image In fact the sizes are proportional e The dynamic threshold selects the pixels with a positive gray value difference of more than 5 brighter than the local environment mask 11 x 11 5 4 Texture Transformation Texture transformation is useful in order to obtain specific frequency bands in an image Thus a texture filter detects specific structures in an image In the following case this structure depends on the chosen filter 16 are available for the operator TextureLaws HByteImage Image file_xyz HByteImage TT Image TextureLaws Image ee 2 5 HBytelmage Mean TT MeanImage 71 71 HRegion Reg Mean Threshold 30 255 e The mean filter MeanImage is applied with a large mask size in order to smooth the fre quency image e You can also apply several texture transformations and combine the results by using the operators AddImage and MultImage 5 5 Eliminating Small Objects The following morphological operator eliminates small objects and smoothes the contours of regions HALCON C 2005 02 01 5 6 SELECTING ORIENTED OBJECTS 51 segmentation Image amp Seg HCircle Circle 100 100 3 5 HRegionArray Res Seg Opening Circle e The term se

HALCON/C++ User`s Manual

Contents

Download Pdf Manuals

Related Search

Related Contents