Soluion Guide II-A Image Acquisiion HALCON 17.12 Progress
The Ar of Image Acquisiion, Version 17.12 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. Copyrigh 2002-2017 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 Server 2008/2012/2012 R2/2016, Windows 7/8/8.1/10, Microsof.NET, Visual C++, and Visual Basic are eiher rademarks or regisered rademarks of Microsof Corporaion. Linux is a rademark of Linus Torvalds. macos and OpenCL are rademarks of Apple Inc. 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 s 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 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 acquisiion devices (see secion 1 on page 7). Wihin your HALCON applicaion, he ask of 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 s from various configuraions of frame grabbers and cameras (see secion 3 on page 11) in differen iming modes (see secion 5 on page 21). 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 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 7 on page 49 and chaper 15 on page 99, 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......................... 11 3.2 Connecing o Muliple Boards and Cameras............................. 12 3.2.1 Single Camera........................................ 13 3.2.2 Muliple Boards....................................... 13 3.2.3 Muliple Handles Per Board................................. 13 3.2.4 Por Swiching........................................ 13 3.2.5 Simulaneous Grabbing (Only For Specific Inerfaces)................... 14 3.3 Requesing Informaion Abou he Image Acquisiion Inerface................... 14 4 Configuring he Acquisiion 17 4.1 General Parameers.......................................... 17 4.2 Special Parameers.......................................... 18 4.3 Fixed vs. Dynamic Parameers.................................... 19 5 The Various Modes of Grabbing Images 21 5.1 Real-Time Image Acquisiion..................................... 21 5.1.1 Non-Real-Time Grabbing Using grab_........................ 21 5.1.2 Grabbing Wihou Delay Using Asynchronously Reseable Cameras........... 23 5.1.3 Volaile Grabbing....................................... 23 5.1.4 Real-Time Grabbing Using grab async....................... 24 5.1.5 Coninuous Grabbing..................................... 26 5.1.6 Using grab async Togeher Wih Asynchronously Reseable Cameras....... 27 5.1.7 Specifying a Maximum Delay................................ 27 5.2 Using an Exernal Trigger....................................... 28 5.2.1 Special Parameers for Exernal Triggers.......................... 29 5.3 Acquiring Images From Muliple Cameras.............................. 29 5.3.1 Dynamic Por Swiching and Asynchronous Grabbing................... 29 5.3.2 Simulaneous Grabbing.................................... 31 6 Miscellaneous 33 6.1 Acquiring Images From Sandardized Image Acquisiion Devices.................. 33 6.2 Acquiring Images From Unsuppored Image Acquisiion Devices.................. 34 6.3 Grabbing Image Arrays and Preprocessed Image Daa........................ 35 6.4 Error Handling............................................ 35 6.4.1 Error Handling in HDevelop................................. 36 6.4.2 Error Handling Using HALCON/C............................. 37 6.4.3 Error Handling Using HALCON/C++............................ 37 6.4.4 Error Handling Using HALCON/.NET........................... 38 6.5 Callback Funcions.......................................... 38 6.6 Line Scan Cameras.......................................... 39 A HALCON Images 43 A.1 The Philosophy of HALCON Images................................. 43
A.2 Image Tuples (Arrays)........................................ 44 A.3 HALCON Operaors for Handling Images.............................. 44 A.3.1 Creaion............................................ 44 A.3.2 Channels........................................... 44 A.3.3 Domain............................................ 44 A.3.4 Access............................................ 44 A.3.5 Manipulaion......................................... 45 A.3.6 Image Tuples......................................... 45 B Parameers Describing he Image 47 B.1 Image Size.............................................. 47 B.2 Image Daa.............................................. 48 C Objec Appearance 49 C.1 Lighing................................................ 49 C.1.1 Reflecion Properies of he Objec.............................. 49 C.1.2 Characerisics of he Ligh Source.............................. 50 C.2 Geomery............................................... 52 Index 55
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 s is only a prelude o he acual machine vision ask. Of course i is imporan ha s 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 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 acquisiion device probably requires o rewrie he acquisiion par of he applicaion. HALCON s answer o his problem are is 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; macos: shared libraries). HALCON acquisiion inerfaces bridge he gap beween he individual acquisiion devices and he HALCON library, which is independen of he used 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 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. camera compuer HALCON applicaion HDevelop / C / C++ / C# / Visual Basic frame grabber sofware HALCON 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. In fac, he elemenary asks of acquisiion are covered by wo HALCON operaors: open_framegrabber connecs o he 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 grab_ (or grab async, see secion 5.1 on page 21 for he difference) grabs s. If no only a single bu an array of s or preprocessed 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 35). If an acquisiion device provides addiional funcionaliy, e.g., on-board modificaion of he signal, special grabbing modes, or digial oupu lines, i is available via he operaor se_framegrabber_param (see secion 4 on page 17). Noe, ha for some acquisiion devices he full funcionaliy is no available wihin HALCON; please refer o he corresponding online documenaion which can be found in he direcory %HALCONROOT%\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/-acquisiion. If he 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 34 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 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 acquisiion ask, which uses he acquisiion device in is defaul configuraion and he sandard grabbing mode. The grabbed s are hen segmened. To follow he example acively, sar he HDevelop program soluion_guide\_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 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 socalled handle (AcqHandle), by which you can access he acquisiion device, e.g., in calls o he operaor grab_. In he example, defaul values are used for mos oher parameers ( defaul or -1); secion 4.1 on page 17 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 grab_ (Image, AcqHandle) Afer successfully connecing o your acquisiion device you can grab s by calling he operaor grab_ wih he corresponding handle AcqHandle. More advanced modes of grabbing s are described in secion 5 on page 21. a) b) Figure 2.1: a) Acquired ; b) processed (auomaic segmenaion).
A-10 A Firs Example Sep 3: Grab and process s in a loop while (Buon!= 1) grab_ (Image, AcqHandle) auo_hreshold (Image, Regions, 4) connecion (Regions, ConnecedRegions) ge_mposiion (WindowHandleBuon, Row, Column, Buon) endwhile In he example, he grabbed s 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 3.1 Opening a Connecion o a Specified Configuraion Wih he operaor open_framegrabber you open a connecion o an 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. 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 As a resul, open_framegrabber reurns a handle for he opened connecion in he parameer AcqHandle. Noe ha if you use HALCON s 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 acquisiion device and choose suiable parameers (for deails see he HDevelop User s Guide, secion 7.1 on page 184), 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 acquisiion device (see %HALCONROOT%\doc\hml\manuals, he HALCON folder in he Windows sar menu, or hp://www.halcon.com/-acquisiion) which configuraions i suppors. 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 por 0 por swich board 0 por 1 board 1 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.
3.2 Connecing o Muliple Boards and Cameras A-13 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\_acquisiion\muliple_boards.hdev. 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 acquisiion inerfaces. To grab s from he wo cameras, you simply call he operaor grab_ once wih he wo handles reurned by he wo calls o open_framegrabber: Connecing grab_ (Image0, AcqHandle0) grab_ (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\_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_ (Image0, AcqHandle0) grab_ (Image1, AcqHandle1) As figure 3.2c shows, you can also use muliple boards wih muliple conneced cameras. 3.2.4 Por Swiching Some 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\_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 s you swich pors using he operaor se_framegrabber_param (see secion 4.2 on page 18 for more informaion abou his operaor):
A-14 Connecing o Your Image Acquisiion Device se_framegrabber_param (AcqHandle, 'por', Por0) dev_se_window (WindowHandle0) grab_ (Image0, AcqHandle) se_framegrabber_param (AcqHandle, 'por', Por1) dev_se_window (WindowHandle1) grab_ (Image1, AcqHandle) 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, s were grabbed from he individual cameras by muliple calls o he operaor grab_. In conras, some acquisiion inerfaces allow o grab s from muliple cameras wih a single call o grab_, which hen reurns a muli-channel (see figure 3.2e; appendix A.1 on page 43 conains more informaion abou muli-channel s). 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 s from a sereo camera sysem. Noe ha simulaneous grabbing is available only for very few acquisiion inerfaces. In his mode, open_framegrabber is called only once, as can be seen in he HDevelop example program soluion_guide\_acquisiion\simulaneous_grabbing.hdev: open_framegrabber (AcqName, 1, 1, 0, 0, 0, 0, 'defaul', -1, 'defaul', -1, \ 'defaul', 'defaul', 'defaul', 0, -1, AcqHandle) You can check he number of reurned s (channels) using he operaor coun_channels grab_ (SimulImages, AcqHandle) coun_channels (SimulImages, num_channels) and exrac he individual s, e.g., using decompose2, decompose3 ec., depending on he number of s: if (num_channels == 2) decompose2 (SimulImages, Image0, Image1) Alernaively, you can conver he muli-channel ino an array using _o_channels and hen selec he individual s 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 31 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 acquisiion inerface is o use he operaor info_framegrabber. In he HDevelop example program soluion_guide\_acquisiion\info_framegrabber.hdev (preconfigured for he HALCON 1394IIDC inerface, please adap he inerface name for your own 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.
3.3 Requesing Informaion Abou he Image Acquisiion Inerface A-15 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 acquisiion device wih open_framegrabber. The only condiion is ha he HALCON acquisiion inerface and he device driver and SDK have been insalled. Connecing Figure 3.3: An example resul of he operaor info_framegrabber.
A-16 Connecing o Your Image Acquisiion Device
Configuring he Acquisiion A-17 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 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 using only wo operaors. However, HALCON s second goal is o make he full funcionaliy of an acquisiion device available o he user. As 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 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: HorizonalResoluion, VericalResoluion ImageWidh, ImageHeigh, SarRow, SarColumn spaial resoluion of he ransferred in relaion o he original size (see appendix B.1 on page 47) size and upper lef corner of he ransferred in relaion o he original size (see appendix B.1 on page 47) Field grabbing mode for analog cameras, e.g., inerlaced-scan, progressive-scan, field grabbing BisPerChannel, ColorSpace Generic ExernalTrigger CameraType, Device, Por, LineIn daa conained in a pixel (number of bis, number of channels, color encoding, see appendix B.2 on page 48) generic parameer wih device-specific meaning hooking he acquisiion of s o an exernal rigger signal (see also secion 5.2 on page 28) configuraion of frame grabber(s) and camera(s) from which s are o be acquired (see secion 3.1 on page 11) In secion 3.1 on page 11, we already encounered he parameers describing he frame grabber / camera configuraion. Mos of he oher parameers of open_framegrabber specify he forma; hey are described in more deail in appendix B on page 47. The parameer ExernalTrigger acivaes a special grabbing mode which is described in deail in secion 5.2 on page 28. 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 14.
A-18 Configuring he Acquisiion 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 19 for more informaion abou hese opics. 4.2 Special Parameers Even he funcionaliy ha is no generally available for all 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: grab_imeou imeou afer which he operaors grab_ and grab async sop waiing for an and reurn an error (see also secion 5.2.1 on page 29 and secion 6.4 on page 35) volaile enable volaile grabbing (see also secion 5.1.3 on page 23) coninuous_grabbing rigger_signal _widh, _heigh, sar_row, sar_column, generic, exernal_rigger, por swich on a special acquisiion mode which is necessary for some acquisiion devices o achieve real-ime performance (see also secion 5.1.5 on page 26) 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 17, allowing o modify hem dynamically, i.e., afer opening he connecion (see also secion 4.3) 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 39), 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) 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 13 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, ['_widh','_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: 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:
4.3 Fixed vs. Dynamic Parameers A-19 Figure 4.1: Querying available special parameers via info_framegrabber. ge_framegrabber_param (AcqHandle, 'gamma', CurrenGamma) NewGamma := CurrenGamma + 1.0 if (NewGamma > MaxGamma) NewGamma := MaxGamma endif se_framegrabber_param (AcqHandle, 'gamma', NewGamma) Configuring 4.3 Fixed vs. Dynamic Parameers The disincion beween fixed and dynamic parameers is made relaing o he lifeime of a connecion o an 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 18, some 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., _widh or exernal_rigger. 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.
A-20 Configuring he Acquisiion
The Various Modes of Grabbing Images A-21 Chaper 5 The Various Modes of Grabbing Images Secion 2 on page 9 showed ha grabbing s is very easy in HALCON you jus call grab_! Bu of course here s more o grabbing han jus o ge an, 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, 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 s he camera produces. Processing delay: The 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 acquisiion i is ignored in he following.! Grabbing 5.1.1 Non-Real-Time Grabbing Using grab_ Figure 5.1 shows he iming diagram for he sandard grabbing mode, i.e., if you use he operaor grab_ from wihin your applicaion. This operaor call is ranslaed by he HALCON acquisiion 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. In he example, a free-running analog progressive-scan camera is used, which produces s coninuously a a fixed frame rae; he sar of a new is indicaed by a so-called verical sync signal. The frame grabber hen digiizes he incoming analog signal and ransforms i ino an marix. If a digial camera is used, he camera iself performs he digiizing and ransfers a digial signal which is hen ransformed ino an marix by he frame grabber. The 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-22 The Various Modes of Grabbing Images original frame rae original frame rae original frame rae camera expose expose expose expose ransfer (analog) frame grabber wai for vsync digiize wai for vsync digiize ransfer (DMA) Grab Grab IAI & SDK wai for creae HImage wai for creae HImage sofware applicaion grab_ delay process grab_ delay frame rae processing process Figure 5.1: Sandard iming using grab_ (configuraion: free-running progressive-scan camera, frame grabber wih incremenal ransfer). a FIFO buffer, or in a single burs as depiced in figure 5.2 on page 23, 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., 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 is compleely sored in he compuer memory, he HALCON acquisiion inerface ransforms i ino a HALCON and reurns he conrol o he applicaion which processes he and hen calls grab_ again. However, even if he processing ime is shor in relaion o he frame rae, he camera has already begun o ransfer he nex which is herefore los ; he applicaion can herefore only process every second. You can check his behavior using he HDevelop example program soluion_guide\_acquisiion\ real_ime_grabbing.hdev, which deermines achievable frame raes for grabbing and processing (here: calculaing a difference ) firs separaely and hen ogeher as follows: grab_ (BackgroundImage, AcqHandle) coun_seconds (Seconds1) for i := 1 o 20 by 1 grab_ (Image, AcqHandle) sub_ (BackgroundImage, Image, DifferenceImage, 1, 128) endfor coun_seconds (Seconds2) TimeGrabImage := (Seconds2 - Seconds1) / 20 FrameRaeGrabImage := 1 / TimeGrabImage To see he non-deerminisic delay, execue he operaor grab_ 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 Real-Time Image Acquisiion A-23 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 creae HImage wai for creae HImage sofware applicaion grab_ process grab_ process delay = 0 frame rae processing Figure 5.2: Using an asynchronously reseable camera ogeher wih grab_ (configuraion: progressive-scan camera, frame grabber wih burs ransfer, volaile grabbing). 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 is acquired (exposed). This leads o a delay beween he momen you call grab_ and he acual acquisiion (see figure 5.1). 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. Grabbing 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 chip and (almos) immediaely sars o expose i. Typically, such a camera does no grab s coninuously bu only on demand. An example iming diagram is shown in figure 5.2. In conras o figure 5.1, he delay is (almos) zero. Furhermore, because he applicaion now specifies when s are o be grabbed, all s 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. 5.1.3 Volaile Grabbing As shown in figure 5.1 on page 22, afer he has been ransferred ino he compuer memory, he HALCON acquisiion inerface needs some ime o creae a corresponding HALCON which is hen reurned in he oupu parameer Image of grab_. Mos of his ime is needed o copy he 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')
A-24 The Various Modes of Grabbing Images! Then, he ime needed by he acquisiion inerface o creae he HALCON is significanly reduced as visualized in figure 5.2. Noe ha usually volaile grabbing is only suppored for gray value s! The drawback of volaile grabbing is ha grabbed s are overwrien by subsequen grabs. To be more exac, he overwriing depends on he number of buffers allocaed by he acquisiion inerface or SDK. Typically, a leas wo buffers exis; herefore, you can safely process an even if he nex is already being grabbed as in figure 5.4 on page 26. 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., s are copied neverheless, oherwise here would be scenarios when HDevelop would crash. Thus, o experimen wih volaile grabbing using he HDevelop example program soluion_guide\ _acquisiion\volaile_grabbing.hdev, you mus expor i o a programming language or use HDev- Engine. Afer grabbing a firs and displaying i via grab_ (FirsImage, AcqHandle) dev_open_window (0, 0, Widh / 2, Heigh / 2, 'black', FirsWindow) dev_display (FirsImage) change he scene and grab a second which is displayed in an individual window: grab_ (SecondImage, AcqHandle) dev_open_window (0, Widh / 2 + 8, Widh / 2, Heigh / 2, 'black', \ SecondWindow) dev_display (SecondImage) Now, s are grabbed in a loop and displayed in a hird window. The wo oher s are also displayed each ime. If you change he scene before each grab you can see how he firs wo s 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_ (CurrenImage, AcqHandle) dev_se_window (ThirdWindow) dev_display (CurrenImage) dev_se_window (FirsWindow) dev_display (FirsImage) dev_se_window (SecondWindow) dev_display (SecondImage) endfor 5.1.4 Real-Time Grabbing Using grab async! The main problem wih he iming using grab_ is ha he wo processes of grabbing and processing run sequenially, i.e., one afer he oher. This means ha he ime needed for processing he 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 async. Here, he wo processes are decoupled and can run asynchronously, i.e., an can be processed while he nex is already being grabbed. Figure 5.3 shows a corresponding iming diagram: The firs call o grab async is processed similar o grab_ (compare figure 5.1 on page 22). The difference becomes apparen afer he ransfer of he ino compuer memory: Almos immediaely afer receiving he, he acquisiion inerface auomaically commands he frame grabber o acquire a new. Thus, he nex is grabbed while he applicaion processes he previous. Afer he processing, he applicaion calls grab async again, which wais unil he already running 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 async; secion 5.1.5 on page 26 shows how o solve his problem.
5.1 Real-Time Image Acquisiion A-25 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 creae HImage wai for creae HImage wai for creae HImage sofware applicaion grab async grab async grab async process process process delay delay "negaive" frame rae processing Figure 5.3: Grabbing and processing in parallel using grab async. In he HDevelop example program soluion_guide\_acquisiion\real_ime_grabbing.hdev, which was already described in secion 5.1.1 on page 21, he reached frame rae for asynchronous processing is deermined as follows: grab_ (BackgroundImage, AcqHandle) coun_seconds (Seconds1) for i := 1 o 20 by 1 grab async (Image, AcqHandle, -1) sub_ (BackgroundImage, Image, DifferenceImage, 1, 128) endfor coun_seconds (Seconds2) TimeGrabImageAsync := (Seconds2 - Seconds1) / 20 FrameRaeGrabImageAsync := 1 / TimeGrabImageAsync Grabbing As can be seen in figure 5.3, he firs call o grab 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, you can use he operaor grab sar which jus riggers he grab command; hen, he firs call o grab 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 async. Noe ha you can use grab 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 29, 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 will already be ready when he nex call o grab async arrives. In his case, you can specify how old he is allowed o be using he parameer MaxDelay. Please refer o secion 5.1.7 on page 27 for deails. Please noe ha when using grab async i is no obvious anymore which is reurned by he operaor call, because he call is decoupled from he command o he frame grabber! In conras o grab_, which always riggers he acquisiion of a new, grab async ypically reurns an which has been exposed before he operaor was called, i.e., he delay is negaive (see figure 5.3)! Keep his effec in mind
A-26 The Various Modes of Grabbing Images when changing parameers dynamically; conrary o inuiion, he change will no affec he reurned by he nex call of grab async bu by he following ones! Anoher problem appears when swiching dynamically beween cameras (see secion 5.3.1 on page 29). 5.1.5 Coninuous Grabbing For some frame grabbers, grab 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 (see figure 5.4a). 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 creae HImage wai for creae HImage sofware applicaion ec grab async process grab async process grab sar frame rae processing b) ransfer (analog) frame digiize digiize digiize grabber ransfer (DMA) Grab Grab Grab Grab IAI & SDK wai for creae HImage wai for creae HImage wai for creae HImage sofware applicaion ec grab async grab async grab async process process process grab sar se coninuous_grabbing frame rae processing Figure 5.4: a) grab async fails o reach frame rae; b) problem solved using coninuous grabbing.
5.1 Real-Time Image Acquisiion A-27 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') In his mode, he frame grabber reads s 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\_acquisiion\ real_ime_grabbing.hdev, which was already described in he previous secions; he program measures he achievable frame rae for grab async wihou and wih coninuous grabbing. We recommend o use coninuous grabbing only if you wan o process every ; oherwise, s 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. 5.1.6 Using grab async Togeher Wih Asynchronously Reseable Cameras As described in secion 5.1.2 on page 23, you can acquire s wihou delay by using an asynchronously reseable camera. Figure 5.5 shows he resuling iming when using such a camera ogeher wih grab async. When comparing he diagram o he one in figure 5.2 on page 23, 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 Grabbing ransfer (DMA) Grab Grab Grab IAI & SDK wai for creae HImage wai for creae HImage sofware applicaion grab async process grab async process delay = 0 frame rae processing Figure 5.5: Using an asynchronously reseable camera ogeher wih grab async (configuraion as in figure 5.2 on page 23. 5.1.7 Specifying a Maximum Delay In conras o grab_, he operaor grab async has an addiional parameer MaxDelay, which les you specify how old an already grabbed may be in order o be acceped. Figure 5.6 visualizes he effec
A-28 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 Grab Grab > MaxDelay? NO > MaxDelay? YES creae HImage creae HImage wai for process process process process grab async Grab Figure 5.6: Specifying a maximum delay for grab async (using coninuous grabbing). of his parameer. There are wo cases o disinguish: If he call o grab async arrives before he nex has been grabbed (firs call in he example), he parameer has no effec. However, if an 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 is acceped; oherwise (hird call), a new is grabbed. Please noe ha he delay is no measured saring from he momen he 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 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 In he previous secion, he sofware performing he machine vision ask decided when o acquire an (sofware rigger). In indusrial applicaions, however, he momen for 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 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 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_ and a free-running camera. Afer he call o grab_, he acquisiion device wais for he rigger signal. When i appears, he procedure described in he previous secion follows: The device wais for he nex, digiizes i, and
5.3 Acquiring Images From Muliple Cameras A-29 ransfers i ino compuer memory; hen, he HALCON acquisiion inerface ransforms i ino a HALCON and reurns he conrol o he applicaion which processes he and hen calls grab_ again, which causes he 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, which may mean ha he objec o be inspeced is no compleely visible anymore. Secondly, because grab_ is used, rigger signals which arrive while he applicaion is processing an are los. Boh problems can easily be solved by using an asynchronously reseable camera ogeher wih he operaor grab async as depiced in figure 5.7b. The C++ example program examples\soluion_guide\_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); Then, s are grabbed: HImage ; do { = 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 37. 5.2.1 Special Parameers for Exernal Triggers Grabbing Mos 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 18, 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_ and grab 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 35 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 s 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 13, you mus be careful when using grab async: By defaul, he acquisiion inerface commands he
A-30 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 creae HImage wai for sofware applicaion rigger grab_ Trigger process Trigger grab_ Trigger delay 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 creae HImage wai for creae HImage wai for sofware ec applicaion rigger grab sar grab async Trigger delay = 0 Trigger delay = 0 process grab async Trigger delay = 0 process grab async Trigger Figure 5.7: Using an exernal rigger ogeher wih: a) free-running camera and grab_; b) asynchronously reseable camera and grab async. frame grabber board o grab he nex auomaically afer i received he curren bu before he nex call of grab async! If you swiched o anoher camera before his call, he frame grabber migh already be busy grabbing an 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. se_framegrabber_param (AcqHandle, 'sar_async_afer_grab_async', \ 'disable')
5.3 Acquiring Images From Muliple Cameras A-31 Now, all grab commands mus be issued explicily wih he operaor grab sar. The following code shows how o swich beween cameras in a loop: * swich o camera 0 and grab a firs se_framegrabber_param (AcqHandle, 'por', Por0) grab sar (AcqHandle, -1) dev_se_window (WindowHandle0) grab 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 sar (AcqHandle, -1) * meanwhile, process 0 * hen ge from camera 1 dev_se_window (WindowHandle1) grab async (Image1, AcqHandle, -1) dev_display (Image1) * swich o camera 0 and sar a new grab se_framegrabber_param (AcqHandle, 'por', Por0) grab sar (AcqHandle, -1) * meanwhile, process 1 * hen ge from camera 0 dev_se_window (WindowHandle0) grab async (Image0, AcqHandle, -1) dev_display (Image0) endwhile 5.3.2 Simulaneous Grabbing Some acquisiion inerfaces provide special funcionaliy o grab s 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 14, he s are grabbed by a single call o grab_ or grab async, which reurn hem in form of a muli-channel. Depending on he acquisiion inerface, i may be necessary o swich on he simulaneous grabbing via he operaor se_framegrabber_param. Grabbing 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 s 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.
A-32 The Various Modes of Grabbing Images
Miscellaneous A-33 Chaper 6 Miscellaneous 6.1 Acquiring Images From Sandardized Image Acquisiion Devices Differen commiees have developed sandards for acquisiion inerfaces. HALCON suppors several of hese sandards and provides he corresponding inerfaces. In paricular he sandards GenICam, GigE Vision, OpenNI, Video4Linux, DCAM, DirecFile, DirecShow, and Twain are suppored. A sandardized acquisiion inerface is suiable for differen acquisiion devices ha do no necessarily have he same se of parameers o adjus during he 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: 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
A-34 Miscellaneous 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 acquisiion inerfaces differen ypes of parameers are used: he parameers specific for he 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 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. As a very easy o use alernaive, you can pass exernally creaed s, i.e., he raw marix, o HALCON using he operaors gen_1, gen_3, gen_1_exern, or gen_3_exern, which creae a corresponding HALCON. The main difference beween he operaors gen_1 and gen_1_exern and heir varians for hree-channel s is ha he former copies he marix when creaing he HALCON, whereas he laer doesn, which is useful if you wan o realize volaile grabbing as described in secion 5.1.3 on page 23. The C example program examples\soluion_guide\_acquisiion\c\use_exern_.c shows how o use he operaor gen_1_exern o pass sandard gray value s o HALCON. In his case, he 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 s o be grabbed ; in a real applicaion his corresponds o he buffer(s) used by he acquisiion device SDK. unsigned char *_marix_pr; Hlong widh, heigh; IniializeBuffer(&_marix_pr, &widh, &heigh); The example program simulaes he grabbing of s wih a procedure which reads s from an sequence and copies hem ino he buffer. Then, he conen of he buffer is ransformed ino a HALCON (ype bye) via gen_1_exern. The parameer ClearProc is se o 0 o signal ha he program iself akes care of freeing he memory. The creaed HALCON is hen displayed. The loop can be exied by clicking ino he HALCON window wih any mouse buon.
6.3 Grabbing Image Arrays and Preprocessed Image Daa A-35 Hobjec long ; window_id; open_window (0, 0, widh, heigh, 0, "visible", "", (Hlong*)&window_id); while (!BuonPressed(window_id)) { MyGrabImage((cons unsigned char **) &_marix_pr); gen_1_exern(&, "bye", (Hlong)widh, (Hlong)heigh, (long) _marix_pr, (long) 0); } disp_obj(, window_id); If your acquisiion device supplies s wih more han 8 bi pixels, you mus adap boh he daa ype for he marix and he ype of he creaed HALCON (parameer Type of gen_1_exern). In case of color s HALCON expecs he daa in form of hree separae marices. Correspondingly, you can creae a HALCON by calling he operaors gen_3 or gen_3_exern wih he hree poiners o he marices. Please refer o appendix A on page 43 for more informaion abou HALCON s in general. 6.3 Grabbing Image Arrays and Preprocessed Image Daa The previous secions described in deail how o acquire s using grab_ or grab async. Wih hese operaors s can be grabbed and, if an consiss of several channels, he is grabbed as a muli-channel (see also appendix A.1 on page 43). For he ypical color, his approach is suied very well, as muli-channel s can be furher processed convenienly by many HALCON operaors. Bu someimes, e.g., if he grabbed daa describes 3D daa raher han a color, he s are needed in an array insead of a muli-channel. Then, you can eiher grab he as a muli-channel, access he individual channels wih he operaor access_channel, and sore he s 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 s in an array. Furhermore, hey provide he possibiliy o addiionally grab preprocessed daa like regions, conours, or conrol daa. Noe ha grab_daa and grab_daa_async are no available for all 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 s from a SwissRanger inerface ha conains amongs ohers he X, Y, and Z s 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) Miscellaneous 6.4 Error Handling Jus as he HALCON acquisiion inerfaces encapsulae he communicaion wih an acquisiion device, hey also encapsulae occurring errors wihin he HALCON error handling mechanism. How o cach and reac o hese
A-36 Miscellaneous Figure 6.1: Popup dialog in HDevelop signaling a imeou. 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 acquisiion device should qui waiing for an. The examples described in he following secions show how o handle he corresponding HALCON error. 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 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\_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_ 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, 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: dev_error_var (ErrorNum, 1) dev_se_check ('~give_error') grab_ (Image, AcqHandle) dev_error_var (ErrorNum, 0) dev_se_check ('give_error') 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 acquisiion can be found in he Image Acquisiion Inerface Programmer s Manual, appendix G on page 75. In he example, he imeou is handled by disabling he exernal rigger mode
6.4 Error Handling A-37 via he operaor se_framegrabber_param (parameer exernal_rigger ). Then, he call o grab_ 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, 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 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\_acquisiion\c\error_handling_imeou.c performs he same ask as he HDevelop program in he previous secion; if he call o grab_ succeeds, he program grabs and displays s 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_ (&, 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 G on page 75, for a lis of acquisiion error codes and heir corresponding consans). Miscellaneous 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 39. 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\_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\_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:
A-38 Miscellaneous ry { = acqdevice.grabimage(); } cach (HExcepion &excep) { if (excep.errorcode() == H_ERR_FGTIMEOUT) { acqdevice.seframegrabberparam("exernal_rigger", "false"); As already noed, if your 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/.NET For error handling wih HALCON/.NET (e.g., in C# or Visual Basic.NET applicaions) please refer o he Programmer s Guide, secion 10.9 on page 76. 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 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 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 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 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 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
6.6 Line Scan Cameras A-39 for he user-specific callback funcion o finish before i proceeds. Insead, i wais a fixed ime afer acivaing he user-specific 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 s of a cerain widh and heigh; wheher he heigh is 1, i.e., a single line, or larger does no maer. In fac, in many line scan applicaions he 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 s 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 s acquired from a line scan camera can hen be processed jus like s from area scan cameras. However, line scan s ofen pose an addiional problem: The objecs o inspec may be spread over muliple s (pages). To solve his problem, HALCON provides special operaors: ile_s allows o merge s ino a larger, merge_regions_line_scan and merge_con_line_scan_xld allow o merge he (inermediae) processing resuls of subsequen s. How o use hese operaors is explained in he HDevelop example program soluion_guide\ _acquisiion\line_scan.hdev. The program is based on an 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 s an objec can be spread. In he example, a clip can be spread over 4 s: MaxImagesRegions := 4 The coninuous processing is realized by a simple loop: A each ieraion, a new is grabbed, and he regions forming candidaes for he clips are exraced using hresholding. while (1) grab_ (Image, AcqHandle) hreshold (Image, CurrRegions, 0, 80) The curren regions are hen merged wih ones exraced in he previous 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. Miscellaneous 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. copy_obj (CurrMergedRegions, PrevRegions, 1, -1) endwhile
A-40 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 s: sae afer a) 2, b) 3, c) 4 s (large coordinae sysem: iled ; small coordinae sysems: curren or mos recen ). Noe ha he operaor copy_obj does no copy he regions hemselves bu only he corresponding HALCON objecs, which can be hough of as references o he acual region daa. Before we show how o merge he s le s ake a look a figure 6.2, which visualizes he whole process: Afer he firs wo s 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 ; 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 ; as a consequence he currenly merged regions seem o move ino negaive coordinaes. Afer he fourh (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 (depiced wih dashed arrow); o visualize hem ogeher wih CurrMergedRegions hey mus be moved o he coordinae sysem of he curren using he operaor move_region: move_region (FinishedClips, ClipsInCurrenImageCoordinaes, \ -ImageHeigh, 0) Le s ge back o he ask of merging s: To access he gray values around a clip, one mus merge hose s over which he PrevMergedRegions can be spread. A he beginning, an empy is creaed which can hold 4 s: gen cons (TiledImage, 'bye', ImageWidh, \ ImageHeigh * MaxImagesRegions) A he end of each ieraion, he oldes, i.e., he a he op, is cu off he iled using crop_par, and he curren is merged a he boom using ile_s_offse:
6.6 Line Scan Cameras A-41 crop_par (TiledImage, TiledImageMinusOldes, ImageHeigh, 0, \ ImageWidh, (MaxImagesRegions - 1) * ImageHeigh) conca_obj (TiledImageMinusOldes, Image, ImagesToTile) ile_s_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 (depiced wih dashed arrows in figure 6.2c); o exrac he corresponding gray values from he iled, 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-42 Miscellaneous
HALCON Images A-43 Appendix A HALCON Images HALCON Images In he following, we ake a closer look a he way HALCON represens and handles s. Of course, we won boher you wih deails abou he low-level represenaion and he memory managemen; HALCON 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 objecs: 1. Muliple channels Typically, one hinks of an as a marix of pixels. In HALCON, his marix is called a channel, and s may consis of one or more such channels. For example, gray value s consis of a single channel, color s 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 s from anoher, you can apply sub_ wihou worrying abou he ype. Wheher an operaor processes all channels a once can be seen in he parameer descripion in he reference manual: If an parameer is described as (mulichannel-) or (mulichannel-)(-array) (e.g., he parameer ImageMinuend of sub_), all channels are processed; if i is described as or (-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. 2. Various pixel ypes Besides he sandard 8 bi (ype bye) used o represen gray value, HALCON allows s 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 s auomaically use a suiable pixel ype. For example, he operaor derivae_gauss creaes a real o sore he resul of he derivaion. As anoher example, if you connec o an acquisiion device selecing a value > 8 for he parameer BisPerChannel, a subsequen grab_ reurns an uin2. 3. Arbirarily-shaped region of ineres Besides he pixel informaion, each HALCON also sores is so-called domain in form of a HAL- CON 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 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 s, you can ignore channels and pixel ypes. A he momen you decide o use color s insead, all
A-44 HALCON Images you need o do is o add some lines o decompose he ino is channels. And if your camera / frame grabber provides s 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 s in he same way, e.g., o smooh hem, you can call he operaor (e.g., mean_) once passing all s as a uple (array), insead of calling i muliple imes. Furhermore, some operaors always reurn 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 parameer is described as (-array) or (mulichannel-)(-array) (e.g., he parameer Image of mean_), i suppors uple processing; if i is described as or (mulichannel- ) (e.g., he parameer Image of find_bar_code), only one is processed. For informaion abou creaing or accessing 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 s or o modify echnical aspecs like he size or he number of channels. A.3.1 Creaion HALCON s are creaed auomaically when you use operaors like grab_ or read_. You can also creae s from scrach using he operaors lised in he HDevelop menu Operaors Image Creaion, e.g., gen cons or gen_1_exern (see also secion 6.2 on page 34). 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 wih he operaor coun_channels. Channels can be accessed using access_channel (which exracs a specified channel wihou copying), _o_channels (which convers a muli-channel ino an uple), or decompose2 ec. (which convers a muli-channel ino 2 or more single-channel s). Vice versa, you can creae a muli-channel using channels_o_ or compose2 ec., and add channels o an using append_channel. A.3.3 Domain Operaors for manipulaing he domain of an can be found in he HDevelop menu Operaors Image Domain. Upon creaion of an, is domain is se o he full 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 can be found in he HDevelop menu Operaors Image Access. For example, ge poiner1 reurns he size of an and a poiner o he marix of is firs channel.
A.3 HALCON Operaors for Handling Images A-45 A.3.5 Manipulaion You can change he size of an 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 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 ino anoher. HALCON Images A.3.6 Image Tuples Operaors for creaing and accessing 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 ha is par of a uple.
A-46 HALCON Images
Parameers Describing he Image A-47 Appendix B Parameers Describing he Image Image Parameers When opening a connecion wih open_framegrabber, you can specify he desired 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 s: HorizonalResoluion and Verical- Resoluion specify he spaial resoluion of he in relaion o he original size. For example, if you choose VericalResoluion = 2, you ge an wih half he heigh of he original as depiced in figure B.1b. Anoher name for his process is (verical and horizonal) subsampling. Wih he parameers ImageWidh, ImageHeigh, SarRow, and SarColumn you can grab only a par of he (possibly subsampled) ; his is called cropping. In figure B.1, he par o be grabbed is marked wih a recangle in he original (or subsampled) ; o he righ, he resuling is depiced. Noe ha he resuling HALCON always sars wih he coordinaes (0,0), i.e., he informaion conained in he parameers SarRow and SarColumn canno be recovered from he resuling. Depending on he involved componens, boh subsampling and cropping may be execued a differen poins during he ransfer of an from he camera ino HALCON: in he camera, in he frame grabber, or in he sofware. Image cropping in he camera or in he framegrabber is also called hardware cropping, whereas cropping on he sofware side is called sofware cropping. Please noe ha subsampling and cropping do no necessarily have a direc effec on he performance in form of a higher frame rae. In paricular, for analog a) c) b) d) Figure B.1: The effec of resoluion (subsampling) and 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.