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-2008 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 on page 4). 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 5. 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 7) in differen iming modes (see secion 5 on page 16). 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 subdirecory hdevelop\image\framegrabber of he direcory %HALCONROOT%\examples. Please refer o he Programmer s Guide, chaper 6 on page 57 and chaper 14 on page 107, 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 subdirecory i586-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) Ediion 2 December 2003 (HALCON 7.0) 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.halcon.com/
3 Conens 1 The Philosophy Behind he HALCON Frame ber Inerfaces 4 2 A Firs Example 5 3 Connecing o Your Frame ber 7 3.1 Opening a Connecion o a Specified Configuraion.................... 7 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..................................... 13 4.2 Special Parameers..................................... 14 4.3 Fixed vs. Dynamic Parameers............................... 15 5 The Various Modes of bing Images 16 5.1 Real-Time Image Acquisiion................................ 16 5.2 Using an Exernal Trigger.................................. 25 5.3 Acquiring Images From Muliple Cameras......................... 27 6 Miscellaneous 29 6.1 Acquiring Images From Unsuppored Frame bers.................. 29 6.2 Error Handling....................................... 30 6.3 Line Scan Cameras..................................... 34 A HALCON Images 37 A.1 The Philosophy of HALCON Images............................ 37 A.2 Image Tuples (Arrays)................................... 38 A.3 HALCON Operaors for Handling Images......................... 38 B Parameers Describing he Image 40 B.1 Image Size......................................... 40 B.2 Frames vs. Fields...................................... 41 B.3 Image Daa......................................... 44
4 Applicaion Noe on Image Acquisiion 1 The Philosophy Behind he HALCON Frame ber 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 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, swiching o a differen frame grabber probably requires 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: 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++ / 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: 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_ (or grab async, see secion 5.1 on page 16 for he difference) grabs s. 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 on page 12).
2 A Firs Example 5 a) b) Firs Example Figure 2: a) Acquired ; b) processed (auomaic segmenaion). Noe, ha for some frame grabbers 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/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 on page 29 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, hen press Run once o iniialize he applicaion. 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), by which you can access he frame grabber, 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 13 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 7.
6 Applicaion Noe on Image Acquisiion 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 on page 16. 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 7 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 operaor open_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. 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 Connecing SDK & IAI A SDK & IAI B frame grabber board 0 frame grabber board 1 por 0 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: Describing a connecion wih he parameers of open_framegrabber.
8 Applicaion Noe on Image Acquisiion check box o sar online grabbing double click handle o open dialog Figure 4: Online grabbing in HDevelop. 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). 3.2 Connecing o Muliple Boards and Cameras Mos HALCON frame grabber 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.halcon.com/framegrabber) which configuraions i suppors. 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 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 9 a) b) handle 0 frame grabber por 0 handle 0 frame grabber por 0 board 0 board 0 handle 1 frame grabber por 0 board 1 c) handle 0 handle 1 frame grabber board 0 por 0 por 1 d) handle 0 frame grabber por 0 handle 2 frame grabber board 1 por 0 por swich board 0 por 1 Connecing e) f) por 0 frame grabber handle 0 frame grabber por 0 handle 0 board 0 por 1 HImage[2] board 0 por 1 HImage[3] frame grabber por 0 board 1 Figure 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.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 HALCON PX inerface; o use i wih a differen frame grabber, please adap he pars which open he connecion.
10 Applicaion Noe on Image Acquisiion 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 parameer Device ( 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 o open_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 do no access he cameras via muliple handles, bu by swiching he inpu por dynamically (see figure 5d). Therefore, open_framegrabber is called only once, like in he HDevelop example program hdevelop\por_swiching_inspeca.dev (preconfigured for he HALCON INSPECTA 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, MyCamType, defaul, 0, -1, FGHandle) Beween grabbing s you swich pors using he operaor se_framegrabber_param (see secion 4.2 on page 14 for more informaion abou his operaor):
3.2.5 Simulaneous bing 11 se_framegrabber_param (FGHandle, por, Por0) grab_ (Image0, FGHandle) se_framegrabber_param (FGHandle, por, Por1) grab_ (Image1, FGHandle) 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 on page 37 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. 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 INSPECTA inerface, please adap he pars which open he connecion for your own frame grabber): Connecing open_framegrabber (FGName, 1, 1, 0, 0, 0, 0, defaul, -1, defaul, -1, defaul, MyCamType, defaul, 0, -1, FGHandle) You can check he number of reurned s (channels) using he operaor coun_channels grab_ (SimulImages, FGHandle) 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 frame grabber inerfaces allow simulaneous grabbing also for muliple boards (see figure 5f). Please refer o secion 5.3.2 on page 28 for addiional informaion. 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 HAL- CON 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.
12 Applicaion Noe on Image Acquisiion Figure 6: An example resul of 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 operaor info_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. 4 Configuring he Acquisiion As explained in secion 1 on page 4, he inenion of HALCON s frame grabber inerfaces is o provide he user wih a common inerface for many differen frame grabbers. This inerface is 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
4.1 General Parameers 13 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 on page 40) size and upper lef corner of he ransferred in relaion o he original size (see appendix B.1 on page 40) grabbing mode for analog cameras, e.g., inerlaced-scan, progressive-scan, field grabbing (see appendix B.2 on page 41) daa conained in a pixel (number of bis, number of channels, color encoding, see appendix B.3 on page 44) 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 on page 25) configuraion of frame grabber(s) and camera(s) from which s are o be acquired (see secion 3.1 on page 7) Configuring In secion 3.1 on page 7, 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 40. The parameer ExernalTrigger acivaes a special grabbing mode which is described in deail in secion 5.2 on page 25. 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 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 on page 11. Afer connecing o a frame grabber, you can query he curren value 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 15 for more informaion abou hese opics.
14 Applicaion Noe on Image Acquisiion 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 operaor se_framegrabber_param. Typical parameers are, for example: grab_imeou volaile coninuous_grabbing rigger_signal _widh, _heigh, sar_row, sar_column, gain, exernal_rigger, por 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 27 and secion 6.2 on page 30) enable volaile grabbing (see also secion 5.1.3 on page 18) swich on a special acquisiion mode which is necessary for some frame grabbers o achieve real-ime performance (see also secion 5.1.5 on page 22) 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 13, 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 on page 34), 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 on page 10 he following line was used o swich o por 0: se_framegrabber_param (FGHandle, 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 (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 infor-
4.3 Fixed vs. Dynamic Parameers 15 Figure 7: Querying available special parameers via info_framegrabber. maion 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) Configuring 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 on page 14, 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.
16 Applicaion Noe on Image Acquisiion 5 The Various Modes of bing Images Secion 2 on page 5 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. 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 on page 41 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 on page 19, 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
5.1.1 Non-Real-Time bing Using grab_ 17 camera original frame rae original frame rae original frame rae expose expose expose expose ransfer (analog) frame grabber wai for vsync digiize wai for vsync digiize ransfer (DMA) IAI & SDK wai for creae HImage wai for creae HImage 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). 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. bing 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:
18 Applicaion Noe on Image Acquisiion 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 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 UNIX sysems, 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 on page 17). 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. 5.1.3 Volaile bing As shown in figure 8 on page 17, 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 of grab_. 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 operaor se_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!
5.1.3 Volaile bing 19 original frame rae camera expose expose ransfer (analog) frame grabber Expose wai for vsync digiize Expose wai for vsync digiize ransfer (DMA) IAI & SDK wai for creae HImage wai for creae HImage 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). 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 on page 23. 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 bing 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:
20 Applicaion Noe on Image Acquisiion 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 5.1.4 Real-Time bing 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 10 shows a corresponding iming diagram: The firs call o grab async is processed similar o grab_ (compare figure 8 on page 17). 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 on page 22 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 on page 16, he reached frame rae for asynchronous processing is deermined as follows:
5.1.4 Real-Time bing Using grab async 21 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) 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 10: bing and processing in parallel using grab async. 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 bing 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 calling grab 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 on page 24 for deails.
22 Applicaion Noe on Image Acquisiion 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 on page 28). 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 enabled 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. Noe ha some frame grabber inerfaces provide addiional funcionaliy in he coninuous grabbing mode, e.g., he HALCON BiFlow inerface. 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 18, you can acquire s wihou delay by using an asynchronously reseable camera. Figure 12 shows he resuling iming when using such a camera ogeher wih grab async. When comparing he diagram o he one in figure 9 on page 19, you can see ha a higher frame rae can now be reached, because he processing ime is no included anymore.
5.1.6 Using grab async Togeher Wih Asynchronously Reseable Cameras 23 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) 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 grabber ransfer digiize digiize digiize bing (DMA) 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 11: a) grab async fails o reach frame rae; b) problem solved using coninuous grabbing.
24 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) IAI & SDK wai for creae HImage wai for creae HImage 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 on page 19. 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 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 frame grabber SDKs provide his informaion; herefore, he las grab command from he inerface o he frame grabber is used as he saring poin insead.
5.2 Using an Exernal Trigger 25 camera expose expose expose expose ransfer (analog) frame grabber digiize digiize digiize digiize ransfer (DMA) IAI & SDK sofware applicaion wai for > MaxDelay? NO > MaxDelay? YES creae HImage creae HImage wai for process process process process grab async Figure 13: Specifying a maximum delay for grab async (using coninuous grabbing). 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; 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. bing
26 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) 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) 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 14: Using an exernal rigger ogeher wih: a) free-running camera and grab_; b) asynchronously reseable camera and grab async. The (bad) example in figure 14a 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
5.2.1 Special Parameers for Exernal Triggers 27 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 14b. The C++ example program cpp\error_handling_imeou_picpor.cpp (preconfigured for he HALCON Leuron inerface) shows how simple i is o use an exernal rigger: The connecion is opened wih ExernalTrigger 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: HImage ; 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 on page 32. 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 on page 14, 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 on page 30 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. bing 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 8 for possible configuraions).
28 Applicaion Noe on Image Acquisiion 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 on page 10, 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 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 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 Leuron inerface also allows o grab simulaneously from cameras conneced o muliple boards. As described in secion 3.2.5 on page 11, 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 operaor se_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.
6 Miscellaneous 29 6 Miscellaneous 6.1 Acquiring Images From Unsuppored Frame bers If you wan o use a frame grabber ha is currenly no suppored by HALCON, i.e., for which no HAL- CON 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 HALCON 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 on page 18. 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 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 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 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. 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 gen_1_exern hree imes and Miscellaneous
30 Applicaion Noe on Image Acquisiion Figure 15: Popup dialog in HDevelop signaling a imeou. hen using he operaor channels_o_ o combine he hree s ino a muli-channel. Please refer o appendix A on page 37 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 in he frame grabber SDK (or in he HALCON inerface) 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 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
6.2.2 Error Handling Using HALCON/C 31 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, 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, appendix B on page 69. In he example, he imeou is handled by disabling he exernal rigger mode via he operaor se_framegrabber_param (parameer exernal_rigger ). Then, he call o grab_ 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 operaor ge_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: Miscellaneous
32 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 predefined consans for he error codes (see he Frame ber Inegraion Programmer s Manual, appendix B on page 69, 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, 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 Programmer s Guide, secion 4.3 on page 26. 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 cpp\error_handling_imeou_picpor.cpp, which performs he same ask as he examples in he previous secions. In he example program cpp\error_handling_imeou_picpor.cpp (preconfigured for he HAL- CON Leuron inerface), 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. void MyHalconExcepionHandler(cons Halcon::HExcepion& excep) { hrow excep; } In he program, you insall his procedure via a class mehod of HExcepion: in main(in argc, char *argv[]) { using namespace Halcon; 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");
6.2.4 Error Handling Using HALCON/COM 33 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 wih Exernal- Trigger 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 class HSysemX: 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 Miscellaneous If he error is no caused by a imeou, he error handler raises i anew, whereupon he Visual Basic defaul error handler is invoked.
34 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 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 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, 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 hdevelop\line_scan.dev. The program is based on an file sequence which is read using he HALCON virual frame grabber 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, 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 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.
6.3 Line Scan Cameras 35 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 ). 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 Noe ha he operaor copy_obj does no copy he regions hemselves bu only he corresponding HAL- CON objecs, which can be hough of as references o he acual region daa. Miscellaneous
36 Applicaion Noe on Image Acquisiion 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 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 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: 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 arrows 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 using add_channels: move_region (FinishedClips, ClipsInTiledImageCoordinaes, (MaxImagesRegions-1) * ImageHeigh, 0) shape_rans (ClipsInTiledImageCoordinaes, AroundClips, recangle1 ) add_channels (AroundClips, TiledImage, GrayValuesAroundClips)
A HALCON Images 37 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; HAL- CON akes care of i in a way o guaranee opimal performance. HALCON Images 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 a frame grabber 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 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 on page 39.
38 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 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_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 on page 29). 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 39 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. HALCON Images 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.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.
40 Applicaion Noe on Image Acquisiion B Parameers Describing he Image 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 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 called cropping. In figure 17, 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. 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 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.