HALCON/C User`s Manual
Contents
1. 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 The HALCON Parameter Classes This chapter describes how to use the parameter classes of HALCON in your C program e Return Values of HALCON Operators This chapter explains how to deal with the return values of HALCON operators e HALCON for Philips TriMedia DSPs This chapter gives an overview over the HALCON version for Philips TriMedia DSPs e Generation of HALCON C Applications 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 5a HALCON 6 0 1 July 2001 The manual now also describes how to use HALCON on Philips Tr Media DSPs 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 September 2000 The manual has been restructured and revised slightly especially the chapter Generation of HALCON C Applications Contents 1 Introducing HALCON C 1 1 Additional Sources of Information 1 2 A First Example 4chox he x ae Owe REE REDE RRR a 2 The HALCON Parameter Classes el Se wae eee ee eee Ee ee RR 3 a 2 2 Controlparameters usu eee Ro ox ow a eee ae2. HALCON for TriMedia contains all relevant parts of the HALCON image processing library plus the HALCON C interface The decision was made in favour of the C interface because it produces slightly more efficient code regarding runtime and code size than the corresponding HALCON C interface Taking into account the special requirements of the TriMedia the image processing library 1s built with an emphasis on optimizing runtime code size and memory allocation behavior This implies that parts not necessary for image processing as well as some online support features like textual error reports are left out of the library The remainder of the chapter is dedicated to explaining the differences between HALCON for TriMedia and standard HALCON Currently HALCON for TriMedia runs on the TriMedia vision boards Allegro Fuga and Presto To support the existing TriMedia hardware the Philips image processing software Rhapsody version 2 0 has to be installed on the system 17 18 4 1 CHAPTER 4 HALCON FOR PHILIPS TRIMEDIA DSPS Limitations Following functionalities of the standard HALCON image processing l brary are not contained In HALCON for TriMedia X Windows and Windows NT 2000 XP display methods Frame grabber support Serial 1 0 Socket I 0 HALCON Spy Gnuplot Online information about arbitrary HALCON operators Textual HALCON error messages The only supported image file formats are ima tiff and bmp Corresponding to above en
3. control parameter tuples for HALCON operators need special treat ment In this chapter we will give the details on how to construct and use those tuples The HALCON C 2003 08 01 2 2 CONTROL PARAMETERS 9 HALCON reference manual describes a large number of operators that don t operate on single control values but on tuples of values Using those operators it 1s easy to write very compact and efficient programs because often it 1s possible to combine multiple similar operator calls into a single call Unfortunately C provides no generic tuple or list constructor In contrast HALCON allows tuples with mixed types as control parameter values e g integers mixed with floating point numbers Therefore in addition to the very intuitive simple mode there is another mode in HALCON C The tuple mode Using this mode s a little more elaborate If at least one of the control parameters of a HALCON operator is passed as a tuple the tuple mode has to be used for all control parameters Mixing of both modes isn t possible Furthermore the tuple mode also has to be used 1f the number or type of the calculated values aren t known beforehand Syntactically tuple mode is distinguished from simple mode by a T_ preceeding the operator name For example calling disp_circle in tuple mode is done by T_disp_circle To ease the usage of the tuple mode HALCON C provides the abstract data type Htuple for control parameter tuples Objects
4. of type Htuple may be constructed using values of the types e long for integers HALCON type INT_PAR e double for floating point numbers DOUBLE_PAR or e char for character arrays strings STRING_PAR in arbitrary combination Control parameter tuples must be created deleted and manipulated using the appropriate HALCON C operators only overview in figures 2 2 and 2 3 The rules for parameter passing are valid in tuple mode too Input control parameters type Htuple are passed by value as usual output control parameters are passed by reference us ing the amp operator Output parameters that are of no further interest can be denoted by the anonymous variable t instead of a dummy tuple Let s summarize the five most important steps when calling a HALCON operator in tuple mode l step First memory must be allocated for all tuples of input control parameters using create tuple Memory for output control parameter tuples is allocated by HAL CON C a call of create tuple isn t necessary 2 step Now the input control parameter tuples are constructed using the appropriate set _ operators set_s which inserts a string into a tuple allocates the needed memory by itself and then copies the string 3 step Then the HALCON operator is actually called The operator name is as already explained preceeded by a T denote tuple mode HALCON 6 0 4 10 CHAPTER 2 THE HALCON PARAMETER CLASSES 4 step Further proces
5. operation or that a specific event didn t happen Nearly all HALCON operators return H_MSG_TRUE if no error occurs Errors in HALCON operators usually result in an exception 1 e a program abort with the appropriate error message in HALCON C default exception handling However users can disable this mechanism with a few exceptions like errors in Htuple operators using set check give error to provide their own error handling routines In that case the operator error text is very useful This operator returns the plain text message for any given error number Finally the operator set check give error enables the HALCON error handling again Several examples showing the handling of error messages can be seen in the file exampleb 15 16 CHAPTER 3 RETURN VALUES OF HALCON OPERATORS HALCON C 2003 08 01 Chapter 4 HALCON for Philips TriMedia DSPs The Philips TriMedia is a real time Digital Signal Processor DSP used primarily for multi media applications Development and execution of TriMedia software are supported by the TriMedia SDE runtime and development software that has to be installed on a host computer running under Windows NT 2000 XP The TriMedia Compilation System TCS translates C and C programs generating code for a machine in the TriMedia architecture family The gen erated executables can be loaded and run on the TriMedia via the host using e g the TriMedia loader tmrun
6. set_d tuple val index or macro SD tuple val index Htuple tuple double val long index inserts a double with value val into a tuple at position index index in O length_tuple tuple 11 void set_s tuple val index or macro SS tuple val index Htuple tuple char val long index inserts a copy of string val into a tuple at position index index in O length_tuple tuple 1 The memory necessary for the string is allocated by set_s Figure 2 2 HALCON C Htuple operators part one HALCON C 2003 08 01 2 2 CONTROL PARAMETERS 11 int get_type tuple index or macro GT tuple index Htuple tuple long index returns the type of the value at position index in the tuple Possible values INT_PAR DOUBLE_PAR or STRING_PAR long get_i tuple index or macro GI tuple index Htuple tuple long index returns the integer at position index in the tuple a type error results in a run time error double get_d tuple index or macro GD tuple index Htuple tuple long index returns the floating point number at position index in the tuple a type error results in a run time error char get_s tuple index or macro GS tuple index Htuple tuple long index returns the pointer to the string at position index in the tuple a type error results in a run time error Atte
7. wee es Z1 TheSimple MODE lt a deeb Ow OR OE do ELDRED ded 254 Tho Tope Modo o osa Ru nun nea eh iR rien 3 Return Values of HALCON Operators 4 HALCON for Philips TriMedia DSPs 4 1 Limitations 42 Memory Management usu o uoc oum komm RE ad A A e 5 Generation of HALCON C Applications 5 1 Windows 2000 D AAA eo NO 6 Typical Image Processing Problems 61 Thresholding 6 2 Detecting Edges uu aoo oe nn ER EER a a u OE RO ha ha and 6 3 6 4 Simple Texture Transformations 6 5 Eliminating Small Objects 6 6 Selecting Specific Orientations 6 7 Smoothing Region Boundaries N e COON Nn yu 15 17 18 19 21 23 24 23 Chapter 1 Introducing HALCON C HALCON C is the interface of the image analysis system HALCON to the programming lan guage C Together with the HALCON library it allows to use the image processing power of HALCON inside C programs After pointing out additional sources of information about HALCON we start with a first exam ple application The following chapters describe the details of integrating HALCON operators into C programs Chapter 2 introduces the four different parameter classes of HALCON oper ators We will explain
8. ATIONS 29 segmentation Image amp Seg gen_circle amp Mask 100 0 100 0 3 5 opening Seg Mask amp Res e The size of the circular mask 3 5 In this case determines the smallest size of the remain ing objects e It is possible to use any kind of mask for object elimination not only circular masks e segmentation is used to denote a segmentation operator that calculates a tuple of image objects Seg 6 6 Selecting Specific Orientations Yet another application example of morphological operations is the selection of image objects with specific orientations segmentation Image amp Seg gen_rectangle2 amp Mask 100 0 100 0 0 5 21 0 2 0 opening Seg Mask amp Res e The rectangle s shape and size length and width determine the smallest size of the re maining objects e The rectangle s orientation determines the orientation of the remaining regions In this case the main axis and the horizontal axis form an angle of 0 5 rad e Lines with an orientation different from the mask s 1 e the rectangle s orientation are suppressed e segmentation is used to denote a segmentation operator that calculates a tuple of image objects Seg 6 7 Smoothing Region Boundaries The third and final application example of morphological operations covers another common image processing problem the smoothing of region boundaries and closing of small holes in the regions segmentation Image kS
9. HALCON Version 6 0 4 MT MVTec Software GmbH HALCON Users Manual How to use the mage analys s tool HALCON Version 6 0 4 In your own C 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 EC Copyright 1997 2003 by MVTec Software GmbH M nchen Germany Microsoft Windows Windows NT Windows 2000 Windows XP and Visual C are either trademarks or registered trademarks of Microsoft Corporation All 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 C It provides all necessary information to understand and use the provided data structures and mechanisms in your own programs A set of example programs shows how to apply HALCON C to solve typical image processing tasks The reader of this user manual should be familar with basic concepts of image analysis and the programming language C
10. HAPTER 5 GENERATION OF HALCON C APPLICATIONS Chapter 6 Typical Image Processing Problems This final chapter shows the possibilities of HALCON and HALCON C on the basis of several simple image processing problems 6 1 Thresholding One of the most common HALCON operators is the following read image amp Image File xyz threshold Image amp Thres 0 0 120 0 connection Thres amp Conn select shape Conn amp Result area and 10 0 100000 0 Step by step explanation of the code e First all image pixels with gray values between 0 and 120 channel 1 are selected e The remaining image regions are split into connected components e By suppressing regions that are too small noise is eliminated 6 2 Detecting Edges The following HALCON C sequence is suitable for edge detection read image amp Image File xyz sobel amp Image amp Sobel sum abs 3 threshold Sobel amp Max 30 0 255 0 skeleton Max amp Edges Some remarks about the code e Before filtering edges with the sobel operator a low pass filter may be useful to suppress noise 27 28 CHAPTER 6 TYPICAL IMAGE PROCESSING PROBLEMS e Apart from the sobel operator filters like edges_image roberts bandpass_image or laplace are suitable for edge detection too e The threshold 30 0 in this case has to be selected depending on the actual images or depending on the quality of the edges found in the image e Before any further processing
11. Some HALCON operators like neighbor or difference allow the use of the following specific image objects as input parameters NO_OBJECTS An empty tuple of image objects EMPTY_REGION An image object with empty region area 0 FULL_REGION An image object with maximal region These objects may be returned by HALCON operators too 2 2 Control parameters HALCON C supports the following data types as types for control parameters of HALCON operators e integers HALCON C 2003 08 01 2 2 CONTROL PARAMETERS 7 Hobject objects tuple of image objects Hobject obj single image object long surrogate object key converted to integer Htuple Tsurrogates tuple of object keys Htuple Index Num temporary tuple for parameter passing long i loop variable long num number of objects count_obj amp num variant 1 object key gt control parameter create_tuple amp Index 1 set_i Index 1 0 create_tuple amp Num 1 set_i Num num 0 T_obj_to_integer objects Index Num amp Tsurrogates for i20 i lt num i i surrogate get i Tsurrogates i process single object variant 2 copying objects individually for 1 i lt num i x copy_obj objects amp obj i 1 process single object Figure 2 1 Accessing the i th image object in a tuple of image objects e floating point numbers e character arrays st
12. arted 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 s 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 s also used in the sample makefile The variable ARCHITECTURE describes the platform HALCON is used on The following ta ble gives an overview of the currently supported platforms and the corresponding values of ARCHITECTURE HALCON C 2003 08 01 5 1 WINDOWS NT 2000 XP 23 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 Linux 2 2 2 4 on Intel Pentium or compatible poc 2 95 Solaris 7 on Sparc Workstations UU 50 mips sgi irix6 5 IRIX 6 5 on SGI Workstations Mips processors CC alpha compaq osf5 1 Tru64 UNIX 5 1 on Alpha processors uM Philips Tr Media DSPs nt mns En on host Windows NT 4 0 2000 XP 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 pro
13. by the example programs help english Files necessary for online information doc 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 examplei c reads an image and demonstrates several graphics operators example2 c introduces several image processing operators example3 c is an example for the usage of the tuple mode example4 c shows more basic image processing operators like the sobel filter for edge detection region growing thresholding histograms the skeleton operator and the usage of different color lookup tables example5 c describes the HALCON messages and error handling example6 c demonstrates the generic calling interface for the tuple mode T_call_halcon example7 c describes the handling of RGB images example8 c demonstrates the creation of an image from user memory example9 c describes some additional handling of RGB images A special case is the example program example_multithreadedi c It demonstrates the use of Parallel HALCON in a multithreaded application Please note that this example must be linked to the libraries of Parallel HALCON as described in the following sections Of course it does not make sense to run on a single processor computer In the following we briefly describe the relevant environment variables see the manual Getting St
14. control parameters see Chap ter 2 2 2 for details and the data structure Hobject for image objects single objects as well as object tuples see Chapter 2 1 2 1 Image objects Image processing isn t possible without actual images By using image objects HALCON provides a abstract data model that covers a lot more than simple image arrays Basically there are two different types of image objects e Images e Regions 6 CHAPTER 2 THE HALCON PARAMETER CLASSES A region consists of a set of coordinate values in the image plane Regions do not need to be connected and may include holes They may even be larger than the image format Internally regions are stored in the so called runlength encoding Images consist of at least one image array and a region the so called domain The domain denotes the pixels that are defined 1 HALCON operators working on gray values will only access pixels in this region But HALCON supports multi channel images too Images may consist of an almost arbitrary number of channels An image coordinate therefore isn t necessarily represented by a single gray value but by a vector of up to n gray values if the coordinate lies within the image region This may be visualized as a stack of image arrays instead of a single array RGB or voxel images may be represented this way HALCON provides operators for region transformations among them a large number of mor phological opera
15. ects of memory allocation behavior The HALCON sys tem parameter alloctmp single block can be used to manipulate the internal HALCON stack management If set true all allocated stack memory is released immediately when no longer in use and only as much new stack memory as needed 1s allocated A slightly weaker approach in order to limit the size of internally allocated memory is to use the system parameter al loctmp_max_blocksize to manually determine the maximum size of temporary memory blocks which in the default case would be estimated internally by HALCON If alloctmp_single_block is true alloctmp max blocksize has no effect Furthermore the general HALCON memory management is modified to only allocate storage blocks of the size requested by a given operator and to free all storage not longer needed without further internal usage Generally the above modifications are aimed to reduce the amount of dynamically allocated memory without having considerable negative effects on runtime behavior In addition the HALCON system parameters external_alloc_funct and external free funct can be used to pass pointers to external functions for allocat ng and deallocating memory for HALCON im ages This can e g be useful if result images should always be written to the same position within memory HALCON 6 0 4 20 HALCON C 2003 08 01 CHAPTER 4 HALCON FOR PHILIPS TRIMEDIA DSPS Chapter 5 Generation of HALCON C A
16. eg gen_circle amp Mask 100 0 100 0 3 5 closing Seg Mask amp Res e For the smoothing of region boundaries circular masks are suited best e The mask size determines the degree of the smoothing HALCON 6 0 4 30 CHAPTER 6 TYPICAL IMAGE PROCESSING PROBLEMS e segmentation is used to denote a segmentation operator that calculates a tuple of image objects Seg HALCON C 2003 08 01
17. es the project should be of the WIN 32 ConsoleApplication type Please note that the Visual C compiler formerly called DIGITAL UNIX HALCON 6 0 4 24 CHAPTER 5 GENERATION OF HALCON C APPLICATIONS 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 HalconC h in cludes several UNIX specific headers as well f included under UNIX Since they don t exist under Windows and the Visual C compiler is dumb enough to ignore the operating system specific cases in the include files you will get a number 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 dll and parhalconc lib dll instead of halcon 1ib d11 and halconc lib dll in your project 5 2 Creating Applications Under UNIX Your own C programs that use HALCON operators must include the file HalconC h which contains all user relevant definitions of the HALCON system and the declarations necessary for the C interface Do this by adding the command include HalconC h near the top of your C file Using this s
18. getline style get line width get paint get part get part style get pixel get rgb get shape set color set colored set comprise set draw set gray set hsi set insert set line approx set line style set line width set paint set part set part style set pixel set rgb set shape disp xld write shape model read shape model set framegrabber lut get framegrabber lut open framegrabber close framegrabber close_all_framegrabbers info framegrabber grab image grab image start grab image async grab_region grab region async set framegrabber param get framegrabber param open serial close_serial close all serials set serial param get serial param read serial write serial clear serial open socket accept open socket connect socket accept connect close socket get next socket data type send tuple receive tuple send xld receive xld send region receive region send image receive image get spy set spy query spy gnuplot_open_pipe gnuplot_open file gnuplot close gnuplot_plot_image gnuplot plot ctrl gnu plot plot funct 14 disp info get chapter info get keywords search_operator get param info get operator info get operator name query param info query operator info HALCON C 2003 08 01 4 2 MEMORY MANAGEMENT 19 4 2 Memory Management Due to hardware memory limitations on the Tr Media HALCON for TriMedia should differ from standard HALCON in certain asp
19. grams The default directory for the HALCON operator read image to look for images is 4HALCONROOT A images If the images reside in different directories the appropriate path must be set in read image or the default image directory must be changed using set system image dir This 1s also possible with the environment variable HALCONIMAGES It has to be set before start ing 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 the machine that is specified in the environment variable 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 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 5 1 Creating Applications Under Windows NT 2000 XP Your own C programs that use HALCON operators must include the file HalconC h which contains all user relevant definitions of the HALCON system and the declarations necessary for the C interface Do this by adding the command include HalconC h near the top of your C file In order to create an application you must link the library halconc lib d11 to your program The example projects show the necessary Visual C settings For the exampl
20. j conn clear obj area clear_obj eyes Figure 1 2 Introductory example program HALCON 6 0 4 4 CHAPTER 1 INTRODUCING HALCON C HALCON C 2003 08 01 Chapter 2 The HALCON Parameter Classes HALCON distinguishes four different classes of operator parameters e Input image objects e Output image objects e Input control parameters e Output control parameters Input parameters are passed by value output parameters are passed by reference using the amp operator An exception to this rule are output control parameters of type char Here the caller has to provide the memory and only a pointer to that memory 1s passed to the operator As a rule of thumb all HALCON operators can also be called using tuples of parameters in stead of single values Take the connection operator from our example program in the previous chapter It calculates a tuple of output image objects the connected components Of course there are several HALCON operators that cannot be called with tuples for some or all parameters Whether this 1s the case for specific operators 1s described in detail in the HAL CON reference manual Unfortunately C doesn t provide a generic list constructor e g like the one in PROLOG Therefore the use of tuples of control parameters 1s a little elaborate Using tuples of image objects on the other hand ls In no way different from using single values HALCON C provides the data structure Htuple for tuples of
21. nly value of ino c first query free parameter number of system flags th system flag prepare query insert i th system flag print name T_get_system In amp Info get corresponding info destroy_tuple In free parameter switch get_type Info 0 print the value according to the flag s type case INT_PAR printi Cintra dct os p break case DOUBLE PAR printf double ffAn get_d info 0 break case STRING_PAR printf string 4s a get_s info 0 break i destroy_tuple Info free parameter for i 13 ui 7 7 7 Figure 2 5 Tuple mode example program Printing the current HALCON system state HALCON 6 0 4 14 CHAPTER 2 THE HALCON PARAMETER CLASSES HALCON C 2003 08 01 Chapter 3 Return Values of HALCON Operators HALCON operator return values type Herror can be divided into two categories e Messages H_MSG_ and e Errors H_ERR_ According to its procedural concept HALCON distinguishes four kinds of messages e H_MSG_TRUE The operator finished without error and returns the boolean value true e H_MSG_FALSE The operator finished without error and returns the boolean value false e H_MSG_VOID The operator finished without error but doesn t return a value e H_MSG_FAIL the operator finished without error and returns operation failed This could mean that the operator doesn t consider itself relevant for the
22. ntion all indices must be in 0 length_tuple tuple 1 Figure 2 3 HALCON C Htuple operators part two Before we end this chapter with a short example program we will explain an alternative generic calling mechanism for HALCON operators in tuple mode This mechanism is intended for the use in interpreters or graphical user interfaces T_call_halcon ProcName calls the HALCON operator ProcName in tuple mode To do so the operator parameters have to be set first using set_in_opar set_out_opar set_in_tpar und set_out_tpar Accessing these parameters is still possible with the ordinary tuple operators Figure 2 4 sum marizes the operators of the generic HALCON C calling interface But now to the mentioned example program see figure 2 5 or the file example3 c The aim 15 to get informations about the current HALCON system state The HALCON opera tor get_system Values here in HDevelop syntax returns all system flags with their HALCON 6 0 4 12 CHAPTER 2 THE HALCON PARAMETER CLASSES void set_in_opar obj par or macro IO obj par Hobject obj par defines obj as input image object parameter no par inside the input image object parameter parameter class void set_out_opar obj par or macro OO obj par Hobject obj par defines obj as output image object parameter no par inside the output image object parameter parameter class void set_in_
23. ny C program Their use 1s very intuitive Users don t have to think about the basic data structures and algorithms involved And since all HALCON operators are hardware independent users don t even have to care about things like different I O devices HALCON has its own memory management and provides a sophisticated runtime environment HALCON C 2003 08 01 1 2 A FIRSTEXAMPLE 3 include HalconcC hy main 1 Hobject mandrill thresh conn area eyes required objects long WindowHandle open window 0 0 512 512 0 visible WindowHandle open window read image amp mandrill monkey read input image monkey x disp image mandrill WindowHandle display input image get mbutton WindowHandle wait for mouse click Select image region with pixels in 128 255 threshold mandrill amp thresh 128 0 255 0 connection thresh amp conn compute connected components select regions with an area of at least 500 pixels select shape conn amp area area and 500 0 90000 0 select the eyes in these regions by using the anisometry feature select shape area amp eyes anisometry and 1 0 1 7 disp region eyes WindowHandle display result get mbutton WindowHandle wait for mouse click close_window WindowHandle close window delete image objects from the Halcon database clear obj mandrill clear obj thresh clear ob
24. pplications The HALCON distribution contains examples for building an application w th HALCON C Here is an overview of HALCON C Windows notation of paths include c HalconC 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 halconc lib halconc dl1 The HALCON C library Windows NT 2000 XP bin i586 nt4 parhalcon 1lib parhalcon d1ll parhalconc 1lib parhalconc d1l The corresponding libraries of Parallel HALCON Windows NT 2000 XP 1ib ZARCHITECTURE libhalcon so The HALCON library UNIX 1ib ARCHITECTUREA libhalconc so The HALCON C library UNIX 1ibVAARCHITECTURE M libparhalcon so libparhalconc so The corresponding libraries of Parallel HALCON UNIX lib Vtmix philips nt4Mlibhalcon a The HALCON library for Philips TriMedia DSPs include V cMHProto h External function declarations examples Vc Vexamplei1 11 c Example programs examples c i586 nt4 examplei 11 Example projects to compile and link the example programs Windows NT 2000 XP 21 22 CHAPTER 5 GENERATION OF HALCON C APPLICATIONS examples trimedia dev HDevelop example programs that can be exported to C and run on TriMedia DSPs examples c makefile make ARCHITECTUREfS Example makefiles to compile the example programs UNIX images Images used
25. rface 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 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 Before going into the details of HALCON C let s have a look at a small example Given the image of a mandrill in figure 1 1 left the goal is to segment its eyes This is done by the C program shown in figure 1 2 The segmentation result is shown in figure 1 1 right Lt LM PPA d P dA 2 ee 7 Iri Figure 1 1 To the left the image of a mandrill is shown input image To the right the result of the segmentation process in the example program can be seen eyes The program s quite self explanatory We will describe the bas c principles nevertheless First all image pixels with gray values greater than 128 are selected Then all connected components of the region formed by these pixels are calculated The corresponding HALCON operator calculates a region tuple and thus splits the image in different regions objects From these the mandrill s eyes are selected by their area and shape This example shows how easy it is to integrate HALCON operators in a
26. rings As already mentioned in the introduction to this chapter using control parameter tuples in C isn t as elegant as using image object tuples To circumvent the missing generic lists in C it was necessary to introduce two different working modes into HALCON C The simple mode and the tuple mode If a tuple is necessary for at least one control parameter the tuple mode has to be used for operator calls In tuple mode all control parameters of an operator must be passed as type Htuple Mixing of the two modes is not possible The tuple mode also has to be used if the number or type of values that a operators calculates isn t known beforehand Mentioning the control parameter types How is the default type of control parameters deter mined for a given operator Basically there are three ways 1 The operator description in the HALCON reference manual 2 the HALCON system operator get_param_info and 3 the description of the HALCON interface in the file HProto h HALCON 6 0 4 8 CHAPTER 2 THE HALCON PARAMETER CLASSES Sometimes the manuals mention more than one possible type If only integers and floating point numbers are allowed for a parameter values have to be passed as parameters of type double For all other combinations of types the tuple mode has to be used HALCON operators that are called in tuple mode are distinguished from simple mode calls by a preceeding T_ That means select_shape is a call of
27. sing of the output parameter tuples takes place using the operators length_tuple get_type and get_ When processing strings using get_s please note that the allocated memory is freed automatically upon deleting the tuple with destroy_tuple If the string has to be processed even after the deletion of the tuple the whole string must be copied first The maximal string length incl ter mination character 0 in HALCON is MAX_STRING 1024 in HALCON version 6 0 4 5 step Finally the memory allocated by all the tuples input and output has to be freed again This is done with destroy_tuple If you still need the values of the tuple variables remember to copy them first Now the whole series can start again using different or the same tuple variables void create_tuple tuple length or macro CT tuple length Htuple tuple long length creates a tuple that can hold length entries void destroy_tuple tuple or macro DT tuple Htuple tuple deletes a tuple if the tuple contains string entries the memory allocated by the strings is freed too long length_tuple tuple or macro LT tuple Htuple tuple returns the length of a tuple number of entries void set_i tuple val index or macro SI tuple val index Htuple tuple long long UE inserts an integer with value val into a tuple at position index index in O length_tuple tuple 11 void
28. the HALCON operator select_shape as described in the HALCON reference manual in simple mode whereas T_select_shape is a call of the same operator in tuple mode 2 2 1 The Simple Mode In the so called simple mode all operators described in the HALCON reference manual can be used in a very intuitive way in your own C programs All control parameters are variables or constants of the data types e long for integers HALCON type INT_PAR e double for floating point numbers DOUBLE_PAR or e char for character arrays strings STRING_PAR long and double input control parameters are passed by value as usual the corresponding output control parameters are passed by reference using the amp operator String parameters are pointers to char in both cases Please note that the memory for output control parameters esp strings has to be provided by the caller Output parameter values that are of no further interest can be denoted by the anonymous variables e _ or _i for long parameters e _d for double parameters and 66 99 e _s for char parameters As an example for the use of anonymous variables see the small introductory program in figure 1 2 We coded get_mbutton WindowHandle _ _ _ because the actual button pressed is of no further interest Examples for HALCON operator calls in simple mode can be found in the C programs in figures 1 2 and 2 1 2 2 2 The Tuple Mode We mentioned already that
29. the edges are reduced to the width of a single pixel using skeleton 6 3 Dynamic Threshold Among other things the following code is suitable for edge detection too read image amp Image File xyz mean image Image amp Lp 11 11 dyn threshold Image Lp amp Thres 5 0 light e The size of the filter mask 11 x 11 in this case depends directly on the size of the expected objects both sizes are directly proportional to each other e In this example the dynamic threshold operator selects all pixels that are at least 5 gray values brighter than their surrounding 11 x 11 pixels 6 4 Simple Texture Transformations Texture transformations are used to enhance specific image structures The behavior of the transformation depends on the filters used HALCON provides 16 different texture filters read image amp Image File xyz Filter ee texture_laws Image amp TT Filter 2 5 mean_image TT amp Lp 31 31 threshold Lp amp Seg 30 0 255 0 e mean_image has to be called with a large mask to achieve a sufficient generaliza tion e It is also possible to calculate several different texture transformations and to combine them later using add_image mult_image or a similar operator 6 5 Eliminating Small Objects The following morphological operation eliminates small image objects and smoothes the boundaries of the remaining objects HALCON C 2003 08 01 6 6 SELECTING SPECIFIC ORIENT
30. the use of HALCON tuples chapter 2 2 2 for supplying operators with tuples of control parameters in great detail Using tuples the two select_shape calls in our example program could be combined into only one call Chapter 3 is dedicated to the return values of HALCON operators Chapter 5 gives an overview over all the include files and C libraries necessary for compiling C programs and shows how to create a stand alone ap plication Finally chapter 6 contains example solutions for some common problems in image processing like edge detection 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 Programmers Manual A guide on how to integrate a new frame grabber in the HALCON system Note that 2 CHAPTER 1 INTRODUCING HALCON C in some cases you might define new operators using the Extension Package Interface instead of using the standard HALCON Frame Grabber Integration Inte
31. tion and thus can be compiled and run on the TriMedia without further modification Make sure that the TriMedia SDE runtime and development software is installed properly on your system and the environment variable TRI MEDIAROOT is set to the SDE install directory Your own C programs that use HALCON operators must include the file HalconC h which contains all user relevant definitions of the HALCON system and the declarations necessary for the C interface Do this by adding the command include oic near the top of your C file To create an application you have to link the libraries libhalconc a and libhalcon a to your program libhalconc a contains the HALCON C interface and libhalcon a contains the HALCON image processing library Additionally you currently have to link the Philips image processing library Rhapsody version 2 0 allowing hardware sup port for the TriMedia Please take a look at the makefile for suitable settings To create an application e g test call nmake TEST_PROG test from a command shell You can load and run the application onto the Tr Media by calling tmrun test The majority of the HDevelop programs in HALCONROOT examples trimedia write out put data to file as either image or region format This 1s done to compensate for the lack of display routines in HALCON for TriMedia that otherwise would be used to visualize and thus verify the output results HALCON 6 0 4 26 HALCON C 2003 08 01 C
32. tors as well as operators for gray value transformations Segmentation opera tors are the transition from images gray values to regions HALCON C provides the data type Hobject for image objects both images and regions In fact Hobject is a surrogate of the HALCON database containing all image objects Input image objects are passed to the HALCON operators by value as usual output image objects are passed by reference using the amp operator Variables of type Hobject may be a single image object as well as tuples of image objects Single objects are treated as tuples with length one Of course users can access specific objects in an object tuple too To do so it is nec essary to extract the specific object key converted to integer first using the operators obj_to_integer or copy_obj The number of objects in a tuple can be queried with count_obj To convert the keys returned from obj_to_integer back to im age objects again the operator integer_to_obj has to be used It may be noted that integer_to_obj duplicates the image objects Don t worry this doesn t mean neces sarily that the corresponding gray value arrays are duplicated too As long as there is only read access a duplication of the references is sufficient Therefore all extracted objects have to be deleted explicitly from the HALCON database using clear_obj Figure 2 1 con tains an excerpt from a C program to clarify that approach
33. tpar tuple par GE macro IT tuple par Htuple tuple defines tuple as input control parameter no inside the input control parameter parameter class void set_out_tpar tuple par or macro OT tuple par Htuple tuple defines tuple as output control parameter no par inside the output control parameter parameter class Herror T_call_halcon ProcName or macro TC ProcName char ProcName calls the Halcon operator ProcName using tuple mode input and output parameters of ProcName must be declared using set_in_ par and set_out_ par first Figure 2 4 Generic calling mechanism for the HALCON C tuple mode current values Since in our case neither number nor type of the output parameters is known beforehand we have to use tuple mode for the actual operator call in HALCON C The rest of the program should be self explanatory HALCON C 2003 08 01 2 2 CONTROL PARAMETERS include HalconC h main i Htuple IE Flacs Into long i num printf system informations n create tuple amp In 1 Saladin lo T get system In amp SysFlags s destroy tuple In num length_tuple SysFlags for i20 i num i 1 determine the value of the i create tuple amp In 1 set s In get s SysFlags i 0 Printf ps get_s SysFlags i tuple variables prepare first query o
34. umeration the following list contains all operators not available in HALCON for TriMedia set fixed lut get fixed lut set lut gamma get lut gamma set fix get fix set lut get lut set lut style get_lut_style draw lut query_lut disp lut write lut draw_polygon draw_region draw circle draw circle mod draw_ellipse draw_ellipse_mod draw line draw line mod draw point draw point mod draw rectanglel draw rectanglel mod draw rectangle2 draw rectangle2 mod drag regionl drag region2 drag region3 get font set font query_font gettshape set tshape query_tshape get string extents get tposition set tposition new line read char read_string write string disp obj disp_arc disp arrow disp circle disp distribution disp ellipse disp color disp channel disp_image disp line disp polygon disp_rectanglel disp rectangle2 disp region disp caltab get mbutton get mposition get mshape setmshape query mshape clear rectangle clear window close_window copy rectangle dump window window extents window pointer3 get window type move rectangle open textwindow open window query window type set window attr set window extents set window type slide image new extern window set window dc set_icon get_icon query color query all colors query_colored query gray query insert query line width query paint query shape get comprise get draw get_hsi get_insert get_line_approx
35. yntax the compiler looks for HalconC 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 To create an application you have to link two libraries to your program The library libhalconc 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 make without further arguments the example application example1 will be created To create the other example applications e g example2 call make TEST_PROG example2 You can use the example makefiles not only to compile and link the example programs but also your own programs called e g test c by calling make TEST_PROG test You can link the program to the Parallel HALCON libraries by calling make parallel TEST_PROG test HALCON C 2003 08 01 5 3 PHILIPS TRIMEDIA 25 5 3 Creating Applications Under Windows NT 2000 XP for Philips TriMedia DSPs For a general description of HALCON for TriMedia refer to chapter 4 The directory HALCONROOT examples trimedia contains HDevelop programs that can be exported di rectly to C programs by calling HDevelop either via command line e g hdevelop convert test dev test c or from HDevelop running under Windows NT 2000 XP The programs do not contain any Windows display procedures or interac
Download Pdf Manuals
Related Search