Home

Frame Grabber Integration Programmer`s Manual

1. HALCON provides camera type string parameter in open framegrabber passed in gt type Use this parameter to specify some frequently used additional settings that are not available among the standard parameters Note that you provide arbitrary additional parameters to be set via set_framegrabber_param AFTER open_framegrabber see FGSetParam If default is used in open_framegrabber the value YOU provided for fg gt camera_type FGInit will be passed A typical application for the camera_type parameter is to specify the video norm ntsc pal auto Another possibility is to specify camera configuration file which many frame grabbers use for configuration It s up to YOU to decide what semantics to assign to this parameter you encounter an unreasonable value return H_ERR_FGCT ka Frame Grabber Integration 2000 11 16 TODO Determine the video norm pal ntsc This might be done by analyzin
2. In general the volatile mode works only with interleaved image data To profit by the volatile mode the buffer data has to be structured in a compatible way to the HALCON image format If you allow the volatile mode on multi channel images e g RGB get sure that your frame grabber delivers the data for each channel in separate and in this example consecutive memory planes The order of the channels is R G B with ascending memory adress in this example Note on this that the decision what type of HALCON image to create is rather crude in this example It assumes that the frame grabber delivers either 8 bit unsigned 16 bit signed or 32 bit signed data otherwise you would have to convert the buffers Thus the volatile mode would be obsolete INT4_8 size INT num_channels if fginst gt num_channels 4 If you ve allowed 32 bits per pixel while setting the volatile mode you have to decide how to handle the redundant data In this example we assume an RGBX ordering of the corresponding memory planes Thus we just take the first three channels num_channels 3 else num_channels fginst gt num_channels size fginst gt image_width fginst gt image_height if fginst gt bits_per_channel lt 8 for i 0 i lt num_channels i
3. Note There might be asynchronous grabs pending on the same board you would like to use general most frame grabbers have only one A D converter thus you might have to cancel all these old jobs before doing anything else Obviously this operation has nasty side effects So you could also return the error H_ERR_FGDV device busy in that case Kil1A110therJobs fginst ooo o o o o k k k kkk TODO Allocate BoardInfo initialize frame grabber hardware if currInst gt board All right it seems that the desired board isn t yet open allocate space for the BoardInfo struct member e g like this 11 proc_id size_t sizeof BoardInfo amp currInst gt board Init the struct currInst gt board e g memset currInst gt board 0 sizeof BoardInfo 79 HALCON 6 0 80 APPENDIX INTERFACE TEMPLATE CIOFGTEMPLATE C strcpy currInst gt board gt DeviceName fginst gt device
4. Now you have to set the frame grabber scaler etc in order to deliver the image part specified by start_col start_row and image_width image_height within the image of size horizontal_resolution x vertical_resolution This might also mean to switch between full images and single fields there is no use to grab a full frame if you would Frame Grabber Integration 2000 11 16 like to do subsampling of factor 2 anyway see also fginst gt field Note Some frame grabbers do not support cropping an image part hardware that case return H_ERR_FGWP if you urged to grab only part of an image do it in SOFTWARE in that case note that you have to provide a buffer to grab to for the full image horizontal_resolution x vertical_resolution not only image_width x image_height PEPEPEPE EPEE kak TODO Allocate buffers PEPEPEPE PEPEPEPE PEPEE PEPEN boy this is going to be fun again because there are lot of things to consider 1
5. This query typically doesn t return any values but only general description of the board 1 or model etc HALCON frame grabber interface template vendor MVTec Software GmbH values NULL numValues 0 break case FG_QUERY_PORT ACCS GCG AG II k ak a ko TODO Return port description Explain what ports are available and how you select them it is the assignment of port numbers to physical connectors like a S VHS plugin example info Port 0 S Video port 1 2 Composite 8 and 24 bits available for each port HCkP 11 proc_id size_t 3 sizeof Hcpar amp val val 0 par 1 0 val 1 par 1 1 val 2 par 1 2 val 0 type 1 1 val 2 type LONG_PAR values val numValues 3 another example Only one port that is No need to specify a port info Unused values NULL numValues 0 break case FG_QUERY_CAMERA_TYPE CI ISG I I GI I a ka a ik kk k TODO Return description of the camera t
6. for 1 0 i lt FG MAX INST i 1 if FGInst i board amp amp currInst gt instance i 1 ok FGInst i is in use and is NOT the current Instance now let s see if the associated board is the requested one if strcmp FGInst i board DeviceName fginst gt device 1 The selected board is already in use Decide whether you can allow parallel usage by this new instance for example using a different port line Note that you can access the other HALCON FGInstance structs using FGInst i fginst if you follow our suggestions or you provide additional information concerning port MUX settings in the struct TFGInstance or you ask the frame grabber API If you detect an incompatibility return H_ERR_FGDV device busy otherwise currInst gt board FGInst i board if 1 return H_ERR_FGDV example Only one instance per board else currInst gt board FGInst i board NOTE From this time on you should reset currInst gt board to NULL before exiting in case of error in order to unlock the instance again
7. FG_PARAM_HORIZONTAL_RESOLUTION horizontal resolution LONG PAR FG_PARAM_VERTICAL_RESOLUTION vertical_resolution LONG_PAR FG_PARAM_IMAGE_WIDTH image width LONG PAR Frame Grabber Integration 2000 11 16 if FG_PARAM_IMAGE_HEIGHT FG_PARAM_START_ROW FG_PARAM_START_COL FG_PARAM_FIELD FG_PARAM_BITS_PER_CHANNEL image height start row start column field bits per channel FG PARAM COLOR SPACE color space FG PARAM GAIN gain FG PARAM CAMERA TYPE camera type FG PARAM DEVICE device PARAM PORT port PARAM LINE line in LONG PAR LONG PAR LONG PAR STRING PAR LONG PAR STRING PAR FLOAT PAR STRING PAR STRING PAR LONG PAR LONG PAR Note that field fginst gt field externally is defined as string but internally as int using the following conversion FG_FIRST_FIELD_TXT first lt gt FG_SECOND_FIELD_TXT second lt gt FG_NEXT_FIELD_TXT next lt gt FG_FULL_FRAME_TXT interlaced lt gt FG_PROGRESSIVE_FRAME_TXT progressive lt gt FG_FIRST_FIELD FG_SECOND_FIELD FG_NEXT_FIELD FG_FULL_FRAME FG_PROGRESSIVE_FRAME Note further that external_trigger externally is defined as string true false but internally as HBOOL The input to FGSetParam is ONE parameter value check the name of the parameter the type of the p
8. Open this device fginst gt device for the 15 time PLEASE REFER TO THE MANUAL OF YOUR FRAME GRABBER FOR DETAILS query frame grabber capabilities and store them in the struct currInst gt board newBoardalloc TRUE Note some cases parameter checks not possible until now that is until the specific board has been initialized and can be ASKED about its abilities this is typically true for evaluating the image size and the camera_type parameter NOTE From this time you might have to do some cleaning up before exiting case of an error deallocate the BoardInfo unlock the frame grabber etc see CleanupFGOpen as a reference RR k Ok at this point we know that the frame grabber board IS available and initialized Note that some parameters like number of bits per channel field to be grabbed etc typically only influence the GRABBING that is F
9. I i aa I Kk aa GK TODO terminate my own async job the one belonging to this instance TODO Select frame grabber board pete The desired frame grabber board is specified by fginst gt device If default is used open_framegrabber the string YOU provided for fg gt device in FGInit will be passed in fginst gt device If the default value depends on the CURRENT configuration of the system specify default FGInit get the corresponding information NOW and overwrite the device name in fginst gt device In case of foolish inputs return H_ERR_FGWD wrong device Note In many cases there is a call in the frame grabber to ASK for Frame Grabber Integration 2000 11 16 all available frame grabbers in the system if strcemp fginst gt device default strcpy fginst gt device 1 example default device 1 else if strcmp fginst gt device 1 amp amp strcmp fginst gt device 2 return H
10. miscellaneous parameters 4 8 mode current operating mode INT width max height max maximum image size num channels number of image channels HBOOL async_grab TRUE lt gt async grabbing engaged image image objects to grab into aux void gen_pointer generic pointer auxiliary ei external memory allocation HBOOL halcon_malloc TRUE lt gt standard memory allocation by HNewImage DBFreeImageProc 1 _ pointer to specific clear function if halcon_malloc FALSE FGInstance Figure 2 6 The data structure FGInstance defined in include hlib CIOFrameGrab h 2 2 Recommended Auxiliary Structures The structures FGClass and FGInstance provide data relevant to the HALCON library that is outside of your interface common to all different frame grabber types However to handle a specific frame grabber you will need additional data structures We recommend to adapt the following two structures BoardInfo and TFGInstance for your needs 2 2 4 Structure BoardInfo We suggest to define a structure BoardInfo to hold all data relevant for a specific frame grabber board that 1s the physical instance of a frame grabber model you plugged into your computer Fig 2 7 shows a typical example Deviceld is an entry in this structure you will need
11. 17 222 TFGInstance 2c de ow Ge Goel Sele Sele Seles 18 Interface Routines 21 Sd GRE nen Rs OR d oa a 21 3 2 25 FGO a hc a te oerte Serin Song oe riu 27 EGCC O Dee est oth 35 S ODIO cu 3A E SOL SOR SOB SES oa Be Wat 38 910 sisse ie gets ates e e OA GO es ue A 07556 4 3 7 Auxiliary Routine GrablmgO 46 3 97 RS Ded RO RS A 50 3 0 PGOrabStartAsync SETA E RU 3 10 FGGrabRegion 3 11 FGGrabRegionAsync 3 12 PGSetParam 324 230425 44 ES 3 12 EGGetParam cg See 244 3 15 sue eue eue de 4 Generating a Frame Grabber Interface Library A Changes the HALCON Frame Grabber Integration Interface B HALCON Error Codes C Interface Template CIOFGTemplate c Index Frame Grabber Integration 2000 11 16 Contents 65 69 71 107 1 Introduction This chapter provides an introduction to the HALCON frame grabber integration interface and the underlying concepts It is intended for
12. Frame Grabber Integration 2000 11 16 Index ExtractChannelsFromRGB 45 Set framegrabber param 9 57 FGClose 7 35 37 BoardInfo 18 28 29 58 FGGetLut 0 9 62 DBFreeImageProc 17 FGGetParam 9 60 FGClass 14 16 22 FGGrab 8 41 42 44 50 FGInstance 17 26 FGGrabAsync O 8 41 50 HCkP 31 FGGrabRegion 8 41 53 56 Hcpar 38 58 60 FGGrabRegionAsync 9 41 55 56 Himage 43 FGGrabStartAsync 8 51 52 Hrlregion 53 FGInfoO 7 38 40 LD LIBRARY PATH 64 FGInit O 21 24 Path 64 FGOpen 7 27 34 TFGInstance 19 23 58 FGOpenRequest 0 7 25 26 FGSetLut 9 61 double buffering 6 FGSetParam 9 57 59 GrabImg 41 46 47 49 HA110c 29 31 35 38 HAllocRL 55 HAllocRLLocal 55 frame grabber class 6 13 handle 6 instance 6 13 HAllocRLNumLocal 54 55 grabbing HAllocRLTmp 55 asynchronous 5 8 9 46 50 51 56 HFree 35 synchronous 5 8 41 46 53 HNewImage 31 44 volatile 6 18 31 42 58 HNewImagePtr 43 HReallocRLNumLocal 55 Parallel HALCON 10 63 64 SecFGInit 7 UNIX 21 64 SetInstParam 48 ftime 49 Windows 2000 21 63 close_all_framegrabbers 7 Windows NT 21 63 close_framegrabber 7 35 get framegrabber lut 9 62 get framegrabber param 9 60 gettimeofday O 49 grab image async 8 50 grab image start 8 51 grab image 8 41 grab region async 9 56 grab region 8 53 info framegrabbe
13. HCkP HNewImagePtr proc_id amp image il BYTE_IMAGE fginst gt image_width fginst gt image_height void currInst gt InstFrameBuffer readBuffer i size sizeof BYTE IMAGE FALSE else if fginst gt bits_per_channel lt 16 for i 0 i lt fginst gt num_channels i HCkP HNewImagePtr proc_id amp image i INT2 IMAGE fginst image width fginst image height void currInst gt InstFrameBuffer readBuffer i size sizeof INT2 IMAGE FALSE else for i 0 i lt fginst gt num_channels i HCkP HNewImagePtr proc_id amp image 0 INT4_IMAGE fginst gt image_width fginst gt image_height void currInst gt InstFrameBuffer readBuffer i size sizeof INT4 IMAGE FALSE num image num channels else 93 HALCON 6 0 94 APPENDIX C INTERFACE TEMPLATE CIOFGTEMPLATE C Copy the buffer into NEW HALCON object DOR ooo INT save Do not initialize the new images with 0 HReadSysComInfo proc id HGInitNewImage amp save HWriteSysComInfo proc id HGInitNewImage FALSE Note that we support in our example following different image types 8 bit unsig
14. board Thus this other instance will rely on the fact that all the frame grabber settings have been done FGOpen It won t set the port and input line etc again before grabbing Thus you have to make sure that these settings are correct NOW for 1 0 i lt FG MAX INST i if FGInst i board amp amp currInst gt instance i Ok FGInst i is in use and is NOT the current instance Now let s see if it references the same board as the current instance if FGInst i board currInst gt board DRCOG GG OR OGRA GAR aR kaka x TODO Restore frame grabber settings for the instance FGInst i instance FGInst i fginst Frame Grabber Integration 2000 11 16 APPENDIX C INTERFACE TEMPLATE CIOFGTEMPLATE C 87 everything that you allow to be different for instances of the same board like port and input line etc HCkP Set InstParam fginst gt fgclass gt instance i break F for i currInst gt board gt refInst 1 currInst gt board gt refInst gt 1 currInst gt board NULL numInstance return H MSG OK FGClose m LLLILILILILILILILILIL IL ILI L LILILI LI LILIL LIL LILILILIL ILIL ILILILLIL ILI IL ILIL
15. fg gt Open FG pen fg gt Close FGClose fg gt Info FGInfo fg gt Grab FGGrab fg gt GrabStartAsync FGGrabStartAsync fg gt GrabAsync FGGrabAsync fg gt GrabRegion FGGrabRegion fg gt GrabRegionAsync FGGrabRegionAsync fg gt SetParam FGSetParam fg gt GetParam FGGetParam fg gt SetLut FGSetLut fg gt GetLut FGGetLut default values The following defaults will be delivered to FGOpen if default or 1 is specified open_framegrabber fg gt horizontal_resolution 1 fg gt vertical_resolution 1 fg gt image_width fg gt start_row fg gt image_height fg gt start_col 0 fg gt field FG_FULL_FRAME fg gt bits_per_channel 8 strcpy fg gt color_space gray fg gt gain 1 0f fg gt external_trigger FALSE strcpy fg gt camera_type auto strcpy fg device 0 fg gt port 1 fg gt line_in 1 store the class information fgClass fg 105 HALCON 6 0 106 APPENDIX C INTERFACE TEMPLATE CIOFGTEMPLATE C return H MSG OK FGInit end CIOFGTemplate c FSGS AG aI
16. static FGInstance FGOpenRequest Hproc_handle proc_id FGInstance fginst return available instance prior to FGInit return amp fgClass gt instance 0 Figure 3 6 The prototype for FGOpenRequest If the instance you return is already assigned to a frame grabber handle this old instance is automatically closed using FGClose If you return a NULL pointer HALCON will return the error code ERR FGDV Frame grabber device busy as result of open framegrabber If you support multiple instances you can use the example code listed in Fig 3 7 otherwise use the code in Fig 3 8 static FGInstance FG penRequest Hproc handle proc id FGInstance fginst 1 INT i if numInstance FG MAX INST return NULL too many instances else 1 search for next unused instance for i 0 i FG MAX INST i 1 if FGInst i board break fginst gt gen_pointer void amp FGInst 1 return amp fgClass gt instance i Figure 3 7 Example code for FGOpenRequest Multiple instances gt There is no instance available thus the device is busy HALCON 6 0 26 CHAPTER 3 INTERFACE ROUTINES static FGInstance FGOpenRequest Hproc_handle proc_id FGInstance fginst fginst gt gen_pointer void amp FGInst 0 return amp fgClass gt instance 0 Figure 3 8 Example code for FGOpenRequest Only one instance Note that we
17. HALCON 6 0 42 CHAPTER 3 INTERFACE ROUTINES static Herror FGGrab Hproc_handle proc_id FGInstance fginst Himage image INT num image 1 TFGInstance TFGInstance fginst gen pointer INT readBuffer HCkP GrabImg proc id fginst amp readBuffer if currInst gt volatileMode 1 Insert the 8 bit image buffer directly into a HALCON object HCkP HNewImagePtr proc id amp image 0 BYTE IMAGE fginst image width fginst image height void currInst gt InstFrameBuf fer readBuffer FALSE num image 1 else num_image fginst gt num_channels for i 0 i lt num image i HCkP HNewImage proc_id amp image i BYTE_IMAGE fginst gt image_width fginst gt image_height if fginst gt num_channels 1 memcpy void image 0 pixel b currInst gt InstFrameBuffer readBuffer fginst gt image_width fginst gt image_height else HCkP ExtractChannelsFromRGB fginst currInst gt InstFrameBuffer readBuffer image 0 1 image 1 pixel b image 2 pixel b fginst gt async_grab FALSE return H_MSG_OK Figure 3 29 Example code for FGGrab The basic structure in this example We further assume that color images are delivered an interleaved format with RGB triples per pixel Thus this raw data must be separated into three image channels ExtractChannelsFromRGB As a consequence volatile grabbing does not make sen
18. Consequently there would be no time at all left to process images In this synchronous mode the host computer is exclusively busy triggering one grab after another Therefore HALCON also supports asynchronous grabbing as explained in the next section 1 3 Synchronous vs Asynchronous Grabbing To understand what asynchronous grabbing means we first should take a look at what the frame grabber does with a grabbed frame It is easily understood that a digitized frame must be stored in some kind of memory Basically there are three possibilities Device memory on the frame grabber board e Device memory on the host machine e Host memory Device memory on the board means dedicated memory physically mounted to the board This way the frame grabber can store the acquired image s directly in its own memory with each process on the host being able to get the data at any time On the other hand memory size is fixed If it is too small it may not be possible to keep several images in memory If it is very big the whole board can get rather expensive Device memory on the host machine is non paged system memory dynamically allocated by the frame grabber s device driver Thus the memory size can be easily adjusted On the other hand heavy bus traffic is likely to occur if the frame grabber is delivering data to the host computer s memory permanently Therefore we usually do not use continuous grabbing modes provided by some frame grabbers bu
19. Determine the video norm and the maximum image size to be delivered by the frame grabber HALCON 6 0 30 CHAPTER 3 INTERFACE ROUTINES Once you have selected and initialized the frame grabber board you should analyze the video signal Many frame grabber APIs provide routines to do this automatically If such a function ality is missing or the analysis is very time consuming you might want to specify the video norm in open_framegrabber Use the camera type parameter fginst gt camera_type for this purpose see Fig 3 13 static Herror FGOpen Hproc_handle proc id FGInstance fginst INT widthScale fginst gt horizontal_resolution INT heightScale fginst gt vertical_resolution if widthScale fginst gt width_max widthScale 1 if heightScale fginst gt height_max heightScale 1 if widthScale fginst gt width_max 2 widthScale 2 if heightScale heightScale 2 if widthScale fginst gt width_max 4 widthScale 4 if heightScale fginst gt height_max 4 heightScale 4 fginst gt height max 2 if widthScale 1 widthScale 2 widthScale 4 return H_ERR_FGWR wrong resolution if heightScale 1 heightScale 2 heightScale 4 return H_ERR_FGWR wrong resolution fginst gt horizontal_resolution fginst gt width_max widthScale fginst gt vertical_resolution fginst gt height_max heightScale return H MSG OK Figure 3 14 Exa
20. ERR FGWD example only 1 or 2 NOTE Some of the following parameter checks might be possible without accessing the frame grabber hardware in other cases it might be necessary to initialize the hardware and ASK the specific frame grabber about its abilities We suggest to make parameter tests as soon as possible as late as necessary o o k k kk k kk kk TODO Check the desired port multiplexed input line The desired physical port into which your camera is plugged is typically passed fginst gt port if there multiplexer available at this port the desired input line is passed in fginst gt line_in If 1 for default is used in open framegrabber the values YOU provided for fg gt port and fg gt line_in FGInit will be passed fginst gt port fginst
21. FGClass fg endif pooo ooo ooo GOGO ooo oo o oo o o k kk k k k kkk TODO Adapt the following structs to match your frame grabber s hardware features GOOG IG AG IGG k kk k k kkk k BoardInfo struct is used physical board It contains hardware features tightly coupled with the board e g a board handle memory mapping The TFGInstance struct is the internal representation of a frame grabber handle thus it contains board related data for one instance for example different instances may represent different multiplexed inputs one single board or on the other hand maybe different physical boards with only one physical input each typedef struct Note The following struct members will only be used once per board DOCG a k k k kk k kkk TODO place your FG specific entries here examples DeviceName 255 assign a name to each board INT4_8 Deviceld some sort of handle specific to the frame grabber API BoardFrameBuffer MAX_BUFFERS buffers assigned to the board that is to ALL TFG
22. LIL LILILILILI ILILILI LILILI ILI ILILILI ILI ILI LI II LI ILI LI ILI LI II I Herror ExtractChannelsFromRGB32 Typically color frame grabber delivers the data as interleaved tuple e g RGB triples per pixel Thus you have to split this data into separate channels conform to the HALCON philosophy This routine might be a very simple template for such a procedure static Herror ExtractChannelsFromRGB32 FGInstance fginst HBYTE data HBYTE r img HBYTE g img b img 1 8 i size size fginst gt image_width fginst gt image_height Assume that the frame grabber delivers 32 bits per pixel e g BGRX for i 0 i lt size i b imgtt datatt g imgtt datat imgtt datatt datat return H MSG OK ExtractChannelsFromRGB32 Typically a color frame grabber delivers the data as interleaved tuple e g RGB triples per pixel Thus y
23. The same might be true for any frame grabber library provided by the manufacturer of the frame grabber which is used by your HALCON interface Do not copy a frame grabber DLL into the Windows system directories as it would be loaded twice this case Generating a Frame Grabber Interface Under UNIX To build HALCON frame grabber interface you have to generate a shared library from the file containing the source code of your interface like CIOFGTemplate c by linking the corre sponding object file s using 1d We recommend to use some level of optimization for the compilation process otherwise grab bing especially of color images will be slowed down significantly In order to be automatically loadable by HALCON the name of the frame grabber interface library must start with the prefix HFG The rest of the library name automatically defines the name of the interface as used in the operator open framegrabber For example if your inter face library is called HFGMegaGrabber so you access the frame grabber by calling open framegrabber MegaGrabber Note that the location of the generated HALCON frame grabber interface must be included in the search path for dynamic objects 1 the variable LD_LIBRARY_PATH The same might be true for any frame grabber library provided by the manufacturer of the frame grabber which is used by your HALCON interface In contrast to Windows NT 2000 both standard HALCON and Parallel
24. available for backward compatibility only instances num etc These are the internal and some additional entries used for managing instances see chap 3 Interface specific functions Open etc Pointers to the interface routines you provide see chapter 3 and Fig 2 5 Frame Grabber Integration 2000 11 16 2 1 FRAME GRABBER CLASSES AND INSTANCES 15 typedef struct _FGClass 5 interface specific functions FGInstance Hproc_handle proc_id FGInstance fginst Herror Herror Herror Herror Herror Herror Herror Herror Herror Herror Herror Herror pen Close Grab GrabStartAsync GrabAsync GrabRegion GrabRegionAsync Info SetParam GetParam SetLut GetLut handle proc_id FGInstance fginst Hproc_handle proc_id FGInstance fginst Hproc_handle proc_id FGInstance fginst Himage image INT num image Hproc handle proc id FGInstance fginst double maxDelay Hproc handle proc id FGInstance fginst double maxDelay Himage image INT num image Hproc handle proc id FGInstance fginst Hrlregion region INT num region INT rlalloc type Hproc handle proc id FGInstance fginst double maxDelay Hrlregion region INT num_region INT rlalloc type handle proc id INT queryType char info Hcpar values INT numValues
25. buffers are allocated instance not only references to the buffers in board TRUE lt gt pass buffer memory directly to a HALCON image possibly overwriting older images 19 will also mean to include additional parameters in TFGInstance BoardInfo to allow the fine tuning of the hardware HALCON 6 0 20 Frame Grabber Integration 2000 11 16 CHAPTER 2 DATA STRUCTURES Chapter 3 Interface Routines This chapter explains all the routines you have to implement inside your frame grab ber interface in order to support the corresponding HALCON frame grabber opera tors see section 1 6 The example code of the next sections can also be found in HALCONROOOTY examples fg_integration CIOFGTemplate c 3 1 FGInit FGInit as defined in Fig 3 1 is called by the HALCON operators open_framegrabber or info_framegrabber when you access a specific frame grabber for the very first time include Halcon h include hlib CIOFrameGrab h Herror FGInit Hproc_handle proc_id FGClass fg initialize the data structure FGClass the frame grabber interface return H_MSG_OK Figure 3 1 The prototype of FGInit In order to do so the routine FGInit must be accessible from outside that is the HALCON library must be able to find the symbol and call the routine inside the DLL or shared library In UNIX it is sufficient just to avoid declaring the routin
26. currInst gt timeout Bad luck The image is there but too old Peet TODO grab new image DAC a o k k k kk kk HALCON 6 0 92 APPENDIX C INTERFACE TEMPLATE CIOFGTEMPLATE C You ve got your image by now TODO Switch the buffer if you use more than one buffer GO A RK kak kak readBuffer currInst gt currBuffer Select the next buffer for grabbing currInst gt currBuffer if currInst gt currBuffer gt MAX_BUFFERS currInst gt currBuffer 0 if fginst gt async_grab T TODO Start the next asynchronous grab ifdef WIN32 _ftime amp currInst gt grabStarted the time the grab was started else gettimeofday amp currInst gt grabStarted amp currInst gt tzp endif currInst gt busy TRUE return H MSG OK GrabImg SSS SS SS SS SS SS SS SS SS SS SS 5 SS SSS SS SSS SSS SSS 5 SS SS 5 SS SSS 5555555
27. gt line_in You have to check the values of both parameters and return appropriate error codes in case of a failure If the desired port is invalid return H_ERR_FGPT wrong port If the desired input line is invalid return H_ERR_FGLI wrong line if fginst gt port lt 1 fginst gt port gt 3 return H_ERR_FGPT example available ports 1 2 3 if fginst gt line_in 1 return H_ERR_FGLI example no MUX TODO Check number of bits per channel desired number of bits per image channel is passed fginst gt bits_per_channel eg use 8 bits for 8 8 8 rgb image 8 bit grayscale If 1 for default is used in open framegrabber the values YOU provided for fg gt bits_per_channel in FGInit will be passed in fginst gt bits_per_channel If the default value depends on the CURRENT configuration of the system specify 1 in FGInit get the corresponding information NOW and overwrite the default value in fginst gt bits_per_channel If you encounter unreasonable requests return H_ERR_FGWC
28. numValues Hcpar val case FG_QUERY_CAMERA_TYPE info Video Signal of the camera ntsc pal auto HCkP HAlloc proc_id size_t 3 sizeof val amp val val 0 par s ntsc val il par s pal val 2 par s auto val 0 type val i type val 2 type STRING PAR values val numValues break return H_MSG_OK Figure 3 25 Example code for FGInfo The query FG_QUERY_CAMERA_TYPE define FG_PARAM_VOLATILE volatile static Herror FGInfo Hproc_handle proc_id INT queryType char info Hcpar values INT numValues 1 case FG QUERY PARAMETERS info Additional parameters for this frame grabber HAlloc proc id size t 1 sizeof val amp val val O par s FG PARAM VOLATILE val 0 type STRING PAR values val numValues zu break return H MSG OK Figure 3 26 Example code for FGInfo query FG_QUERY_PARAMETERS Frame Grabber Integration 2000 11 16 3 6 FGGRAB 41 3 6 FGGrab The routine FGGrab as defined in Fig 3 27 is called by the HALCON operator grab_image see section 1 6 It has to perform the following tasks e Terminate pending asynchronous grabs e Re set the parameters on the frame grabber board e Grab an image synchronously e Return a HALCON image containing the grabbed raw data include Halcon h include hlib CIOFrameGrab h static Herror FGGrab Hproc
29. then all you have to do to use your new frame grabber is DLLs for Windows NT 2000 shared libraries for UNIX systems 2 CHAPTER 1 INTRODUCTION e Plug in the hardware and install the vendor specific device driver libraries etc shipped with the board e Copy the new HALCON interface i e the loadable module with the encapsulated hardware dependent code to a directory within your search path for DLLs or shared li braries respectively For the proper prefix of the filename of the new HALCON interface see chapter 4 e Specify the name of the new frame grabber i e the name of the corresponding interface in the open_framegrabber operator e Enjoy the performance of all the features you have integrated in your new frame grabber interface The HALCON operators used for image acquisition remain the same so existing application code can be used without modification in most cases HALCON automatically loads the inter face during the first call to open_framegrabber Thus you can exchange add frame grabber interfaces even without restarting your application Special features of different frame grabber boards can be accessed through the general purpose parameter setting mechanism Example files As a guideline for the frame grabber integration the HALCON distribution contains a template for a frame grabber interface see CIOFGTemplate c in examples fg_integration and also in Appendix C It covers most situations you might enco
30. C programs e HALCON COM User s Manual How to use the HALCON library in your COM programs e g in Visual Basic e Extension Package Programmer s Manual How to extend the HALCON system with your own operators e HALCON HDevelop HALCON C HALCON C HALCON COM The reference manuals for all HALCON operators versions for HDevelop C C and 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 Please see also the frame grabber interface template and the example files CIOFGTemplate c MyDT3155 c and MySlicVideo c HALCONROOTY examples fg_integration HALCON 6 0 12 CHAPTER 1 INTRODUCTION Frame Grabber Integration 2000 11 16 2 Data Structures This chapter introduces the data structures provided by the HALCON frame grabber integration interface Furthermore it contains some recommendations on how to handle multiple frame grabber instances 2 1 Frame Grabber Classes and Instances The HALCON frame grabber interfaces manage frame grabbers using classes and instances Since HALCON is designed to access any number and combination of boards simultaneously situations may occur where several boards controlled by the same interface or boards using different interfaces or a combination of both must be addressed The mechanism chosen to handle situ
31. FGInfo to query all the installed frame grabber boards ac cessible from your interface see section 3 5 The value of the define FG_INTERFACE_VERS ION should be set from 1 x to 2 0 The parameter lists of the functions FGSetParam and FGGetParam were extended to han dle multi parameter values Therefore the declaration of these functions has changed to static Herror FGSetParam Hproc handle proc_id FGInstance fginst char param Hcpar value INT num static Herror FGGetParam Hproc handle proc id FGInstance fginst char param Hcpar value INT num Make sure that you set num to a reasonable value within FGSetParam See also the chap ters 3 12 and 3 13 for more details Frame Grabber Integration 2000 11 16 67 To fix a bug of the old CIOFGTemplate c delete the line fginst gt async_grab TRUE at the end of the functions FGGrabStartAsync FGGrabAsync FGGrabRegionAsync HALCON 6 0 68 APPENDIX CHANGES IN THE HALCON FRAME GRABBER INTEGRATION INTERFACE Frame Grabber Integration 2000 11 16 Appendix HALCON Error Codes In this chapter all HALCON error codes relevant for programming a frame grabber interface are summarized Please refer to CIOFGTemplate c for a discussion when to use which error code Error Name Code Description H_ERR_NFS 5300 No frame grabber opened H_ERR_FGWC 5301 Wrong color depth H_ERR_FGWD 5302 Wrong device H_ERR_FGVF 5303 Determination of video f
32. FGInstance fginst INT readBuffer TFGInstance currInst TFGInstance fginst gt gen_pointer HBOOL done FALSE HBOOL checkTimeAgain FALSE HBOOL newGrab FALSE ifdef WIN32 struct _timeb now else 89 HALCON 6 0 90 APPENDIX C INTERFACE TEMPLATE CIOFGTEMPLATE C struct timeval now struct timezone tzp endif INT4_8 time_diff Note There might be asynchronous grabs pending on the same board you would like to use In general most frame grabber have only one A D converter thus you might have to cancel all these old jobs before doing anything else Obviously this operation has nasty side effects So you could also return the error H_ERR_FGDV device busy in this case Kil1A110therJobs fginst if currInst gt busy amp amp currInst gt board gt refInst gt 1 There are other instances using the same board Thus you have to set the frame grabber parameters again fk TOD0 Restore frame grabber settings for currInst everything that you allow to be different for instances of the board like port and input line et
33. Grabber Integration 2000 11 16 3 10 FGGRABREGION 53 3 10 FGGrabRegion The routine FGGrabRegion as defined in Fig 3 40 is called by the HALCON operator grab region see section 1 6 It has to perform the following tasks e Terminate pending asynchronous grabs e Re set the parameters on the frame grabber board e Grab an image synchronously e Return a segmentation based on the grabbed raw data include Halcon h include hlib CIOFrameGrab h static Herror FGGrabRegion Hproc_handle proc_id FGInstance fginst Hrlregion region INT num_region INT rlalloc_type grab an image synchronously and segment it return H MSG OK Figure 3 40 prototype for FGGrabRegion O A routine like this should be implemented if the frame grabber hardware offers some specific features that support an image segmentation It might also be more efficient to segment color images within the frame grabber interface even without hardware support because in this case one can avoid the channel splitting see Fig 3 33 and work on the original raw data instead However please note that neither grab_region nor grab region async return the image itself Thus the visualization of the segmentation results cannot use the underlying image The implemented segmentation is up to you and maybe dependent on some specific hardware features of your frame grabber We cannot provide example source code for that However we
34. HALCON library halcon lib and e the frame grabber libraries provided by the frame grabber manufacturer Make sure that the optimization is switched on for the compilation process 1 create a lease not a Debug version otherwise grabbing especially of color images will be slowed down significantly If you want to use the new frame grabber interface in Parallel HALCON as well you must create a second DLL which is linked to the Parallel HALCON library parhalcon 1ib instead of halcon lib In order to be automatically loadable by HALCON or Parallel HALCON the name of the frame grabber interface library must start with the prefix HFG or parHFG respectively The rest of the library name automatically defines the name of the interface as used in the operator open framegrabber For example if your interface library is named HFGMegaGrabber d11 and parHFGMegaGrabber d11 you access the frame grabber by calling open framegrabber MegaGrabber A DLL for Windows NT 2000 or a shared library for UNIX systems respectively 63 64 CHAPTER 4 GENERATING A FRAME GRABBER INTERFACE LIBRARY Do not forget to export the symbol FGInit with the line extern __declspec dllexport Herror FGInit Hproc handle proc_id FGClass fg in your interface code see also section 3 1 Note that the location of the generated HALCON frame grabber interface must be included in the search path for dynamic objects i e the variable PATH
35. Hproc handle proc id FGInstance fginst char param Hcpar value INT num Hproc handle proc id FGInstance fginst char param Hcpar value INT num Hproc_handle proc_id FGInstance fginst INT4_8 red INT4_8 green INT4 8 blue INT num Hproc_handle proc_id FGInstance fginst INT4_8 red INT4_8 green INT4_8 blue INT num Figure 2 3 The data structure FGClass defined in include hlib CIOFrameGrab h to be con tinued e Default values image_width image_height etc The default values for the standard parameters used in open_framegrabber Whenever the user specifies default or 1 respectively in this operator the HALCON library will pass the corresponding values inside FGClass to the interface routine FGOpen see section 3 3 Please see also Fig 3 47 on page 58 2 1 2 Structure FGInstance There is a data structure called FGInstance see Fig 2 6 you will encounter very often when programming an interface since almost every routine you provide see chapter 3 expects a pointer to the frame grabber instance it should work with The structure FGInstance contains the actual parameters for a specific frame grabber in stance The corresponding default values for the underlying frame grabber model are stored HALCON 6 0 16 typedef struct _FGClass 5 INT INT INT INT char float HBOOL char char INT INT void reserved FG_NUM_RESERVED FGClass CHAPTER 2 DATA STRUCTU
36. If you are first interested in the basics of the HALCON frame grabber interface from the user s point of view you can also have a look in section 4 3 The HALCON Frame Grabber Interface of the Getting Started with HALCON User s Manual The manual is divided into the following parts Introduction This chapter explains the basics of image acquisition and introduces the HALCON frame grabber integration interface and the underlying concepts Data Structures In this chapter the basic data structures of the frame grabber integration interface are described Interface Routines This chapter explains all the routines you have to implement inside your frame grabber interface Generating a Frame Grabber Interface Library This chapter contains information on how to generate a dynamic object encapsulating your frame grabber interface Appendix A Changes between versions 1 and 2 of the HALCON frame grabber integration interface This section describes the differences between the versions and 2 of the HALCON frame grabber integration interface Appendix B HALCON Error Codes This section describes all error codes which you may use for programming a frame grabber interface Appendix C Interface Template CIOFGTemplate c This section contains a source code template for a frame grabber interface Naturally this also includes knowledge about the programming environment how to invoke the com piler linker Release Notes Plea
37. STRING_PAR INTERFACE_REVISION adapt to Revision in header value gt type value gt par s else parameter not supported return H ERR FGPARAM return H MSG OK FGGetParam static FGInstance FG penRequest Hproc handle proc id FGInstance fginst 1 INT i if numInstance gt FG MAX INST 1 too many instances return NULL else Note If you do not want to bother about multiple instances just return ALWAYS the same instance fginst gt gen_pointer void amp FGInst 0 return amp fgClass gt instance 0 instance will be closed using FGClose and re opened using FGopen retrieve next unused instance for 1 0 i lt FG MAX INST i 1 if FGInst i board break F if i gt FG_MAX_INST return NULL this cannot happen but you know Murphy don t you fginst gt gen_pointer void amp FGInst i return amp fgClass gt instance i F FGOpenRequest Frame Grabber Integration 2000 11 16 SS SSS SSS SS SS SS SSS SS SS SS SSS SSS SSS SS SSS SSS SSS SS SSS S55 SSS SSS 555555555 S gt Herror FGInit Init
38. TEMPLATE CIOFGTEMPLATE C BoardInfo board currInst gt board currInst gt allocBuffer FALSE if board gt sizeBuffer 1 that s the very first time such buffers per board are requested for i20 i MAX BUFFERS i 1 err 11 proc id size_t sizeBuffer amp board gt BoardFrameBuffer i if err H MSG OK return CleanupFG pen proc id currInst newBoardalloc err board gt sizeBuffer sizeBuffer else if board gt sizeBuffer sizeBuffer bad luck The size of the shared buffers does not match the required size currInst gt allocBuffer TRUE if currInst gt allocBuffer 1 insert references for i20 i MAX BUFFERS 1 1 currInst gt InstFrameBuffer i board gt BoardFrameBuffer i board gt refBuffert one more instance that uses the board buffers else currInst gt allocBuffer TRUE if currInst gt allocBuffer do not use shared buffers but allocate the buffers for this new instance for 1 0 i lt MAX_BUFFERS i 1 err HAlloc proc_id size_t sizeBuffer amp currInst gt InstFrameBuffer i if err H_MSG_OK return CleanupFG pen proc id currInst newBoardalloc err currInst gt currBuffer 0 start whith the first buffer TODO Final Settings IE IE ISIS I A ia ak ka ak increase the number of instanc
39. Terminates jobs pending asynchronous grabs started the same physical board another board is no problem since that usually has its own memory Note that if the board has more than one A D converter the other jobs in general won t have to be killed This routine might be useful for FGOpen please see the FGopen routine prior to studying this one here static HBOOL KillAllO0therJobs FGInstance fginst TFGInstance currInst TFGInstance fginst gt gen_pointer INT i HBOOL killedSomebody FALSE if numInstance gt 1 1 for 1 0 i lt FG MAX INST i 1 if FGInst i board amp amp currInst gt instance i Frame Grabber Integration 2000 11 16 5 ok FGInst i is in use and is NOT the current Instance Now let s see if it references the same board as the current instance if FGInst i board currInst gt board amp amp FGInst i busy There might be a problem Another asynchronous grab using the same frame grabber board TODO terminate this async job killedSomebody TRUE FGInst i busy FALSE return ki
40. c DOGO aK k k k kk k kk kk CIOFGTemplate c aaoo ooo o ooo ooo o ok kk kk Project HALCON Author s Th Bandlow Ch Zierl Description General purpose frame grabber interface version 2 template 1996 2000 by Software GmbH www mvtec com ee dG de de ode aeoo E oko oko oko oko ook ook ok ok ok ok oko k oko o ok ok ok ok ok Kok k kk ook ook Kok ook k kk oko o ok ok ok Kok Kok 2k oe o K k K K K KK KKK See also Frame Grabber Integration Programmer s Manual Extension Package Interface Programmer s Manual Procedures Herror FGInit handle proc id FGClass fg static Herror FG pen Hproc_handle proc id FGInstance fg static Herror FGClose Hproc_handle proc id FGInstance fg static Herror FGGrabStartAsync Hproc handle proc id FGInstance fginst double maxDelay static Herror FGGrab Hproc_handle proc id FGInstance fginst Himage image INT num image static Herror FGGrabAsync Hproc_handle proc_id FGInstance fginst double maxDelay Himage image INT num_image static Herror FGGrabRegion Hproc_handle proc_id FGInstance fginst Hrlregion region INT num_region INT rlalloc_type static Herror FGGrabRegionAsync Hproc_handle proc_id FGInstance fginst Hrlregion region INT num_region INT rlalloc_type static Herror FGInfo Hproc_hand
41. fginst gt gen_pointer Set timeout and asynchronous mode currInst gt timeout INT4_8 1 0 5 fginst gt async_grab TRUE Get current image segment it and start new grab HCkP FGGrabRegion proc_id fginst region num_region rlalloc_type return H_MSG_OK FGGrabRegionAsync Information value list if applicable concerning a specific query for this frame grabber as requested by info_framegrabber ATTENTION No memory has been allocated for values L static Herror FGInfo Hproc handle proc INT queryType char info Hcpar values INT numValues 1 queryType FG_QUERY_GENERAL General Info full name vendor etc FG QUERY PORT Descript of the ports signal connectors FG_QUERY_CAMERA_TYPE Descript of the camera_type paramater FG_QUERY_DEFAULTS Default values see open_framegrabber FG_QUERY_PARAMETERS Names of non standard parameters available for set_framegrabber_param FG_QUERY_INFO_BOARDS Info about installed boards HALCON 6 0 98 APPENDIX INTERFACE TEMPLATE CIOFGTEMPLATE C Hcpar val INT i switch queryType 1 case FG QUERY GENERAL kokokokok kokokokeleokeokokeokokokekelokokokokokokolelolokokokokokololololokokokokolololelololololololeleleleleololek TODO Return general information
42. for 1 0 i lt FG_PARAM_NUM i val i type STRING PAR values val numValues FG PARAM NUM break case FG QUERY INFO BOARDS switch return H_MSG_OK FGInfo static Herror FGSetLut Hproc_handle proc_id FGInstance fginst INT4_8 red INT4_8 green INT4_8 blue INT num TFGInstance currInst TFGInstance fginst gt gen_pointer TODO Return the real device numbers of the installed boards something like that info Info about installed xy boards values NULL numValues 0 break default info Unsupported query values NULL numValues 0 TODO Set the lookup table of your frame grabber DOC OOOO OC GG GGG GCI CG IG GCI GCI IG Ia I ICI CI ak kak a kk input to this routine is RGB lookup table with num entries of RGB triples There is not much more than can be said in general Sorry you will have to find o
43. frame grabbers but it cannot change the handles in your program Thus it is in your responsibility not to use these handles later on Since close all framegrabbers is based on close framegrabber you do not have to pro vide specific routines for this operator inside your frame grabber interface 1 6 4 info framegrabber The operator info_framegrabber is used to access basic information about a specific frame grabber board and the corresponding interface Note that since many parameter settings de pend on the specfic properties of a frame grabber HALCON can neither provide meaningful defaults nor check parameters automatically This operator will call the routine FGInfo in your frame grabber interface see section 3 5 HALCON 6 0 8 CHAPTER 1 INTRODUCTION 1 6 5 grab image The operator grab image is used to grab a new image synchronously that means a new grab is started and the operator waits until this grab has been finished This operator will call your interface routine FGGrab see section 3 6 1 6 6 grab image async The operator grab image async grabs a new image asynchronously It waits until a pending asynchronous grab has been finished if you got the timing right this grab should be finished already to prevent wasting time at this point This image 15 then returned unless it is older than a specified threshold Otherwise a new synchronous grab is performed Afterwards grab image async triggers a new async
44. handle proc id FGInstance fginst Himage image INT num image grab an image synchronously return H MSG OK Figure 3 27 prototype for FGGrab Note that there might be an asynchronous grab pending when entering this routine if the application called grab_image_async or grab_imgage_start prior to grab_image Since you want to grab an image synchronously now you should terminate these grabs and launch a new grab However if you have a closer look at the semantics of the grab routines you will notice that it is quite easy to implement FGGrabAsync based on FGGrab if you include some additional branches in the code Furthermore FGGrabRegion and FGGrabRegionAsync also share the basic task of grabbing an image to a buffer with the other two routines Thus we suggest to implement an auxiliary routine GrabImg underlying all four of them see Fig 3 28 include Halcon h include hlib CIOFrameGrab h static Herror GrabImg handle proc id FGInstance fginst INT readBuffer grab an image to the current buffer return H MSG OK Figure 3 28 The prototype for the auxiliary routine GrabImg Based on this auxiliary routine FGGrab might look as shown in Fig 3 29 Note that we only support one channel grayscale and three channels color images of 8 bit scale depth per channel In the framework suggested in this manual it is also called by FGGrabAsync see section 3 8
45. physical frame grabber board currInst gt board gt refInst Again this is only of importance if you would like to support multiple instances Note that these counters have been suggested in Fig 3 5 and section 2 2 1 It is up to you whether you follow this recommendation or come up with another solution Frame Grabber Integration 2000 11 16 3 3 FGOPEN 33 static Herror FGOpen Hproc_handle proc id FGInstance fginst 8 sizeBuffer SizeBuffer fginst gt image_width fginst gt image_height fginst gt bits_per_channel 7 8 fginst num channels if 1 share the buffers with other instances BoardInfo board currInst gt board currInst gt allocBuffer FALSE if board gt sizeBuffer af that s the very first time such buffers per board are requested for i 0 i lt MAX_BUFFERS i err HAlloc proc id size t sizeBuffer amp board 5BoardFrameBuffer i l if err H MSG OK return CleanupFGOpen proc_id currInst newBoardalloc err board gt sizeBuffer sizeBuffer else if board gt sizeBuffer sizeBuffer bad luck The size of the shared buffers does not match the required size currInst gt allocBuffer TRUE if currInst gt allocBuffer insert references for i 0 i lt MAX_BUFFERS i currInst gt InstFrameBuffer i board gt BoardFrameBuffer i board gt refBuffer one more instan
46. should use the appropriate frame grabber API call to terminate the grab Otherwise you may encounter severe troubles if you deallocate the buffers the frame grabber grabs into The latter has to be done in accordance with the strategies for buffer allocation in FGOpen see section 3 3 Fig 3 20 may serve as a template for this Note that we use HALCON extension package interface routine HFree to deallocate memory delivered by HA11oc However in most cases you will have to replace HAlloc and thus HFree by specific routines of your frame grabber If the frame grabber instance to be closed is the last one assigned to a specific physical board you have to close or unlock the board using the appropriate API calls and to deallocate the BoardInfo structure if any see Fig 3 21 Note that you might have to consider the spe cial case that after closing the specified instance there is only one more instance left assigned to the board This case is special in that sense that other routines like FGGrab will assume that all parameters of this single remaining instance have already been set on the board during FGOpen Thus they might skip resetting these parameters again which could lead to unex pected grabbing results There are two obvious solutions to this problem One is to restore the parameters of the last remaining instance in FGC1ose the other is to check for discrepancies between board settings and instan
47. specified lookup table for an instance return H_MSG_OK Figure 3 51 The prototype for FGGetLut This routine is the counterpart to FGSetLut in section 3 14 It has to return three integer arrays for the red green and blue components of the LUT and the number of entries in these arrays Memory for FG MAX LUT LENGTHP entries per array has already been allocated by the HALCON library Whether lookup tables are supported or not and how to handle such lookup tables depends on the frame grabber and its API Therefore we cannot provide source code for this task Tn the current version FG MAX LUT LENGTH is 4096 corresponding to a maximum resolution of 12 bits per channel Frame Grabber Integration 2000 11 16 Chapter 4 Generating a Frame Grabber Interface Library Whenever a frame grabber is accessed for the very first time by using open_framegrabber or info_framegrabber the corresponding HALCON frame grabber interface library a dynami cally loadable module is loaded This chapter contains information on how to generate such a dynamic object Please refer to the documentation of your programming environment for details on compiling and linking Generating a Frame Grabber Interface Under Windows NT 2000 To build a HALCON frame grabber interface you have to generate a DLL from the file contain ing the source code of your interface like CIOFGTemplate c by linking the corresponding object file s with e the
48. the corresponding In any case you have to set the corresponding input line prior to grabbing Frame Grabber Integration 2000 11 16 3 3 FGOPEN 29 include Halcon h Herror HAlloc Hproc_handle proc_id size_t size void pointer allocate memory on the heap return H_MSG_OK Figure 3 12 The prototype for the HALCON extension package interface routine HAlloc BoardInfo structure if you follow our suggestions see also section 2 2 1 Fig 3 11 shows some example code dealing with this The routine HA11oc as defined in Fig 3 12 is provided by the HALCON extension package interface see the Extension Package Programmer s Manual for details It is used to allocate memory on the heap ifdef WIN32 define STR_CASE_CMP S1 S2 stricmp 1 82 else define STR_CASE_CMP S1 S2 strcasecmp S1 S2 endif static Herror FGOpen Hproc_handle proc_id FGInstance fginst INT norm if STR_CASE_CMP fginst gt camera_type auto use special routines provided by your frame grabber to analyze the video signal else if STR_CASE_CMP fginst gt camera_type ntsc norm FG_NTSC fginst width max 640 gt max 480 else if STR_CASE_CMP fginst gt camera_type 1 norm FG_PAL fginst gt width_max 768 fginst gt height_max 576 else well whatever return H MSG OK Figure 3 13 Example code for FGOpen
49. use the global pointer fgClass that has been set to the FGC1ass structure assigned to this interface that is to this frame grabber model in FGinit as suggested in Fig 3 5 Al ternatively you could also use fginst gt fgclass which is also a pointer to the same structure Note further that in Fig 3 7 the generic pointer gen pointer inside the data structure FGInstance see section 2 1 2 is used to establish a link between the exterior structure fginst provided by the HALCON library and the TFGInstance structure FGInst i inside the inter face The example code in Fig 3 8 will cause HALCON to automatically close the old instance whenever you request a new instance using open framegrabber This is very convenient for interactive programming with HDevelop but obviously leads to a severe side effect Thus you might also check whether there is an active instance using a boolean flag and return NULL in case the frame grabber is busy You should not bother too much about this routine In most cases you can use one of the two examples provided without any changes Frame Grabber Integration 2000 11 16 3 3 FGOPEN 27 FGOpen The routine FGOpen as defined in Fig 3 9 is called by HALCON operator open_framegrabber see section 1 6 It has to perform the following tasks e Check all parameters specified in the FGInstance structure fginst e Check the availability of the specified frame grabber board and initialize th
50. users who are not familiar with topics like frame grabber hardware A D conversion synchronous or asynchronous mode of operation buffer ing strategies and the like Although this manual is not intended to supply you with detailed knowledge about your frame grabber s internals we still want to give explanations of the basic terms and methods Reading the manuals supplied with your frame grabber is a necessity of course and possibly gives you a much more detailed view on the things being discussed here Unless stated otherwise all notations refer to Windows NT 2000 conventions Thus for example file paths and environment variables are printed like AHALCONROOT NexamplesNf g integrationNCIOFGTemplate c If you are using a UNIX system you have to consider the corresponding UNIX syntax 1 1 HALCON s Generic Frame Grabber Interface HALCON provides a generic frame grabber interface that allows free integration of new frame grabbers on the fly that is even without restarting a HALCON application The two basic concepts used are e Encapsulation of the interface code in dynamically loadable modules e set of predefined HALCON operators for image acquisition including operators for setting and retrieving specific hardware parameters The latter allow the parameterization of even the most exotic boards If you have successfully developed a new HALCON frame grabber interface based on the detailed information given in this manual
51. which is more general than necessary for a pure synchronous grabbing we can easily implement FGGrabAsync based on FGGrab see Fig 3 37 we have to do is to set the asynchronous grabbing mode fginst async grab is TRUE and to update the threshold for the decision whether an asynchronously grabbed image is too old and thus has to be replaced by a new image currInst gt timeout see also Fig 3 36 Frame Grabber Integration 2000 11 16 3 9 FGGRABSTARTAS YNC 51 3 9 FGGrabStartAsync The routine FGGrabStartAsync as defined in Fig 3 38 is called by the HALCON operator grab_image_start see section 1 6 It has to perform the following tasks e Terminate pending asynchronous grabs of all instances assigned to the current board e Re set the parameters on the frame grabber board e Start an asynchronous grab include Halcon h include hlib CIOFrameGrab h static Herror FGGrabStartAsync Hproc_handle proc_id FGInstance fginst double maxDelay start an aynchronous grab return H MSG OK Figure 3 38 The prototype for FGGrabStartAsync The implementation of this routine is rather straightforward see Fig 3 39 Please also take a look at the auxiliary routine GrabImg in section 3 7 which is the counterpart to FGGrabStartAsync finishing the grab started here Note that in general all pending grabs of instances assigned to the same board have to be canceled A pending job of the current ins
52. wrong color depth if fginst gt bits_per_channel 8 fginst gt bits_per_channel 12 example Allow only 8 and 12 bits per image channel return H_ERR_FGWC TODO Check the desired color space desired color space eg gray or rgb is passed fginst gt color_space What we have to do is to test for each valid color space the fginst bits per channel parameter on valid value and set fginst gt num_channels on the number of image channels of the resulting HALCON image NOTE within this concept can t distinguish between rgb images of 24 and 32 bits per pixel if both modes should be offered This is because both modes result a 8 8 8 rgb HALCON image In this case we recommend to prefer the 24 bit mode it implicates lower load the PCI bus If you have to provide 32 bits per pixel set fginst gt num_channels 4 If you want to offer both modes anyhow we recommend to initiate a separate color space xrgb for the 32 bit mode and use the rgb value to denote the 24 bit mo
53. 4 How many buffers most cases 2 in order to support asynchronous grabbing see also the define MAX BUFFERS If you fail to allocate buffers return H_ERR_MEM not enough memory example NOTE YOU WILL HAVE TO CHANGE THIS SECTION IN 99 OF 100 CASES We assume that we can crop an image part of size fginst gt image_width x image_height in hardware thus the size of the buffers is something like sizeBuffer fginst gt image_width fginst gt image_height fginst bits per channel47 8 fginst gt num_channels Note that especially for color frame grabbers fginst gt bits_per_channel 7 8 fginst gt num_channels might fail e g if the frame grabber delivers 32 bits of data instead of 24 this case make sure that you have set the fginst gt num_channels parameter to 4 above Now we decide whether to use the memory pool of the board shared by maybe more than one instance or to allocate instance specific buffers if 1 1 share the buffers with other instances 83 HALCON 6 0 84 APPENDIX C INTERFACE
54. 55555 S gt Herror FGGrab SS SS SS SS SS SSS SSS SS SSS SSS SSS SSS SS SSS SSS SSS SSS SSS SSS SSS SSS Grab an image via grab_image that is synchronously Note In most cases you can use this routine also for asynchronous grabbing see FGGrabAsync SSS S SSS SSSSSSSS SS SS SS SSS SS SSS SS SSS SSS SSS SSS SSS SS SSS SSS SSS SSS SSS SSS SSS static Herror FGGrab Hproc_handle proc_id FGInstance fginst Himage image INT num_image TFGInstance currInst TFGInstance fginst gt gen_pointer INT readBuffer INT i Herror err HCkP GrabImg proc id fginst amp readBuffer Vette TODO Create image from the grabbed data DOCG Kk k k k kk kk Note that this might be slightly more difficult as indicated below if you would like to do subsampling or cropping of image parts in software For the example we assume that this is done by the frame grabber hardware if currInst gt volatileMode 1 OOO IOS Insert the buffer into HALCON object fast but with side effects see above Frame Grabber Integration 2000 11 16
55. CON operators see section 1 6 Before we take a look at the data structures involved we should bear in mind that some parts of the frame grabber management take place in the HALCON library and others are up to your frame grabber interface It is important to keep in mind who is responsible for what The HALCON library s job is to e Maintain a list of frame grabber classes e Maintain a list of instances for each class and to e Decode and preprocess an operator s parameters The interface s job is to e Define a class e g filling the data structure with appropriate data e Manage multiple instances and their mutual dependencies e Interprete an operator s parameters and map them to the underlying hardware and to e Grab images based on the frame grabber s application programming interface APT 1 8 Additional Sources of Information For further information please consult one of 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 10A DLL for Windows NT 2000 or a shared library for UNIX systems respectively Frame Grabber Integration 2000 11 16 1 8 ADDITIONAL SOURCES OF INFORMATION 11 e HALCON C User s Manual How to use the HALCON library in your programs e HALCON C User s Manual How to use the HALCON library in your
56. GGrab FGGrabStartAsync and FGGrabAsync Others have to be SET right now TODO Set port input line we did the checks already now we set these values on the board kk kk TODO Set video gain DECRG OOOO IE IE ISI We did the check already now we set this value on the board o o o kk k kk k kk kk TODO Set external triggering if fginst gt external_trigger Well whatever the frame grabber API requests you to do TODO Evaluate the camera_type parameter
57. HALCON Version 6 0 Mr MVTec Software GmbH Frame Grabber Integration Programmer s Manual This manual describes the integration of user specific frame grabbers into the HALCON system Version 6 0 All rights reserved No part of this publication may be reproduced stored in a retrieval system or transmitted in any form or by any means electronic mechanical photocopying recording or otherwise without prior written permission of the publisher Edition July 1997 Edition November 1997 Edition March 1998 Edition April 1999 Edition November 2000 LE P E EC Copyright 1997 2000 by MVTec Software GmbH M nchen Germany Microsoft Windows Windows 95 Windows NT Windows 2000 Visual C and Visual Basic 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 basic techniques needed to integrate third party image acquisition hardware frame grabber boards into the HALCON system The manual is written for the expert HALCON user who wants to integrate a new frame grabber board The reader should be familiar with the standard HALCON system Furthermore C programming skills are required Finally detailed knowledge about the frame grabber API will be necessary
58. HALCON can use one and the same HALCON frame grabber interface library Frame Grabber Integration 2000 11 16 Appendix Changes between Versions 1 and 2 of the HALCON Frame Grabber Integration Interface This section summarizes all syntactic and semantic differences between the HALCON frame grabber integration interface version and version 2 Please note that because of these changes older frame grabber interfaces won t work together with HALCON 6 0 and vice versa This applies to every supported operating system since the library symbols of the integration interface have changed The following variable names of the structures FGClass and FGInstance have changed Version 1 Version 2 bits bits_per_channel generic camera_type start_line start_row internal_width horizontal_resolution internal height vertical resolution width image width height image height Sel input line in In addition the structure FGClass does not contain the variables bw available color available gray available width max height max width max and mode any more The structure FGInstance does not contain the variable threshold anymore The variable num channels has been moved from FGClass to FGInstance Note that not only the notation has changed but also the meaning of variables bits per channel now denotes the number of actually transferred bits per pixel for one im age channel while bits denoted the number of bits per pixel ov
59. INIT 23 Herror FGInit Hproc handle proc id FGClass fg A mcs ECC D E The following defaults will be delivered to FGOpen if default or 1 is specified open_framegrabber fg gt horizontal_resolution 1 fg gt vertical_resolution ale fg gt image_width fg gt image_height 0 fg gt start_row fg gt start_col 0 fg gt field FG_FULL_FRAME fg gt bits_per_channel 8 strcpy fg gt color_space gray fg gt gain 1 04 fg gt external_trigger FALSE strcpy fg gt camera_type auto strcpy fg device 0 fg gt port ils fg gt line_in als return H MSG OK Figure 3 3 Example code for FGInit Initialize FGClass continued Interface routine Function pointer Error code FGGrabAsync fg GrabAsync ERR FGASYNC FGGrabStartAsync fg gt GrabStartAsync ERR FGASYNC FGGrabRegion fg gt GrabRegion H_ERR_FGFNS FGGrabRegionAsync fg gt GrabRegionAsync H_ERR_FGFNS FGSetParam fg gt SetParam H_ERR_FGPARAM FGGetParam fg gt GetParam H_ERR_FGPARAM FGSetLut fg gt SetLut H_ERR_FGFNS FGGetLut fg gt GetLut H_ERR_FGFNS Figure 3 4 Optional interface routines and the corresponding error codes returned by the HAL CON library if the routines are missing section 2 2 2 Note that in this example we have also assumed that you are willing to support multiple instances If you would like to start with a simple f
60. Instance currInst TFGInstance fginst gt gen_pointer paaa aaoo ooo ooo ooo ooo ooo ooo ooo ooo ook kk TODO Parse the parameter param and set the corresponding frame grabber parameter for this instance The standard parameters specified open_framegrabber evaluated in FGOpen cannot cover every aspect of the hardware features of all available frame grabbers Therefore HALCON provides an additional operator to specify settings for frame grabber specific features OR tox change the values for standard parameters without closing an opening the frame grabber again Additional parameters are denoted by an arbitrary string of YOUR choice However please make the names of these parameters available via the query FG_QUERY_PARAMETERS FGInfo so that the user can access this information online The STANDARD PARAMETERS be handled using the following defines note that you do NOT have to support all these parameters here this routine They set via FGOpen during the initialization of a new instance However you might want to change the original settings dynamically without closing opening the frame grabber again define curr value of the define type
61. Instances INT currBuffer index of the active buffer INT sizeBuffer size of each buffer INT refBuffer number of references to the buffers from TFGInstance s INT refInst number of instances assigned to this board more examples HBOOL doesPhysicalSubsampling INT maxBitsPerChannel BoardInfo typedef struct Note The following struct members will be used once per instance that is more than one per board e g if you use several cameras per frame grabber DORE ISI I a TODO Place your FG specific data here 7 73 HALCON 6 0 74 APPENDIX C INTERFACE TEMPLATE CIOFGTEMPLATE C examples BoardInfo board the physical board this instance is attached to HBOOL busy useful if you plan to support asynchr grabbing is the last grab still running INT instance a useful backreference to the general HALCON instance information The instance index 0 to FG_MAX_INST 1 4 8 timeout useful for async grabbing timeout threshold for images too old INT currBuffer you probably use more than one buffer Index of the active buffer
62. LLocal HAllocRLNumLocal 1 11 FG RLALLOC LOCAL Attention If you the Tmp version you MUST allocate the image regions ascending order because they re stored on the stack and the HALCON interface will free them in descending order We recommend to use the Local version It s more flexible than the Tmp version but still includes an automatic garbage collection Example Allocate two regions e g one for all image parts of specific color and one for the rest of the image HCkP HAllocRLNumLocal proc_id amp region 0 fginst gt image_width fginst gt image_height 2 HCkP HAllocRLNumLocal proc_id amp region 1 fginst gt image_width fginst gt image_height 2 rlalloc type FG_RLALLOC_LOCAL Frame Grabber Integration 2000 11 16 97 Well the segmentation itself is up to you num region 2 Note that we will use FGGrabRegion for asynchronous grabbing also Thus we set the async grab here explicetly for synchronous grabbing and reset it to asynchronous grabbing FGGrabRegionAsync if necessary fginst gt async_grab FALSE return H_MSG_OK FGGrabRegion static Herror FGGrabRegionAsync Hproc_handle proc_id FGInstance fginst double maxDelay Hrlregion region INT num_region INT rlalloc_type TFGInstance currInst TFGInstance
63. M return H MSG OK FGSetParam static Herror FGGetParam Hproc handle proc_id FGInstance fginst char param Hcpar value INT num TFGInstance currInst TFGInstance fginst gt gen_pointer num 1 GCG IG IG GCG GI IS II I a Ik kok ak 7 TODO Parse the parameter param and return the corresponding frame grabber parameter for this instance Please see FGSetParam for detailed discussion Note The standard parameters encoded fginst are already handled by the HALCON system You do NOT have to provide code for these 103 HALCON 6 0 104 APPENDIX C INTERFACE TEMPLATE CIOFGTEMPLATE C parameters here Example Return the volatile status see FGSetParam if strcmp param FG_PARAM_VOLATILE VOLATILE value gt type STRING_PAR value gt par s currInst gt volatileMode enable disable else if strcmp param FG_PARAM_REVISION T REVISION
64. NT widthScale INT heightScale HBOOL newBoardalloc FALSE Herror err 4 8 sizeBuffer TODO Set defaults fginst gt async_grab FALSE currInst gt busy FALSE currInst gt allocBuffer FALSE currInst gt currBuffer 0 currInst gt volatileMode FALSE DOGG Kk k k k kk TODO Place initialization code here the complexity of this fk task depends on the features you want to support e g fk if you allow only one board with only one input line this fk is quite simple if however you want to support multiple boards with different features using API with every fk board having many ports and multiplexed input lines things could get bit tricky NOTE following example fragments assume that you want fk it the hard way multiple boards multiple ports multiple input lines different board types Kk k k k kk if currInst gt busy kill my own job This should not happen but who knows
65. RES SS SSS SSS SSS SSS default values xf horizontal resolution desired resolution delivered vertical_resolution by the board image width image height desired image size start_row start_col upper left corner field even or odd field full image mode bits channel color depth per pixel amp channel color space MAX STRING gray rgb yuv gain video preamp gain external trigger trigger mode camera_type MAX_STRING used camera type fg specific device MAX_STRING device name port to use line multiplexer input line miscellaneous Figure 2 4 The data structure FGClass defined in include hlib CIOFrameGrab h continued HALCON operator corresponding function pointer open_framegrabber FGClass close_framegrabber FGClass grab_image FGClass grab_image_async FGClass grab_region FGClass grab_region_async FGClass grab_image_start FGClass info_framegrabber FGClass set_framegrabber_lut FGClass get_framegrabber_lut FGClass set_framegrabber_param FGClass get_framegrabber_param FGClass OpenRequest FGClass pen Close Grab GrabRegion GrabRegionAsync GrabStartAsync Info GetLut SetParam GetParam Figure 2 5 HALCON operators and the corresponding FGClass members in FGClass Moreover ad
66. TER 3 INTERFACE ROUTINES external trigger is externally defined as string true or false but is internally defined as boolean value of type HBOOL The parameter value to be set is passed in a structure of type Hcpar Please refer to the Ex tension Package Programmer s Manual for a detailed description of this structure Some comments have been made on page 38 in this manual as well external define internal define FG_FIRST_FIELD_TXT first FG_FIRST_FIELD FG_SECOND_FIELD_TXT second FG_SECOND_FIELD FG_NEXT_FIELD_TXT next FG NEXT FIELD FG FULL FRAME TXT interlaced FG FULL FRAME FG PROGRESSIVE FRAME TXT progressive FG PROGRESSIVE FRAME Figure 3 47 Internal and external representation of values for the parameter Field in open framegrabber Feel free to choose arbitrary names for additional parameters However we suggest to try to preserve the look and feel of typical HALCON operators and to choose names in correspon dence with the API of the specific frame grabber Please do not forget to return these parameter names for the query FG QUERY PARAMETERS in FGInfo see Fig 3 26 on page 40 The HALCON frame grabber integration interface also provides the opportunity to pass multi parameter values This enables you to pass a tuple of values for the parameter param with num denoting the number of values In general you will have to extend the structures BoardInfo and TFGInstance to hold these additional para
67. ab HCkP FGGrab proc_id fginst image num_image return H MSG OK FGGrabAsync static Herror FGGrabRegion Hproc handle proc id FGInstance fginst Hrlregion region INT num region INT rlalloc type TFGInstance currInst TFGInstance fginst gen pointer INT readBuffer TODO Grab an image and segment it into region s region is an array of 0BJ PER PAR pointers to Hrlregion the Hrlregions themself have not been allocated so far HCkP GrabImg proc_id fginst amp readBuffer Now you ve got an image in buffer readBuffer segment it Note that there three different ways to allocate region data see the C Interface Programmer s Manual for details Since the data you allocate in this routine is copied to the HALCON data base and then deallocated again the caller of this routine must know which one you used This is specified by rlalloc_type HAllocRLTmp HAllocRLNumTmp rlalloc_type FG_RLALLOC_TMP HAllocRL HAllocRLNum rlalloc type FG RLALLOC PERMANENT HAllocR
68. air You should corresping value and of course the consistency of the specified value In case of unreasonable inputs return the error codes H_ERR_FGPARAM parameter not supported H_ERR_FGPART invalid parameter type H_ERR_FGPARV invalid parameter value Note that some of the parameters might have side instances Thus you might have to include these effects on other parameters in the BoardInfo and TFGInstance structs and set them prior to each grab Example In our example we will enable disable the volatile mode for an instance see also FG pen This does not change the current configuration of the board itself Thus we can perform all necessary steps right here in this routine without side effects on other instances strcmp param FG PARAM VOLATILE 1 11 In the volatile mode we attach the frame grabber s buffer memory to the HALCON image instead of allocating new memory thus avoiding a memcpy Note that this grabbing method has a severe side effect 014 HALCON images are overwritten By the way many color frame grabbers is e g RGB triples instead of three separate channels In this case you have to split the data explicitly Thus a volatile mode is not attractive anymore If YOU
69. ations like these uses classes and instances of classes A class represents a specific frame grabber model and its interface The corresponding data structure contains all the function pointers needed to access the routines within the interface and the default parameter settings for open_framegrabber Such an entry exists only once for each type of frame grabber Each new instance created from this class represents either a specific board belonging to this class or a multiplexed port on such a board Fig 2 1 shows a possible configuration The first two frame grabber boards in our example a model 1000 and a model 2000 are different boards from the same manufacturer labs Assuming these similar boards being con trolled by the same frame grabber interface they belong to the same class Therefore the input lines connected to camera 1 and 2 represent two instances of this class The third frame grabber is a totally different one bar inc smega grabber and therefore another interface is needed the second class This frame grabber has two probably multiplexed ports attached thus camera 3 and 4 can be understood as two instances of this second class 2 1 4 Structure FGClass The data structure FGClass encapsulates the data common to all instances of one frame grab ber model see Fig 2 2 to 2 4 It is initialized by your interface routine FGInit see sec Well to be honest there is a limitation HALCON ca
70. buffer therefore delete the buffer now for 1 0 i lt MAX_BUFFERS i 1 if board gt BoardFrameBuffer i 1 HFree proc_id board gt BoardFrameBuffer i board gt BoardFrameBuffer i NULL board gt sizeBuffer 0 otherwise Do not touch the buffers they still in use board gt refBuffer TODO Deallocate Board Check if the referenced board is still use by another instance if currInst gt board gt refInst lt 1 k Ok here comes the serious part You must close the board itself because its not in use anymore But please do not ask how to do this ask the API manual of the frame grabber instead deallocate the BoardInfo you have allocated FGOpen HFree proc_id currInst gt board else 1 curr Inst gt board gt refInst if currInst gt board gt refInst 1 This is sort of a special situation After you close this instance there is only one other instance left using the same frame grabber
71. c has to be set again HCkP SetInstParam fginst OOO GOGO GOI IO IG Note If you encounter errors during grabbing return one of the following error codes H_ERR_FGNV no video signal H_ERR_FGF grabbing failed general H ERR FGTIMEOUT timeout x ia if currInst gt busy there is an asynchronous job pending for this instance if fginst gt async_grab a SYNCHRONOUS grab was requested TODO Cancel the current job Peet newGrab TRUE else an ASYNCHRONOUS grab was requested TODO Check if the previously started grab has finished there is pending grab currInst gt busy is TRUE Assume that the checking routine sets done to TRUE FALSE if done old grab fi
72. ce settings prior to each grab in any case Finally you should mark the internal instance currInst as free again currInst gt board NULL and decrease the number of active instances numInstance HALCON 6 0 36 CHAPTER 3 INTERFACE ROUTINES static Herror FGClose Hproc_handle proc_id FGInstance fginst TFGInstance currInst TFGInstance fginst gt gen_pointer if currInst gt allocBuffer buffers have been allocated for this instance exclusively get rid of them for 0 i lt MAX_BUFFERS i if currInst gt InstFrameBuffer i af HFree proc_id currInst gt InstFrameBuffer i currInst gt InstFrameBuffer i NULL else BoardInfo board currInst gt board the instance shared the board buffers with other instances if board gt refBuffer 1 This is the last instance which uses the board frame buffer therefore delete the buffer now for i 0 i lt MAX_BUFFERS i if board gt BoardFrameBuffer i HFree proc_id board gt BoardFrameBuffer i board gt BoardFrameBuffer i NULL board gt sizeBuffer 0 otherwise Do not touch the buffers they still in use board gt refBuffer return H_MSG_OK Figure 3 20 Example code for FGC1ose Deallocate buffers Frame Grabber Integration 2000 11 16 3 4 FGCLOSE 37 static Herror FGClose Hproc han
73. ce structure pointed to by fginst see also section 2 1 2 HALCON 6 0 28 CHAPTER 3 INTERFACE ROUTINES Whenever you specify default in this operator the corresponding default value you provided in FGInit O see Fig 3 3 will be passed in fginst The parameter checking is rather straightforward Test whether the specified values are reason able for your frame grabber board or not Please note that the HALCON library itself cannot do much of such plausibility tests since the hardware capabilities of frame grabbers differ too much Whenever you detect an incorrect request return one of the error codes listed in ap pendix B Note that returning from an arbitrary position inside your interface code might lead to memory leaks or blocked frame grabber boards Therefore we recommend to do as much parameter checks as possible before accessing the physical board or allocating memory On the other hand some of these tests must be delayed until the board itself is initialized and an analysis of the video signal is possible for example In this case be sure to deallocate all the memory and to unlock the frame grabber board before returning an error code static Herror FGOpen Hproc_handle proc id FGInstance fginst if currInst gt board HCkP HA110c proc id size_t sizeof BoardInfo amp currInst gt board init the struct currInst gt board e g memset currInst gt board 0 sizeof BoardInfo strcpy c
74. ce that uses the board buffers Figure 3 17 Example code for FGOpen O Allocate buffers to be continued HALCON 6 0 34 CHAPTER 3 INTERFACE ROUTINES static Herror FGOpen Hproc_handle proc_id FGInstance fginst else currInst gt allocBuffer TRUE if currInst gt allocBuffer at do not use shared buffers but allocate the buffers for this new instance for i 0 i lt MAX_BUFFERS i HCkP HA110oc proc id size_t sizeBuffer amp currInst gt InstFrameBuffer i return H MSG OK Figure 3 18 Example code for FGOpen O Allocate buffers continued Frame Grabber Integration 2000 11 16 3 4 FGCLOSE 35 3 4 FGClose The routine FGClose as defined in Fig 3 19 is called by the HALCON operator close_framegrabber see section 1 6 It has to perform the following tasks e Terminate pending asynchronous grabs e Deallocate the buffers e Close or unlock the physical frame grabber board if the instance to be closed is the last one assigned to this board e Mark the instance as include Halcon h include hlib CIOFrameGrab h static Herror FGClose Hproc handle proc id FGInstance fginst 1 close the specified frame grabber instance fginst return H MSG OK Figure 3 19 The prototype for FGClose A pending asynchronous grab is indicated by currInst gt busy TRUE see also FGGrabAsync in section 3 8 In this case you
75. commend to store instance specific data in another structure called TFGInstance see below 2 2 2 Structure TFGInstance We recommend to use a data structure called TFGInstance to extend the data provided by FGInstance for each frame grabber instance Fig 2 8 shows a typical example Obviously it is very convenient to hold references to both the assigned physical board board and the corresponding instance data from the HALCON library instance Moreover to han dle asynchronous grabbing entries like busy indicating that a grab is still pending timeout holding the current setting for the maximum tolerated of an asynchronously grabbed image or grabStarted containing a timestamp might be a good idea If you would like to support volatile grabbing i e to let the frame grabber buffers containing the image data insert into HALCON images a flag like volatileMode is useful In this case but also if you encounter frame grabber instances using different image sizes buffer memory cannot be shared among all instances assigned to a board Allocate buffers for each instance instead using entries like InstFrameBuffer and allocBuffer Please refer to chapter 3 and CIOFGTemplate c for more details on how to use TFGInstance It is hard to provide a framework for all possible frame grabbers in this manual If you would like to develop with an optimal interface you will always have to adapt the example code to the specific API of th
76. d for frame completion is rather long 40 msec with PAL 33 msec with NTSC video compared to the small time gap between two adjacent frames in the video stream Most frame grabber boards support asynchronous data transfer Therefore HALCON provides both synchronous grab image and asynchronous grabbing grab image async The reason for supporting the somehow less powerful synchronous mode is the clearer semantics The operator grab image starts a grab and waits until it is finished Thus the delivered image is per definition up to date Using asynchronous grabbing needs a little bit more insight in the timing of the application The grabbed images might be too old to be used otherwise Now let us take a look at some memory management strategies useful for efficient image acquisition in the next section 1 4 Buffering Strategies Let us look back at the real time grabbing problem Assuming a board capable of asynchronous transfer a possible sequence to choose is 1 Trigger a grab control returns immediately to the calling process 2 Wait for the grab to finish 3 Trigger the next grab 4 Process the image resulting from step 2 5 Go back to step 2 This sequence corresponds to the simple HALCON program while 1 grab image async Image 1 lt process Image gt end while Since steps 1 and 3 starting an asynchronous grab do not block the process no time is wasted while the frame grabber is busy The only topic le
77. de 77 HALCON 6 0 78 APPENDIX C INTERFACE TEMPLATE CIOFGTEMPLATE C If default is used in open framegrabber the string YOU provided for fg color space in FGInit will be passed If the default value depends on the CURRENT configuration of the system specify default in FGInit get the corresponding information NOW and overwrite the default value in fginst color space In case of unreasonable requests Return H_ERR_FGCS invalid color if STR_CASE_CMP fginst gt color_space default strcpy fginst gt color_space rgb example default rgb else if STR CASE CMP fginst color space gray 1 if fginst 5bits per channel 8 fginst bits per channel 16 example allow only 8 or 16 bit grayscale images return H_ERR_FGWC fginst gt num_channels 1 grayscale means one channel HALCON image else if STR_CASE_CMP fginst gt color_space rgb 1 if fginst bits per channel 5 fginst bits channel 8 example allow only 5 6 5 and 8 8 8 rgb images return H_ERR_FGWC fginst gt num_channels 3 rgb means a three channel HALCON image else if STR_CASE_CMP fginst gt color_space xrgb example 32 bits per pixel rgb image if fginst gt bits_per_channel 8 return H_ERR_FGWC fginst gt num_channels 4 denote the 32 bit color mode by four channel
78. ditional information concerning asynchronous grabbing might be stored in this structure async grab etc Finally if you want to insert raw data allocated with other than the HALCON memory management routines into HALCON images you must specify halcon_malloc and clear proc see FGGrab in section 3 6 Please note that FGInstance also contains a generic pointer gen pointer which is very useful for example to link the structure to a structure like TFGInstance section 2 2 2 holding additional information for an instance see also FGOpenRequest in section 3 2 Frame Grabber Integration 2000 11 16 2 2 RECOMMENDED AUXILIARY STRUCTURES 17 typedef struct _FGInstance struct _FGClass fgclass a pointer to the corresponding class ii s recddarEpacametensM horizontal_resolution desired resolution delivered vertical_resolution by the board INT image width image height desired image size INT start_row start_col upper left corner INT field even or odd field full image mode INT bits per channel color depth per pixel amp channel char color space MAX STRING gray rgb yuv float gain video preamp gain HBOOL external trigger trigger mode char camera_type MAX_STRING used camera type fg specific char device MAX_STRING device name port to use INT line_in multiplexer input line
79. dle proc id FGInstance fginst if currInst gt board gt refInst lt 1 close the board using the appropriate API call and deallocate the BoardInfo you have allocated in FGOpen HCkP HFree proc_id currInst gt board else currInst 5board refInst if currInst gt board gt refInst 1 1 This is sort of a special situation See the text currInst gt board NULL numInstance return H MSG OK Figure 3 21 Example code for FGC1ose Deallocate board HALCON 6 0 38 CHAPTER 3 INTERFACE ROUTINES 3 5 FGInfo The routine FGInfo as defined in Fig 3 22 is called by the HALCON operator info_framegrabber see section 1 6 It has to perform the following task e Return framegrabber specific informations depending on the specified query include Halcon h include hlib CIOFrameGrab h static Herror FGInfo Hproc_handle proc_id INT queryType char info Hcpar values INT numValues return some framegrabber specific informations return H_MSG_OK Figure 3 22 The prototype for FGInfo Currently the queries listed in Fig 3 23 should be supported Thus a reasonable skeleton for this routine might look like the example in Fig 3 24 Please see CIOFGTemplate c fora detailed example FG_QUERY_GENERAL General information vendor etc FG_QUERY_PORT Description of the ports signal connectors FG_QUERY_CAMERA_TYPE Descript
80. do the memory management of the image data inside a HALCON image you MUST let HALCON know otherwise there will be system crashes during deallocating images INT i BoardInfo board currInst gt board INT4_8 sizeBuffer if value gt type STRING_PAR return H ERR FGPART if strcmp value par s enable 1 GOO OOO IOI CRICK Enable the volatile mode if fginst gt bits_per_channel 8 fginst gt bits_per_channel 16 fginst gt bits_per_channel 32 deliver interleaved data that 101 HALCON 6 0 102 APPENDIX INTERFACE TEMPLATE CIOFGTEMPLATE C There s no use for the volatile mode grabbing non byte conform channel depth because we have to split the grabbed pixel data into separate bytes return H_ERR_FGPARV else if fginst gt num_channels 1 We assume for our example that the frame grabber delivers interleaved color data which is inoperative for volatile mode This is because we have to split the grabbed raw data into separate RGB channels return H_ERR_FGPARV if currInst volatileMode 1 Otherwise we don t have to do anything at all since the volatile mode already IS enabled if currInst allocBuffer 1 This specific instance uses buffers assigned to the board The
81. e as static In Windows NT 2000 you have to export the symbol explicitly extern __declspec dllexport Herror FGInit Hproc handle proc id FGClass fg By the way FGInit is the only restriction concerning symbol names The names of all other procedures variables and macros you use inside your interface is up to you but never change the name of this routine Otherwise HALCON will fail to access your frame grabber interface The routine FGInit must perform three basic tasks lOr if you access a frame grabber again after closing all instances 21 22 CHAPTER 3 INTERFACE ROUTINES Initialize the data structure FGClass see section 2 1 1 Especially the function pointers to all the other routines within the interface must be inserted Provide default values for the standard parameters used in the HALCON operator open framegrabber Initialize the data structures inside the frame grabber interface and link them to the corre sponding data structures in the HALCON library if necessary An example for the first two tasks is given in Fig 3 2 and 3 3 an example for the latter is shown in Fig 3 5 Herror FGInit Hproc handle proc id FGClass fg il fg gt available management For backward compatibility TRUE Do not change the next line or modify fg gt instances_num anywhere else in the interface otherwise HALCON will fail to unload the interface DLL properly fg gt
82. e board ac cording to the parameter settings e Allocate buffers if necessary Please refer to CIOFGTemplate c for a detailed example of such a routine include Halcon h include hlib CIOFrameGrab h static Herror FGOpen Hproc_handle proc id FGInstance fginst 1 initialize the new frame grabber instance fginst return H MSG OK Figure 3 9 The prototype for FGOpen At the very beginning of FGOpen we suggest to access the internal TFGInstance structure corresponding to the specified instance fginst and set some defaults as shown in Fig 3 10 AII the examples in this section are aiming at a complete frame grabber integration If you are only interested in a basic integration many of the things discussed here are unnecessary Thus the resulting code might be much shorter and easier to understand e g see MyS1icVideo c but also much less general and flexible static Herror FG pen Hproc handle proc id FGInstance fginst TFGInstance currInst TFGInstance fginst gt gen_pointer fginst gt async_grab FALSE currInst gt busy FALSE currInst gt allocBuffer FALSE currInst gt currBuffer 0 currInst gt volatileMode FALSE return H_MSG_OK Figure 3 10 Example code for FGOpen Accessing the corresponding TFGInstance structure and setting some defaults Note that all the parameters you specify in the HALCON operator open_framegrabber are passed to FGOpen in the FGInstan
83. e evaluated fginst gt horizontal_resolution vertical_resolution specifying the image size subsampling for the frame grabber and fginst gt start_row start_col fginst gt image_width image_height specifying a part of this image to be delivered in the HALCON image In many cases frame grabbers can be used for NTSC and PAL signals Thus reasonable values for these parameters depend the camera signal see fginst gt width_max height_max This is inconvenient for the user Therefore we recommend not only to support the absolute values but also the following relative values horizontal_resolution vertical_resolution 1 2 4 Full half quarter resolution image_width image_height 0 Return full image Note that due to this convention you cannot grab images of size 1 1 2x2 or 4x4 pixels we are certain that this loss is acceptable following code segments assumes that you already know what video norm to use that is fginst gt width_max height_max is set properly Now some arithmetic Check amp set the required cropping subsampling values The purpose of this is to deliver a unified internal representation of the requested subsampling values Regardless whether the user selects 2320 and 240 22 and 2 for a half size NTSC image the internal repr
84. e frame grabber and to its specific hardware features In general this Since most frame grabbers have only A D converter you have to synchronize the grabbing by different instances anyway 4This prevents an additional copy of data However as a side effect old images are overwritten Frame Grabber Integration 2000 11 16 2 2 RECOMMENDED AUXILIARY STRUCTURES typedef struct 5 BoardInfo board HBOOL busy INT instance INT4_8 timeout currBuf fer ifdef WIN32 struct _timeb grabStarted just to check the timeout the timestamp else struct timeval grabStar struct timezone tzp endif HBYTE InstFrameBuf HBOOL allocBuffer HBOOL volatileMode TFGInstance Figure 2 8 An example for the recommended auxiliary data structure TFGInstance the physical board this instance is attached to useful if you plan to support asynchronous grabbing is the last grab still running a useful backreference to the general Halcon instance information The instance index 0 to MAX INST 1 useful for async grabbing timeout threshold for images too old you probably use more than one buffer Index of the active buffer when the last grab was started ted the same for UNIX systems fer MAX BUFFERS buffers assigned to this instance TRUE lt gt
85. e specific API of your frame grabber Most of Fig 3 34 should be rather self explaining However some specific topics should be discussed in detail First of all if multiple instances are assigned to the same physical frame grabber board with only one A D converter you have to synchronize grabs by these instances If you enter GrabImg with asynchronous grabs of other instances pending you have to cancel these jobs or return an error code H_ERR_FGDV Device busy Moreover in case of multiple instances you have to make sure that the board is correctly parameterized for grabbing by a specific instance We suggest to provide an auxiliary routine SetInstParam for this purpose see Fig 3 35 Within this routine you have to reset all parameters that can differ from instance to instance If this is a time consuming task it might be a good idea to store the current settings of the board in the corresponding BoardInfo structure and to set only those values again which differ from the requested values in fginst or additional parameters in the TFGInstance structure currInst Throughout this section we assume a ring buffer to which images should be delivered by the frame grabber The current buffer for grabbing is indicated by currInst gt currBuffer This index should be returned in the parameter readBuffer The next grab should be done to the buffer currInst gt currBuffer 1 or 0 if there is a wrap around in the ring structure of the buf
86. er all channels The following table shows how typical images are encoded 65 66 APPENDIX CHANGES IN THE HALCON FRAME GRABBER INTEGRATION INTERFACE 8 bit gray value image 10 bit gray value image 12 bit gray value image RGB image 8 bit per channel RGB image 5 bit per channel The number of channels is implicitly encoded in the variable color_space If the variable is set to rgb or yuv for example the number of channels is 3 if the variable is set to gray the number of channels is 1 We recommend to set the variable num channels to the inferred number of channels in FGOpen while evaluating the parameters bits_per_channel and color space see section 3 3 To distinguish color spaces you now set fginst gt color_space fginst num channels while evaluating the parameters fginst bits per channel and in FGOpen see section 3 3 Correspondingly the names of the following defines changed Version 1 Version 2 FG_QUERY_GENERIC FG_QUERY_CAMERA_TYPE FG_PARAM_FGWIDTH FG_PARAM_HORIZONTAL_RESOLUTION FG_PARAM_FGHEIGHT FG_PARAM_VERTICAL_RESOLUTION FG_PARAM_WIDTH FG_PARAM_IMAGE_WIDTH FG_PARAM_HEIGHT FG_PARAM_IMAGE_HEIGHT FG_PARAM_BITS FG_PARAM_BITS_PER_CHANNEL FG_PARAM_GENERIC FG_PARAM_CAMERA_TYPE FG_PARAM_LINE FG_PARAM_LINE_IN H_ERR_FGGP H_ERR_FGCT Furthermore a new define called FG_QUERY_INFO_BOARDS has been added This define is used in a new branch in the function
87. erefore a HALCON frame grabber interface always should create new image objects by default and offer volatile grabbing only as an additional option see section 3 6 1 5 A D Conversion and Multiplexing Still bearing in mind that we are talking about analog video we now take a quick look at the interface through which analog and digital domains are connected the A D converter We are not interested in details except that a frame grabber s A D converter needs to be synchronized to the video signal in order to keep track with subsequent lines horizontal sync and frames vertical sync The sync information is either encoded in the analog video signal or is delivered to the frame grabber through additional input lines so the A D circuitry is able to synchronize itself to the video source This is important to know if we consider frame grabber boards having multiple input lines In most cases rather expensive and complex additional A D converters are traded off against one analog multiplexer circuit allowing multiple video sources to be connected to one A D converter selectively This means that every time a new video source is about to be connected to the A D converter the circuit has to re synchronize itself to the new signal which usually means one or two frames being lost in some cases synchronization can take much longer up to one second To avoid this one might use genlocked cameras Please keep in mind that in general you have to ada
88. es assigned to this board currInst gt board gt refInst and the overall number of instances numInstance t that s it You finally succeeded return H M G 0X FGOpen Set the instance specific frame grabber parameters Frame Grabber Integration 2000 11 16 static Herror SetInstParam FGInstance fginst TFGInstance currInst TFGInstance fginst gt gen_pointer TODO Restore frame grabber settings for the instance everything that you allow to be different for instances of the same board like port and input line etc Note If this is very time consuming you might want to store the current parameter settings of the board currInst gt board and check whether they differ from the values currInst currInst gt fginst 1 if currInst gt board gt port fginst gt port currInst board port fginst gt port return H_MSG_OK SetInstParam static Herror FGClose Hproc_handle proc_id FGInstance fginst TFGInstance currInst TFGInstance fginst g
89. esentation should always be 227 and 222 half height and half width 81 HALCON 6 0 82 APPENDIX C INTERFACE TEMPLATE CIOFGTEMPLATE C widthScale fginst horizontal resolution heightScale fginst vertical resolution if widthScale fginst width max widthScale 1 if heightScale fginst height max heightScale 1 if widthScale fginst gt width_max 2 widthScale 2 if heightScale fginst gt height_max 2 heightScale 2 if widthScale fginst gt width_max 4 widthScale 4 if heightScale fginst gt height_max 4 heightScale 4 Subsampling has to be either 1 2 or 4 but may be different for the x and y axes Note This is the standard behaviour of HALCON frame grabber interface Allow only full size and subsampling by a factor of 2 or 4 Of course if you feel like supporting some arbitrary weird image zooming scaling also Go ahead if widthScale 1 widthScale 2 widthScale 4 wrong resolution return CleanupFG pen proc id currInst newBoardalloc H ERR FGWR if heightScale 1 heightScale 2 heightScale 4 wrong resolution return CleanupFG pen proc id currInst newBoardalloc H ERR FGWR Now that we have a proper representation of the desired values let s compute the effective image size fginst gt horizontal_resolution fginst gt width_max wid
90. esired board using the parame ter Device Itis also possible to use more than one camera per board In that case you create a frame grabber handle for each camera by a sequence of open framegrabber calls specifying the camera via the parameters Port or LineIn Note that you have to handle multiple frame grabber instances inside your frame grabber interface if you would like to support multiple cameras or boards In detail this HALCON operator will call your interface routines FGOpenRequest see sec tion 3 2 and FGOpen see section 3 3 In addition FGInit see section 3 3 will be called when you access a specific frame grabber for the very first time 1 6 2 close framegrabber The operator close framegrabber is the counterpart to open framegrabber It deallocates a frame grabber handle releases the associated memory and unlocks the frame grabber board depending on whatever you program in the underlying interface routine FGClose see section 3 4 1 6 3 close all framegrabbers The operator close all framegrabbers 15 convenience operator that calls close framegrabber for all frame grabber handles in use This can be very useful e g if you have forgotten to close a frame grabber instance before loading a new program in HDevelop The variables containing the old handles are cleared and thus there is no other way left to unlock frame grabbers However note that this operator has severe side effects It closes all
91. etParam define FG_PARAM_VOLATILE volatile define FG_PARAM_REVISION revision define FG_PARAM_NUM 2 Typically you will need two buffers to grab to alternatively let s set MAX_BUFFERS to 2 for the moment define MAX_BUFFERS 2 Also quite convenient define FG_PAL 0 define FG_NTSC 1 define FG_SPECIAL_NORM 2 Use this Macro to display error messages define MY_PRINT_ERROR_MESSAGE ERR if HDoLowError I0PrintErrorMessage ERR Frame Grabber Integration 2000 11 16 ifdef WIN32 define STR CASE CMP S1 92 stricmp S1 2 else define STR_CASE_CMP S1 S2 strcasecmp 1 S2 endif DON T TOUCH THE NEXT LINE IGG II II A Ia ak ak ak Make the Procedure FGInit visible outside the DLL NOTE If you re using C you have to use extern C __declspec dllexport instead of extern __declspec dllexport in the following declaration VEEE EEEE EEEE EEEE EEEE EEEE E EE E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E E A ifdef WIN32 extern __declspec dllexport Herror FGInit Hproc_handle proc_id
92. ething like this if fginst gt num_channels 4 32 bit RGB format HCkP ExtractChannelsFromRGB32 fginst currInst gt InstFrameBuffer readBuffer image 0 pixel b image 1 pixel b image 2 pixel b else if fginst gt bits_per_channel 5 5 6 5 RGB format HCkP ExtractChannelsFromRGB16 fginst INT2 currInst gt InstFrameBuffer readBuffer image 0 pixel b image 1 pixel b image 2 pixel b else fginst gt bits_per_channel 8 8 8 8 RGB format HCkP ExtractChannelsFromRGB24 fginst currInst gt InstFrameBuffer readBuffer image 0 pixel b image 1 pixel b image 2 pixel b copy data Note that we will use FGGrab for asynchronous grabbing also Thus we set the async grab here explicitly for synchronous grabbing and reset it to asynchronous grabbing in FGGrabAsync if necessary fginst gt async_grab FALSE return H_MSG_OK FGGrab Grab an image via grab_image_async that is asynchronously 95 HALCON 6 0 96 APPENDIX INTERFACE TEMPLATE CIOFGTEMPLATE C static Herror FGGrabAsync Hproc_handle proc_id FGInstance fginst double maxDelay Himage image INT num_image TFGInstance currInst TFGInstance fginst gt gen_pointer Set timeout and asynchronous mode currInst gt timeout INT4_8 maxDelay 0 5 fginst gt async_grab TRUE Get current image and start new gr
93. eturn a segmentation based on the grabbed raw data include Halcon h include hlib CIOFrameGrab h static Herror FGGrabRegionAsync Hproc handle proc id FGInstance fginst double maxDelay Hrlregion region INT num region INT rlalloc_type grab an image asynchronously and segment it TFGInstance currInst TFGInstance fginst gen pointer INT4_8 1 0 5 TRUE currInst gt timeout fginst gt async_grab HCkP FGGrabRegion proc_id fginst region num region rlalloc type return H MSG OK Figure 3 44 The prototype for FGGrabRegionAsync O based on FGGrabRegion Since we have chosen an implementation of FGGrabRegion in section 3 10 based on GrabImg in section 3 7 which is more general than necessary for a pure synchronous grabbing we can easily implement FGGrabRegionAsync based on FGGrabRegion see Fig 3 44 Please see also FGGrabAsync in Fig 3 37 which is the corresponding routine to grab images instead of regions asynchronously Frame Grabber Integration 2000 11 16 3 12 FGSETPARAM 57 3 12 FGSetParam The routine FGSetParam as defined in Fig 3 45 is called by the HALCON operator set_framegrabber_param see section 1 6 It has to perform the following tasks e Parse the specified parameter e Set the parameter value s for the specified instance or return an error code include Halcon h include hlib CIOFrameGrab h static Herror FGSetParam Hproc
94. fers The corresponding frame buffers that is pointers to the memory are accessible via currInst gt InstFrameBuffer i see also Fig 3 17 We recommend to cancel the other jobs They will be started again when the user requests the corresponding image Frame Grabber Integration 2000 11 16 3 7 AUXILIARY ROUTINE GRABIMG 47 static Herror GrabImg Hproc_handle proc_id FGInstance fginst INT readBuffer TFGInstance xcurrInst TFGInstance fginst gt gen_pointer HBOOL done FALSE HBOOL newGrab FALSE HBOOL checkTimeAgain FALSE lt terminate pending grabs of other instances using the same ADC gt if currInst gt busy amp amp currInst gt board gt refInst gt 1 HCkP SetInstParam fginst if currInst gt busy if fginst gt async_grab lt cancel the pending asynchronous grab gt newGrab TRUE else done lt test whether the pending grab is already finished gt if done newGrab lt test whether the grabbed image is too old gt else checkTimeAgain TRUE else newGrab TRUE if newGrab lt grab new image gt done TRUE if done lt wait for the end of the current grab gt if checkTimeAgain lt test if the new image is too old and grab a new one if necessary gt readBuffer currInst gt currBuffer currInst gt currBuffert if currInst gt currBuffer gt MAX_BUFFERS currInst gt currBuffer 0 if fginst gt a
95. ffer board gt refBuffer board gt BoardFrameBuffer and currInst gt InstFrameBuffer The macro is used to return from a function in case of an error see the Extension Package Programmer s Manual for details Note that returning from FGOpen from a point like this can lead to a memory leak as discussed before In the real interface code you should keep this in mind One more note concerning volatile grabbing If you decide to create new HALCON im ages not based on the standard HALCON extension package interface routine HNewImage but insert buffers directly you should not forget to let the system know this Set fginst gt halcon_malloc to FALSE and fginst clear proc to NULL in this case See Fig 3 16 and the discussion of FGGrab O in section 3 6 for details Please define MAX BUFFERS according to your needs inside the interface In most cases two buffers will be sufficient HALCON 6 0 32 CHAPTER 3 INTERFACE ROUTINES static Herror FGOpen Hproc_handle proc id FGInstance fginst increase the number of instances assigned to this board currInst gt board gt refInst and the overall number of instances numInstance t return H MSG OK Figure 3 16 Example code for FGOpen Final settings Finally after successfully initializing the new instance you should increase both the overall counter for instances numInstance and the number of instances for the corresponding
96. for every frame grabber we know although the corresponding data type will vary It is used to store a handle returned by the frame grabber API to access a board If you decide to support multiple boards you might also want to hold a HALCON 6 0 18 CHAPTER 2 DATA STRUCTURES typedef struct 5 char DeviceName 255 assign a name to each board INT4_8 Deviceld some sort of handle specific to the frame grabber API HBYTE BoardFrameBuffer MAX_BUFFERS buffers assigned to the board that is to ALL TFGInstances INT currBuf fer index of the active buffer sizeBuffer size of each buffer refBuffer number of references to the buffers from TFGInstance s INT refInst number of instances assigned to this board BoardInfo Figure 2 7 An example for the recommended auxiliary data structure BoardInfo device name for each board Moreover it might be a good idea to share buffer memory among all frame grabber instances using the same board The other entries in the example refer to the management of these buffers and the instances using the board Please refer to chapter 3 and the example template file CIOFGTemplate c for details For every frame grabber board you have installed in your computer you should allocate one structure BoardInfo In general there might be more than one frame grabber instance operat ing on such a physical board Thus we re
97. ft to think about is how the memory used for grabbing should be organized Assuming step 3 makes the frame grabber deliver data into a dedicated memory area without knowledge about what the host is doing in step 4 it is easily seen that the frame grabber must use a different memory area than the host If not the frame Direct Memory Access HALCON 6 0 6 CHAPTER 1 INTRODUCTION grabber might write to memory the host is reading at the same time and the processed image would be corrupt The best way to handle this problem is to use two alternative buffers One to write new data into the other to hold the previous image These buffers might be allocated only once before the cycle is started They exchange their role after every iteration the buffer the frame grabber wrote to becomes the process s reading buffer and vice versa This is a very common technique whenever asynchronous data transfer is involved and is called double buffering Since older image data is overwritten we also use the term volatile grabbing A technique like this offers maximum grabbing performance On the other hand flexibility decreases Obviously the older images are overwritten again and again So all the history is lost This strict organization is a contradiction to the general HALCON philosophy that allows to create an arbitrary number of iconic objects and to process them in parallel until you decide in the application that you do not need them anymore Th
98. g the video signal by evaluating the camera_type parameter see above This might look like this if STR_CASE_CMP fginst gt camera_type auto 1 use special routines provided by your frame grabber to analyze the the video signal else if STR_CASE_CMP fginst gt camera_type ntsc norm FG_NTSC else if STR_CASE_CMP fginst gt camera_type 1 norm FG_PAL else norm FG_SPECIAL_NORM eer TODO Set fginst gt width_max fginst gt height_max Depending on the video norm set the maximum allowed image size fginst switch norm 1 case FG PAL fginst width max 768 fginst gt height_max 576 break case FG_NTSC fginst gt width_max 640 fginst gt height_max 480 break case FG_SPECIAL_NORM default well whatever fginst gt width_max 768 fginst gt height_max 576 DCC GG Kk k k kk k kk kk TODO Evaluate the image size part This is going to be tricky There six parameters to b
99. ggering return external triggering not supported if fginst gt external_trigger return H_ERR_FGET example Do not allow external triggering DCG oR amp TODO Check the desired field DEGRA GCAO desired field to be grabbed is specified fginst gt field FG_FIRST_FIELD grab first even field FG_SECOND_FIELD grab second odd field FG_NEXT_FIELD grab arbitrary next field FG_FULL_FRAME grab a full frame interlaced Frame Grabber Integration 2000 11 16 FG_PROGRESSIVE_FRAME grab full frame progressive scan If default is used open_framegrabber the value YOU provided for fg gt field FGInit will be passed In case of unreasonable values return H_ERR_FGFIELD invalid field Note This parameter is tightly coupled with the specified image size So many HALCON frame grabber interfaces IGNORE this parameter and decide what to do exclusively by the size parameters if fginst gt field 1 FG FIRST FIELD amp amp fginst gt field FQ FULL FRAME return H ERR FGFIELD example first field or interleaved frame TODO Check availability
100. gt num_channels for 1 0 i lt MAX BUFFERS i HCkP HAlloc proc id size_t sizeBuffer amp currInst InstFrameBuffer il board gt refBuffer currInst gt allocBuffer TRUE currInst gt volatileMode fginst gt halcon_malloc fginst gt clear_proc TRUE FALSE NULL return H_MSG_OK Figure 3 48 Example code for FGSetParam Activate volatile SIAN 60 60 CHAPTER 3 INTERFACE ROUTINES 3 13 FGGetParam The routine FGGetParam as defined in Fig 3 49 is called by the HALCON operator get_framegrabber_param see section 1 6 It has to perform the following tasks e Parse the specified parameter e Return the current parameter value s for the specified instance or return an error code include Halcon h include hlib CIOFrameGrab h static Herror FGGetParam Hproc_handle proc id FGInstance fginst char param Hcpar value INT num return the specified parameter value for an instance TFGInstance currInst TFGInstance fginst gt gen_pointer num 1 if strcmp param FG PARAM VOLATILE T value gt type STRING PAR value gt par s currInst volatileMode enable disable else if else parameter not supported return H ERR FGPARAM return H MSG OK Figure 3 49 The prototype for FGGetParam and a simple example This routine is the counterpart of FGSetParam see section 3 12 The values for all standard paramete
101. handle proc_id FGInstance fginst char param Hcpar value INT num 1 set the specified parameter value for an instance return H MSG OK Figure 3 45 The prototype for FGSetParam FG_PARAM_HORIZONTAL_RESOLUTION horizontal_resolution LONG_PAR FG_PARAM_VERTICAL_RESOLUTION vertical resolution LONG PAR FG PARAM IMAGE WIDTH image width LONG PAR FG PARAM IMAGE HEIGHT image height LONG PAR FG PARAM START ROW start row LONG PAR FG PARAM START COL start column LONG PAR FG PARAM FIELD field STRING PAR _ BITS PER CHANNEL bits per channel LONG PAR FG PARAM COLOR SPACE color_space STRING_PAR FG_PARAM_GAIN gain FLOAT PAR FG PARAM EXT TRIGGER external trigger STRING PAR FG PARAM CAMERA TYPE camera type STRING PAR FG PARAM DEVICE device STRING PAR FG PARAM PORT port LONG PAR FG PARAM LINE IN line in LONG PAR Figure 3 46 Defines for the standard parameters used in open framegrabber A routine like this should be implemented if you would like to use additional parame ters to tune specific hardware features or to change the standard parameters specified in open framegrabber on the fly The names of the standard parameters are fixed see Fig 3 46 Please note that field corresponding to fginst gt field is externally defined as string but internally as integer using the conversion indicated in Fig 3 47 Note further that HALCON 6 0 58 CHAP
102. hronous grab and returns without further waiting This operator will call the routine FGGrabAsync see section 3 8 in your frame grabber inter face If this routine is missing the error code FGASYNC Frame grabber asynchronous grab not supported will be returned Thus if you do not want to support asynchronous grab bing just do not provide FGGrabAsync O 1 6 7 grab image start The operator grab image start starts the asynchronous grabbing of a new image and re turns immediately The image itself is then delivered by the next call to grab image or grab image async unless it is older than the specified threshold This operator is useful if your application involves time consuming processing In this case asynchronously grabbed images might be too old if you start the grab immediately after grabbing the prior image via grab image async grab image start allows you to fine tune the moment you start the grab In case of a free running camera call this operator approximately one and a half frames before you need the next image This operator will call the routine FGGrabStartAsync see section 3 9 in your frame grab ber interface If this routine is missing the error code ERR FGASYNC Frame grabber asyn chronous grab not supported will be returned 1 6 8 grab region The operator grab_region grabs a new image synchronously but does not return the image itself Instead a segmentation that is image reg
103. ialize the frame grabber class This routine is called by HALCON the very first time a HALCON process wants to access a frame grabber via open_framegrabber or info_framegrabber Herror FGInit Hproc handle proc id FGClass fg 1 INT i Initialize the instance data structure inside of this interface for 1 0 i lt FG MAX INST i 1 memset amp FGInst i 0 sizeof TFGInstance FGInst i instance aoe numInstance 0 fg gt interface_version FG_INTERFACE_VERSION do not change this line J sokokokok kokolokokokekokolokokokekokolokokolokekokololokokokekololekekololekolololokololekololelelololelolololelololelekeloleleloleleelolelelek TODO Provide reasonable defaults etc for open_framegrabber Management For backward compatibility fg gt available TRUE Do not change the next line or modify fg gt instances_num anywhere else in the interface otherwise HALCON will fail to unload the interface DLL properly fg gt instances_num 0 Tell HALCON how many instances you are willing to support fg gt instances_max FG_MAX_INST interface specific functions fg gt OpenRequest FG penRequest
104. ifdef WIN32 struct _timeb grabStarted just to check the timeout the timestamp when the last grab was started else struct timeval grabStarted the same for UNIX systems struct timezone tzp endif HBYTE InstFrameBuffer MAX_BUFFERS buffers assigned to this instance HBOOL allocBuffer TRUE lt gt buffers are allocated per instance not only references to the buffers in board HBOOL volatileMode TRUE lt gt pass buffer memory directly to a HALCON image possibly overwriting older images TFGInstance DCG a k k k k k kkk We recommend that you leave these untouched I I A k k kkk k static FGClass 1 5 a pointer to the frame grabber class struct Static TFGInstance FGInst FG MAX INST all possible instances static INT numInstance 0 current instances Some useful general purpose buffers e g for status messages static char errMsg 512 SSS SS SS SS SS SS SS SS SSS SSS SSS SSS SSS SS SS SSS S555 SSS HBOOL KillAllOtherJobs
105. ill be returned 1 7 HALCON Frame Grabber Integration Interface ver sus HALCON Frame Grabber Interface The term HALCON frame grabber interface refers to an external module encapsulating the frame grabber specific code this is the one have to provide In contrast the Actually this is not completely true get framegrabber param automatically returns the current settings for the standard parameters you specify with open framegrabber HALCON 6 0 10 CHAPTER 1 INTRODUCTION frame grabber integration interface is the module inside the HALCON library which is respon sible for managing and accessing external frame grabber interface modules Whenever a frame grabber is accessed for the very first time using open_framegrabber or info_framegrabber the corresponding external frame grabber interface a dynamically load able module is loaded For example a call like open framegrabber PicPort will cause the HALCON library to load the module HFGPicPort d11 in the case of Windows NT 2000 or HFGPicPort so for UNIX systems respectively If you use Parallel HALCON under Windows NT or Windows 2000 it will load the library parHFGPicPort dll Please note that in order for this mechanism to work all frame grabber libraries need the prefix HFG and parHFG under Windows NT 2000 After the first call the interface routines inside this module programmed by you will be called by the corresponding HAL
106. inst amp readBuffer example Allocate two regions e g one for all image parts of a specific color and for the rest of the image HCkP HAllocRLNumLocal proc id amp region 0 fginst gt image_width fginst gt image_height 2 HCkP HAllocRLNumLocal proc id amp region 1 fginst image width fginst image height 2 rlalloc_type FG RLALLOC LOCAL num region ES S Well the segmentation itself is up to you fginst gt async_grab FALSE return H_MSG_OK Figure 3 42 Example code for FGGrabRegionO The basic structure You can allocate region data e temporarily on stacks inside the HALCON library e temporarily on the heap e permanently on the heap The first two methods include an automatic garbage collection in case you return an error as a result of FGGrabRegion and should therefore be preferred The most flexible memory Frame Grabber Integration 2000 11 16 3 10 FGGRABREGION 55 allocation method is the second one which is also used the example in Fig 3 42 The Extension Package Interface routine HAllocRLNumLocal as defined in Fig 3 41 is used to temporarily allocate memory for the specified number of chords and to initialize the Hrlregion structure Since we do not know the number of chords in advance we have used a rather conservative estimate in Fig 3 42 Note that you can change this number dynamically using HReallocRLNumLocal FG_RLALLOC_TMP Temp
107. instances_num 0 Tell HALCON how many instances you willing to support fg gt instances_max FG_MAX_INST interface specific functions fg gt OpenRequest FGOpenRequest fg gt Open FG pen fg gt Close FGClose fg gt Info FGInfo fg gt Grab FGGrab fg GrabStartAsync FGGrabStartAsync fg gt GrabAsync FGGrabAsync fg gt GrabRegion FGGrabRegion fg GrabRegionAsync FGGrabRegionAsync fg gt SetParam FGSetParam fg gt GetParam FGGetParam fg gt SetLut FGSetLut fg gt GetLut FGGetLut return H_MSG_OK Note Figure 3 2 Example code for FGInit Initialize FGClass to be continued that in Fig 3 2 the function pointers inside FGClass are assigned to the specific routines you provide in the frame grabber interface Thus you can choose arbitrary names for the latter However we recommend to stick to the names used in this manual to ease understanding different interface code Some of these function pointers are optional see Fig 3 4 If you do not assign anything or assign a NULL pointer to these function pointers HALCON will return an error while executing the corresponding operators see section 1 6 In Fig 3 5 we have assumed that you followed our suggestion to provide a data structure TFGInstance to hold additional framegrabber specific information about an instance see also Frame Grabber Integration 2000 11 16 3 1 FG
108. ion of the camera type parameter FG_QUERY_DEFAULTS Default values for open_farmegrabber FG_QUERY_PARAMETERS Names of the supported non standard parameters FG_QUERY_INFO_BOARDS Information about the installed boards Figure 3 23 Queries that should be supported by FGInfo FGInfo has two output parameters A string containing a textual description of the de sired information and optional a list of parameter values The latter can for example hold the values auto pal and ntsc as possible values of the camera type parameter in open_framegrabber if you decide to use this parameter with this specific semantics see Fig 3 25 and Fig 3 13 Hcpar is CameraType data structure for storing control parameters integer strings or floating point numbers see the HALCON Extension Package Program mer s Manual for details In our example values is used to return three strings Thus the type tag type in the Hcpar structure is set to STRING_PAR The corresponding settings for integers and floating pointer num bers is LONG_PAR and FLOAT_PAR respectively The parameter value should be written to par s strings par 1 integers of type long or par f floating point numbers of type double Note that neither the string info nor the array of Hcpar structures have been allocated prior to calling FGInit Please use the HALCON extension package interface routine HAlloc Frame Grabber Integration 2000 11 16 3 5 FGINFO 39 s
109. ions based on this image is delivered The kind of segmentation used is up to you and maybe dependent on some specific hardware features of your frame grabber This operator will call your interface routine FGGrabRegion see section 3 10 If this routine is missing the error code Frame grabber function not supported will be returned Alternatively a segmentation of the image will be returned by grab region grab region async Frame Grabber Integration 2000 11 16 1 7 HALCON FRAME GRABBER INTEGRATION INTERFACE VERSUS HALCON FRAME GRABBER INTERFACE 9 1 6 9 grab region async The operator grab region async grabs a new image asynchronously that means it waits for a pending grab to finish and starts a new asynchronous grab again before returning Similar to grab region it does not return the image itself but a segmentation that is image regions based on this image The kind of segmentation used is up to you and maybe dependent on some specific hardware features of your frame grabber This operator will call your interface routine FGGrabRegionAsync see section 3 11 If this routine is missing the error code ERR FGFNS Frame grabber function not supported will be returned 1 6 10 set framegrabber param get framegrabber param The operators set framegrabber param and get framegrabber param are used to set or retrieve specific parameters of a frame grabber instance They have bee
110. kP directly as shown in Fig 3 32 In case of byte images the image matrix in a Himage structure is accessed via pixel b For discussion on other supported image types please refer to the Extension Package Program mer s Manual Splitting interleaved raw color data into three separated image channels is straightforward see Fig 3 33 Please refer to the API manual of your frame grabber to learn about the specific data representation In our example we assumed a 24 bit per pixel representation of RGB triples HALCON 6 0 44 CHAPTER 3 INTERFACE ROUTINES include Halcon h Herror HNewImage Hproc handle proc_id Himage image INT kind INT width INT height initialize image and allocate new image matrix return H_MSG_OK Figure 3 31 The prototype for the extension package interface routine HNewImage static Herror FGGrab Hproc handle proc id FGInstance fginst Himage image INT num image 1 Herror err INT save HReadSysComInfo proc id HGInitNewImage amp save HWriteSysComInfo proc id HGInitNewImage FALSE for i20 i lt num image i 1 err HNewImage proc id amp image i BYTE IMAGE fginst image width fginst image height if err H MSG OK HWriteSysComInfo proc id HGInitNewImage save return err HWriteSysComInfo proc id HGInitNewImage save HCkP err return H MSG OK Figure 3 32 Example code for FGGrab Avoid initialization of the
111. ke a video signal which can be understood as a continuous stream of video frames and grab one or more video frames out of the sequence Except for the new name of the frame grabber and framegrabber specific parameters used by the operator set framegrabber param Frame Grabber Integration 2000 11 16 1 2 IMAGE ACQUISITION BASICS Frame Grabber BitFlow Raven and RoadRunner Cheops Ramses 1 Data Translation DT3152 DT3153 DT3155 Eltec PCEye IDS FALCON FALCONplus and EAGLE Imagenation PX510 610 610A PXC200 and PXD Integral FlashBus Leutron PicPort LinX GINGA MATRIX Vision MVdelta MVsigma PCimage MVtitan Matrox Meteor I Mikrotron Inspecta 2 MRT VideoPort Professional Opteon The Imaging Source DFG LC1 DFG LC2 DFG BW1 VideoPort TWAIN interface Unibrain FireBoard 400 Operating System Windows NT 2000 Windows NT 2000 Windows NT 2000 Windows NT 2000 Windows NT 2000 Windows NT 2000 Windows NT 2000 Windows NT 2000 Linux Windows NT 2000 Windows NT 2000 Windows NT 2000 Linux Windows NT 2000 Windows NT 2000 Windows NT 2000 Windows NT 2000 Windows NT 2000 Windows NT 2000 Virtual frame grabber interface for accessing image files and sequences Windows NT 2000 also AVI files Figure 1 1 Frame grabbers integrated into the HALCON system November 2000 whenever triggered to do so In many cases the video signal will be an analog one alth
112. le proc_id INT queryType char info Hcpar values INT numValues static Herror FGSetLut Hproc_handle proc id FGInstance fginst 4 8 red 4 8 green INT4_8 blue INT num static Herror FGGetLut Hproc_handle proc id FGInstance fginst 4 8 red INT4_8 green INT4_8 blue INT num Ae cde dod AX cde de de dB 71 72 APPENDIX INTERFACE TEMPLATE CIOFGTEMPLATE C static Herror FGSetParam Hproc_handle proc_id FGInstance fginst char param Hcpar value INT num static Herror FGGetParam Hproc_handle proc_id FGInstance fginst char param value INT num static FGInstance FGOpenRequest Hproc_handle proc_id FGInstance fginst k k k kk k kkk a k k k kk k kk TODO adapt INTERFACE_REVISION appropriately define INTERFACE_REVISION 2 x TODO If you provide software for different architec
113. ll be overwritten In any case the HALCON library that calls FGGrab must know that you did not use the HALCON memory management to allocate the image matrix Otherwise the system will crash when the image object encapsu lating the returned Himage structure is cleared from the data base Thus for volatile grabbing fginst gt halcon_malloc must be set to FALSE and fginst gt clear_proc must be set to NULL In the examples provided in this manual this was done in FGInit see Fig 3 16 The standard routine to initialize a Himage structure is HNewImage as defined in Fig 3 31 This routine allocates a new image matrix using HAlloc Thus either a memcpy or a call to ExtractChannelsFromRGB is necessary in Fig 3 29 to fill the matrix with the grabbed image This induces a small overhead On the other hand the resulting HALCON images are independent which conforms to the HALCON philosophy The user should decide how long he she would like to use an image It should not be overwritten as a side effect of calling another HALCON operator Thus we strongly recommend to implement this non volatile grabbing strategy as default For reasons of backward compatibility a flag like initImg in HNewImagePtr is missing in HNewImage To surely avoid an unnecessary initialization of the new image matrix you might use the code fragment in Fig 3 32 Please make sure to restore the old setting before returning from FGGrab This implies not to use HC
114. lledSomebody Kill1A110therJobs CleanupFGOpen Auxiliary routine for FGOpen If you have to exit FGOpen in case of an error you might have to do some cleaning up before returning the error code Note that in case of newBoardalloc TRUE that is you have initialized the frame grabber board for the first time you might also have to close or unlock the frame grabber again atic Herror CleanupFGOpen Hproc_handle proc_id TFGInstance currInst HBOOL newBoardalloc Herror err INT j if currInst allocBuffer amp amp currInst gt board gt refBuffer for j 0 lt MAX_BUFFERS j if currInst gt board gt BoardFrameBuffer j void HFree proc_id currInst gt board gt BoardFrameBuffer j currInst gt board gt BoardFrameBuffer j NULL if currInst gt allocBuffer INT 1 for j 0 j MAX_BUFFERS j if currInst gt InstFrameBuffer j void HFree proc_id currInst gt InstFrameBuffer j currInst gt InstFrameBuffer j NULL if newBoardalloc HFree proc_id currInst gt board currInst gt board NULL return err 75 HALCON 6 0 76 APPENDIX C INTERFACE TEMPLATE CIOFGTEMPLATE C CleanupFGOpen static Herror FG pen Hproc handle proc_id FGInstance fginst 1 TFGInstance currInst TFGInstance fginst gen pointer other local variables INT i INT norm I
115. lsFromRGB16 static Herror FGGrabStartAsync Hproc_handle proc_id FGInstance fginst double maxDelay TFGInstance currInst TFGInstance fginst gt gen_pointer paoa ooo ooo ooo oo oo ooo oo o o o ok k kkk kkk Note If your frame grabber does not support asynchronous grabbing Return H_ERR_FGASYNC J kckokokokekokokokokokokokokokolkokolokolkokolokolkokokolokokokokokolokololokolokolololokolokokoloklololololelolelolelokokelekelolololelelelelelelek currInst gt timeout is the maximum allowed age for an image see FGGrab just set the new threshold currInst gt timeout INT4_8 maxDelay 0 5 Frame Grabber Integration 2000 11 16 Note There might be asynchronous grabs pending on the same board you would like to use general most frame grabber have only one A D converter thus you might have to cancel all these old jobs before doing anything else Obviously this operation has nasty side effects So you could also return the error H_ERR_FGDV device busy in this case KillAllO0therJobs fginst if currInst gt busy 1 I 7 TODO Cancel pending job there an asynchronous grab pending check whe
116. meters Fig 3 48 shows example code for activating volatile grabbing which only uses the entry volatileMode already included in the TFGInstance structure Please see also the comments on allocating buffers according to Fig 3 17 in section 3 6 Please refer to CIOFGTemplate c for a detailed discussion Frame Grabber Integration 2000 11 16 3 12 FGSETPARAM 59 define FG_PARAM_VOLATILE volatile static Herror FGSetParam Hproc handle proc_id FGInstance fginst char param Hcpar value INT num TFGInstance currInst TFGInstance fginst gt gen_pointer INT aig BoardInfo xboard currInst gt board INT4_8 sizeBuffer if strcmp param FG_PARAM_VOLATILE if value gt type STRING_PAR return H_ERR_FGPART if strcmp value gt par s enable if fginst gt num_channels 1 return H_ERR_FGPARV if currInst gt volatileMode if currInst gt allocBuffer This specfic instance uses buffers assigned to the board if board gt refBuffer 1 No other instance uses the board buffer Just transfer them to the instance for 1 0 i lt MAX_BUFFERS i currInst gt InstFrameBuffer 1 board gt BoardFrameBuf fer i board gt sizeBuffer 0 else board gt BoardFrameBuf fer i NULL There are other instances using the board buffers sizeBuffer fginst gt image_width fginst gt image_height fginst gt bits_per_channel 7 8 fginst
117. mple code for FGOpen O Determine the desired scaling and thus the image size to be delivered by the frame grabber The next step is to determine the scaling of the image and thus the desired image size to be delivered by the frame grabber Note that we only support subsampling by a factor of 2 or 4 in the example code in Fig 3 14 After this analyze the specified part of the frame grabber image to be delivered as HALCON image by the grabbing routines see Fig 3 15 Once you have determined both the image size and the part of the image to be grabbed you have to set the video scaler of the frame grabber according to this values Obviously how to do this depends on the frame grabber API Thus we cannot provide source code There is one very important topic left to be discussed for the implementation of FGOpen the allocation of buffer memory In the following we assume that you use a ring buffer with Frame Grabber Integration 2000 11 16 3 3 FGOPEN 31 static Herror FGOpen Hproc_handle proc id FGInstance fginst if fginst gt image_width 0 fginst gt image_width fginst gt horizontal_resolution 2 fginst gt start_col if fginst gt image_height 0 fginst image height fginst gt vertical_resolution 2 fginst gt start_row if fginst gt start_col fginst gt image_width gt fginst gt horizontal_resolution l fginst gt start_rowtfginst gt image_height gt fginst gt vertical_resolution wrong par
118. n designed to allow the fine tuning of exotic hardware For whatever you can think of as being useful to adjust on your board just define corresponding parameters You can either set single parameter values or tuples of parameter values The latter case might be very useful if some parameters depend on each other and therefore have to be set within one call of get framegrabber param get framegrabber param and set framegrabber param do not evaluate the parameters themselves but only pass them to your interface routines FGSetParam see section 3 12 and FGGetParam see section 3 13 Note that since the name values and semantics of such parameters depend on the specific properties of a frame grabber HALCON can neither provide meaningful defaults nor check parameters automatically This is all up to your frame grab ber interface If FGSetParam or FGGetParam are missing the error code ERR FGPARAM Frame grabber unsupported parameter will be returned 1 6 11 set framegrabber lut get framegrabber lut The operators set framegrabber lut and get framegrabber lut are used to set or retrieve color lookup tables of a frame grabber instance thus supporting things like gamma correction or white balancing These operators will call your interface routines FGSetLut see section 3 14 or FGGetLut see section 3 15 If one of these routines 15 missing the error code H ERR FGFNS Frame grabber function not supported w
119. n h include hlib CIOFrameGrab h static Herror FGSetLut Hproc handle proc id FGInstance fginst 4 8 red INT4_8 green 4 8 blue INT set the specified lookup table for instance return H_MSG_OK Figure 3 50 The prototype for FGSetLut A modification of a frame grabber s lookup table might be used for a gamma correction or white balancing The input to FGSetLut are three integer arrays for the red green and blue components of the LUT and the number of entries in these arrays Whether lookup tables are supported or not and how to handle such lookup tables depends on the frame grabber and its API Therefore we cannot provide source code for this task Please note that the modification of a frame grabber s lookup table will affect other instances assigned to the same board Thus you should think about a mechanism to check whether instance specific LUTs differ and to restore them prior to grabbing if necessary HALCON 6 0 62 CHAPTER 3 INTERFACE ROUTINES 3 15 FGGetLut The routine FGGetLut as defined in Fig 3 51 is called by the HALCON operator get framegrabber lut see section 1 6 It has to perform the following task e Return the lookup table for the specified instance include Halcon h include hlib CIOFrameGrab h static Herror FGGetLut _ handle proc id FGInstance fginst 4 8 INT4 8 green INT4_8 blue INT num return the
120. n handle 32 FG MAX NUM different frame grabbers with up to 32 FG_MAX_INST instances each at the same time Or a family of frame grabber models like DT3152 DT3153 and DT3155 by Data Translation 13 14 CHAPTER 2 DATA STRUCTURES foo labs model 1000 foo labs model 2000 bar inc mega grabber Figure 2 1 A possible configuration with multiple frame grabbers tion 3 1 typedef struct _FGClass internal SS a char name MAX_STRING frame grabber name interface module void 1 _ 1 handle of interface library INT J interface version current HALCON frame grabber interface version eee properties management HBOOL available supported for the current platform instances num current number instances INTERNAL INT instances max maximum number of instances FGInstance instance FG_MAX_INST list of instances INTERNAL Figure 2 2 The data structure FGClass defined in include hlib CIOFrameGrab h to be con tinued You do not have to set all the members of the structure Especially do not touch the IN TERNAL entries like name or lib handle They are controlled by HALCON library exclusively We won t discuss each member of the structure However it may be useful to look at the different types of fields e Internal Management name lib handle
121. nding for this instance Thus you have to grab new image You can do this synchronously or asynchronously you have to wait anyway newGrab TRUE if newGrab TODO grab a new image done TRUE FALSE if you use API call for grabbing that does not wait for the end of the grab if done 1 POS TODO wait until the asynchronous grab has finished if checkTimeAgain old grab finished Check whether this image is too old ifdef WIN32 _ftime amp now time_diff now millitm currInst gt grabStarted millitm 1000 now time currInst gt grabStarted time else gettimeofday know amp tzp time_diff CINT4_8 double now tv_sec 1000 0 double now tv_usec 1000 0 double currInst gt grabStarted tv_sec 1000 0 double currInst gt grabStarted tv_usec 1000 0 0 5 endif if time_diff gt
122. ned 16 bit signed or 32 bit signed for one channel grayscale 5 8bit unsigned for three channel color format Obviously the subsequent memcpy for gray value images can only work if the frame grabber delivers the data in the same format otherwise you must do some shifting For color images we assume that the channel image data is delivered in an interleaved format The use of memcpy is obsolet therefore Create NEW HALCON object if fginst gt num_channels 4 32 bit par pixel discard the redundant data and copy the image data to a three channel HALCON image num image 3 else num image fginst num channels if fginst 5bits per channel lt 8 1 for i 0 i num image i 1 err HNewImage proc id amp image i BYTE IMAGE gt width fginst image height if err H MSG OK 1 HWriteSysComInfo proc id HGInitNewImage save return err else if fginst gt bits_per_channel lt 16 for i 0 i lt num_image i err HNewImage proc id amp image 0 INT2 IMAGE fginst image width fginst image height if e
123. new image matrix HNewImage Frame Grabber Integration 2000 11 16 3 6 FGGRAB 45 static Herror ExtractChannelsFromRGB FGInstance fginst HBYTE data HBYTE r_img HBYTE g_img HBYTE b_img INT4_8 i size fginst gt image_width fginst gt image_height for i20 1 lt size i r imgtt datat g imgtt datatt b_img datat return H_MSG_OK Figure 3 33 Example code for the auxiliary routine ExtractChannelsFromRGB HALCON 6 0 46 3 5 3 7 Auxiliary Routine GrabImg We suggest to implement an auxiliary routine GrabImg as defined in Fig 3 28 on page 41 as basis for the grabbing routines FGGrab and FGGrabRegion and thus also for FGGrabAsync and FGGrabRegionAsync It has to perform the following tasks e Terminate pending grabs of other instances in case they use the same A D converter e If there is an asynchronous grab pending Terminate it in case of a synchronous grab command and wait for its end otherwise e If synchronous grabbing is requested or an asynchronously grabbed image is too old Grab a new image e If asynchronous grabbing is requested Start the next grab but do not wait for the end of the grab e Switch to the next buffer Fig 3 34 shows the basic structure of such a routine Naturally there is a lot of pseudo code indicated by lt gt since the grabbing routines etc depend on th
124. nished Check whether this image is too old ifdef WIN32 _ftime amp now time_diff now millitm currInst gt grabStarted millitm 1000 now time currInst gt grabStarted time else gettimeofday know amp tzp time_diff CINT4_8 double now tv_sec 1000 0 double now tv usec 1000 0 double currInst gt grabStarted tv_sec 1000 0 double currInst gt grabStarted tv_usec 1000 0 0 5 endif if time_diff gt currInst gt timeout Frame Grabber Integration 2000 11 16 91 Bad luck The image is there but too old Thus you have to grab a new image You can do this synchronously or asynchronously you have to wait anyway newGrab TRUE else There is an old job pending and the grab has not finished yet Basically you can just skip doing anything in this branch and wait until the grab has finished However the image still might be too old This is sort of timing problem because you can measure the time since the grab has started HERE and cancel the grab if the image is already too old NOW but its hard to tell when the grab will finish Maybe its not too old NOW but it will be too old THEN In this case there is no use waiting We could cancel the job right now checkTimeAgain TRUE async grab pending job else 1 There is no asynchronous job pe
125. on t have to do anything at all since the volatile mode already IS disabled sizeBuffer fginst gt image_width fginst gt image_height fginst bits per channel 7 8 fginst gt num_channels Frame Grabber Integration 2000 11 16 if board gt refInst gt 1 1 There are other instances using the same board Thus if the size of the board buffers allows to use these for the current instance as well we can deallocate the instance specific buffers to decrease the memory load if board gt sizeBuffer gt sizeBuffer 1 for i20 i MAX BUFFERS i 1 HCkP HFree proc_id currInst gt InstFrameBuffer i currInst gt InstFrameBuffer i board gt BoardFrameBuffer il currInst gt allocBuffer FALSE board gt refBuffert if board gt sizeBuffer 0 This is special case There no board buffers far Transfer the instance buffers to the board in order to make them shared for 1 0 i lt MAX BUFFERS i 1 board gt BoardFrameBuffer i currInst gt InstFrameBuffer i currInst gt allocBuffer FALSE board gt refBuffer 1 board gt sizeBuffer sizeBuffer currInst gt volatileMode FALSE fginst gt halcon_malloc TRUE currInst gt volatileMode disable else return H_ERR_FGPARV 2 param FG PARAM VOLATILE else parameter not supported return H ERR FGPARA
126. orary data on stacks allocated with HAllocRLTmp or HAllocRLNumTmp Attention In this case you MUST allocate the image regions in ascending order because in the HALCON interface the corresponding freeing is done in descending order FG_RLALLOC_LOCAL Temporary data on the heap allocated with HAllocRLLocal or HAllocRLNumLocal FG RLALLOC PERMANENT Permanent data on the heap allocated with HAllocRL or HAllocRLNum Figure 3 43 Defines for indicating the memory allocation strategy for regions FGGrabRegion Whatever you decide to use you have to indicate the memory allocation strategy to the HAL CON library using one of the defines listed in Fig 3 43 as return value for the parameter rlalloc_type If you fail to do so you will encounter program crashes 2Please refer to HAllocRLLocal HAllocRLNumLocal and HReallocRLLocal in the Extension Package Programmer s Manual HALCON 6 0 56 CHAPTER 3 INTERFACE ROUTINES 3 11 FGGrabRegionAsync The routine FGGrabRegionAsync as defined in Fig 3 44 is called by the HALCON operator grab region async see section 1 6 It has to perform the following tasks e Re set the parameters on the frame grabber board Wait until a pending asynchronous grab is finished or grab a new image if there is no pending job e Check if the asynchronously grabbed image is too old If this is the case grab a new image Start a new aynchronous grab without waiting e R
127. ormat not possible H_ERR_FGNV 5304 No video signal H_ERR_UFG 5305 Unknown frame grabber H_ERR_FGF 5306 Failed grabbing of an image H_ERR_FGWR 5307 Wrong resolution chosen H_ERR_FGWP 5308 Wrong image part chosen H_ERR_FGWPR 5309 Wrong pixel ratio chosen H_ERR_FGWH 5310 Handle not valid H_ERR_FGCL 5311 Instance not valid already closed ERR FGNI 5312 Frame grabber cannot be initialized H_ERR_FGET 5313 External triggering not supported ERR FGLI 5314 Wrong camera input line multiplex ERR FGCS 5315 Wrong color space ERR FGPT 5316 Wrong port H_ERR_FGCT 5317 Wrong camera type H_ERR_FGTM 5318 Maximum number of frame grabber classes exceeded H_ERR_FGDV 5319 Device busy H_ERR_FGASYNC 5320 Asynchronous grab not supported H_ERR_FGPARAM 5321 Unsupported parameter H_ERR_FGTIMEOUT 5322 Timeout H_ERR_FGGAIN 5323 Invalid gain ERR FGFIELD 5324 Invalid field 69 70 H_ERR_FGPART 5325 H_ERR_FGPARV 5326 H_ERR_FGFNS 5327 H_ERR_FGIVERS 5328 H_ERR_DNA 5104 H_ERR_MEM 6001 APPENDIX B HALCON ERROR CODES Invalid parameter type Invalid parameter value Function not supported Incompatible interface version Device or operator not available Not enough memory available Frame Grabber Integration 2000 11 16 Appendix Interface Template CIOFGTemplate c This chapter contains a listing of the interface template source code CIOFGTemplate c Please see also AHALCONROOTA NexamplesMframegrabberNCIOFGTemplate
128. ou have to split this data into separate channels conform to the HALCON philosophy This routine might be a very simple template for such a procedure 4 Re 3 5 static Herror ExtractChannelsFromRGB24 FGInstance fginst data HBYTE r_img HBYTE g_img HBYTE b_img 1 HALCON 6 0 88 APPENDIX INTERFACE TEMPLATE CIOFGTEMPLATE C INT4_8 i size size fginst gt image_width fginst gt image_height Assume that the frame grabber delivers 24 bits per pixel e g RGB for 1 0 i lt size i r imgtt datat g imgtt datat b imgtt datatt return H MSG 0K ExtractChannelsFromRGB24 Typically a color framegrabber delivers the data as interleaved tuple e g RGB triples per pixel Thus you have to split this data into separate channels conform to the HALCON philosophy This routine might be a very simple template for such a procedure It 16bpp 1 1 Static Herror ExtractChannelsFromRGB16 FGInstance fginst INT2 data HBYTE r img g img img 1 4 8 i size size fginst image width fginst image height Assume that the frame grabber delivers 5 6 5 RGB data for i20 i lt size i 1 copy pixel wise r_imgt data amp OxiF lt lt 3 g_imgt data amp 0 7 0 gt gt 3 b_imgt data amp OxF800 gt gt 8 datat return H MSG OK ExtractChanne
129. ough more professional equipment often uses digital signals nowadays The most common analog video formats are e NTSC 640 x 480 pixel 30 frames per second and e PAL 768 x 576 pixel 25 frames per second Both formats carry color information although many frame grabber boards only deliver grayscale images even from a color video signal The following explanations assume that you are using an analog frame grabber board With digital boards things may be different Let us take a look at the analog input signal Actually it is composed of many different sig nals There are vertical and horizontal sync signals and of course the raw data signals as well Sometimes the color and brightness signals are overlaid composite signal sometimes they are delivered on separated input lines Y C RGB Since the frame grabber is usually synchronized by the video source it has to wait for the next vertical sync signal to start grabbing a new image see Fig 1 2 3At least if you do not use a setup that supports asynchronous frame resets HALCON 6 0 4 CHAPTER 1 INTRODUCTION grab command frame being grabbed frame 1 frame n frame 1 time Figure 1 2 Grabbing one frame This will cause a delay of half a frame on average when grabbing an image of random frames It also implies that you have to start grabbing the next frame immediately after receiving the previous frame if you want to achieve full frame rate
130. pt parameter settings on your frame grabber board whenever you switch between different input lines HALCON provides a concept for dealing with multiple cameras connected to one frame grabber board as well as multiple frame grabber boards inside one host computer Each camera board pair is represented by a frame grabber handle Inside HALCON such a handle corresponds to a frame grabber instance If you would like to support multiple cameras boards with your frame grabber interface you have to keep track of all instances corresponding to your frame grabber class see chapters 2 and 3 1 6 HALCON Frame Grabber Operators This section provides a short overview of the HALCON frame grabber operators please refer to the reference manuals for additional information These operators are internally mapped to the frame grabber interface routines you have to provide for a new HALCON frame grabber interface see chapter 3 Frame Grabber Integration 2000 11 16 1 6 HALCON FRAME GRABBER OPERATORS 7 1 6 1 open framegrabber The operator open framegrabber is used to create a new frame grabber handle It loads the specified frame grabber interface and accesses the frame grabber board itself Moreover the typical parameters for standard cameras are set like image size and part color space frame grabber port etc If the frame grabber that is the driver as well as your interface supports multiple boards inside one host computer you also specify the d
131. r 7 21 38 open framegrabber 7 21 25 27 57 58 set framegrabber lut 9 61 107 108 Index Frame Grabber Integration 2000 11 16
132. rab lt start the next asynchronous grab gt ifdef WIN32 _ftime amp currInst gt grabStarted else gettimeofday amp currInst gt grabStarted amp currInst gt tzp endif return H MSG OK Figure 3 36 Example code for GrabImg O Check the age of images HALCON 6 0 50 CHAPTER 3 INTERFACE ROUTINES 3 8 FGGrabAsync The routine FGGrabAsync as defined in Fig 3 37 is called by the HALCON operator grab_image_async see section 1 6 It has to perform the following tasks e Re set the parameters on the frame grabber board Wait until a pending asynchronous grab is finished or grab a new image if there is no pending job e Check if the asynchronously grabbed image is too old If this is the case grab a new image Start a new aynchronous grab without waiting e Return a HALCON image containing the grabbed raw data include Halcon h include hlib CIOFrameGrab h static Herror FGGrabAsync Hproc_handle proc_id FGInstance fginst double maxDelay Himage image INT num_image grab an image asynchronously TFGInstance currInst TFGInstance fginst gt gen_pointer INT4_8 maxDelay 0 5 TRUE currInst gt timeout fginst async grab HCkP FGGrab proc id fginst image num image return H MSG OK Figure 3 37 The prototype for FGGrabAsync based on FGGrab Since we have chosen an implementation of FGGrab in section 3 6 based on GrabImg in section 3 7
133. rame grabber integration support ing only one instance you can simplify FGInit In that case it might be enough to hold all framegrabber specific information in one global data structure or a bunch of global variables inside the interface Thus you could skip the suggested array TFGInstance FGInst FG_MAX_INST and all the code in Fig 3 5 HALCON 6 0 24 CHAPTER 3 INTERFACE ROUTINES static TFGInstance FGInst FG_MAX_INST all possible instances static INT numInstance 0 current instances static FGClass fgClass pointer to the class struct Herror FGInit Hproc handle proc_id FGClass fg 1 INT i Initialize the instance data structure inside of this interface for i 0 i FG MAX INST i 1 memset amp FGInst il O sizeof TFGInstance FGInst i instance i numInstance 0 D d store the class mformdtion c ecu fgClass return H_MSG_OK Figure 3 5 Example code for FGInit Initialize FGClass Frame Grabber Integration 2000 11 16 3 2 FGOPENREQUEST 25 3 2 FGOpenRequest The routine FGOpenRequest as defined in Fig 3 6 is called by the HALCON operator open_framegrabber prior to calling FGOpen see section 3 3 It has to perform only one task e Return the next available instance 1 one of the instance pointers inside the FGClass data structure see section 2 1 1 include Halcon h include hlib CIOFrameGrab h
134. rategies hte ea ae aa Get ee 5 1 5 A D Conversion and Multiplexing 6 1 6 HALCON Frame Grabber Operators 6 1 6 1 topen framegrabber Co Rex RR 7 1 6 2 _ 7 1 6 3 close allframegrabbers 7 1 0 4 ntoframegtabber ee ERAN OS NES X 7 re ole 8 SAND AI AE HS VIRG HR IRE D END ta 8 16 7 cgrabamag start s qo e d Gu Yrs Qi 8 1 0 8 cen oe RS X 8 1 6 9 grab regiOn asyfiC 9 1 6 10 set_framegrabber_param get framegrabber param 9 1 6 11 set framegrabber lut get_framegrabberlut 9 1 7 HALCON Frame Grabber Integration Interface versus HALCON Frame Grab ber Interface ace Reds oce tee os 9 1 8 Additional Sources of Information 10 Data Structures 13 2 1 Frame Grabber Classes and Instances 13 Zoli Structure teu mone cue veut ue ux S S 13 22 Str ct re uos ex XN YMO Y XS 15 2 2 Recommended Auxiliary Structures 17 2 2 1 gt
135. rr H MSG OK 1 HWriteSysComInfo proc id HGInitNewImage save return err else if fginst gt bits_per_channel lt 32 for i 0 i lt num_image i err HNewImage proc id amp image 0 INT4 IMAGE fginst gt image_width fginst gt image_height if err H_MSG_OK HWriteSysComInfo proc_id HGInitNewImage save return err HWriteSysComInfo proc id HGInitNewImage save IOS a II data Frame Grabber Integration 2000 11 16 RK if num_image 1 if fginst gt bits_per_channel lt 8 memcpy void image 0 pixel b currInst gt InstFrameBuffer readBuffer fginst gt image_width fginst gt image_height else if fginst gt bits_per_channel lt 16 1 memcpy void image 0 pixel s p currInst gt InstFrameBuffer readBuffer fginst gt image_width fginst gt image_height 2 image 0 pixel s num bits 16 else if fginst gt bits_per_channel lt 32 memcpy void image 0 pixel 1 currInst gt InstFrameBuffer readBuffer fginst gt image_width fginst gt image_height 4 else Note again Many color frame grabbers deliver the data in an interleaved format incompatible to HALCON Thus you typically will have to use som
136. rs used in open framegrabber are automatically returned by the HALCON library So you do not need to provide code for the parameters listed in Fig 3 46 on page 57 However please make sure to replace default values in fginst by the current settings if necessary in FGOpen FGGetParam should be able to handle all additional framegrabber specific parameters you introduced in FGSetParam The parameter value has to be returned in a structure of type Hcpar Please see the Extension Package Programmer s Manual for a detailed description of this structure A short description is given on page 38 Like FGSetParam FGGetParam offers the opportunity to return multi parameter values Therefore assign index wise each parameter to value i But do not forget to specify the type of the value in value il type and to set the function parameter num to the number of returned values Fig 3 49 shows a simple example assuming that there is only one additional parameter controlling volatile grabbing see also Fig 3 48 Remember that the names of these parameters must be returned for the query FG QUERY PARAMETERS by FGInfo see Fig 3 26 on page 40 Frame Grabber Integration 2000 11 16 3 14 FGSETLUT 61 3 14 FGSetLut The routine FGSetLut as defined in Fig 3 50 is called by the HALCON operator Set framegrabber lut see section 1 6 It has to perform the following task e Set the lookup table for the specified instance include Halco
137. ry There is one special configuration worth thinking about it for a minute If you enter GrabImg in asynchronous mode fginst gt grab_async is TRUE with an asynchronous grab pending currInst gt busy is TRUE which is not finished up to now done is FALSE you have to decide what to do If the grab already lasts for too long you can cancel it and start a new one However if the duration of the grab is still below the timeout threshold it is impossible to say whether the image will be too old or not after completion of the grab Therefore we delayed the time check in the example in Fig 3 34 in this specific case by setting checkTimeAgain TRUE Frame Grabber Integration 2000 11 16 3 7 AUXILIARY ROUTINE GRABIMG 49 static Herror GrabImg Hproc handle proc id FGInstance fginst INT readBuffer ifdef WIN32 struct _timeb now 1 struct timeval now struct timezone tzp endif INT4_8 time diff test whether the grabbed image is too old ifdef WIN32 _ftime amp now time diff now millitm currInst 5grabStarted millitm 1000 now time currInst gt grabStarted time 1 gettimeofday amp now amp tzp time_diff INT4_8 double now tv_sec 1000 0 double now tv usec 1000 0 double currInst gt grabStarted tv_sec 1000 0 double currInst gt grabStarted tv_usec 1000 0 0 5 endif if time_diff gt currInst gt timeout newGrab TRUE if fginst gt async_g
138. s the mode results also in a three channel 8 bit HALCON image else return H ERR FGCS o o k k kk k kk kk TODO Check the desired video gain desired video gain is passed fginst gt gain Just ignore this parameter if your board does not support any gain setting If 1 0 for default is used open_framegrabber the values YOU provided for fg gt gain in FGInit will be passed fginst gt gain If you encounter unreasonable requests return H_ERR_FGGAIN invalid video gain if fginst gt gain lt 0 0 return H_ERR_FGGAIN example gain must be positive DCG o k o kk k kk k kkk k TODO Check for external triggering If external triggering is desired fginst gt external_trigger is set to TRUE otherwise to FALSE If default is used open_framegrabber the value YOU provided for fg gt external_trigger in FGInit will be passed If the frame grabber does not support external tri
139. se buffers might be shared with other instances To prevent side effects we have to provide buffers for the current instance exclusively if board gt refBuffer 1 t No other instance uses the board buffer Just transfer them to the instance for 1 0 i lt MAX_BUFFERS i currInst gt InstFrameBuffer i board gt BoardFrameBuffer i board gt BoardFrameBuffer i NULL board gt sizeBuffer 0 else There are other instances using the board buffers Thus we have to allocate new buffers typically you will have to use frame grabber specific routines for this task see FG pen also sizeBuffer fginst gt image_width fginst gt image_height fginst gt bits_per_channel 7 8 fginst gt num_channels for i 0 i lt MAX_BUFFERS i 11 proc_id size_t sizeBuffer amp currInst InstFrameBuffer i l board gt refBuffer currInst gt allocBuffer TRUE currInst allocBuffer currInst gt volatileMode TRUE fginst gt halcon_malloc FALSE fginst gt clear_proc NULL Do not deallocate the grabbed image currInst gt volatileMode enable else if strcmp value 5par s disable 1 Disable the volatile mode GOS OO IO k k kk kk if currInst gt volatileMode Otherwise we d
140. se for color images Before we have a closer look at GrabImg let us finish the discussion of FGGrab For the moment we just assume that GrabImg delivered the grabbed image in the buffer Actually most frame grabbers we know do not allow to grab three separated channels Frame Grabber Integration 2000 11 16 3 6 FGGRAB 43 currInst gt InstFrameBuffer readBuffer There are two possibilities to allocate a HALCON image of type Himage see the Extension Package Programmer s Manual for details on both the data structure and the allocation rou tines HNewImagePtr as defined in Fig 3 30 initializes the data structure but does not allocate memory for the image matrix that is the gray values or the raw data itself Instead only a pointer to the data is inserted Note that you have to set initImg to FALSE to avoid an initialization of the image matrix with 0 which would wipe out the grabbed image include Halcon h Herror HNewImagePtr Hproc_handle proc_id Himage image INT kind INT width INT height void data HBOOL initImg initialize image and insert the pointer data as image matrix return H MSG OK Figure 3 30 The prototype for the extension package interface routine HNewImagePtr Inserting the image buffer assigned to the frame grabber instance into the new HALCON im age avoids the overhead introduced by a memcpy On the other hand this is a severe side effect Older HALCON images wi
141. se note the latest updates of this manual e 5 Edition HALCON 6 0 November 2000 The manual has been adapted to the syntactic and semantic changes of the new HALCON frame grabber integration interface version 2 A summary of changes can be found in Appendix A Besides the list of currently supported frame grabbers see Fig 1 1 has been updated Furthermore a small number of syntactic corrections of this manual has taken place e 4 Edition HALCON 5 2 March 1999 Some clarifications in the introduction have been made especially an updated list of cur rently supported frame grabbers see Fig 1 1 The order of the allocated image regions in FGGrabRegion is fixed see new hint in Fig 3 43 Furthermore a small number of syntactical corrections have taken place e 2 Edition HALCON 5 1 March 1998 The manual has been revised completely regarding both the structure and the content The HALCON frame grabber interface was extended by the op erators set framegrabber param get framegrabber param grab region and grab region async which do correspond to the routines FGSetParam FGGetParam FGGrabRegion and FGGrabRegionAsync within the frame grabber interface to be programmed Contents 2 3 1 Introduction 1 1 1 HALCON s Generic Frame Grabber Interface 1 1 2 Image Acquisition 2 1 3 Synchronous vs Asynchronous Grabbing 4 1 4 Buffering St
142. size of the buffers image_width x image_height x bytes per pixel in case your frame grabber supports grabbing only a part of an image horizontal_resolution x vertical_resolution x bytes per pixel otherwise 2 Allocate buffers per board or per instance If you do not pass this memory directly to HALCON objects but perform memcopy or other copying procedures for example to split color raw data into three channels AND you ve got only A D converter per board you allocate the buffer s board frame grabber board e g using currInst gt board gt BoardFrameBuf fer Otherwise and also if you allow several instances per board with different image sizes allocate them per instance both cases we would recommend to store at least copies of the pointers to the buffers currInst gt InstFrameBuffer in order to have a unified access to the data Note that the recommended entries sizeBuffer refBuffer in BoardInfo and allocBuffer TFGInstance might be quite handy to keep track of the current memory configuration 3 How to allocate them In most cases the frame grabber API will provide specific routines for this task since buffer memory to grab to at least has to non paged etc
143. sync_grab lt start the next asynchronous grab gt return H_MSG_OK Figure 3 34 Example code for GrabImg The basic structure Note that asynchronous grabbing might lead to old images returned by the grabbing op erators Therefore grab image start grab image async and grab region async allow HALCON 6 0 48 CHAPTER 3 INTERFACE ROUTINES static Herror SetInstParam FGInstance fginst TFGInstance currInst TFGInstance fginst gt gen_pointer Everything that you allow to be different for instances of the same board like port and input line etc must be checked and set again if necessary Note If this is very time consuming you might want to store the current parameter settings of the board currInst gt board and check whether they differ from the values currInst fginst example if currInst gt board gt port fginst gt port 1 lt set the port fginst gt port gt currInst board port fginst gt port Y return H MSG OK Figure 3 35 The prototype for SetInstParam to specify the maximum tolerated age of an image see the HALCON reference manual for details Consequently you should store a timestamp whenever you start grabbing an im age see Fig 3 36 Then before returning an asynchronously grabbed image check whether too much time has passed and grab a new image again if necessa
144. t return CleanupFGOpen proc_id currInst newBoardalloc H_ERR_FGWP return H_MSG_OK Figure 3 15 Example code for FGOpen O Determine the desired image part to be delivered as HALCON image MAX BUFFERS entries Obviously you have to allocate such buffers once per instance if you would like to support different image sizes or color depths or volatile grabbing see sections 1 4 and 2 2 2 On the other hand if several instances are assigned to the same physical frame grabber board and they have to share a single A D converter you have to synchronize the grabbing by these instances Thus they could actually share the buffers as well to reduce the demand for typically non paged buffer memory Therefore we suggest to allocate shared buffers per board if possible and per instance only if necessary Variant to this suggestion you can adapt the condition of the first if command in Fig 3 17 to your needs The allocation itself usually is done using framegrabber specific API calls In the following examples we will use the HALCON extension package interface routine HAlloc as a template Please note that in most cases you will have to replace these HAlloc calls by other routines Fig 3 17 demonstrates this strategy Note that the data structures BoardInfo and TFGInstance as introduced in the sections 2 2 1 and 2 2 2 have been designed for that pur pose They include all the informations needed to handle the buffers board gt sizeBu
145. t gen_pointer INT i if currInst gt busy 1 TODO terminate the pending asynchronous job the one belonging to this instance currInst gt busy FALSE DOGG Gk k k k k kkk TODO Cleanup Basically you have to deallocate the buffers associated with the instance and maybe you have to deallocate the data associated with the board and unlock the frame grabber TODO Deallocate Buffers DOCG if currInst gt allocBuffer buffers have been allocated for this instance exclusively get rid of them for i 0 i lt MAX_BUFFERS i 85 HALCON 6 0 86 if currInst gt InstFrameBuffer i HFree proc_id currInst gt InstFrameBuffer i currInst gt InstFrameBuffer i NULL else BoardInfo board currInst gt board the instance shared the board buffers with other instances if board gt refBuffer 1 1 This is the last instance which uses the board frame
146. t grab images only on demand Host memory is allocated by the user somewhere in the address space of the application Since this memory might be pagable the images delivered from the frame grabber in general must be explicitly copied to this memory since DMA will fail Naturally this is not true if the camera supports an asynchronous reset mode i e the camera starts the new grab almost immediately gt There is a very short sync period before the next frame starts 6When grabbing a PAL signal with a RGB frame grabber using 32 bit per pixel representation more than 42 Megabytes per second have to be transferred to the host Frame Grabber Integration 2000 11 16 1 4 BUFFERING STRATEGIES 5 The host computer s job as mentioned above is to trigger the frame grabber when a new image is needed but it does not necessarily need to wait while the board digitizes the frame With device memory being on the board this is self evident but also if the target memory is host based externally initiated data transfer is usually possible with techniques like DMA So the only thing the host process has to do is to trigger the frame grabber board an average time of 1i frames before an image is actually needed and then it can do some other processing while the new frame is captured by the board in the background This technique is called asynchronous grabbing It is easily understood that this eases real time grabbing since the time neede
147. tance since we want to start a new grab but also grabs started by other instances since in most cases they share the A D converter with the current instance Terminating other instances obviously is a side effect Thus you might consider to return an error code instead H ERR FGDV Device busy Note further that the threshold currInst gt timeout is used to determine whether an asyn chronously grabbed image is too old to be delivered see also Fig 3 36 However only the performance is affected If you terminate an asynchronous grab a new grab will be launched when you access the corresponding image with one of the HALCON grabbing operators grab image grab image async grab region or grab region async HALCON 6 0 52 CHAPTER 3 INTERFACE ROUTINES static Herror FGGrabStartAsync Hproc handle proc id FGInstance fginst double maxDelay TFGInstance currInst TFGInstance fginst gt gen_pointer currInst gt timeout INT4_8 maxDelay 0 5 lt terminate pending grabs of other instances using the same ADC gt if currInst gt busy lt terminate the current grab gt else HCkP SetInstParam fginst lt start the new asynchronous grab gt ifdef WIN32 _ftime amp currInst gt grabStarted else gettimeofday amp currInst gt grabStarted amp currInst gt tzp endif currInst gt busy TRUE return H_MSG_OK Figure 3 39 Example code for FGGrabStartAsync O Frame
148. tatic Herror FGInfo Hproc_handle proc_id INT queryType char info Hcpar values INT numValues switch queryType case FG_QUERY_GENERAL info HALCON frame grabber interface template vendor MVTec values NULL numValues 0 break case FG QUERY PORT break case FG QUERY CAMERA TYPE break case FG QUERY DEFAULTS info Default values as used for open framegraber HCkP HFgGetDefaults proc id fgClass values numValues break case FG QUERY PARAMETERS break case FG QUERY INFO BOARDS info Info about installed boards break default info Unsupported query values NULL numValues 0 return H MSG OK Figure 3 24 Example code for FGInfo Parsing the query exclusively to allocate the latter see Fig 3 25 Otherwise you will encounter system crashes when info_framegrabber deallocates the array using HFree Figure 3 26 shows another example For the query FG_QUERY_PARAMETERS FGInfo has to return a list of all names of additional framegrabber specific parameters supported by your frame grabber see also FGSetParam in section 3 12 and FGGetParam in section 3 13 In our example we assume that there is only one additional parameter controlling volatile grabbing see also Fig 3 48 on page 59 and Fig 3 49 on page 60 HALCON 6 0 40 CHAPTER 3 INTERFACE ROUTINES static Herror FGInfo Hproc_handle proc_id INT queryType char info Hcpar values INT
149. thScale fginst gt vertical_resolution fginst gt height_max heightScale It might be useful to store the current subsampling mode e g in fginst gt mode if widthScale 1 heightScale 1 fginst gt mode FG_FULL_RESOLUTION else if widthScale 2 amp amp heightScale 2 fginst gt mode FG_HALF_RESOLUTION else if widthScale 4 amp amp heightScale 4 fginst gt mode FG_QUARTER_RESOLUTION else fginst gt mode FG_OTHER_RESOLUTION the subsampling is hopefully handled properly now let s analyze the image part full centred image part if fginst gt image_width 0 fginst gt image_width fginst gt horizontal_resolution 2 fginst gt start_col if fginst gt image_height 0 fginst gt image_height fginst gt vertical_resolution 2 fginst gt start_row Now let s check the part if not reasonable Return H ERR FGWP wrong image part if fginst gt start_col fginst gt image_width gt fginst gt horizontal_resolution fginst gt start_row fginst gt image_height gt fginst gt vertical_resolution wrong part return CleanupFG pen proc id currInst newBoardalloc H ERR FGWP TODO Set the image size part
150. ther its finished if not terminate it you have to start a new grab NOW else if currInst gt board gt refInst gt 1 There are other instances using the same board Thus you have set the frame grabber parameters again TODO Restore frame grabber settings for currInst Everything that you allow to be different for instances of the board like port and input line etc has to be set again HCkP Set InstParam fginst TODO start an asynchronous grab ifdef WIN32 _ftime amp currInst gt grabStarted remeber the time the grab was started else gettimeofday amp currInst gt grabStarted amp currInst gt tzp endif currInst gt busy TRUE return H_MSG_OK FGGrabStartAsync static Herror GrabImg Hproc_handle proc_id
151. tures you might have to encapsulate code sections like this ifdef WIN32 include lt sys timeb h gt else include lt time h gt endif include Halcon h include hlib CIOFrameGrab h TODO Place your vendor specific include s here e g include filei h include file2 h include file3 h k k kk kkk k eek TODO place your vendor specific define s here oook kk kkk kkk e g define MY_BUFFER_SIZE Oxffff These defines be a good idea if you would like to support subsampling define FG_FULL_RESOLUTION 0 define FG_HALF_RESOLUTION 1 define FG_QUARTER_RESOLUTION 2 define FG_OTHER_RESOLUTION 3 You might want to define additional parameters to be handled by FGSetParam FGG
152. unter while programming such an interface like supporting multiple boards with multiple cameras per board etc Although the template is extensively commented it might be quite tough to understand the code prior to reading this manual On the other hand it can provide a powerful skeleton for a wide range of integrations You will also find two specific example interfaces in the HALCON distribution A very simple one MySlicVideo c for the SLIC Video SBus frame grabber from Multimedia Access Cor poration and a fairly complex one MyDT3155 c for the DT3155 board by Data Translation These two examples have been implemented in a straightforward way For the sake of simplic ity they do not follow the general design of the template in CIOFGTemplate c They might be more suitable as starting points for a first prototypical implementation However if you are go ing to design the final HALCON interface we strongly recommend to use CIOFGTemplate c For a list of all the frame grabbers that are currently already supported by HALCON see Fig 1 1 Please check http www mvtec com halcon or contact your local distributor to get the latest releases of the HALCON frame grabber interfaces You can find an up to date list of all currently supported frame grabbers and also a further list of new experimental frame grabber interfaces at http www mvtec com halcon framegrabber 1 2 Image Acquisition Basics Basically what a frame grabber does is to ta
153. urrInst board DeviceName fginst device open the board for the 1st time currInst gt board gt DeviceId return H MSG OK Figure 3 11 Example code for FGOpen O Access physical frame grabber board for the very first time If you support multiple instances per physical frame grabber board e g in case of more than one camera connected to a single board you should spend some time on the design of the availability checks A fairly simple solution is to enforce different ports fginst gt port the parameter 11 to denote a multiplexed input line has historical reasons and is not rec ommended anymore but identical values for the rest of the parameters image size color depth etc Otherwise you have to reset all these parameters the frame grabber board whenever you grab for one instance or the other This might be both a lot of work to program and time consuming during the application The latter might be partly compensated by storing the current parameter settings of the board within the BoardInfo structure see section 2 2 1 and compar ing them to corresponding settings in the FGInstance see section 2 1 2 or TFGInstance see section 2 2 2 structures Obviously you only have to reset the parameters that differ If you encounter the first instance to be assigned to a physical frame grabber board you have to access the board using the frame grabber API and you might have to allocate
154. ut by yourself what your frame grabber supports concerning such a feature Note that setting the frame grabber LUT will have side effects on the other instances using the same board Thus in case that fginst gt board gt refInst gt 1 you will have to store the LUT in the TFGInstance struct and set it again and again before grabbing return H_MSG_OK FGSetLut 99 HALCON 6 0 100 APPENDIX INTERFACE TEMPLATE CIOFGTEMPLATE C static Herror FGGetLut Hproc_handle proc_id FGInstance fginst INT4_8 red INT4_8 green INT4_8 blue INT num TFGInstance currInst TFGInstance fginst gt gen_pointer TODO Get the lookup table of your frame grabber ok The output of this routine is a RGB lookup table with num entries of RGB triples There is not much more than can be said in general Sorry you will have to find out by yourself what your frame grabber supports concerning such a feature num 0 return H_MSG_0K FGGetLut static Herror FGSetParam Hproc_handle proc_id FGInstance fginst char param Hcpar value INT num TFG
155. will indicate how to allocate image regions encoded in the data structure Hrlregion Please see the HALCON Extension Package Programmer s Manual for both a discussion of this data type and routines to manipulate it Please note that in most cases you will have to provide additional parameters for the segmentation process We suggest to use FGSetParam for that purpose see section 3 12 The HALCON library passes array of MAX OBJ PER PAR pointers to Hrlregion FGGrabRegion However the region data itself is not allocated automatically This has to be done within your interface There are several methods to do so 107 the framework suggested in this manual it is also called by FGGrabRegionAsync see section 3 11 lIn the current version this define is set to 100 000 That should be more than enough to hold all reasonable segmentation results HALCON 6 0 54 CHAPTER 3 INTERFACE ROUTINES include Halcon h Herror HAllocRLNumLocal Hproc handle proc_id Hrlregion region size_t len initialize region and temporarily allocate memory for len chords return H MSG OK Figure 3 41 The prototype for the extension package interface routine HAllocRLNumLocal static Herror FGGrabRegion handle proc_id FGInstance fginst Hrlregion region INT num region INT 1 11 type TFGInstance currInst TFGInstance fginst gen pointer INT readBuffer HCkP GrabImg fg
156. ype parameter GCC GOCE SG a ka kik ak k Explain the usage of the camera type parameter in open_framegrabber and its possible values example info Video signal of the camera HCkP 11 proc_id size_t 3 sizeof Hcpar amp val val 0 par s ntsc val 1 par s pal val 2 par s auto val 0 type val 1 type val 2 type STRING_PAR values val numValues 3 break case FG_QUERY_DEFAULTS Just leave this one here like it is info Default values as used for open framegraber HCkP HF gGetDefaults proc_id fgClass values numValues break case FG QUERY PARAMETERS J sckokokokok kokokokokokokokokokokokokokokokokolokolokokookolokolololololelokelokokolekelololololelelelolelokekelekelolelelelelelelelek TODO Return the names of non standard parameters sckokokokokokokokokokokokokokokokokokokokokokolokolokokookololololokelolelokelokokolokolololololelelelolelolokelelelolelolelelelelelek Frame Grabber Integration 2000 11 16 What additional parameters are supported for set_framegrabber_param see FGSetParam 1 info Additional parameters for this frame grabber 11 proc_id size_t FG_PARAM_NUM sizeof Hcpar amp val val 0 par s FG_PARAM_VOLATILE val i par s FG_PARAM_REVISION

Frame Grabber Integration Programmer`s Manual

Contents

Download Pdf Manuals

Related Search

Related Contents