he power of machine vision Soluion Guide II-A Image Acquisiion
The Ar of Image Acquisiion, Version 12.0.2 All righs reserved. No par of his publicaion may be reproduced, sored in a rerieval sysem, or ransmied in any form or by any means, elecronic, mechanical, phoocopying, recording, or oherwise, wihou prior wrien permission of he publisher. Ediion 1 June 2002 (HALCON 6.1) Ediion 2 December 2003 (HALCON 7.0) Ediion 3 June 2007 (HALCON 8.0) Ediion 4 December 2008 (HALCON 9.0) Ediion 4a June 2009 (HALCON 9.0.1) Ediion 4b Ocober 2010 (HALCON 10.0) Ediion 5 November 2011 (HALCON 10.0.2) Ediion 6 May 2012 (HALCON 11.0) Ediion 7 November 2014 (HALCON 12.0) Ediion 7a July 2015 (HALCON 12.0.1) Copyrigh 2002-2016 by MVTec Sofware GmbH, München, Germany MVTec Sofware GmbH Proeced by he following paens: US 7,062,093, US 7,239,929, US 7,751,625, US 7,953,290, US 7,953,291, US 8,260,059, US 8,379,014, US 8,830,229. Furher paens pending. Microsof, Windows, Windows Visa, Windows Server 2008, Windows 7, Windows 8, Windows 10, Microsof.NET, Visual C++, Visual Basic, and AciveX are eiher rademarks or regisered rademarks of Microsof Corporaion. Linux is a rademark of Linus Torvalds. All oher naionally and inernaionally recognized rademarks and radenames are hereby recognized. More informaion abou HALCON can be found a: hp://www.halcon.com/
Abou This Manual Obviously, he acquisiion of images is a ask o be solved in all machine vision applicaions. Unforunaely, his ask mainly consiss of ineracing wih special, non-sandardized hardware in form of image acquisiion devices, i.e., cameras or frame grabber boards. To le you concenrae on he acual machine vision problem, HALCON already provides inerfaces performing his ineracion for a large number of image acquisiion devices (see secion 1 on page 7). Wihin your HALCON applicaion, he ask of image acquisiion is hus reduced o a few lines of code, i.e., a few operaor calls, as can be seen in secion 2 on page 9. Wha s more, his simpliciy is no achieved a he cos of limiing he available funcionaliy: Using HALCON, you can acquire images from various configuraions of frame grabbers and cameras (see secion 3 on page 11) in differen iming modes (see secion 5 on page 25). The example programs ha are presened in his Soluion Guide can be found in he specified subdirecories of he direcory %HALCONEXAMPLES%. Noe ha mos programs are preconfigured o work wih a cerain HALCON acquisiion inerface; in his case, he name of he program conains he name of he inerface. To use he program wih anoher image acquisiion device, please adap he pars which open he connecion o he device. More example programs for he differen HALCON acquisiion inerfaces can be found in he subdirecory hdevelop\image\acquisiion of he direcory %HALCONEXAMPLES%. Please refer o he Programmer s Guide, chaper 13 on page 115 and chaper 23 on page 195, for informaion abou how o compile and link he C++ and C example programs; among oher hings, hey describe how o use he example makefiles for Unix-like sysems which can be found in he subdirecories c and cpp of he direcory %HALCONEXAMPLES%. Under Windows, you can use Visual Sudio workspaces conaining he examples, which can be found in he subdirecory win parallel o he source files.
Conens 1 The Philosophy Behind he HALCON Acquisiion Inerfaces 7 2 A Firs Example 9 3 Connecing o Your Image Acquisiion Device 11 3.1 Opening a Connecion o a Specified Configuraion.................... 12 3.2 Connecing o Muliple Boards and Cameras........................ 12 3.2.1 Single Camera................................... 12 3.2.2 Muliple Boards.................................. 12 3.2.3 Muliple Handles Per Board............................ 14 3.2.4 Por Swiching................................... 14 3.2.5 Simulaneous Grabbing (Only For Specific Inerfaces).............. 15 3.3 Requesing Informaion Abou he Image Acquisiion Inerface.............. 15 4 Configuring he Acquisiion 19 4.1 General Parameers..................................... 19 4.2 Special Parameers..................................... 20 4.3 Fixed vs. Dynamic Parameers............................... 22 5 The Various Modes of Grabbing Images 25 5.1 Real-Time Image Acquisiion................................ 25 5.1.1 Non-Real-Time Grabbing Using grab_image................... 25 5.1.2 Grabbing Wihou Delay Using Asynchronously Reseable Cameras...... 27 5.1.3 Volaile Grabbing.................................. 27 5.1.4 Real-Time Grabbing Using grab_image_async.................. 29 5.1.5 Coninuous Grabbing................................ 31 5.1.6 Using grab_image_async Togeher Wih Asynchronously Reseable Cameras.. 33 5.1.7 Specifying a Maximum Delay........................... 33 5.2 Using an Exernal Trigger.................................. 35 5.2.1 Special Parameers for Exernal Triggers..................... 37 5.3 Acquiring Images From Muliple Cameras......................... 37 5.3.1 Dynamic Por Swiching and Asynchronous Grabbing.............. 37 5.3.2 Simulaneous Grabbing............................... 38 6 Miscellaneous 39 6.1 Acquiring Images From Sandardized Image Acquisiion Devices............. 39
6.2 Acquiring Images From Unsuppored Image Acquisiion Devices............. 40 6.3 Grabbing Image Arrays and Preprocessed Image Daa................... 42 6.4 Error Handling....................................... 42 6.4.1 Error Handling in HDevelop............................ 43 6.4.2 Error Handling Using HALCON/C........................ 44 6.4.3 Error Handling Using HALCON/C++....................... 45 6.4.4 Error Handling Using HALCON/COM...................... 45 6.4.5 Error Handling Using HALCON/.NET...................... 46 6.5 Callback Funcions..................................... 46 6.6 Line Scan Cameras..................................... 46 A HALCON Images 51 A.1 The Philosophy of HALCON Images............................ 51 A.2 Image Tuples (Arrays)................................... 52 A.3 HALCON Operaors for Handling Images......................... 52 A.3.1 Creaion....................................... 52 A.3.2 Channels...................................... 53 A.3.3 Domain....................................... 53 A.3.4 Access....................................... 53 A.3.5 Manipulaion.................................... 53 A.3.6 Image Tuples.................................... 53 B Parameers Describing he Image 55 B.1 Image Size......................................... 55 B.2 Image Daa......................................... 56 C Objec Appearance 59 C.1 Lighing........................................... 59 C.1.1 Reflecion Properies of he Objec......................... 60 C.1.2 Characerisics of he Ligh Source......................... 60 C.2 Geomery.......................................... 63
The Philosophy Behind he HALCON Acquisiion Inerfaces A-7 Chaper 1 Philosophy The Philosophy Behind he HALCON Acquisiion Inerfaces From he poin of view of a user developing sofware for a machine vision applicaion, he acquisiion of images is only a prelude o he acual machine vision ask. Of course i is imporan ha images are acquired a he correc momen or rae, and ha he camera and he frame grabber are configured suiably, bu hese asks seem o be elemenary, or a leas independen of he used image acquisiion device. The realiy, however, looks differen. Image acquisiion devices differ widely regarding he provided funcionaliy, and even if heir funcionaliy is similar, he SDKs (sofware developmen ki) provided by he manufacurers do no follow any sandard so far. Therefore, swiching o a differen image acquisiion device probably requires o rewrie he image acquisiion par of he applicaion. HALCON s answer o his problem are is image acquisiion inerfaces (IAI) which are provided o currenly more han 50 frame grabbers and hundreds of indusrial cameras (analog, Camera Link, USB 2.0, IEEE 1394, and GigE) in form of dynamically loadable libraries (Windows: DLLs; OS X: shared libraries). HALCON image acquisiion inerfaces bridge he gap beween he individual image acquisiion devices and he HALCON library, which is independen of he used image acquisiion device, compuer plaform, and programming language (see figure 1.1). In oher words, hey provide a sandardized inerface o he HALCON user in form of 15 HALCON operaors, and encapsulae deails specific o he frame grabber or camera, i.e., he ineracion wih he SDK provided by he device manufacurer. Therefore, if you decide o swich o a differen image acquisiion device, all you need o do is o insall he corresponding driver and SDK provided by he manufacurer and o use differen parameer values when calling he HALCON operaors; he operaors hemselves say he same. In fac, he elemenary asks of image acquisiion are covered by wo HALCON operaors: open_framegrabber connecs o he image acquisiion device and ses general parameers, e.g., he ype of he used camera or he por he camera is conneced o, hen
A-8 The Philosophy Behind he HALCON Acquisiion Inerfaces camera compuer HALCON applicaion HDevelop / C / C++ / C# / Visual Basic frame grabber sofware HALCON image processing library halcon.dll & halconc/cpp/done/x.dll HALCON xyz acquisiion inerface hacqxyz.dll device driver & SDK Figure 1.1: From he camera o a HALCON applicaion. grab_image (or grab_image_async, see secion 5.1 on page 25 for he difference) grabs images. If no only a single image bu an array of images or preprocessed image daa like regions or conours have o be grabbed, grab_daa or grab_daa_async can be used (see also secion 6.3 on page 42). If an image acquisiion device provides addiional funcionaliy, e.g., on-board modificaion of he image signal, special grabbing modes, or digial oupu lines, i is available via he operaor se_framegrabber_param (see secion 4 on page 19). Noe, ha for some image acquisiion devices he full funcionaliy is no available wihin HALCON; please refer o he corresponding online documenaion which can be found in he direcory %HALCON- ROOT%\doc\hml\manuals or via he HALCON folder in he Windows sar menu (if you insalled he documenaion). The laes informaion can be found under hp://www.halcon.com/imageacquisiion. If he image acquisiion device you wan o use is no (ye) suppored by HALCON, you can neverheless use i ogeher wih HALCON. Please refer o secion 6.2 on page 40 for more deails. Please noe ha wih HALCON 8.0 our erminology has changed: Since digial cameras, which are conneced by USB 2.0, IEEE 1394 or GigE, are no really based on an acual frame grabber board, we no longer use he erm HALCON frame grabber inerface. Insead, we use he erm HALCON acquisiion inerface, and he erm image acquisiion device is used as a subsiue for eiher a frame grabber board or a digial camera. For backwards compaibiliy reasons, he names of he HALCON operaors have been unchanged, hus, he operaor names open_framegrabber, info_framegrabber, and close_framegrabber may sound a lile bi old-fashioned.
A Firs Example A-9 Chaper 2 A Firs Example Firs Example In his secion we sar wih a simple image acquisiion ask, which uses he image acquisiion device in is defaul configuraion and he sandard grabbing mode. The grabbed images are hen segmened. To follow he example acively, sar he HDevelop program soluion_guide\image_acquisiion\ firs_example_acquisiion.hdev, hen press Run once o iniialize he applicaion. Sep 1: Connec o he frame grabber open_framegrabber (AcqName, 1, 1, 0, 0, 0, 0, 'defaul', -1, 'defaul', -1, \ 'false', CameraType, myboard, -1, -1, AcqHandle) When opening he connecion o your image acquisiion device using he operaor open_framegrabber, he main parameer is he Name of he corresponding HALCON acquisiion inerface. As a resul, you obain a so-called handle (AcqHandle), by which you can access he image acquisiion device, e.g., in calls o he operaor grab_image. a) b) Figure 2.1: a) Acquired image; b) processed image (auomaic segmenaion).
A-10 A Firs Example In he example, defaul values are used for mos oher parameers ( defaul or -1); secion 4.1 on page 19 akes a closer look a his opic. How o connec o more complex frame grabber and camera configuraions is described in secion 3 on page 11. Sep 2: Grab an image grab_image (Image, AcqHandle) Afer successfully connecing o your image acquisiion device you can grab images by calling he operaor grab_image wih he corresponding handle AcqHandle. More advanced modes of grabbing images are described in secion 5 on page 25. Sep 3: Grab and process images in a loop while (Buon!= 1) grab_image (Image, AcqHandle) auo_hreshold (Image, Regions, 4) connecion (Regions, ConnecedRegions) ge_mposiion (WindowHandleBuon, Row, Column, Buon) endwhile In he example, he grabbed images are hen auomaically segmened using he operaor auo_hreshold (see figure 2.1). This is done in a loop which can be exied by clicking ino a window wih he lef mouse buon.
Connecing o Your Image Acquisiion Device A-11 Chaper 3 Connecing o Your Image Acquisiion Device In his secion, we show how o connec o differen configuraions of frame grabber(s) and camera(s), ranging from he simple case of one camera conneced o one frame grabber board o more complex ones, e.g., muliple synchronized cameras conneced o one or more boards. Connecing SDK & IAI A por 0 frame SDK & IAI B grabber board 0 frame grabber board 1 por 1 por 0 por 1 camera ype abc camera ype xyz AcqHandle which inerface? which device? which por? which camera? Name Device Por CameraType Figure 3.1: Describing a connecion wih he parameers of open_framegrabber.
A-12 Connecing o Your Image Acquisiion Device 3.1 Opening a Connecion o a Specified Configuraion Wih he operaor open_framegrabber you open a connecion o an image acquisiion device. This connecion is described by four parameers (see figure 3.1): Firs, you selec an acquisiion inerface wih he parameer Name. The parameer Device specifies he acual board or camera; depending on he acquisiion inerface, his parameer can conain a sring describing he board or simply a number (in form of a sring!). Ofen, he camera can be conneced o he frame grabber a differen pors, whose number can be seleced via he parameer Por (in rare cases LineIn). The parameer CameraType describes he conneced camera: For analog cameras, his parameer usually specifies he used signal norm, e.g., nsc. For digial cameras, his parameer ypically specifies he camera model; more complex acquisiion inerfaces use his parameer o selec a camera configuraion file. As a resul, open_framegrabber reurns a handle for he opened connecion in he parameer AcqHandle. Noe ha if you use HALCON s COM or C ++ inerface and call he operaor via he corresponding classes, e.g., HFramegrabber in C++, no handle is reurned because he insance of he class iself acs as your handle. Wih HDevelop s Image Acquisiion Assisan you can easily connec o your image acquisiion device and choose suiable parameers (for deails see he HDevelop User s Guide, secion 7.1 on page 241), which is very useful o seup your vision sysem (illuminaion, focus, field of view). 3.2 Connecing o Muliple Boards and Cameras Mos HALCON acquisiion inerfaces allow o use muliple frame grabber boards and cameras. However, here is more han one way o connec cameras and boards and o access hese configuraions from wihin HALCON. Below, we describe he differen configuraions; please check he online documenaion of he HALCON inerface for your image acquisiion device (see %HALCONROOT%\doc\hml\manuals, he HALCON folder in he Windows sar menu, or hp://www.halcon.com/image-acquisiion) which configuraions i suppors. 3.2.1 Single Camera Figure 3.2a shows he simples configuraion: a single camera conneced o a single board, accessible via a single handle. Some frame grabbers, especially digial ones, only suppor his configuraion; as described in he following secion, you can neverheless use muliple cameras wih such frame grabbers by connecing each one o an individual board. Noe ha his configuraion is he ypical one in case of digial cameras conneced by USB 2.0, IEEE 1394, or GigE. 3.2.2 Muliple Boards Figure 3.2b shows a configuraion wih muliple cameras, each conneced o a separae board. In his case you call he operaor open_framegrabber once for each connecion as in he HDevelop example program soluion_guide\image_acquisiion\muliple_boards.hdev.
3.2 Connecing o Muliple Boards and Cameras A-13 a) b) handle 0 por 0 frame grabber handle 0 frame grabber por 0 board 0 board 0 handle 1 frame grabber por 0 board 1 c) handle 0 handle 1 frame grabber board 0 por 0 por 1 d) handle 0 frame grabber por 0 handle 2 frame grabber board 1 por 0 por swich board 0 por 1 Connecing e) f) por 0 frame grabber handle 0 frame grabber por 0 handle 0 board 0 por 1 HImage[2] board 0 por 1 HImage[3] frame grabber por 0 board 1 Figure 3.2: a) single board wih single camera; b) muliple boards wih one camera each; c) muliple boards wih one or more cameras; d) single board wih muliple cameras and por swiching; e) single board wih muliple cameras and simulaneous grabbing; f) simulaneous grabbing wih muliple boards and cameras. open_framegrabber (AcqName, 1, 1, 0, 0, 0, 0, 'defaul', -1, 'defaul', -1, \ 'defaul', 'defaul', Board0, -1, -1, AcqHandle0) open_framegrabber (AcqName, 1, 1, 0, 0, 0, 0, 'defaul', -1, 'defaul', -1, \ 'defaul', 'defaul', Board1, -1, -1, AcqHandle1) In his example, he wo calls differ only in he value for he parameer Device ( 0 and 1 ); of course, you can use differen values for oher parameers as well, and even connec o differen image acquisiion inerfaces.
A-14 Connecing o Your Image Acquisiion Device To grab images from he wo cameras, you simply call he operaor grab_image once wih he wo handles reurned by he wo calls o open_framegrabber: grab_image (Image0, AcqHandle0) grab_image (Image1, AcqHandle1) 3.2.3 Muliple Handles Per Board Many frame grabbers provide muliple inpu pors and hus allow o connec more han one camera o he board. Depending on he HALCON acquisiion inerface, his configuraion is accessed in differen ways which are described in his and he following secions. The sandard HALCON mehod o connec o he cameras is depiced in figure 3.2c: Each connecion ges is own handle, i.e., open_framegrabber is called once for each camera wih differen values for he parameer Por, like in he HDevelop example program soluion_guide\image_acquisiion\ muliple_pors.hdev: open_framegrabber (AcqName, 1, 1, 0, 0, 0, 0, 'defaul', -1, 'defaul', -1, \ 'defaul', 'defaul', Board0, Por0, -1, AcqHandle0) open_framegrabber (AcqName, 1, 1, 0, 0, 0, 0, 'defaul', -1, 'defaul', -1, \ 'defaul', 'defaul', Board1, Por1, -1, AcqHandle1) grab_image (Image0, AcqHandle0) grab_image (Image1, AcqHandle1) As figure 3.2c shows, you can also use muliple boards wih muliple conneced cameras. 3.2.4 Por Swiching Some image acquisiion inerfaces do no access he cameras via muliple handles, bu by swiching he inpu por dynamically (see figure 3.2d). Therefore, open_framegrabber is called only once, like in he HDevelop example program soluion_guide\image_acquisiion\por_swiching.hdev: open_framegrabber (AcqName, 1, 1, 0, 0, 0, 0, 'defaul', -1, 'defaul', -1, \ 'defaul', 'defaul', 'defaul', 0, -1, AcqHandle) Beween grabbing images you swich pors using he operaor se_framegrabber_param (see secion 4.2 on page 20 for more informaion abou his operaor): se_framegrabber_param (AcqHandle, 'por', Por0) dev_se_window (WindowHandle0) grab_image (Image0, AcqHandle) se_framegrabber_param (AcqHandle, 'por', Por1) dev_se_window (WindowHandle1) grab_image (Image1, AcqHandle)
3.3 Requesing Informaion Abou he Image Acquisiion Inerface A-15 Noe ha por swiching only works for compaible (similar) cameras because open_framegrabber is only called once, i.e., he same se of parameers values is used for all cameras. In conras, when using muliple handles as described above, you can specify differen parameer values for he individual cameras (wih some board-specific limiaions). 3.2.5 Simulaneous Grabbing (Only For Specific Inerfaces) In he configuraions described above, images were grabbed from he individual cameras by muliple calls o he operaor grab_image. In conras, some acquisiion inerfaces allow o grab images from muliple cameras wih a single call o grab_image, which hen reurns a muli-channel image (see figure 3.2e; appendix A.1 on page 51 conains more informaion abou muli-channel images). This mode is called simulaneous grabbing (or parallel grabbing); like por swiching, i only works for compaible (similar) cameras. For example, you can use his mode o grab synchronized images from a sereo camera sysem. Noe ha simulaneous grabbing is available only for very few image acquisiion inerfaces. In his mode, open_framegrabber is called only once, as can be seen in he HDevelop example program soluion_guide\image_acquisiion\simulaneous_grabbing.hdev: open_framegrabber (AcqName, 1, 1, 0, 0, 0, 0, 'defaul', -1, 'defaul', -1, \ 'defaul', 'defaul', 'defaul', 0, -1, AcqHandle)! Connecing You can check he number of reurned images (channels) using he operaor coun_channels grab_image (SimulImages, AcqHandle) coun_channels (SimulImages, num_channels) and exrac he individual images, e.g., using decompose2, decompose3 ec., depending on he number of images: if (num_channels == 2) decompose2 (SimulImages, Image0, Image1) Alernaively, you can conver he muli-channel image ino an image array using image_o_channels and hen selec he individual images via selec_obj. Noe ha some acquisiion inerfaces allow simulaneous grabbing also for muliple boards (see figure 3.2f). Please refer o secion 5.3.2 on page 38 for addiional informaion. 3.3 Requesing Informaion Abou he Image Acquisiion Inerface As menioned already, he individual HALCON acquisiion inerfaces are described in deail on HTML pages which can be found in he direcory %HALCONROOT%\doc\hml\manuals or in he HALCON folder in he Windows sar menu (if you insalled he documenaion). Anoher way o access informaion abou an image acquisiion inerface is o use he operaor info_framegrabber.
A-16 Connecing o Your Image Acquisiion Device In he HDevelop example program soluion_guide\image_acquisiion\ info_framegrabber.hdev (preconfigured for he HALCON 1394IIDC inerface, please adap he inerface name for your own image acquisiion device) his operaor is called muliple imes o query he version number of he inerface, he available devices, por numbers, camera ypes, and he defaul values for all parameers of open_framegrabber; he resul, i.e., he values displayed in he HDevelop Variable Window, is depiced in figure 3.3. info_framegrabber (AcqName, 'general', GeneralInfo, GeneralValue) info_framegrabber (AcqName, 'revision', RevisionInfo, RevisionValue) info_framegrabber (AcqName, 'info_boards', BoardsInfo, BoardsValue) info_framegrabber (AcqName, 'generic', GenericInfo, GenericValue) info_framegrabber (AcqName, 'camera_ype', CamTypeInfo, CamTypeValue) info_framegrabber (AcqName, 'defauls', DefaulsInfo, DefaulsValue) The operaor info_framegrabber can be called before acually connecing o an image acquisiion device wih open_framegrabber. The only condiion is ha he HALCON acquisiion inerface and he device driver and SDK have been insalled.
3.3 Requesing Informaion Abou he Image Acquisiion Inerface A-17 Connecing Figure 3.3: An example resul of he operaor info_framegrabber.
A-18 Connecing o Your Image Acquisiion Device
Configuring he Acquisiion A-19 Chaper 4 Configuring he Acquisiion As explained in secion 1 on page 7, he inenion of HALCON s acquisiion inerfaces is o provide he user wih a common inerface for many differen image acquisiion devices. This inerface is kep as simple as possible; as shown, you can connec o your frame grabber or camera and grab a firs image using only wo operaors. However, HALCON s second goal is o make he full funcionaliy of an image acquisiion device available o he user. As image acquisiion devices differ widely regarding he provided funcionaliy, his is a difficul ask o realize wihin a simple, common inerface. HALCON solves his problem by dividing he ask of configuring an image acquisiion device connecion ino wo pars: Those parameers which are common o mos acquisiion inerfaces (herefore called general parameers) are se when calling he operaor open_framegrabber. In conras, he funcionaliy which is no generally available can be configured by seing so-called special parameers using he operaor se_framegrabber_param. Configuring 4.1 General Parameers When opening a connecion via open_framegrabber, you can specify he following general parameers:
A-20 Configuring he Acquisiion HorizonalResoluion, VericalResoluion ImageWidh, ImageHeigh, SarRow, SarColumn Field BisPerChannel, ColorSpace Generic ExernalTrigger CameraType, Device, Por, LineIn spaial resoluion of he ransferred image in relaion o he original size (see appendix B.1 on page 55) size and upper lef corner of he ransferred image in relaion o he original size (see appendix B.1 on page 55) grabbing mode for analog cameras, e.g., inerlaced-scan, progressive-scan, field grabbing daa conained in a pixel (number of bis, number of channels, color encoding, see appendix B.2 on page 56) generic parameer wih device-specific meaning hooking he acquisiion of images o an exernal rigger signal (see also secion 5.2 on page 35) configuraion of frame grabber(s) and camera(s) from which images are o be acquired (see secion 3.1 on page 12) In secion 3.1 on page 12, we already encounered he parameers describing he frame grabber / camera configuraion. Mos of he oher parameers of open_framegrabber specify he image forma; hey are described in more deail in appendix B on page 55. The parameer ExernalTrigger acivaes a special grabbing mode which is described in deail in secion 5.2 on page 35. Noe ha when calling open_framegrabber you mus specify values for all parameers, even if your acquisiion inerface does no suppor some of hem or uses values specified in a camera configuraion file insead. To alleviae his ask, he HALCON acquisiion inerfaces provide suiable defaul values which are used if you specify defaul or -1 for sring or numeric parameers, respecively. The acually used defaul values can be queried using he operaor info_framegrabber as shown in secion 3.3 on page 15. Afer connecing o a frame grabber or camera, you can query he curren values of general parameers using he operaor ge_framegrabber_param; some inerfaces even allow o modify general parameers dynamically. Please refer o secion 4.3 on page 22 for more informaion abou hese opics. 4.2 Special Parameers Even he funcionaliy ha is no generally available for all image acquisiion devices can be accessed and configured wih a general mechanism: by seing corresponding special parameers via he operaor se_framegrabber_param. Typical parameers are, for example:
4.2 Special Parameers A-21 grab_imeou volaile coninuous_grabbing rigger_signal image_widh, image_heigh, sar_row, sar_column, generic, exernal_rigger, por imeou afer which he operaors grab_image and grab_image_async sop waiing for an image and reurn an error (see also secion 5.2.1 on page 37 and secion 6.4 on page 42) enable volaile grabbing (see also secion 5.1.3 on page 27) swich on a special acquisiion mode which is necessary for some image acquisiion devices o achieve real-ime performance (see also secion 5.1.5 on page 31) signal ype used for exernal riggering, e.g., rising or falling edge duplicaes of some of he general parameers described in secion 4.1 on page 19, allowing o modify hem dynamically, i.e., afer opening he connecion (see also secion 4.3 on page 22) Depending on he acquisiion inerface, various oher parameers may be available, which allow, e.g., o add an offse o he digiized video signal or modify he brighness or conras, o specify he exposure ime or o rigger a flash. Some acquisiion inerfaces offer special parameers for he use of line scan cameras (see also secion 6.6 on page 46), or parameers conrolling digial oupu and inpu lines. Which special parameers are provided by an acquisiion inerface is described in he already menioned online documenaion. You can also query his informaion by calling he operaor info_framegrabber as shown below; figure 4.1 depics he resul of double-clicking ParameersValue in he Variable Window afer execuing he line: info_framegrabber (AcqName, 'parameers', ParameersInfo, ParameersValue) Configuring To se a parameer, you call he operaor se_framegrabber_param, specifying he name of he parameer o se in he parameer Param and he desired value in he parameer Value. For example, in secion 3.2.4 on page 14 he following line was used o swich o por 0: se_framegrabber_param (AcqHandle, 'por', Por0) You can also se muliple parameers a once by specifying uples for Param and Value as in he following line: se_framegrabber_param (AcqHandle, ['image_widh','image_heigh'], [256, \ 256]) For all parameers which can be se wih se_framegrabber_param excep hose wih he prefix do_, you can query he curren value using he operaor ge_framegrabber_param. Some inerfaces also allow o query addiional informaion like minimum and maximum values for he parameers. In his example, an inerface is queried for he minimum and maximum gamma values:
A-22 Configuring he Acquisiion Figure 4.1: Querying available special parameers via info_framegrabber. ge_framegrabber_param (AcqHandle, 'gamma_range', GammaRange) MinGamma := GammaRange[0] MaxGamma := GammaRange[1] Thus, you can check a new brighness value agains hose boundaries before seing i: ge_framegrabber_param (AcqHandle, 'gamma', CurrenGamma) NewGamma := CurrenGamma + 1.0 if (NewGamma > MaxGamma) NewGamma := MaxGamma endif se_framegrabber_param (AcqHandle, 'gamma', NewGamma) 4.3 Fixed vs. Dynamic Parameers The disincion beween fixed and dynamic parameers is made relaing o he lifeime of a connecion o an image acquisiion device. Fixed parameers, e.g., he CameraType, are se once when opening he connecion wih open_framegrabber. In conras, hose parameers which can be modified via se_framegrabber_param during he use of he connecion are called dynamic parameers. As already noed in secion 4.2 on page 20, some image acquisiion inerfaces allow o modify general parameers like ImageWidh or ExernalTrigger dynamically via se_framegrabber_param, by providing a corresponding special parameer wih he same name bu wrien wih small leers and underscores, e.g., image_widh or exernal_rigger.
4.3 Fixed vs. Dynamic Parameers A-23 Independen of wheher a general parameer can be modified dynamically, you can query is curren value by calling he operaor ge_framegrabber_param wih is ranslaed name, i.e., capials replaced by small leers and underscores as described above. Configuring
A-24 Configuring he Acquisiion
The Various Modes of Grabbing Images A-25 Chaper 5 The Various Modes of Grabbing Images Secion 2 on page 9 showed ha grabbing images is very easy in HALCON you jus call grab_image! Bu of course here s more o image grabbing han jus o ge an image, e.g., how o assure an exac iming. This secion herefore describes more complex grabbing modes. 5.1 Real-Time Image Acquisiion As a echnical erm, he aribue real-ime means ha a process guaranees ha i mees given deadlines. Please keep in mind ha none of he sandard operaing sysems, i.e., neiher Windows nor Linux, are real-ime operaing sysems. This means ha he operaing sysem iself does no guaranee ha your applicaion will ge he necessary processing ime before is deadline expires. From he poin of view of a machine vision applicaion running under a non-real-ime operaing sysem, he mos you can do is assure ha real-ime behavior is no already prevened by he applicaion iself. In a machine vision applicaion, real-ime behavior may be required a muliple poins: Image delay: The camera mus grab he image, i.e., expose he chip, a he correc momen, i.e., while he par o be inspeced is compleely visible. Frame rae: The mos common real-ime requiremen for a machine vision applicaion is o reach frame rae, i.e., acquire and process all images he camera produces. Processing delay: The image processing iself mus complee in ime o allow a reacion o is resuls, e.g., o remove a fauly par from he conveyor bel. As his poin relaes only indirecly o he image acquisiion i is ignored in he following.! Grabbing 5.1.1 Non-Real-Time Grabbing Using grab_image Figure 5.1 shows he iming diagram for he sandard grabbing mode, i.e., if you use he operaor grab_image from wihin your applicaion. This operaor call is ranslaed by he HALCON acqui-
A-26 The Various Modes of Grabbing Images camera original frame rae original frame rae original frame rae expose expose expose expose ransfer (analog) frame grabber wai for vsync digiize wai for vsync digiize ransfer (DMA) Grab Grab IAI & SDK wai for image creae HImage wai for image creae HImage sofware applicaion grab_image delay image process grab_image delay image frame rae processing process Figure 5.1: Sandard iming using grab_image (configuraion: free-running progressive-scan camera, frame grabber wih incremenal image ransfer). siion inerface and he SDK ino he corresponding signal o he frame grabber board (marked wih Grab ). Obviously, in case of digial cameras conneced by USB 2.0, IEEE 1394 or GigE here is no acual frame grabber board; neverheless, he principles of he various grabbing modes remain he same. The frame grabber now wais for he nex image. In he example, a free-running analog progressive-scan camera is used, which produces images coninuously a a fixed frame rae; he sar of a new image is indicaed by a so-called verical sync signal. The frame grabber hen digiizes he incoming analog image signal and ransforms i ino an image marix. If a digial camera is used, he camera iself performs he digiizing and ransfers a digial signal which is hen ransformed ino an image marix by he frame grabber. The image is hen ransferred from he frame grabber ino compuer memory via he PCI bus using DMA (direc memory access). This ransfer can eiher be incremenal as depiced in figure 5.1, if he frame grabber has only a FIFO buffer, or in a single burs as depiced in figure 5.2 on page 28, if he frame grabber has a frame buffer on board. The advanage of he incremenal ransfer is ha he ransfer is concluded earlier. In conras, he burs mode is more efficien; furhermore, if he incremenal ransfer via he PCI bus canno proceed for some reason, a FIFO overflow resuls, i.e., image daa is los. Noe ha in boh modes he ransfer performance depends on wheher he PCI bus is used by oher devices as well! When he image is compleely sored in he compuer memory, he HALCON acquisiion inerface rans-
5.1 Real-Time Image Acquisiion A-27 forms i ino a HALCON image and reurns he conrol o he applicaion which processes he image and hen calls grab_image again. However, even if he processing ime is shor in relaion o he frame rae, he camera has already begun o ransfer he nex image which is herefore los ; he applicaion can herefore only process every second image. You can check his behavior using he HDevelop example program soluion_guide\ image_acquisiion\real_ime_grabbing.hdev, which deermines achievable frame raes for grabbing and processing (here: calculaing a difference image) firs separaely and hen ogeher as follows: grab_image (BackgroundImage, AcqHandle) coun_seconds (Seconds1) for i := 1 o 20 by 1 grab_image (Image, AcqHandle) sub_image (BackgroundImage, Image, DifferenceImage, 1, 128) endfor coun_seconds (Seconds2) TimeGrabImage := (Seconds2 - Seconds1) / 20 FrameRaeGrabImage := 1 / TimeGrabImage To see he non-deerminisic image delay, execue he operaor grab_image in he sep mode by pressing Sep; he execuion ime displayed in HDevelop s saus bar will range beween once and wice he original frame period. Please noe ha on Linux sysems, he ime measuremens are performed wih a lower resoluion han on Windows sysems. 5.1.2 Grabbing Wihou Delay Using Asynchronously Reseable Cameras If you use a free-running camera, he camera iself deermines he exac momen an image is acquired (exposed). This leads o a delay beween he momen you call grab_image and he acual image acquisiion (see figure 5.1 on page 26). The delay is no deerminisic, bu a leas i is limied by he frame rae; for example, if you use an NTSC camera wih a frame rae of 30 Hz, he maximum delay can be 33 milliseconds. Of course, such a delay is no accepable in an applicaion ha is o inspec pars a a high rae. The soluion is o use cameras ha allow a so-called asynchronous rese. This means ha upon a signal from he frame grabber, he camera reses he image chip and (almos) immediaely sars o expose i. Typically, such a camera does no grab images coninuously bu only on demand. An example iming diagram is shown in figure 5.2. In conras o figure 5.1, he image delay is (almos) zero. Furhermore, because he applicaion now specifies when images are o be grabbed, all images can be processed successfully; however, he achieved frame rae sill includes he processing ime and herefore may be oo low for some machine vision applicaions. Grabbing 5.1.3 Volaile Grabbing As shown in figure 5.1 on page 26, afer he image has been ransferred ino he compuer memory, he HALCON acquisiion inerface needs some ime o creae a corresponding HALCON image which is
A-28 The Various Modes of Grabbing Images original frame rae camera expose expose ransfer (analog) Expose Expose frame grabber wai for vsync digiize wai for vsync digiize ransfer (DMA) Grab Grab IAI & SDK wai for image creae HImage wai for image creae HImage sofware applicaion grab_image process grab_image process delay image = 0 frame rae processing Figure 5.2: Using an asynchronously reseable camera ogeher wih grab_image (configuraion: progressive-scan camera, frame grabber wih burs ransfer, volaile grabbing). hen reurned in he oupu parameer Image of grab_image. Mos of his ime is needed o copy he image daa from he buffer which is he desinaion of he DMA ino a newly allocaed area. You can swich off he copying by using he so-called volaile grabbing, which can be enabled via he operaor se_framegrabber_param (parameer volaile ): se_framegrabber_param (AcqHandle, 'volaile', 'enable') Then, he ime needed by he image acquisiion inerface o creae he HALCON image is significanly reduced as visualized in figure 5.2. Noe ha usually volaile grabbing is only suppored for gray value images!! The drawback of volaile grabbing is ha grabbed images are overwrien by subsequen grabs. To be more exac, he overwriing depends on he number of image buffers allocaed by he acquisiion inerface or SDK. Typically, a leas wo buffers exis; herefore, you can safely process an image even if he nex image is already being grabbed as in figure 5.4 on page 32. Some acquisiion inerfaces allow o use more han wo buffers, and even o selec heir number dynamically via se_framegrabber_param (parameer num_buffers ). Please noe ha volaile grabbing is no really volaile wihin HDevelop, i.e., images are copied nev-
5.1 Real-Time Image Acquisiion A-29 erheless, oherwise here would be scenarios when HDevelop would crash. Thus, o experimen wih volaile grabbing using he HDevelop example program soluion_guide\ image_acquisiion\volaile_grabbing.hdev, you mus expor i o a programming language or use HDevEngine. Afer grabbing a firs image and displaying i via grab_image (FirsImage, AcqHandle) dev_open_window (0, 0, Widh / 2, Heigh / 2, 'black', FirsWindow) dev_display (FirsImage) change he scene and grab a second image which is displayed in an individual window: grab_image (SecondImage, AcqHandle) dev_open_window (0, Widh / 2 + 8, Widh / 2, Heigh / 2, 'black', \ SecondWindow) dev_display (SecondImage) Now, images are grabbed in a loop and displayed in a hird window. The wo oher images are also displayed each ime. If you change he scene before each grab you can see how he firs wo images are overwrien in urn, depending on he number of buffers. dev_open_window (Heigh / 2 + 66, Widh / 4 + 4, Widh / 2, Heigh / 2, \ 'black', ThirdWindow) for i := 1 o 10 by 1 grab_image (CurrenImage, AcqHandle) dev_se_window (ThirdWindow) dev_display (CurrenImage) dev_se_window (FirsWindow) dev_display (FirsImage) dev_se_window (SecondWindow) dev_display (SecondImage) endfor Grabbing 5.1.4 Real-Time Grabbing Using grab_image_async The main problem wih he iming using grab_image is ha he wo processes of image grabbing and image processing run sequenially, i.e., one afer he oher. This means ha he ime needed for processing he image is included in he resuling frame rae, wih he effec ha he frame rae provided by he camera canno be reached by definiion. This problem can be solved by using he operaor grab_image_async. Here, he wo processes are decoupled and can run asynchronously, i.e., an image can be processed while he nex image is already being grabbed. Figure 5.3 shows a corresponding iming diagram: The firs call o grab_image_async is processed similar o grab_image (compare figure 5.1 on page 26). The difference becomes apparen afer he ransfer of he image ino compuer memory: Almos immediaely afer receiving he image, he acquisiion inerface auomaically commands he frame grabber o acquire a new image. Thus, he!
A-30 The Various Modes of Grabbing Images original frame rae original frame rae original frame rae camera expose expose expose expose ransfer (analog) frame wai for vsync wai for vsync wai for vsync digiize digiize digiize grabber ransfer (DMA) Grab Grab Grab Grab IAI & SDK wai for image creae HImage wai for image creae HImage wai for image creae HImage sofware applicaion grab_image_async grab_image_async grab_image_async process process process delay image delay image "negaive" frame rae processing Figure 5.3: Grabbing and processing in parallel using grab_image_async. nex image is grabbed while he applicaion processes he previous image. Afer he processing, he applicaion calls grab_image_async again, which wais unil he already running image acquisiion is finished. Thus, he full frame rae is now reached. Noe ha some frame grabbers fail o reach he full frame rae even wih grab_image_async; secion 5.1.5 on page 31 shows how o solve his problem. In he HDevelop example program soluion_guide\image_acquisiion\ real_ime_grabbing.hdev, which was already described in secion 5.1.1 on page 25, he reached frame rae for asynchronous processing is deermined as follows: grab_image (BackgroundImage, AcqHandle) coun_seconds (Seconds1) for i := 1 o 20 by 1 grab_image_async (Image, AcqHandle, -1) sub_image (BackgroundImage, Image, DifferenceImage, 1, 128) endfor coun_seconds (Seconds2) TimeGrabImageAsync := (Seconds2 - Seconds1) / 20 FrameRaeGrabImageAsync := 1 / TimeGrabImageAsync As can be seen in figure 5.3, he firs call o grab_image_async has a slighly differen effec han he following ones, as i also riggers he firs grab command o he frame grabber. As an alernaive,
5.1 Real-Time Image Acquisiion A-31 you can use he operaor grab_image_sar which jus riggers he grab command; hen, he firs call o grab_image_async behaves as he oher ones. This is visualized, e.g., in figure 5.4; as you can see, he advanage of his mehod is ha he applicaion can perform some processing before calling grab_image_async. Noe ha you can use grab_image_sar in combinaion wih he special parameer sar_async_afer_grab_async o specify exacly when a grab command is riggered during asynchronous grabbing. In secion 5.3.1 on page 37, his is used for asynchronous grabbing wih muliple cameras. In he example, he processing was assumed o be faser han he acquisiion. If his is no he case, he image will already be ready when he nex call o grab_image_async arrives. In his case, you can specify how old he image is allowed o be using he parameer MaxDelay. Please refer o secion 5.1.7 on page 33 for deails. Please noe ha when using grab_image_async i is no obvious anymore which image is reurned by he operaor call, because he call is decoupled from he command o he frame grabber! In conras o grab_image, which always riggers he acquisiion of a new image, grab_image_async ypically reurns an image which has been exposed before he operaor was called, i.e., he image delay is negaive (see figure 5.3)! Keep his effec in mind when changing parameers dynamically; conrary o inuiion, he change will no affec he image reurned by he nex call of grab_image_async bu by he following ones! Anoher problem appears when swiching dynamically beween cameras (see secion 5.3.1 on page 37). 5.1.5 Coninuous Grabbing For some frame grabbers, grab_image_async fails o reach he frame rae because he grab command o he frame grabber comes oo lae, i.e., afer he camera has already sared o ransfer he nex image (see figure 5.4a). As a soluion o his problem, some acquisiion inerfaces provide he so-called coninuous grabbing mode, which can be enabled only via he operaor se_framegrabber_param (parameer coninuous_grabbing ): se_framegrabber_param (AcqHandle, 'coninuous_grabbing', 'enable') Grabbing In his mode, he frame grabber reads images from a free-running camera coninuously and ransfers hem ino compuer memory as depiced in figure 5.4b. Thus, he frame rae is reached. If your frame grabber suppors coninuous grabbing, you can es his effec in he example program soluion_guide\image_acquisiion\real_ime_grabbing.hdev, which was already described in he previous secions; he program measures he achievable frame rae for grab_image_async wihou and wih coninuous grabbing. We recommend o use coninuous grabbing only if you wan o process every image; oherwise, images are ransmied over he PCI bus unnecessarily, hereby perhaps blocking oher PCI ransfers. Noe ha some acquisiion inerfaces provide addiional funcionaliy in he coninuous grabbing mode. Please refer o he corresponding documenaion for more informaion.
A-32 The Various Modes of Grabbing Images a) original frame rae original frame rae original frame rae camera expose expose expose expose ransfer (analog) frame wai for vsync digiize wai for vsync digiize grabber ransfer (DMA) Grab Grab Grab IAI & SDK wai for image creae HImage wai for image creae HImage sofware applicaion ec grab_image_async process grab_image_async process grab_image_sar frame rae processing b) ransfer (analog) frame digiize digiize digiize grabber ransfer (DMA) Grab Grab Grab Grab IAI & SDK wai for image creae HImage wai for image creae HImage wai for image creae HImage sofware applicaion ec grab_image_async grab_image_async grab_image_async process process process grab_image_sar se coninuous_grabbing frame rae processing Figure 5.4: a) grab_image_async fails o reach frame rae; b) problem solved using coninuous grabbing.
5.1 Real-Time Image Acquisiion A-33 5.1.6 Using grab_image_async Togeher Wih Asynchronously Reseable Cameras As described in secion 5.1.2 on page 27, you can acquire images wihou delay by using an asynchronously reseable camera. Figure 5.5 shows he resuling iming when using such a camera ogeher wih grab_image_async. When comparing he diagram o he one in figure 5.2 on page 28, you can see ha a higher frame rae can now be reached, because he processing ime is no included anymore. original frame rae camera expose expose ransfer (analog) frame grabber Expose wai for vsync digiize Expose wai for vsync digiize ransfer (DMA) Grab Grab Grab IAI & SDK wai for image creae HImage wai for image creae HImage sofware applicaion grab_image_async process grab_image_async process delay image = 0 frame rae processing Figure 5.5: Using an asynchronously reseable camera ogeher wih grab_image_async (configuraion as in figure 5.2 on page 28. Grabbing 5.1.7 Specifying a Maximum Delay In conras o grab_image, he operaor grab_image_async has an addiional parameer MaxDelay, which les you specify how old an already grabbed image may be in order o be acceped. Figure 5.6 visualizes he effec of his parameer. There are wo cases o disinguish: If he call o grab_image_async arrives before he nex image has been grabbed (firs call in he example), he parameer has no effec. However, if an image has been grabbed already (second and hird call in he example), he elapsed ime since he las grab command o he frame grabber is compared o MaxDelay. If i is smaller (second call in he example), he image is acceped; oherwise (hird call), a new image is grabbed.
A-34 The Various Modes of Grabbing Images camera expose expose expose expose ransfer (analog) frame grabber digiize digiize digiize digiize ransfer (DMA) IAI & SDK sofware applicaion Grab wai for image Grab Grab > MaxDelay? NO > MaxDelay? YES creae HImage creae HImage wai for image process process process process grab_image_async Grab Figure 5.6: Specifying a maximum delay for grab_image_async (using coninuous grabbing). Please noe ha he delay is no measured saring from he momen he image is exposed, as you migh perhaps expec! Currenly, only a few device SDKs provide his informaion; herefore, he las grab command from he inerface o he frame grabber is used as he saring poin insead. Noe ha he parameer MaxDelay in he operaor grab_image_async has a compleely differen meaning han he addiional parameer grab_imeou : Using grab_imeou you can se a imeou for he acquisiion process, i.e., he grab operaors reurn afer a cerain ime period wih an appropriae error.
5.2 Using an Exernal Trigger A-35 5.2 Using an Exernal Trigger In he previous secion, he sofware performing he machine vision ask decided when o acquire an image (sofware rigger). In indusrial applicaions, however, he momen for image acquisiion is ypically specified exernally by he process iself, e.g., in form of a hardware rigger signal indicaing he presence of an objec o be inspeced. Mos image acquisiion devices are herefore equipped wih a leas one inpu line for such signals, which are called exernal riggers. From HALCON s poin of view, exernal riggers are deal wih by he image acquisiion device, he only hing o do is o inform he device o use he rigger. You can do his simply by seing he parameer ExernalTrigger of open_framegrabber o rue. Some acquisiion inerfaces also allow o enable or disable he rigger dynamically using he operaor se_framegrabber_param (parameer exernal_rigger ). Figure 5.7a shows he iming diagram when using an exernal rigger ogeher wih grab_image and a free-running camera. Afer he call o grab_image, he image acquisiion device wais for he rigger signal. When i appears, he procedure described in he previous secion follows: The device wais for he nex image, digiizes i, and ransfers i ino compuer memory; hen, he HALCON acquisiion inerface ransforms i ino a HALCON image and reurns he conrol o he applicaion which processes he image and hen calls grab_image again, which causes he image acquisiion device o wai for he nex rigger signal. The (bad) example in figure 5.7a was chosen on purpose o show an unsuiable configuraion for using an exernal rigger: Firs of all, because of he free-running camera here is a non-deerminisic delay beween he arrival of he rigger signal and he exposure of he image, which may mean ha he objec o be inspeced is no compleely visible anymore. Secondly, because grab_image is used, rigger signals which arrive while he applicaion is processing an image are los. Boh problems can easily be solved by using an asynchronously reseable camera ogeher wih he operaor grab_image_async as depiced in figure 5.7b. The C++ example program examples\soluion_guide\image_acquisiion\cpp\ error_handling_imeou.cpp shows how simple i is o use an exernal rigger: The connecion is opened wih ExernalTrigger se o rue : HFramegrabber acqdevice; acqdevice.openframegrabber(acqname, 1, 1, 0, 0, 0, 0, "defaul", -1, "gray", -1, "rue", "defaul", "defaul", -1, -1); Grabbing Then, images are grabbed: HImage image; do { image = acqdevice.grabimageasync(-1); } while (buon == 0); The example conains a cusomized error handler which checks wheher here is an exernal rigger; his par is described in deail in secion 6.4.3 on page 45.
A-36 The Various Modes of Grabbing Images a) camera expose expose expose expose ransfer (analog) frame grabber wai for rigger wai for vsync digiize wai for rigger ransfer (DMA) Grab Grab IAI & SDK wai for image creae HImage wai for image sofware applicaion rigger grab_image Trigger process Trigger grab_image Trigger delay image b) camera expose expose expose ransfer (analog) frame grabber wai for rigger Expose wai for vsync digiize Expose wai for vsync digiize Expose wai for vsync digiize Expose ransfer (DMA) Grab Grab Grab Grab IAI & SDK wai for image creae HImage wai for image creae HImage wai for image sofware ec applicaion rigger grab_image_sar grab_image_async Trigger delay image = 0 Trigger delay image = 0 process grab_image_async Trigger delay image = 0 process grab_image_async Trigger Figure 5.7: Using an exernal rigger ogeher wih: a) free-running camera and grab_image; b) asynchronously reseable camera and grab_image_async.
5.3 Acquiring Images From Muliple Cameras A-37 5.2.1 Special Parameers for Exernal Triggers Mos image acquisiion inerfaces allow o furher configure he use of exernal riggering via he operaor se_framegrabber_param. As menioned in secion 4.2 on page 20, some inerfaces allow o enable and disable he exernal rigger dynamically via he parameer exernal_rigger. Anoher useful parameer is grab_imeou, which ses a imeou for he acquisiion process (some inerfaces provide an addiional parameer rigger_imeou jus for riggered grabbing). Wihou such a imeou, he applicaion would hang if for some reason no rigger signal arrives. In conras, if a imeou is specified, he operaors grab_image and grab_image_async only wai he specified ime and hen reurn an error code or raise an excepion, depending on he programming language used. Secion 6.4 on page 42 shows how o handle such errors. Oher parameers allow o furher specify he form of he rigger signal ( rigger_signal ), e.g., wheher he falling or he rising edge is used as he rigger, selec beween muliple rigger inpu lines, or even filer rigger signals. Some acquisiion inerfaces also allow o influence he exposure via he rigger signal. 5.3 Acquiring Images From Muliple Cameras The iming diagrams shown in he previous secions depiced he case of a single camera. Below we discuss some issues which arise when acquiring images from muliple cameras (see secion 3.2 on page 12 for possible configuraions). 5.3.1 Dynamic Por Swiching and Asynchronous Grabbing If you swich dynamically beween muliple cameras conneced o a single board as described in secion 3.2.4 on page 14, you mus be careful when using grab_image_async: By defaul, he acquisiion inerface commands he frame grabber board o grab he nex image auomaically afer i received he curren image bu before he nex call of grab_image_async! If you swiched o anoher camera before his call, he frame grabber migh already be busy grabbing an image from he firs camera. Some acquisiion inerfaces solve his problem by providing he parameer sar_async_afer_grab_async for he operaor se_framegrabber_param which allows o disable he auomaic grab command o he frame grabber board. Grabbing se_framegrabber_param (AcqHandle, 'sar_async_afer_grab_async', \ 'disable') Now, all grab commands mus be issued explicily wih he operaor grab_image_sar. The following code shows how o swich beween cameras in a loop:
A-38 The Various Modes of Grabbing Images * swich o camera 0 and grab a firs image se_framegrabber_param (AcqHandle, 'por', Por0) grab_image_sar (AcqHandle, -1) dev_se_window (WindowHandle0) grab_image_async (Image0, AcqHandle, -1) dev_display (Image0) while (1) * swich o camera 1 and sar a new grab se_framegrabber_param (AcqHandle, 'por', Por1) grab_image_sar (AcqHandle, -1) * meanwhile, process image 0 * hen ge image from camera 1 dev_se_window (WindowHandle1) grab_image_async (Image1, AcqHandle, -1) dev_display (Image1) * swich o camera 0 and sar a new grab se_framegrabber_param (AcqHandle, 'por', Por0) grab_image_sar (AcqHandle, -1) * meanwhile, process image 1 * hen ge image from camera 0 dev_se_window (WindowHandle0) grab_image_async (Image0, AcqHandle, -1) dev_display (Image0) endwhile 5.3.2 Simulaneous Grabbing Some image acquisiion inerfaces provide special funcionaliy o grab images simulaneously from muliple (synchronized) cameras. Typically, he cameras are conneced o a single frame grabber board; some inerfaces also allow o grab simulaneously from cameras conneced o muliple boards. As described in secion 3.2.5 on page 15, he images are grabbed by a single call o grab_image or grab_image_async, which reurn hem in form of a muli-channel image. Depending on he acquisiion inerface, i may be necessary o swich on he simulaneous grabbing via he operaor se_framegrabber_param. Please keep in mind ha even if a HALCON acquisiion inerface suppors simulaneous grabbing, his migh no be rue for every frame grabber board he inerface suppors! In order o grab muliple images simulaneously, a frame grabber board mus be equipped wih muliple grabbing unis ; for example, an analog frame grabber board mus be equipped wih muliple A/D converers. Please check his in he documenaion of your frame grabber board. Even if a HALCON acquisiion inerface does no provide he special simulaneous grabbing mode, you can realize a similar behavior manually, e.g., by connecing each (asynchronously reseable) camera o a single frame grabber board and hen using a common exernal rigger signal o synchronize he grabbing.
Miscellaneous A-39 Chaper 6 Miscellaneous 6.1 Acquiring Images From Sandardized Image Acquisiion Devices Differen commiees have developed sandards for image acquisiion inerfaces. HALCON suppors several of hese sandards and provides he corresponding inerfaces. In paricular he sandards GenI- Cam, GigE Vision, OpenNI, Video4Linux, DCAM, DirecFile, DirecShow, and Twain are suppored. A sandardized image acquisiion inerface is suiable for differen image acquisiion devices ha do no necessarily have he same se of parameers o adjus during he image acquisiion. For some inerfaces, e.g, he 1394IIDC inerface ha follows he DCAM sandard, a fixed se of parameers is available and i can be queried for a specific device, which of hese parameers are suppored by he device. For oher inerfaces arbirary parameers are allowed. Such inerfaces are called generic. Examples for generic inerfaces are he GenICamTL inerface, which follows he GenTL module of he GenICam sandard, and he GigEVision inerface ha follows he GigE Vision sandard. As he parameers for a generic inerface may be arbirary, he informaion abou he device-specific parameers is no provided wih he descripion of he inerface bu mus be queried from he device. For example, if he inerface follows he GenICam sandard, he needed informaion is available in form of an xml file ha is ypically sored on he device. When calling open_framegrabber, he informaion is read auomaically. The individual parameer names ha are available for he specific device can hen be queried wih he operaor ge_framegrabber_param seing Param o available_param_names. For he reurned parameer names furher informaion can be queried. For example, you can query he following parameer values for each parameer name (replace name by he specific parameer name): name_range : name_values : name_descripion : range for he allowed numerical values, in paricular, he minimum allowed value, he maximum allowed value, he incremen value, and he defaul value. available sring values. shor descripion of he parameer, i.e., a kind of a ool ip. Miscellaneous Addiionally, parameer values can be queried ha are suppored only for some inerfaces. The following parameer values are very common and are used, e.g., by he GenICamTL and he GigEVision inerface:
A-40 Miscellaneous name_access : name_caegory : name_visibiliy : access ype, i.e., informaion o which degree he parameer can be accessed, i.e., can i only be read or also be wrien? informaion o which hemaic caegory of parameers he parameer belongs. informaion o which group of users he parameer is helpful, i.e., should a beginner ry o adjus i, or is i more suiable for expers or even only for gurus? The HDevelop example program hdevelop\image\acquisiion\gigevision_parameers.hdev shows how o query parameers of a GigEVision inerface. In paricular, afer opening he connecion o he specific device wih open_framegrabber, he uple of available device-specific parameer names is queried using he parameer available_param_names wihin ge_framegrabber_param. Then, for each of he available parameers, he access ype is deermined. If he parameer is readable, is value as well as he range for he numerical values or he available sring values are queried. open_framegrabber (InerfaceName, 0, 0, 0, 0, 0, 0, 'defaul', -1, \ 'defaul', GenericParam, 'false', 'defaul', Device, 0, \ -1, AcqHandle) ge_framegrabber_param (AcqHandle, 'available_param_names', ParameerValues) for Index := 0 o ParameerValues - 1 by 1 ge_framegrabber_param (AcqHandle, ParameerValues[Index] + '_access', \ ParameerAccess) * If he parameer is readable, query furher informaion ge_framegrabber_param (AcqHandle, ParameerValues[Index], ParameerValue) * Noe ha only one ou of he wo queries for '_range' and '_values' * is available for each parameer ge_framegrabber_param (AcqHandle, ParameerValues[Index] + '_range', \ ParameerValuesOu) ge_framegrabber_param (AcqHandle, ParameerValues[Index] + '_values', \ ParameerValuesOu) endfor close_framegrabber (AcqHandle) Noe ha for generic image acquisiion inerfaces differen ypes of parameers are used: he parameers specific for he image acquisiion device, he parameers provided by HALCON, and he parameers provided by he driver. The parameers provided by HALCON are explained wih he descripion of he inerface. All oher parameers are queried wih ge_framegrabber_param seing Param o available_param_names as is described above. 6.2 Acquiring Images From Unsuppored Image Acquisiion Devices If you wan o use an image acquisiion device ha is currenly no suppored by HALCON, i.e., for which no HALCON inerface exiss, here exis wo principal ways: Firs, you can creae your own HALCON acquisiion inerface; how o do his is described in deail in he Image Acquisiion Inerface Programmer s Manual.
6.2 Acquiring Images From Unsuppored Image Acquisiion Devices A-41 As a very easy o use alernaive, you can pass exernally creaed images, i.e., he raw image marix, o HALCON using he operaors gen_image1, gen_image3, gen_image1_exern, or gen_image3_exern, which creae a corresponding HALCON image. The main difference beween he operaors gen_image1 and gen_image1_exern and heir varians for hree-channel images is ha he former copies he image marix when creaing he HALCON image, whereas he laer doesn, which is useful if you wan o realize volaile grabbing as described in secion 5.1.3 on page 27. The C example program examples\soluion_guide\image_acquisiion\c\ use_exern_image.c shows how o use he operaor gen_image1_exern o pass sandard gray value images o HALCON. In his case, he image marix consiss of 8 bi pixels (byes), which can be represened by he daa ype unsigned char. A he beginning, he program calls a procedure which allocaes memory for he images o be grabbed ; in a real applicaion his corresponds o he image buffer(s) used by he image acquisiion device SDK. unsigned char *image_marix_pr; Hlong widh, heigh; IniializeBuffer(&image_marix_pr, &widh, &heigh); The example program simulaes he grabbing of images wih a procedure which reads images from an image sequence and copies hem ino he image buffer. Then, he conen of he image buffer is ransformed ino a HALCON image (ype bye) via gen_image1_exern. The parameer ClearProc is se o 0 o signal ha he program iself akes care of freeing he memory. The creaed HALCON image is hen displayed. The loop can be exied by clicking ino he HALCON window wih any mouse buon. Hobjec long image; window_id; open_window (0, 0, widh, heigh, 0, "visible", "", (Hlong*)&window_id); while (!BuonPressed(window_id)) { MyGrabImage((cons unsigned char **) &image_marix_pr); gen_image1_exern(&image, "bye", (Hlong)widh, (Hlong)heigh, (long) image_marix_pr, (long) 0); } disp_obj(image, window_id); If your image acquisiion device supplies images wih more han 8 bi pixels, you mus adap boh he daa ype for he image marix and he ype of he creaed HALCON image (parameer Type of gen_image1_exern). In case of color images HALCON expecs he image daa in form of hree separae image marices. Correspondingly, you can creae a HALCON image by calling he operaors gen_image3 or gen_image3_exern wih he hree poiners o he marices. Please refer o appendix A on page 51 for more informaion abou HALCON images in general. Miscellaneous
A-42 Miscellaneous 6.3 Grabbing Image Arrays and Preprocessed Image Daa The previous secions described in deail how o acquire images using grab_image or grab_image_async. Wih hese operaors images can be grabbed and, if an image consiss of several channels, he image is grabbed as a muli-channel image (see also appendix A.1 on page 51). For he ypical color image, his approach is suied very well, as muli-channel images can be furher processed convenienly by many HALCON operaors. Bu someimes, e.g., if he grabbed daa describes 3D daa raher han a color image, he images are needed in an array insead of a muli-channel image. Then, you can eiher grab he image as a muli-channel image, access he individual channels wih he operaor access_channel, and sore he images of he individual channels in an array. Or, which is more comforable, you can call he operaor grab_daa or grab_daa_async insead. Boh operaors immedialey reurn he grabbed images in an array. Furhermore, hey provide he possibiliy o addiionally grab preprocessed image daa like regions, conours, or conrol daa. Noe ha grab_daa and grab_daa_async are no available for all image acquisiion inerfaces. Typically, hey are suppored by hose inerfaces ha acquire 3D daa or ha allow a preprocessing in he camera or he framegrabber. For example, he HDevelop example program hdevelop\image\ Acquisiion\swissranger_simple.hdev shows how o use grab_daa o access an array of images from a SwissRanger inerface ha conains amongs ohers he X, Y, and Z images needed o build a 3D objec model. for i := 1 o 100 by 1 grab_daa (ImageDaa, Region, Conours, AcqHandle, Daa) coun_obj (ImageDaa, NumImageDaa) selec_obj (ImageDaa, ImageX, 1) selec_obj (ImageDaa, ImageY, 2) selec_obj (ImageDaa, ImageZ, 3) selec_obj (ImageDaa, DisanceImage, 4) selec_obj (ImageDaa, AmpliudeImage, 5) if (NumImageDaa > 5) selec_obj (ImageDaa, ConfidenceImage, 6) endif endfor xyz_o_objec_model_3d (ImageX, ImageY, ImageZ, ObjecModel3DID) 6.4 Error Handling Jus as he HALCON acquisiion inerfaces encapsulae he communicaion wih an image acquisiion device, hey also encapsulae occurring errors wihin he HALCON error handling mechanism. How o cach and reac o hese errors is described below for HDevelop programs and also for programs using HALCON s programming language inerfaces. Some HALCON acquisiion inerfaces provide special parameers for se_framegrabber_param which are relaed o error handling. The mos commonly used one is he parameer grab_imeou which specifies when he image acquisiion device should qui waiing for an image. The examples described in he following secions show how o handle he corresponding HALCON error.
6.4 Error Handling A-43 Figure 6.1: Popup dialog in HDevelop signaling a imeou. Noe ha all example programs enable he signaling of low level errors via he operaor se_sysem, e.g., in HDevelop synax via se_sysem ('do_low_error', 'rue') In his mode, low level errors occurring in he image acquisiion device SDK (or in he HALCON acquisiion inerface) are signaled by a message box. 6.4.1 Error Handling in HDevelop The HDevelop example soluion_guide\image_acquisiion\error_handling_imeou.hdev shows how o handle HALCON errors in an HDevelop program. To provoke an error, open_framegrabber is called wih ExernalTrigger = rue. If here is no rigger, a call o grab_image resuls in a imeou; HDevelop reacs o his error wih he popup dialog shown in figure 6.1 (provided ha he display of low level error message boxes is acivaed via he Preferences dialog, oherwise he message is only displayed in he Oupu Console of he Window menu) and sops he execuion of he program. open_framegrabber (AcqName, 1, 1, 0, 0, 0, 0, 'defaul', -1, 'defaul', -1, \ 'rue', 'defaul', 'defaul', -1, -1, AcqHandle) se_framegrabber_param (AcqHandle, 'grab_imeou', 2000) grab_image (Image, AcqHandle) HALCON les you modify he reacion o an error wih he operaor se_check (in HDevelop: dev_se_check). If you se i o give_error, he program does no sop in case of an error bu only sores is cause in form of an error code. To access his error code in HDevelop, you mus define a corresponding variable using he operaor dev_error_var. Noe ha his variable is updaed afer each operaor call; o check he resul of a single operaor we herefore recommend o swich back o he sandard error handling mode direcly afer he operaor call as in he following lines: Miscellaneous dev_error_var (ErrorNum, 1) dev_se_check ('~give_error') grab_image (Image, AcqHandle) dev_error_var (ErrorNum, 0) dev_se_check ('give_error')
A-44 Miscellaneous To check wheher a imeou occurred, you compare he error variable wih he code signaling a imeou (5322); a lis of error codes relaing o image acquisiion can be found in he Image Acquisiion Inerface Programmer s Manual, appendix F on page 93. In he example, he imeou is handled by disabling he exernal rigger mode via he operaor se_framegrabber_param (parameer exernal_rigger ). Then, he call o grab_image is esed again. if (ErrorNum == 5322) se_framegrabber_param (AcqHandle, 'exernal_rigger', 'false') dev_error_var (ErrorNum, 1) dev_se_check ('~give_error') grab_image (Image, AcqHandle) dev_error_var (ErrorNum, 0) dev_se_check ('give_error') endif Now, he error variable should conain he value 2 signaling ha he operaor call succeeded; for his value, HDevelop provides he consan H_MSG_TRUE. If you ge anoher error code, he program accesses he corresponding error ex using he operaor ge_error_ex. if (ErrorNum!= H_MSG_TRUE) ge_error_ex (ErrorNum, ErrorTex) endif If your image acquisiion inerface does no provide he parameer exernal_rigger, you can realize a similar behavior by closing he connecion and hen opening i again wih ExernalTrigger se o false. 6.4.2 Error Handling Using HALCON/C The mechanism for error handling in a program based on HALCON/C is similar o he one in HDevelop; in fac, i is even simpler, because each operaor auomaically reurns is error code. However, if a HALCON error occurs in a C program, he defaul error handling mode causes he program o abor. The C example program examples\soluion_guide\image_acquisiion\c\ error_handling_imeou.c performs he same ask as he HDevelop program in he previous secion; if he call o grab_image succeeds, he program grabs and displays images in a loop, which can be exied by clicking ino he window. The following lines show how o es wheher a imeou occurred: se_check ("~give_error"); error_num = grab_image (&image, acqhandle); se_check ("give_error"); swich (error_num) { case H_ERR_FGTIMEOUT: As you see, in a C program you can use predefined consans for he error codes (see he Image Acquisiion Inerface Programmer s Manual, appendix F on page 93, for a lis of image acquisiion error codes and heir corresponding consans).
6.4 Error Handling A-45 6.4.3 Error Handling Using HALCON/C++ If your applicaion is based on HALCON/C++, an excepion handling mechanism is provided based on he class HExcepion, which is described in he Programmer s Guide, secion 5.3 on page 45. Whenever a HALCON error occurs, an insance of his class is creaed. The main idea is ha you can specify a procedure which is hen called auomaically wih he creaed insance of HExcepion as a parameer. How o use his mechanism is explained in he C++ example program examples\soluion_guide\image_acquisiion\cpp\ error_handling_imeou.cpp, which performs he same ask as he examples in he previous secions. In he example program examples\soluion_guide\image_acquisiion\cpp\ error_handling_imeou.cpp, he procedure which is o be called upon error is very simple: I jus raises a sandard C++ excepion wih he insance of HExcepion as a parameer. You reac o a imeou wih he following lines: ry { image = acqdevice.grabimage(); } cach (HExcepion &excep) { if (excep.errorcode() == H_ERR_FGTIMEOUT) { acqdevice.seframegrabberparam("exernal_rigger", "false"); As already noed, if your image acquisiion inerface does no provide he parameer exernal_rigger, you can realize a similar behavior by closing he connecion and hen opening i again wih ExernalTrigger se o false : if (excep.err == H_ERR_FGTIMEOUT) { acqdevice.openframegrabber(acqname, 1, 1, 0, 0, 0, 0, "defaul", -1, "gray", -1, "false", "defaul", "defaul", -1, -1); Noe ha when calling OpenFramegrabber via he class HFramegrabber as above, he operaor checks wheher i is called wih an already opened connecion and auomaically closes i before opening i wih he new parameers. 6.4.4 Error Handling Using HALCON/COM Miscellaneous For error handling wih HALCON/COM please refer o he Programmer s Guide, secion 19.6 on page 175.
A-46 Miscellaneous 6.4.5 Error Handling Using HALCON/.NET For error handling wih HALCON/.NET (e.g., in C# or Visual Basic.NET applicaions) please refer o he Programmer s Guide, secion 16.8 on page 147. 6.5 Callback Funcions! Wih callbacks HALCON applicaions can be noified of occurences ha are defined by differen callback ypes, e.g., if he exposure has finished or he ransfer beween camera and compuer is complee. Callbacks are available only for specific image acquisiion inerfaces or devices and are no available for HDevelop programs bu only for he programming languages suppored by HALCON! In pracice, firs a user-specific callback funcion mus be wrien ha will be called a he occurence defined by he specific callback ype. Noe ha he funcion mus be wrien in he seleced programming language, i.e., if you use HALCON/C++, he callback funcion mus be implemened in HALCON/C++, oo. The funcion mus provide he following parameers: he handle o he image acquisiion device, a poiner o inerface-specific conex daa, and a poiner o user-specific conex daa. The specific signaure is described in deail wih he operaor se_framegrabber_callback. This operaor is hen used o regiser he callback funcion in HALCON. There, he handle o he image acquisiion inerface and he poiner o he opional user-specific daa mus be specified. Addiionally, he specific callback ype mus be se. Noe ha no all image acquisiion inerfaces suppor callbacks and he callback ypes vary beween he inerfaces ha do suppor hem. To check if callbacks are suppored by your inerface and o query he specific callback ypes ha are available for i, you can call ge_framegrabber_param seing he parameer Param o available_callback_ypes. Wih ge_framegrabber_callback you can query he callback funcion and he poiner o he user-specific daa se for a specific callback ype and image acquisiion inerface. When implemening he user-specific callback funcion, you should ake care ha is execuion ime is as shor as possible, because, if he execuion of he user-specific callback funcion akes oo long, he sysem will slow down or he occurence of furher user-specific callbacks migh be los. Which case applies depends on he way he inerface inernally handles he synchronizaion of he callback process. In paricular, he synchronizaion can be based on inernally used callbacks or on a mechanism ha uses so-called evens. In he firs case, he user-specific callback funcion is acivaed by an inernally used callback funcion ha wais for he user-specific callback funcion o finish before he nex callback ype is processed. This process may slow down he frame rae if he user-specific callback funcion is very complex. In he second case, he inerfaces use evens insead of an inernally used callback funcion o acivae he user-specific callback funcion. Then, he process does no wai for he user-specific callback funcion o finish before i proceeds. Insead, i wais a fixed ime afer acivaing he userspecific callback funcion and hen proceeds auomaically. This waiing ime canno be conrolled by he user and hus, i migh happen for very complex user-specific callback funcions ha by he ime an even ries o acivae he user-specific callback funcion, he funcion is sill busy and he even is los. 6.6 Line Scan Cameras From he poin of view of HALCON here is no difference beween area and line scan cameras: Boh acquire images of a cerain widh and heigh; wheher he heigh is 1, i.e., a single line, or larger does no
6.6 Line Scan Cameras A-47 maer. In fac, in many line scan applicaions he image acquisiion device combines muliple acquired lines o form a so-called page which furher lessens he difference beween he wo camera ypes. The main problem is herefore wheher your frame grabber suppors line scan cameras. If yes, you can acquire images from i via HALCON exacly as from an area scan camera. Wih he parameer ImageHeigh of he operaor open_framegrabber you can someimes specify he heigh of he page; ypically, his informaion is se in he camera configuraion file. Some HALCON acquisiion inerfaces allow o furher configure he acquisiion mode via he operaor se_framegrabber_param. The images acquired from a line scan camera can hen be processed jus like images from area scan cameras. However, line scan images ofen pose an addiional problem: The objecs o inspec may be spread over muliple images (pages). To solve his problem, HALCON provides special operaors: ile_images allows o merge images ino a larger image, merge_regions_line_scan and merge_con_line_scan_xld allow o merge he (inermediae) processing resuls of subsequen images. How o use hese operaors is explained in he HDevelop example program soluion_guide\ image_acquisiion\line_scan.hdev. The program is based on an image file sequence which is read using he HALCON virual acquisiion inerface File; he ask is o exrac paper clips and calculae heir orienaion. Furhermore, he gray values in a recangle surrounding each clip are deermined. An imporan parameer for he merging is over how many images an objec can be spread. In he example, a clip can be spread over 4 images: MaxImagesRegions := 4 The coninuous processing is realized by a simple loop: A each ieraion, a new image is grabbed, and he regions forming candidaes for he clips are exraced using hresholding. while (1) grab_image (Image, AcqHandle) hreshold (Image, CurrRegions, 0, 80) The curren regions are hen merged wih ones exraced in he previous image using he operaor merge_regions_line_scan. As a resul, wo ses of regions are reurned: The parameer CurrMergedRegions conains he curren regions, possibly exended by fiing pars of he previously exraced regions, whereas he parameer PrevMergedRegions conains he res of he previous regions. merge_regions_line_scan (CurrRegions, PrevRegions, CurrMergedRegions, \ PrevMergedRegions, ImageHeigh, 'op', \ MaxImagesRegions) connecion (PrevMergedRegions, ClipCandidaes) selec_shape (ClipCandidaes, FinishedClips, 'area', 'and', 4500, 7000) The regions in PrevMergedRegions are finished ; from hem, he program selecs he clips via heir area and furher processes hem laer, e.g., deermines heir posiion and orienaion. The regions in CurrMergedRegions are renamed and now form he previous regions for he nex ieraion. Miscellaneous copy_obj (CurrMergedRegions, PrevRegions, 1, -1) endwhile
A-48 Miscellaneous a) 1 2 3 b) 1 2 3 4 c) 1 2 3 4 5 6 Figure 6.2: Merging regions exraced from subsequen line scan images: sae afer a) 2, b) 3, c) 4 images (large coordinae sysem: iled image; small coordinae sysems: curren image or mos recen image). Noe ha he operaor copy_obj does no copy he regions hemselves bu only he corresponding HAL- CON objecs, which can be hough of as references o he acual region daa. Before we show how o merge he images le s ake a look a figure 6.2, which visualizes he whole process: Afer he firs wo images CurrMergedRegions conains hree clip pars; for he firs one a previously exraced region was merged. Noe ha he regions are described in he coordinae frame of he curren image; his means ha he merged par of clip no. 1 has negaive coordinaes. In he nex ieraion (figure 6.2b), furher clip pars are merged, bu no clip is finished ye. Noe ha he coordinae frame is again fixed o he curren image; as a consequence he currenly merged regions seem o move ino negaive coordinaes. Afer he fourh image (figure 6.2c), clips no. 1 and 2 are compleed; hey are reurned in he parameer PrevMergedRegions. Noe ha hey are sill described in he coordinae frame of he previous image (depiced wih dashed arrow); o visualize hem ogeher wih CurrMergedRegions hey mus be moved o he coordinae sysem of he curren image using he operaor move_region: move_region (FinishedClips, ClipsInCurrenImageCoordinaes, \ -ImageHeigh, 0)
6.6 Line Scan Cameras A-49 Le s ge back o he ask of merging images: To access he gray values around a clip, one mus merge hose images over which he PrevMergedRegions can be spread. A he beginning, an empy image is creaed which can hold 4 images: gen_image_cons (TiledImage, 'bye', ImageWidh, \ ImageHeigh * MaxImagesRegions) A he end of each ieraion, he oldes image, i.e., he image a he op, is cu off he iled image using crop_par, and he curren image is merged a he boom using ile_images_offse: crop_par (TiledImage, TiledImageMinusOldes, ImageHeigh, 0, \ ImageWidh, (MaxImagesRegions - 1) * ImageHeigh) conca_obj (TiledImageMinusOldes, Image, ImagesToTile) ile_images_offse (ImagesToTile, TiledImage, [0, \ (MaxImagesRegions - 1) * ImageHeigh], [0,0], [-1, \ -1], [-1,-1], [-1,-1], [-1,-1], ImageWidh, \ MaxImagesRegions * ImageHeigh) As noed above, he regions reurned in PrevMergedRegions are described in he coordinae frame of he mos recen image (depiced wih dashed arrows in figure 6.2c); o exrac he corresponding gray values from he iled image, hey mus firs be moved o is coordinae sysem (depiced wih longer arrows) using he operaor move_region. Then, he surrounding recangles are creaed using shape_rans, and finally he corresponding gray values are exraced using add_channels: move_region (FinishedClips, ClipsInTiledImageCoordinaes, \ (MaxImagesRegions - 1) * ImageHeigh, 0) shape_rans (ClipsInTiledImageCoordinaes, AroundClips, 'recangle1') add_channels (AroundClips, TiledImage, GrayValuesAroundClips) Miscellaneous
A-50 Miscellaneous
HALCON Images A-51 Appendix A HALCON Images HALCON Images In he following, we ake a closer look a he way HALCON represens and handles images. Of course, we won boher you wih deails abou he low-level represenaion and he memory managemen; HAL- CON akes care of i in a way o guaranee opimal performance. A.1 The Philosophy of HALCON Images There are hree imporan conceps behind HALCON s image objecs: 1. Muliple channels Typically, one hinks of an image as a marix of pixels. In HALCON, his marix is called a channel, and images may consis of one or more such channels. For example, gray value images consis of a single channel, color images of hree channels. The advanage of his represenaion is ha many HALCON operaors auomaically process all channels a once; for example, if you wan o subrac gray level or color images from anoher, you can apply sub_image wihou worrying abou he image ype. Wheher an operaor processes all channels a once can be seen in he parameer descripion in he reference manual: If an image parameer is described as (mulichannel-)image or (mulichannel-)image(- array) (e.g., he parameer ImageMinuend of sub_image), all channels are processed; if i is described as image or image(-array) (e.g., he parameer Image of hreshold), only he firs channel is processed. For more informaion abou channels please refer o appendix A.3.2 on page 53. 2. Various pixel ypes Besides he sandard 8 bi (ype bye) used o represen gray value image, HALCON allows images o conain various oher daa, e.g. 16 bi inegers (ype in2 or uin2) or 32 bi floaing poin numbers (ype real) o represen derivaives. Mos of he ime you need no worry abou pixel ypes, because HALCON operaors ha oupu images auomaically use a suiable pixel ype. For example, he operaor derivae_gauss creaes a real image o sore he resul of he derivaion. As anoher example, if you connec
A-52 HALCON Images o an image acquisiion device selecing a value > 8 for he parameer BisPerChannel, a subsequen grab_image reurns an uin2 image. 3. Arbirarily-shaped region of ineres Besides he pixel informaion, each HALCON image also sores is so-called domain in form of a HALCON region. The domain can be inerpreed as a region of ineres, i.e., HALCON operaors (wih some excepions) resric heir processing o his region. The image domain inheris he full flexibiliy of a HALCON region, i.e., i can be of arbirary shape and size, can have holes, or even consis of unconneced poins. For more informaion abou domains please refer o appendix A.3.3. The power of HALCON s approach lies in he fac ha i offers full flexibiliy bu does no require you o worry abou opions you don need a he momen. For example, if all you do is grab and process sandard 8 bi gray value images, you can ignore channels and pixel ypes. A he momen you decide o use color images insead, all you need o do is o add some lines o decompose he image ino is channels. And if your camera / frame grabber provides images wih more han 8 bi pixel informaion, HALCON is ready for his as well. A.2 Image Tuples (Arrays) Anoher powerful mechanism of HALCON is he so-called uple processing: If you wan o process muliple images in he same way, e.g., o smooh hem, you can call he operaor (e.g., mean_image) once passing all images as a uple (array), insead of calling i muliple imes. Furhermore, some operaors always reurn image uples, e.g., gen_gauss_pyramid or inspec_shape_model. Wheher an operaor suppors uple processing can be seen in he parameer descripion in he reference manual: If an inpu image parameer is described as image(-array) or (mulichannel-)image(- array) (e.g., he parameer Image of mean_image), i suppors uple processing; if i is described as image or (mulichannel-)image (e.g., he parameer Image of find_bar_code), only one image is processed. For informaion abou creaing or accessing image uples please refer o appendix A.3.6. A.3 HALCON Operaors for Handling Images Below you find a brief overview of operaors ha allow o creae HALCON images or o modify echnical aspecs like he image size or he number of channels. A.3.1 Creaion HALCON images are creaed auomaically when you use operaors like grab_image or read_image. You can also creae images from scrach using he operaors lised in he HDevelop menu Operaors Image Creaion, e.g., gen_image_cons or gen_image1_exern (see also secion 6.2 on page 40).
A.3 HALCON Operaors for Handling Images A-53 A.3.2 Channels Operaors for manipulaing channels can be found in he HDevelop menu Operaors Image Channel. You can query he number of channels of an image wih he operaor coun_channels. Channels can be accessed using access_channel (which exracs a specified channel wihou copying), image_o_channels (which convers a muli-channel image ino an image uple), or decompose2 ec. (which convers a muli-channel image ino 2 or more single-channel images). Vice versa, you can creae a muli-channel image using channels_o_image or compose2 ec., and add channels o an image using append_channel. HALCON Images A.3.3 Domain Operaors for manipulaing he domain of an image can be found in he HDevelop menu Operaors Image Domain. Upon creaion of an image, is domain is se o he full image size. You can se i o a specified region using change_domain. In conras, he operaor reduce_domain akes he original domain ino accoun; he new domain is equal o he inersecion of he original domain wih he specified region. Please also ake a look a he operaor add_channels, which can be seen as complemenary o reduce_domain. A.3.4 Access Operaors for accessing informaion abou a HALCON image can be found in he HDevelop menu Operaors Image Access. For example, ge_image_poiner1 reurns he size of an image and a poiner o he image marix of is firs channel. A.3.5 Manipulaion You can change he size of an image using he operaors change_forma or crop_par, or oher operaors from he HDevelop menu Operaors Image Forma. The menu Operaors Image Type-Conversion liss operaors which change he pixel ype, e.g., conver_image_ype. Operaors o modify he pixel values, can be found in he menu Operaors Image Manipulaion, e.g., pain_gray, which copies pixels from one image ino anoher. A.3.6 Image Tuples Operaors for creaing and accessing image uples can be found in he HDevelop menu Operaors Objec Manipulaion. Image uples can be creaed using he operaors gen_empy_obj and conca_obj, while he operaor selec_obj allows o access an individual image ha is par of a uple.
A-54 HALCON Images
Parameers Describing he Image A-55 Appendix B Parameers Describing he Image Image Parameers When opening a connecion wih open_framegrabber, you can specify he desired image forma, e.g., is size or he number of bis per pixel, using is nine parameers, which are described in he following. B.1 Image Size The following 6 parameers influence he size of he grabbed images: HorizonalResoluion and VericalResoluion specify he spaial resoluion of he image in relaion o he original size. For example, if you choose VericalResoluion = 2, you ge an image wih half he heigh of he original as depiced in figure B.1b. Anoher name for his process is (verical and horizonal) subsampling. a) c) b) d) Figure B.1: The effec of image resoluion (subsampling) and image cropping (ImageWidh = 200, ImageHeigh = 100, SarRow = 50, SarColumn = 100): a) HorizonalResoluion (HR) = VericalResoluion (VR) = 1; b) HR = 1, VR = 2; c) HR = 2, VR = 1; d) HR = VR = 2.