HALCON/C User`s Manual
Contents
1. 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 1ib d11 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 compiler formerly called DIGITAL UNIX HALCON 6 1 4 24 CHAPTER 5 GENERATION 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 includes several UNIX specific headers as well if 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 w2. e Lines with an orientation different from the mask s i 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 amp Seg 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 HALCON 6 1 4 30 CHAPTER 6 TYPICAL IMAGE PROCESSING PROBLEMS e The mask size determines the degree of the smoothing e segmentation is used to denote a segmentation operator that calculates a tuple of image objects Seg HALCON C 2005 02 01
3. 2 The HALCON Parameter Classes ZI ANREDE oo ee csee dau ane ade Ea ae a eee ad a A4 o 2 2 2 ee ove nee E 221 TheSimple Mode o se ccc se ee eed ee dae xo e SSS 222 The Tople Mode 2 2 2220 xRR9 o 39 xo 3c EEE ES 3 3 Return Values of HALCON Operators 4 HALCON for Philips TriMedia DSPs 41 Limitations osx sr UE rar EIER XO Rx 42 Memory Management 22s zo o x a m x eee ees 5 Generation of HALCON C Applications 5 1 Windows NT 2000 XP ms UNA 2 aa as A ae QUE UP a e Moi oh an A X Np Wieso s ooi a PPP 6 Typical Image Processing Problems Gl Tes Ge 23 Bed nt e G2 Detecting Edg s o sooo 3 RR 3 9 33 EE d 63 Dynamic Threshold 2 0 eee eee eee ee Cee uox yes 6 4 Simple Texture Transformations 65 Eliminating Small Objects uou sio ke ee RR ad 6 6 Selecting Specific Orientations 6 7 Smoothing Region Boundaries N u Un 15 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
4. Tru64 UNIX 5 1 on Alpha processors MT Philips TriMedia DSPs nt b ci e 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 1586 linux2 2 gcc 2 95 Linux 2 2 2 4 on Intel Pentium or compatible ib86 linux2 2 gcc32 gcc 3 2 3 3 Two things are important in connection with the example programs The default directory for the HALCON operator read_image to look for images 15 4HALCONROOT Nimages 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 is 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 on 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. 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 2005 02 01 6 6 SELECTING SPECIFIC ORIENTATIONS 29 segmentation Image amp Seg gen circle 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 tis 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
6. 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 val long index inserts an integer with value val into a tuple at position index index in 0 length_tuple tuple 1 void set d tuple val index 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 0 length_tuple tuple 1 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 0 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 2005 02 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
7. 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 the use of HALCON tuples section 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 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 how to integrate a new frame grabber in the HALCON system Note that 2 C
8. 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 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 2005 02 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 is easy to write very compact and efficient programs because often it is 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 is 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 if the number or type of the calculated values ar
9. function declarations examplesNcNexamplei 11 c Example programs examples c i586 nt4 example1 11 Example projects to compile and link the example programs Windows NT 2000 XP 21 22 CHAPTER 5 GENERATION HALCON C APPLICATIONS examples trimedia dev HDevelop example programs that can be exported to C and run on TriMedia DSPs examples c makefile make ARCHITECTUREZ Example makefiles to compile the example programs UNIX images Images used 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 descri
10. open window query _window_type set window attr set window extents set window type slide image new extern window set window dc get os window handle get window 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 get line style get line width get paint get part get part style get pixel get rgb get shape set color set colored set comprise setdraw set gray set hsi setinsert 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 write variation model read variation model HALCON C 2005 02 01 4 2 19 e 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 e open serial close_serial close_all_serials set serial param get serial param read serial write serial clear serial e open socket accept open socket connect socket accept connect close_socket set socket timeout get socket timeout get nextsocket data type send tuple re ceive tuple send xld receive xld send region receive region
11. send image re ceive image e get spy set spy query spy e gnuplot open pipe gnuplotopen file gnuplot close gnuplot plotimage gnu plot plot ctrl gnuplot plot funct 1d e dispinfo get chapterinfo getkeywords search operator get param info get operator info get operator name query param info query operator info 4 2 Memory Management Due to hardware memory limitations on the TriMedia HALCON for TriMedia should differ from standard HALCON in certain aspects 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 is 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 is alloctmp 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 w
12. 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_ to denote tuple mode HALCON 6 1 4 10 CHAPTER 2 THE HALCON PARAMETER CLASSES 4 step Further processing 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 40 in HALCON is MAX STRING 1024 in HALCON version 6 1 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 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
13. HALCON Version 6 1 4 MVTec Software GmbH HALCON User s Manual How to use the image analysis tool HALCON Version 6 1 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 Edition 6 December 2002 HALCON 6 1 1 EC Copyright c 1997 2005 by MVTec Software GmbH M nchen Germany vree somere cmbn 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 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
14. HALCON for TriMedia X Windows and Windows NT 2000 XP display methods Frame grabber support Serial 1 0 Socket 1 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 enumeration 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 get tshape 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 set mshape query mshape clear rectangle clear window close window copy rectangle dump window get window extents get window pointer3 _ get window type move rectangle open textwindow
15. HAPTER 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 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 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 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 AFirst 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 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 is quite self explanatory We will describe the basic principles nevertheless First all image pixels with gray v
16. 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 HAL CONROOT examples trimedia contains HDevelop programs that can be exported directly 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 interaction and thus can be compiled and run on the TriMe dia without further modification Make sure that the TriMedia SDE runtime and development software is installed properly on your system and the environment variable TRIMEDIAROOT 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 HalconC h near the top of your 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 applic
17. SG 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 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 i 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 example5 c 15 16 CHAPTER 3 RETURN VALUES HALCON OPERATORS HALCON C 2005 02 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 t
18. alues 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 any C program Their use is very intuitive Users don t have to think about the basic data structures and algorithms HALCON C 2005 02 01 1 2 A FIRST EXAMPLE 3 include HalconC h main i 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 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 W
19. analysis and the programming language C 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 6 HALCON 6 1 1 December 2002 The manual now reflects the support of gcc 3 2 e Edition 5a HALCON 6 0 1 July 2001 The manual now also describes how to use HALCON on Philips TriMedia 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 L2 APETECE oe sa ecos me e haeta e Ges SHS RES Pee Gee
20. ant to use Parallel HALCON you have to link the libraries parhalcon lib dll and parhalconc lib d1l 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 syntax 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 nake without further arguments the example application example 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 2005 02 01 5 3
21. 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 Attention 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 is to get informations about the current HALCON system state The HALCON operator get_system Values here in HDevelop syntax returns all system flags with their cur rent values Since in our case neither number nor type of the output parameters is known HALCON 6 1 4 12 CHAPTER 2 THE HALCON PARAMETER CLASSES void set in opar obj par or macro I0 obj
22. ation e g test call nmake TEST PROG test from a command shell You can load and run the application onto the TriMedia 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 is 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 1 4 26 HALCON C 2005 02 01 CHAPTER 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 15 the following read_image 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 re
23. bes some additional handling of RGB images A special case is the example program example multithreaded1 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 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 15 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 2005 02 01 5 1 WINDOWS NT 2000 XP 23 ARCHITECTURE Operating System Platform Windows NT 4 0 Windows 2000 Windows XP f i586 nt4 Visual Studio on Intel Pentium or compatible sparc sun solaris7 Solaris 7 on Sparc Workstations nips sgi irix6 5 IRIX 6 5 on SGI Workstations Mips processors alpha compag osf5 1
24. en 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 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 1 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
25. indowHandle close window delete image objects from the Halcon database clear obj mandrill clear obj thresh clear obj conn clear_obj area clear obj eyes Figure 1 2 Introductory example program 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 6 1 4 4 CHAPTER 1 INTRODUCING HALCON C HALCON C 2005 02 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 is 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 is the case for specific operators is described in de
26. ithout 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 allocating 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 1 4 20 HALCON C 2005 02 01 CHAPTER 4 HALCON FOR PHILIPS TRIMEDIA DSPS Chapter 5 Generation of HALCON C Applications The HALCON distribution contains examples for building an application with 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 1lib halconc dll The HALCON C library Windows NT 2000 XP binMi586 nt4Nparhalcon lib parhalcon dll parhalconc lib parhalconc dll The corresponding libraries of Parallel HALCON Windows NT 2000 XP libVAARCHITECTURE Mlibhalcon so The HALCON library UNIX libMAARCHITECTURE Mlibhalconc so The HALCON C library UNIX 1ib ARCHITECTURE libparhalcon so libparhalconc so The corresponding libraries of Parallel HALCON UNIX lib tm1x philips nt4 libhalcon a The HALCON library for Philips TriMedia DSPs include c HProto h External
27. m In amp SysFlags destroy_tuple In num length_tuple SysFlags for i20 i lt num i determine the value of the i create tuple amp In 1 set s In get s SysFlags i 0 printf s get s SysFlags i T get system In amp Info destroy_tuple In switch get_type Info 0 print the value accordi case INT_PAR print AQ GTO break case DOUBLE PAR printf double break case STRING PAR printf string break y destroy tuple Info fsa ar 57 tuple variables prepare first query oniy AT OU first query free parameter number of system flags th system flag prepare query insert i th system flag print name get corresponding info free parameter ng to the flag s type ldNn get i info 0 AfNn get d info 0 2 get sinfo 0 free parameter 13 v ey 2 Figure 2 5 Tuple mode example program Printing the current HALCON system state HALCON 6 1 4 14 CHAPTER 2 THE HALCON PARAMETER CLASSES HALCON C 2005 02 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 M
28. marks 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 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 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
29. 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 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 2005 02 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 des loop variable long nun number of objects count_obj 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 num 1 1 surr
30. o be installed on a host computer running under Windows NT 2000 XP The TriMedia Compilation System TCS translates C and 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 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 is 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 library are not contained in
31. oating 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 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 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 99 ec or _i for long parameters e d for double parameters and e _s for char parameters As an example for the use of
32. ogate get i Tsurrogates i process single object if variant 2 copying objects individually for i21 i lt num i al 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 strings 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 1 4 8 CHAPTER 2 THE HALCON PARAMETER CLASSES Sometimes the manuals mention more than one possible type If only integers and fl
33. par Hobject obj int 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 00 obj par Hobject obj int par defines obj as output image object parameter no par inside the output image object parameter parameter class void set in tpar tuple par or macro IT tuple par Htuple tuple int par defines tuple as input control parameter no par inside the input control parameter parameter class void set out tpar tuple par or macro OT tuple par Htuple tuple int par defines tuple as output control parameter no par inside the output control parameter parameter class 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 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 2005 02 01 2 2 CONTROL PARAMETERS include HalconC h main 1 Htuple In SysFlags Info long i num printf system informations Nn create tuple amp In 1 set s In 0 T_get_syste
34. tail 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 is a little elaborate Using tuples of image objects on the other hand is in no way different from using single values HALCON C provides the data structure Htuple for tuples of control parameters see section 2 2 2 for details and the data structure Hobject for image objects single objects as well as object tuples see section 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 represen
35. ted 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 operators 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
Download Pdf Manuals
Related Search