HALCON Applicaion Noe The Ar of Image Acquisiion Provided Funcionaliy Connecing o simple and complex configuraions of frame grabbers and cameras Acquiring s in various iming modes Configuring frame grabbers and cameras online Involved Operaors open framegrabber info framegrabber grab, grab async, grab sar se framegrabber param, ge framegrabber param close framegrabber, close all framegrabbers gen 1, gen 3, gen 1 exern Copyrigh c 2002-2005 by MVTec Sofware GmbH, München, Germany MVTec Sofware GmbH
Overview 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 he frame grabber board. To le you concenrae on he acual machine vision problem, HALCON already provides inerfaces performing his ineracion for a large number of frame grabbers (see secion 1). 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. 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) in differen iming modes (see secion 5). Unless specified oherwise, he example programs can be found in he subdirecory acquisiion of he direcory %HALCONROOT%\examples\applicaion guide. Noe ha mos programs are preconfigured o work wih a cerain HALCON frame grabber inerface; in his case, he name of he program conains he name of he inerface. To use he program wih anoher frame grabber, please adap he pars which open he connecion o he frame grabber. More example programs for he differen HALCON frame grabber inerfaces can be found in he subdirecoryhdevelop\image\framegrabber of he direcory%halconroot%\examples. Please refer o he HALCON/C User s Manual and he HALCON/C++ User s Manual for informaion abou how o compile and link he C and C++ example programs; among oher hings, hey describe how o use he example UNIX makefiles which can be found in he subdirecories c and cpp of he direcory %HALCONROOT%\examples. Under Windows, you can use Visual Sudio workspaces conaining he examples, which can be found in he subdirecoryi586-n4 parallel o he source files. 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) Microsof, Windows, Windows NT, Windows 2000, Windows XP, Visual Sudio, and Visual Basic 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.mvec.com/halcon/
3 Conens 1 The Philosophy Behind he HALCON Frame ber Inerfaces 4 2 A Firs Example 5 3 Connecing o Your Frame ber 6 3.1 Opening a Connecion o a Specified Configuraion............... 6 3.2 Connecing o Muliple Boards and Cameras................... 8 3.3 Requesing Informaion Abou he Frame ber Inerface........... 11 4 Configuring he Acquisiion 12 4.1 General Parameers................................ 12 4.2 Special Parameers................................ 13 4.3 Fixed vs. Dynamic Parameers.......................... 14 5 The Various Modes of bing Images 15 5.1 Real-Time Image Acquisiion........................... 15 5.2 Using an Exernal Trigger............................. 23 5.3 Acquiring Images From Muliple Cameras.................... 25 6 Miscellaneous 27 6.1 Acquiring Images From Unsuppored Frame bers............. 27 6.2 Error Handling.................................. 28 6.3 Line Scan Cameras................................ 32 A HALCON Images 35 A.1 The Philosophy of HALCON Images....................... 35 A.2 Image Tuples (Arrays).............................. 36 A.3 HALCON Operaors for Handling Images.................... 36 B Parameers Describing he Image 38 B.1 Image Size.................................... 38 B.2 Frames vs. Fields................................. 39 B.3 Image Daa.................................... 41 HALCON 6.1.4
4 Applicaion Noe on Image Acquisiion 1 The Philosophy Behind he HALCON Frame ber Inerfaces From he poin of view of an 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 frame grabber. The realiy, however, looks differen. Frame grabbers differ widely regarding he provided funcionaliy, and even if heir funcionaliy is similar, he SDKs (sofware developmen ki) provided by he frame grabber manufacurers do no follow any sandard. Therefore, if one decides o swich o a differen frame grabber, his probably means o rewrie he acquisiion par of he applicaion. HALCON s answer o his problem are is frame grabber inerfaces (HFGI) which are provided for currenly more han 50 frame grabbers in form of dynamically loadable libraries (Windows NT/2000/XP: DLLs; UNIX: shared libraries). HALCON frame grabber inerfaces bridge he gap beween he individual frame grabbers and he HALCON library, which is independen of he used frame grabber, compuer plaform, and programming language (see figure 1). In oher words, hey provide a sandardized inerface o he HALCON user in form of 11 HALCON operaors, and encapsulae deails specific o he frame grabber, i.e., he ineracion wih he frame grabber SDK provided by he manufacurer. Therefore, if you decide o swich o a differen frame grabber, 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++ / Visual Basic frame grabber sofware HALCON processing library halcon.dll & halconc.dll / halconcpp.dll / halconx.dll HALCON xyz frame grabber inerface HFGxyz.dll frame grabber driver & SDK Figure 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 frame grabber and ses general parameers, e.g., he ype of he used camera or he por he camera is conneced o, hen grab (orgrab async, see secion 5.1 for he difference) grabs s. HALCON Applicaion Guide, 2005-02-01
2 A Firs Example 5 a) b) Figure 2: a) Acquired ; b) processed (auomaic segmenaion). If a frame grabber 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). Noe, ha for some frame grabbers no he full funcionaliy is 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.mvec.com/halcon/framegrabber. If he frame grabber you wan o use is no (ye) suppored by HALCON, you can neverheless use i ogeher wih HALCON. Please refer o secion 6.1 for more deails. 2 A Firs Example In his secion we sar wih a simple acquisiion ask, which uses he frame grabber in is defaul configuraion and he sandard grabbing mode. The grabbed s are hen segmened. To follow he example acively, sar he HDevelop program hdevelop\firs example acquisiion ids.dev; he seps described below sar afer he iniializaion of he applicaion (press F5 once o reach his poin). Noe ha he program is preconfigured for he HALCON frame grabber inerface IDS; o use i wih a differen frame grabber, please adap he pars which open he connecion. Sep 1: Connec o he frame grabber open_framegrabber (FGName, 1, 1, 0, 0, 0, 0, defaul, -1, gray, -1, false, nsc, defaul, -1, -1, FGHandle) When opening he connecion o your frame grabber using he operaor open framegrabber, he main parameer is he Name of he corresponding HALCON frame grabber inerface. As a resul, you obain a so-called handle (FGHandle) which acs as your access o he frame grabber, e.g., in calls o he operaorgrab. HALCON 6.1.4
6 Applicaion Noe on Image Acquisiion In he example, defaul values are used for mos oher parameers ( defaul or -1); secion 4.1 akes a closer look a his opic. How o connec o more complex frame grabber and camera configuraions is described in secion 3. Sep 2: an grab_ (Image, FGHandle) Afer successfully connecing o your frame grabber you can grab s by calling he operaor grab wih he corresponding handle FGHandle. More advanced modes of grabbing s are described in secion 5. Sep 3: and process s in a loop while (Buon # 1) grab_ (Image, FGHandle) 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). This is done in a loop which can be exied by clicking ino a window wih he lef mouse buon. 3 Connecing o Your Frame ber 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. 3.1 Opening a Connecion o a Specified Configuraion Wih he operaoropen framegrabber you open a connecion o a frame grabber, or o be more exac, via a frame grabber o a camera. This connecion is described by four parameers (see figure 3): Firs, you selec a frame grabber (family) wih he parameer Name. If muliple boards are allowed, you can selec one wih he parameer Device; depending on he frame grabber inerface, his parameer can conain a sring describing he board or simply a number (in form of a sring!). Typically, 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 ; more complex frame grabber 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 FGHandle. Noe ha if you use HALCON s COM or C ++ inerface and call he operaor via he classes HFramegrabberX or HFramegrabber, no handle is reurned because he insance of he class iself acs as your handle. HALCON Applicaion Guide, 2005-02-01
3.1 Opening a Connecion o a Specified Configuraion 7 SDK & HFGI A por 0 frame SDK & HFGI B grabber board 0 frame grabber board 1 por 1 por 0 por 1 camera ype abc camera ype xyz which frame grabber? which board? which por? which camera? FGHandle Name Device Por CameraType Figure 3: Describing a connecion wih he parameers of open framegrabber. check box o sar online grabbing double-click handle o open dialog Figure 4: Online grabbing in HDevelop. In HDevelop, you can quickly check an opened connecion by double-clicking FGHandle in he Variable Window as shown in figure 4. A dialog appears which describes he saus of he connecion. If you check he corresponding box, s are grabbed online and displayed in he Graphics Window. This mode is very useful o seup your vision sysem (illuminaion, focus, field of view). HALCON 6.1.4
8 Applicaion Noe on Image Acquisiion 3.2 Connecing o Muliple Boards and Cameras Mos HALCON frame grabbers 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 frame grabber (see %HALCONROOT%\doc\hml\manuals, he HALCON folder in he Windows sar menu, or hp://www.mvec.com/halcon/framegrabber) 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 [2] board 0 por 1 [3] frame grabber por 0 board 1 Figure 5: 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.1 Single Camera Figure 5a 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 HALCON Applicaion Guide, 2005-02-01
3.2.2 Muliple Boards 9 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. 3.2.2 Muliple Boards Figure 5b 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 hdevelop\muliple boards px.dev. Noe ha he program is preconfigured for he HALCONPx inerface; o use i wih a differen frame grabber, please adap he pars which open he connecion. open_framegrabber (FGName, 1, 1, 0, 0, 0, 0, defaul, -1, defaul, -1, defaul, defaul, Board0, -1, -1, FGHandle0) open_framegrabber (FGName, 1, 1, 0, 0, 0, 0, defaul, -1, defaul, -1, defaul, defaul, Board1, -1, -1, FGHandle1) In his example, he wo calls differ only in he value for he parameerdevice ( 0 and 1 ); of course, you can use differen values for oher parameers as well, and even connec o differen frame grabber inerfaces. To grab s from he wo cameras, you simply call he operaor grab once wih he wo handles reurned by he wo calls oopen framegrabber: grab_ (Image0, FGHandle0) grab_ (Image1, FGHandle1) 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 frame grabber 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 5c: 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 hdevelop\muliple pors px.dev (preconfigured for he HALCON Px inerface, please adap he pars which open he connecion for your own frame grabber): open_framegrabber (FGName, 1, 1, 0, 0, 0, 0, defaul, -1, defaul, -1, defaul, defaul, defaul, Por0, -1, FGHandle0) open_framegrabber (FGName, 1, 1, 0, 0, 0, 0, defaul, -1, defaul, -1, defaul, defaul, defaul, Por1, -1, FGHandle1) grab_ (Image0, FGHandle0) grab_ (Image1, FGHandle1) As figure 5c shows, you can also use muliple boards wih muliple conneced cameras. 3.2.4 Por Swiching Some frame grabber inerfaces access he cameras no via muliple handles, bu by swiching he inpu por dynamically (see figure 5d). Therefore, open framegrabber is called only once, HALCON 6.1.4
10 Applicaion Noe on Image Acquisiion like in he HDevelop example program hdevelop\por swiching inspeca.dev (preconfigured for he HALCON Inspeca inerface, please adap he pars which open he connecion for your own frame grabber): Por1 := 4 open_framegrabber (FGName, 1, 1, 0, 0, 0, 0, defaul, -1, defaul, -1, Beween grabbing s you swich pors using he operaorse framegrabber param (see secion 4.2 for more informaion abou his operaor): while (1) se_framegrabber_param (FGHandle, por, Por0) disp_ (Image0, WindowHandle0) se_framegrabber_param (FGHandle, por, Por1) 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 bing In he configuraions described above, s were grabbed from he individual cameras by muliple calls o he operaor grab. In conras, some frame grabber inerfaces allow o grab s from muliple cameras wih a single call o grab, which hen reurns a muli-channel (see figure 5e; appendix A.1 conains more informaion abou mulichannel 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. In his mode, open framegrabber is called only once, as can be seen in he HDevelop example program hdevelop\simulaneous grabbing inspeca.dev (preconfigured for he HALCON Inspeca inerface, please adap he pars which open he connecion for your own frame grabber): TM-6701/6705 1-plane, HD ou open_framegrabber (FGName, 1, 1, 0, 0, 0, 0, defaul, -1, defaul, -1, You can check he number of reurned s (channels) using he operaorcoun channels * sep 2: open correcly sized windows ge poiner1 (SimulImages, Poiner, Type, Widh, Heigh) and exrac he individual s, e.g., usingdecompose2,decompose3 ec., depending on he number of s: grab_ (SimulImages, FGHandle) if (num_channels = 2) Alernaively, you can conver he muli-channel ino an array using o channels and hen selec he individual s viaselec obj. Noe ha some frame grabber inerfaces allow simulaneous grabbing also for muliple boards (see figure 5f). Please refer o secion 5.3.2 for addiional informaion. HALCON Applicaion Guide, 2005-02-01
3.3 Requesing Informaion Abou he Frame ber Inerface 11 Figure 6: An example resul of he operaor info framegrabber. 3.3 Requesing Informaion Abou he Frame ber Inerface As menioned already, he individual HALCON frame grabber 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 a frame grabber inerface is o use he operaor info framegrabber. In he HDevelop example program hdevelop\info framegrabber ids.dev (preconfigured for he HALCON IDS inerface, please adap he inerface name for your own frame grabber) his operaor is called muliple imes o query he version number of he inerface, he available boards, 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 Windows, is depiced in figure 6. info_framegrabber (FGName, general, GeneralInfo, GeneralValue) info_framegrabber (FGName, revision, RevisionInfo, RevisionValue) info_framegrabber (FGName, info_boards, BoardsInfo, BoardsValue) info_framegrabber (FGName, pors, PorsInfo, PorsValue) info_framegrabber (FGName, camera_ypes, CamTypeInfo, CamTypeValue) info_framegrabber (FGName, defauls, DefaulsInfo, DefaulsValue) The operaorinfo framegrabber can be called before acually connecing o a frame grabber wih open framegrabber. The only condiion is ha he HALCON frame grabber inerface and he frame grabber SDK and driver have been insalled. HALCON 6.1.4
12 Applicaion Noe on Image Acquisiion 4 Configuring he Acquisiion As explained in secion 1, he inenion of HALCON s frame grabber inerfaces is o provide he user wih a common inerface for many differen frame grabbers. This inerface was kep as simple as possible; as shown, you can connec o your frame grabber and grab a firs using only wo operaors. However, HALCON s second goal is o make he full funcionaliy of a frame grabber available o he user. As frame grabbers 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 a frame grabber connecion ino wo pars: Those parameers which are common o mos frame grabber 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. 4.1 General Parameers When opening a connecion via open framegrabber, you can specify he following general parameers: HorizonalResoluion, VericalResoluion ImageWidh,ImageHeigh, SarRow,SarColumn Field BisPerChannel, ColorSpace Gain ExernalTrigger CameraType,Device,Por, LineIn spaial resoluion of he ransferred in relaion o he original size (see appendix B.1) size and upper lef corner of he ransferred in relaion o he original size (see appendix B.1) grabbing mode for analog cameras, e.g., inerlacedscan, progressive-scan, field grabbing (see appendix B.2) daa conained in a pixel (number of bis, number of channels, color encoding, see appendix B.3) amplificaion facor for he video amplifier on he frame grabber board (if available) hooking he acquisiion of s o an exernal rigger signal (see also secion 5.2) Configuraion of frame grabber(s) and camera(s) from which s are o be acquired (see secion 3.1). In secion 3.1, 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. The parameer ExernalTrigger acivaes a special grabbing mode which is described in deail in secion 5.2. Finally, he parameer Gain can be used o manipulae he acquired s on he frame grabber board by configuring he video amplifier. Noe ha when calling open framegrabber you mus specify values for all parameers, even if your frame grabber inerface does no suppor some of hem or uses values specified in a camera HALCON Applicaion Guide, 2005-02-01
4.2 Special Parameers 13 configuraion file insead. To alleviae his ask, he HALCON frame grabber 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. Afer connecing o a frame grabber, you can query he curren value of general parameers using he operaor se framegrabber param; some inerface even allow o modify general parameers dynamically. Please refer o secion 4.3 for more informaion abou hese opics. 4.2 Special Parameers Even he funcionaliy which is no generally available for all frame grabber can be accessed and configured wih a general mechanism: by seing corresponding special parameers via he operaorse 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 secions 5.2.1 and 6.2) volaile enable volaing grabbing (see also secion 5.1.3) coninuous grabbing rigger signal widh, heigh, sar row, sar column, gain, exernal rigger, por swich on a special acquisiion mode which is necessary for some frame grabbers o achieve realime performance (see also secion 5.1.5) signal ype used for exernal riggering, e.g., rising or falling edge doubles of he some of he general parameers described in secion 4.1, allowing o modify hem dynamically, i.e., afer opening he connecion (see also secion 4.3) Depending on he frame grabber, 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 frame grabbers also offer special parameers for he use of line scan cameras (see also secion 6.3), or parameers conrolling digial oupu and inpu lines. Which special parameers are provided by a frame grabber 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 7 depics he resul of double-clicking ParameersValue in he Variable Window afer execuing he line: info_framegrabber (FGName, 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 he following line was used o swich o por0: while (1) You can also se muliple parameers a once by specifying uples for Param and Value as in he following line: HALCON 6.1.4
14 Applicaion Noe on Image Acquisiion Figure 7: Querying available special parameers via info framegrabber. se_framegrabber_param (FGHandle, [ _widh, _heigh ], [256, 256]) For all parameers which can be se wih se framegrabber param, 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. For example, he HALCON Fire-i inerface allows o query he minimum and maximum values for he brighness: ge_framegrabber_param (FGHandle, brighness_min_value, MinBrighness) ge_framegrabber_param (FGHandle, brighness_max_value, MaxBrighness) Thus, you can check a new brighness value agains hose boundaries before seing i: ge_framegrabber_param (FGHandle, brighness, CurrenBrighness) NewBrighness := CurrenBrighness + 10 if (NewBrighness > MaxBrighness) NewBrighness := MaxBrighness endif se_framegrabber_param (FGHandle, brighness, NewBrighness) 4.3 Fixed vs. Dynamic Parameers The disincion beween fixed and dynamic parameers is made relaing o he lifeime of a frame grabber connecion. 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, some frame grabber 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. HALCON Applicaion Guide, 2005-02-01
5 The Various Modes of bing Images 15 5 The Various Modes of bing Images Secion 2 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 NT/2000/XP 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. 5.1.1 Non-Real-Time bing Using grab Figure 8 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 frame grabber inerface and he SDK ino he corresponding signal o he frame grabber board (marked wih ). 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. Please refer o appendix B.2 for more informaion abou inerlaced grabbing. 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 8, if he frame grabber has only a FIFO buffer, or in a single burs as depiced in figure 9, 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 HALCON 6.1.4
16 Applicaion Noe on Image Acquisiion 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) HFGI & SDK wai for creae wai for creae sofware applicaion grab_ delay process grab_ delay frame rae processing process Figure 8: Sandard iming using grab (configuraion: free-running progressive-scan camera, frame grabber wih incremenal ransfer). 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 frame grabber 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 hdevelop\real ime grabbing ids.dev (preconfigured for he HALCON IDS inerface, please adap he pars which open he connecion for your own frame grabber), which deermines achievable frame raes for grabbing and processing (here: calculaing a difference ) firs separaely and hen ogeher as follows: grab_ (BackgroundImage, FGHandle) coun_seconds (Seconds1) for i := 1 o 20 by 1 grab_ (Image, FGHandle) sub_ (BackgroundImage, Image, DifferenceImage, 1, 128) endfor coun_seconds (Seconds2) TimeImage := (Seconds2-Seconds1)/20 FrameRaeImage := 1 / TimeImage HALCON Applicaion Guide, 2005-02-01
5.1.2 bing Wihou Delay Using Asynchronously Reseable Cameras 17 original frame rae camera expose expose ransfer (analog) Expose Expose frame grabber wai for vsync digiize wai for vsync digiize ransfer (DMA) HFGI & SDK wai for creae wai for creae sofware applicaion grab_ process grab_ process delay = 0 frame rae processing Figure 9: Using a asynchronously reseable camera ogeher wih grab (configuraion: progressive-scan camera, frame grabber wih burs ransfer, volaile grabbing). To see he non-deerminisic delay, execue he operaor grab in he sep mode by pressing F6 ; he execuion ime displayed in HDevelop s saus bar will range beween once and wice he original frame period. Please noe ha on UNIX sysem, he ime measuremens are performed wih a lower resoluion han on Windows sysems. 5.1.2 bing 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 8). 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 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 9. In conras o figure 8, 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. HALCON 6.1.4
18 Applicaion Noe on Image Acquisiion 5.1.3 Volaile bing As shown in figure 8, afer he has been ransferred ino he compuer memory, he HALCON frame grabber inerface needs some ime o creae a corresponding HALCON which is hen reurned in he oupu parameer Image ofgrab. Mos of his ime (abou 3 milliseconds on a 500 MHz Ahlon K6 processor for a gray value NTSC ) 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 operaorse framegrabber param (parameer volaile ): se_framegrabber_param (FGHandle, volaile, enable ) Then, he ime needed by he frame grabber inerface o creae he HALCON is significanly reduced as visualized in figure 9. 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 frame grabber 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 11. Some frame grabber inerfaces allow o use more han wo buffers, and even o selec heir number dynamically via se framegrabber param (parameer num buffers ). You can check his behavior using he HDevelop example program hdevelop\volaile grabbing ids.dev (preconfigured for he HALCON IDS inerface, please adap he pars which open he connecion for your own frame grabber). Afer grabbing a firs and displaying i via grab_ (FirsImage, FGHandle) 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, FGHandle) 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, FGHandle) dev_se_window (ThirdWindow) dev_display (CurrenImage) dev_se_window (FirsWindow) dev_display (FirsImage) dev_se_window (SecondWindow) dev_display (SecondImage) endfor HALCON Applicaion Guide, 2005-02-01
5.1.4 Real-Time bing Using grab async 19 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) HFGI & SDK wai for creae wai for creae wai for creae sofware applicaion grab async grab async grab async process process process delay delay "negaive" frame rae processing Figure 10: bing and processing in parallel using grab async. 5.1.4 Real-Time bing Using grab async The main problem wih he sandard 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 10 shows a corresponding iming diagram: The firs call o grab async is processed similar o grab (compare figure 8). The difference becomes apparen afer he ransfer of he ino compuer memory: Almos immediaely afer receiving he, he frame grabber 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 shows how o solve his problem. In he HDevelop example program hdevelop\real ime grabbing ids.dev, which was already described in secion 5.1.1, he reached frame rae for asynchronous processing is deermined as follows: HALCON 6.1.4
20 Applicaion Noe on Image Acquisiion grab_ (BackgroundImage, FGHandle) coun_seconds (Seconds1) for i := 1 o 20 by 1 grab async (Image, FGHandle, -1) sub_ (BackgroundImage, Image, DifferenceImage, 1, 128) endfor coun_seconds (Seconds2) TimeImageAsync := (Seconds2-Seconds1)/20 FrameRaeImageAsync := 1 / TimeImageAsync As can be seen in figure 10, 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 11; as you can see, he advanage of his mehod is ha he applicaion can perform some processing before callinggrab async. 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 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 10)! Keep his effec in mind 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). 5.1.5 Coninuous bing 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 11a). As a soluion o his problem, some frame grabber inerfaces provide he so-called coninuous grabbing mode which can be enables only via he operaor se framegrabber param (parameer coninuous grabbing ): se_framegrabber_param (FGHandle, 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 11b. Thus, he frame rae is reached. If your frame grabber suppors coninuous grabbing you can es his effec in he example program hdevelop\real ime grabbing ids.dev, 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. HALCON Applicaion Guide, 2005-02-01
5.1.5 Coninuous bing 21 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) HFGI & SDK wai for creae wai for creae sofware applicaion ec grab async process grab async process grab sar frame rae processing b) ransfer (analog) frame digiize digiize digiize grabber ransfer (DMA) HFGI & SDK wai for creae wai for creae wai for creae sofware applicaion ec grab async grab async grab async process process process grab sar se coninuous_grabbing frame rae processing Figure 11: a) grab async fails o reach frame rae; b) problem solved using coninuous grabbing. Noe ha some frame grabber inerfaces provide addiional funcionaliy in he coninuous grabbing mode, e.g., he HALCONBiFlow inerface. Please refer o he corresponding documenaion for more informaion. HALCON 6.1.4
22 Applicaion Noe on Image Acquisiion original frame rae camera expose expose ransfer (analog) frame grabber Expose wai for vsync digiize Expose wai for vsync digiize ransfer (DMA) HFGI & SDK wai for creae wai for creae sofware applicaion grab async process grab async process delay = 0 frame rae processing Figure 12: Using a asynchronously reseable camera ogeher wih grab async (configuraion as in figure 9. 5.1.6 Using grab async Togeher Wih Asynchronously Reseable Cameras As described in secion 5.1.2, you can acquire s wihou delay by using an asynchronously reseable camera. Figure 12 shows he resuling iming when using such a camera ogeher wihgrab async. When comparing he diagram o he one in figure 9, you can see ha a higher frame rae can now be reached, because he processing ime is no included anymore. 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 13 visualizes he effec of his parameer. There are wo cases o disinguish: If he call o grab 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 frame grabber SDKs provide his informaion; HALCON Applicaion Guide, 2005-02-01
5.2 Using an Exernal Trigger 23 camera expose expose expose expose ransfer (analog) frame grabber digiize digiize digiize digiize ransfer (DMA) HFGI & SDK sofware applicaion wai for > MaxDelay? NO > MaxDelay? YES creae creae wai for process process process process grab async Figure 13: Specifying a maximum delay for grab async (using coninuous grabbing). herefore, he las grab command from he inerface o he he frame grabber is used as he saring poin insead. 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 frame grabber boards 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 frame grabber board, he only hing o do is o inform he frame grabber o use he rigger. You can do his simply by seing he parameer ExernalTrigger of open framegrabber o rue. Some frame grabber inerfaces also allow o enable or disable he rigger dynamically using he operaor se framegrabber param (parameer exernal rigger ). Figure 14a shows he iming diagram when using an exernal rigger ogeher wih grab and a free-running camera. Afer he call o grab, he frame grabber board wais for he rigger signal. When i appears, he procedure described in he previous secion follows: The frame grabber wais for he nex, digiizes i, and ransfers i ino compuer memory; HALCON 6.1.4
24 Applicaion Noe on Image Acquisiion a) camera expose expose expose expose ransfer (analog) frame grabber wai for rigger wai for vsync digiize wai for rigger ransfer (DMA) HFGI & SDK wai for creae 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) HFGI & SDK wai for creae wai for creae 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 14: Using an exernal rigger ogeher wih: a) free-running camera and grab ; b) asynchronously reseable camera and grab async. hen, he HALCON frame grabber inerface ransforms i ino a HALCON and reurns he conrol o he applicaion which processes he and hen calls grab again, which causes he frame grabber board o wai for he nex rigger signal. The (bad) example in figure 14a was chosen on purpose o show an unsuiable configuraion HALCON Applicaion Guide, 2005-02-01
5.2.1 Special Parameers for Exernal Triggers 25 for using an exernal rigger: Firs of all, because of he free-running camera here is a nondeerminisic 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 operaorgrab async as depiced in figure 14b. The C++ example program cpp\error handling imeou picpor.cpp (preconfigured for he HALCON PicPor inerface) shows how simple i is o use an exernal rigger: The connecion is opened wihexernaltrigger se o rue : HFramegrabber framegrabber; framegrabber.openframegrabber(fgname, 1, 1, 0, 0, 0, 0, "defaul", -1, "gray", -1, "rue", camype, device, -1, -1); Then, s are grabbed: ; do { = framegrabber.imageasync(-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.2.3. 5.2.1 Special Parameers for Exernal Triggers Mos frame grabber inerfaces allow o furher configure he use of exernal riggering via he operaor se framegrabber param. As menioned in secion 4.2, 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.2 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 frame grabber 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 HALCON 6.1.4
26 Applicaion Noe on Image Acquisiion secion 3.2 for possible configuraions). 5.3.1 Dynamic Por Swiching and Asynchronous bing If you swich dynamically beween muliple cameras conneced o a single board as described in secion 3.2.4 you mus be careful when using grab async: By defaul, he frame grabber inerface commands he frame grabber board o grab he nex auomaically afer i received he curren bu before he nex call ofgrab async! If you swiched o anoher camera before his call, he frame grabber migh already be busy grabbing an from he firs camera. Some frame grabber 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. 5.3.2 Simulaneous bing Some frame grabber inerfaces provide special funcionaliy o grab s simulaneously from muliple (synchronized) cameras. Typically, he cameras are conneced o a single frame grabber board; he PicPor inerface also allows o grab simulaneously from cameras conneced o muliple boards. As described in secion 3.2.5, 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 frame grabber inerface, i may be necessary o swich on he simulaneous grabbing via he operaorse framegrabber param. Please keep in mind ha even if a HALCON frame grabber 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 frame grabber 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. HALCON Applicaion Guide, 2005-02-01
6 Miscellaneous 27 6 Miscellaneous 6.1 Acquiring Images From Unsuppored Frame bers If you wan o use a frame grabber which 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 frame grabber inerface; how o do his is described in deail in he Frame ber Inegraion Programmer s Manual. As an alernaive, you can pass exernally creaed s, i.e., he raw marix, o HAL- CON using he operaors gen 1, gen 3, or gen 1 exern, which creae a corresponding HALCON. The main difference beween he operaors gen 1 and gen 1 exern 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. The C example program 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 ypeunsigned 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 frame grabber SDK. unsigned char *_marix_pr; long 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 parameerclearproc is se o0o 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. Hobjec long ; window_id; open_window (0, 0, widh, heigh, 0, "visible", "", &window_id); while (!BuonPressed(window_id)) { MyImage((cons unsigned char **) &_marix_pr); gen_1_exern(&, "bye", widh, heigh, (long) _marix_pr, (long) 0); disp_obj(, window_id); } If your frame grabber 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. You can creae a HALCON eiher by calling he operaor gen 3 wih he hree poiners o he marices, or by calling he operaor HALCON 6.1.4
28 Applicaion Noe on Image Acquisiion Figure 15: Popup dialog in HDevelop signaling a imeou. gen 1 exern hree imes and hen using he operaor channels o o combine he hree s ino a muli-channel. Please refer o appendix A for more informaion abou HALCON s in general. 6.2 Error Handling Jus as he HALCON frame grabber inerfaces encapsulae he communicaion wih a frame grabber board, 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 frame grabber 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 frame grabber 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 he frame grabber SDK (or in he HALCON inerface) in are signaled by a message box. 6.2.1 Error Handling in HDevelop The HDevelop example hdevelop\error handling imeou picpor.dev shows how o handle HALCON errors in a 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 15 and sops he program. open_framegrabber (FGName, 1, 1, 0, 0, 0, 0, defaul, -1, defaul, -1, rue, CameraType, Device, -1, -1, FGHandle) se_framegrabber_param (FGHandle, grab_imeou, 2000) grab_ (Image, FGHandle) HALCON les you modify he reacion o an error wih he operaorse 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, HALCON Applicaion Guide, 2005-02-01
6.2.2 Error Handling Using HALCON/C 29 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 ino 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, FGHandle) 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 Frame ber Inegraion Programmer s Manual. 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 ograb is esed again. if (ErrorNum = 5322) se_framegrabber_param (FGHandle, exernal_rigger, false ) dev_error_var (ErrorNum, 1) dev_se_check ( ~give_error ) grab_ (Image, FGHandle) 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 operaorge error ex. if (ErrorNum # H_MSG_TRUE) ge_error_ex (ErrorNum, ErrorTex) endif If your frame grabber 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.2.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 c\error handling imeou picpor.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: HALCON 6.1.4
30 Applicaion Noe on Image Acquisiion se_check ("~give_error"); error_num = grab_ (&, fghandle); se_check ("give_error"); swich (error_num) { case H_ERR_FGTIMEOUT: As you see, in a C program you can use prefined consans for he error codes (see he Frame ber Inegraion Programmer s Manual for a lis of acquisiion error codes and heir corresponding consans). 6.2.3 Error Handling Using HALCON/C++ If your applicaion is based on HALCON/C++, here are wo mehods for error handling: If you use operaors in heir C-like form, i.e., preceeded by a double colon (e.g.,::grab ), you can apply he same procedure as described for HALCON/C in he previous secion. In addiion, HALCON/C++ provides an excepion handling mechanism based on he class HExcepion, which is described in he HALCON/C++ User s Manual. Whenever a HAL- CON 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 cpp\error handling imeou picpor.cpp, which performs he same ask as he examples in he previous secions. In he example programcpp\error handling imeou picpor.cpp (preconfigured for he HALCONPicPor inerface), he procedure which is o be called upon error is very simple: I jus raises a sandard C++ excepion wih he insance ofhexcepion as a parameer. void MyHalconExcepionHandler(cons HExcepion& excep) { hrow excep; } In he program, you insall his procedure via a class mehod ofhexcepion: in main(in argc, char *argv[]) { HExcepion::InsallHHandler(&MyHalconExcepionHandler); Now, you reac o a imeou wih he following lines: ry { = framegrabber.image(); } cach (HExcepion excep) { if (excep.err == H_ERR_FGTIMEOUT) { framegrabber.seframegrabberparam("exernal_rigger", "false"); HALCON Applicaion Guide, 2005-02-01
6.2.4 Error Handling Using HALCON/COM 31 As already noed, if your frame grabber inerface does no provide he parameer exernal rigger, you can realize a similar behavior by closing he connecion and hen opening i again wihexernaltrigger se o false : if (excep.err == H_ERR_FGTIMEOUT) { framegrabber.openframegrabber(fgname, 1, 1, 0, 0, 0, 0, "defaul", -1, "gray", -1, "false", camype, "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.2.4 Error Handling Using HALCON/COM The HALCON/COM inerface uses he sandard COM error handling echnique where every mehod call passes boh a numerical and a exual represenaion of he error o he calling framework. How o use his mechanism is explained in he Visual Basic example program vb\error handling imeou picpor\error handling imeou picpor.vbp, which performs he same ask as he examples in he previous secions. For each mehod, you can specify an error handler by insering he following line a he beginning of he mehod: On Error GoTo ErrorHandler A he end of he mehod, you inser he code for he error handler. If a runime error occurs, Visual Basic auomaically jumps o his code, wih he error being described in he variable Err. However, he reurned error number does no correspond direcly o he HALCON error as in he oher programming languages, because low error numbers are reserved for COM. To solve his problem HALCON/COM uses an offse which mus be subraced o ge he HALCON error code. This offse is accessible as a propery of he classhsysemx: ErrorHandler: Dim sys As New HSysemX ErrorNum = Err.Number - sys.errorbasehalcon The following code fragmen checks wheher he error is due o a imeou. If yes, he program disables he exernal rigger mode and ries again o grab an. If he grab is successful he program coninues a he poin he error occurred; oherwise, he Visual Basic defaul error handler is invoked. Noe ha in conras o he oher programming languages HALCON/COM does no provide consans for he error codes. If (ErrorNum = 5322) Then Call FG.SeFramegrabberParam("exernal_rigger", "false") Se Image = FG.Image Resume Nex If he error is no caused by a imeou, he error handler raises i anew, whereupon he Visual Basic defaul error handler is invoked. HALCON 6.1.4
32 Applicaion Noe on Image Acquisiion Else Err.Raise (Err.Number) End If If your frame grabber 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. Noe ha he class HFramegrabberX does no provide a mehod o close he connecion; insead you mus desroy he variable wih he following line: Se FG = Nohing 6.3 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 an heigh; wheher he heigh is 1, i.e., a single line, or larger does no maer. In fac, in many line scan applicaions he frame grabber 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 frame grabber 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, HAL- CON 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 hdevelop\line scan.dev. The program is based on an file sequence which is read using he HALCON virual frame grabber inerfacefile; 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, FGHandle) 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 HALCON Applicaion Guide, 2005-02-01
6.3 Line Scan Cameras 33 a) 1 2 3 b) 1 2 3 4 c) 1 2 3 4 5 6 Figure 16: 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 ). 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 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 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 16, 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 HALCON 6.1.4
34 Applicaion Noe on Image Acquisiion he coordinae frame of he curren ; his means ha he merged par of clip no. 1 has negaive coordinaes. In he nex ieraion (figure 16b), 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 16c), 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 operaormove 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, herefore 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 from he iled using crop par, and he curren is merged a he boom using ile s offse: crop_par (TiledImage, TiledImageMinusOldes, ImageHeigh, 0, ImageWidh, (MaxImagesRegions - 1) * ImageHeigh) ImagesToTile := [TiledImageMinusOldes,Image] 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 arrow in figure 16c); 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 usingadd channels: move_region (FinishedClips, ClipsInTiledImageCoordinaes, (MaxImagesRegions-1) * ImageHeigh, 0) shape_rans (ClipsInTiledImageCoordinaes, AroundClips, recangle1 ) add_channels (AroundClips, TiledImage, GrayValuesAroundClips) HALCON Applicaion Guide, 2005-02-01
A HALCON Images 35 Appendix A 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 (ypereal) 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 a frame grabber selecing a value > 8 for he parameer BisPerChannel, a subsequengrab reurns anuin2. 3. Arbirarily-shaped region of ineres Besides he pixel informaion, each HALCON 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 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. HALCON 6.1.4
36 Applicaion Noe on Image Acquisiion 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 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 i 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 parameerimage ofmean ), i suppors uple processing; if i is described as or (mulichannel-) (e.g., he parameer Image offind 1d 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.1). 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 orcompose2 ec., and add channels o an usingappend channel. HALCON Applicaion Guide, 2005-02-01
A.3.3 Domain 37 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 oreduce domain. A.3.4 Access Operaors for accessing infomaion 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.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. 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. HALCON 6.1.4
38 Applicaion Noe on Image Acquisiion B Parameers Describing he Image When opening a connecion wihopen framegrabber, you can specify he desired forma, e.g., is size or he number of bis per pixel, using 9 parameers, which are described in he following. B.1 Image Size The following 6 parameers influence he size of he grabbed s: HorizonalResoluion and VericalResoluion 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 17b. 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 also called cropping. In figure 17, 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. Please noe ha in mos cases you ge no direc effec on he performance in form of a higher frame rae; excepions are CMOS cameras which adap heir frame rae o he requesed size. Subsampling or cropping on he sofware side has no effec on he frame rae; besides, you can achieve a similar resul using reduce domain. If he frame grabber execues he subsampling or cropping you may ge a posiive effec if he PCI bus is he boleneck of your applicaion and prevens you from geing he a) c) b) d) Figure 17: 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. HALCON Applicaion Guide, 2005-02-01