HALCON 5.2 Frame Grabber Interface for IDS FALCON, FALCONplus, and EAGLE Boards

This document provides the documentation of the HALCON frame grabber interface IDS.dll for the IDS frame grabber boards FALCON, FALCONplus, and EAGLE. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 1.15

• Intel compatible PC with Windows NT 4.0 (Service Pack 4) or Windows 2000.
• IDS driver falcon.sys version 3.00 or higher.
  Typically, this file resides in the directory C:\Winnt\system32\drivers. If you do not have this driver, please contact IDS or the vendor from which you bought the frame grabber board.
• IDS DLL falcon.dll version 3.00 or higher.
  This DLL must be within your search path %PATH% (typically, it resides in the directory C:\Winnt\system32). If you do not have this DLL, please contact IDS or the vendor from which you bought the frame grabber board.
• HALCON frame grabber interface IDS.dll.
  If you have properly installed the interface, IDS.dll should reside in bin\i486-nt4 within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.

• Multiple frame grabber boards.
• Synchronous and asynchronous grabbing.
• Field grabbing up to 60 fields per second.
• Subsampling.
• Image cropping (not allowed while scaling).
• External trigger (EAGLE only).
• Optional: Automatic gain control.
• Optional: Gamma correction.
• Software control of brightness, contrast, and hue.
• Software control of the type of trigger signal.
• Software control of horizontal and vertical smoothing filters.
• Setting/reading digital input and digital output (EAGLE only).

• Only one connected camera per frame grabber board.
• Image scaling AND cropping simultaneously is not possible.
• grab_region() and grab_region_async() not supported.
• No LUTs.

Parameters for open_framegrabber():

	Name	'IDS'	The name of the HALCON frame grabber interface.
	FGWidth	1, 2, 4, width	The desired image resolution. Use '1' for full resolution, '2' for subsampling by factor 2, '4' for subsampling by factor 4, or the corresponding absolute values like 640, 320, 160 (NTSC) or 768, 384, 192 (PAL). Default: 1.
	FGHeight	1, 2, 4, height	The desired image resolution. Use '1' for full resolution, '2' for subsampling by factor 2, '4' for subsampling by factor 4, or the corresponding absolute values like 480, 240, 120 (NTSC) or 576, 288, 144 (PAL). Note that you can achieve field grabbing if FGWidth=1 and FGHeight=2. In this case the Field parameter will specify the desired field type. Default: 1.
	Width	0, width	The width of the desired image part ('0' stands for the complete image). This value has to be equal or smaller than the maximum image width. Default: 0.
	Height	0, height	The height of the desired image part ('0' stands for the complete image).This value has to be equal or smaller than the maximum image height. Default: 0.
	StartRow	0, row	The row coordinate of the upper left pixel within the desired image part. If Height is set to 0, then both the first AND last StartRow rows of the image matrix are discarded. Default: 0.
	StartColumn	0, column	The column coordinate of the upper left pixel within the desired image part. If Width is set to 0, then both the first AND last StartColumn columns of the image matrix are discarded. Default: 0.
	Field	'first', 'second', 'next', 'interlaced', 'progressive'	When grabbing in full resolution (FGWidth=FGHeight=1) you can control how to handle the two fields: Use 'interlaced' for grabbing whole frames or 'progressive' to arrange the two fields upon another. In case of subsampling you can control which fields will be grabbed: To grab specific fields use 'first' for the odd field or 'second' for the even field; using 'next' you can achieve full field rate (there will be a line jitter as every field is grabbed), and using 'interlaced' always both fields are grabbed and scaled. Default: 'interlaced'.
	Bits	8, 16, 24	Number of bits per pixel: Grayscale (8 bits) or color (16 and 24 bits). The 16 bit mode is used to reduce the PCI bus load (5 bits R/B channel, 6 bits G channel). You will get an 24 bit HALCON image in this case, too. Default: 24.
	ColorSpace	---	Ignored.
	Gain	---	Ignored.
	ExternalTrigger	'true', 'false'	Activate/deactivate external triggering. External triggering is supported by the EAGLE board only. Default: 'false'.
	Generic	'NTSC', 'PAL', 'SECAM', 'AUTO', 'S-NTSC', 'S-PAL', 'S-SECAM', 'S-AUTO'	The generic parameter is used to specify the video signal: 'NTSC', 'PAL', 'SECAM', or 'AUTO'. For the parameterization of an EAGLE board, please use 'S-xxx' to specify a S-Video input signal (otherwise, a composite signal is assumed). Parameterizing a FALCON board the distinction between S-Video and composite signals is implicitly done via the Port setting. Default: 'AUTO'.
	Device	'0', '1', '2', ...	The number of the frame grabber board (passed as a string!). Default: '0' (searches for the first board).
	Port	FALCON: 0, 1, 2 FALCONplus: 0, 1, 2, 3 EAGLE: 0, 1, 2, 3	Specifies the video input (together with the parameters Bits and Generic). For a FALCON board '0' and '1' are used for composite video, '2' is used for S-Video. FALCONplus uses all four ports for composite video input only. An EAGLE board can read S-Video or composite signals from all ports. In this case, the distinction between S-Video and composite is done via the 'Generic' parameter. Default: 0.
	LineIn	---	Ignored.

Parameters for set_framegrabber_param():

	'volatile'	'enable', 'disable'	Grayscale only. In the volatile mode the two frame grabber interface buffers are used directly to store HALCON images. This is the fastest mode avoiding to copy raw images in memory. However, be aware that older images are overwritten again and again as a side-effect. Thus, you can only process one image while you grab another image. Older images are invalid! Default: 'disable'.
	'agc'	'enable', 'disable'	Enables or disables automatic gain control.
	'brightness'	0 - 255	Changes brightness of an image. Default: 128.
	'contrast'	0 - 511	Changes contrast between 0% and 200%.
	'gamma'	'enable', 'disable'	Switch gamma correction on ('enable') and off ('disable').
	'hue'	0 - 255	Changes the hue of a color image (no effect on grayscale images). Default: 128.
	'chromU'	0 - 511	Changes U-value of color saturation. Default: 254.
	'chromV'	0 - 511	Changes V-value of color saturation. Default: 180.
	'synclevel'	75, 125	Sets sync level to 75 mV or 125 mV.
	'trigger_signal'	'rising', 'falling'	Specify the desired type of trigger signal: rising (default) or falling edge.
	'show_internal_errors'	'true', 'false'	Specify whether the frame grabber interface should pop up an alert box in case of an error or not. If you use your own error management, we recommend to switch off the internal error display. In this mode only the error code is returned by the frame grabber operators, but the interface itself is "silent" (important for inline applications etc.). Otherwise, the user has to click on one of the buttons in the error dialog. On the other side, activated internal error display will result in more detailed and specific error messages for trouble shooting. Default: 'true'.
	'horfilter'	0, 1, 2, 3	Turns on a horizontal interpolation filter. There are 3 filters available: 1 (weak filtering), 2 (normal filtering), and 3 (strong filtering); 0 turns the filter off.
	'vertfilter'	0, 1, 2, 3	Turns on a vertical interpolation filter. There are 3 filters available: 1 (weak filtering), 2 (normal filtering), and 3 (strong filtering); 0 turns the filter off. Attention: The filter mode 2 (3) can only be used in combination with horizontal subsampling of at least factor 2 (4), see parameter FGWidth in open_framegrabber().
	'grab_timeout'	100 - 327680	Sets a timeout value for grabbing (in ms). After grab_timeout milliseconds the grabbing routine returns with a timeout error.
	'suppress_errors'	'true', 'false'	When set to 'true', FIFO overruns (resulting from PCI transfer problems) are ignored; otherwise, an error is returned. Default: 'false'.
	'suppress_error_beep'	'true', 'false'	When set to 'false', a "Beep" is produced every time a FIFO overrun occurs. Beeping can be switched off by setting 'suppress_error_beep' to 'true'. Default: 'false'.
	'continuous_grabbing'	'enable', 'disable'	Sets grabbing mode from single frame capture to continuous mode. If the continuous mode is enabled, the frame grabber board will grab all the time. In this mode you can achieve full frame rate (or full field rate when subsampling the image). Default: 'disable'.
	'digital_output'	'enable', 'disable'	Sets digital output (supported by the EAGLE board only). Default: 'disable'.
	'camera_sync'	'enable', 'disable'	Turns camera sync-generator on or off (supported by the EAGLE board only).
	'port'	number	Switch to a camera connected to the specified port number. See also the description of the parameter Port in open_framegrabber().

Parameters for get_framegrabber_param():

Additional parameters supported by get_framegrabber_param() only. Note that all parameters supported by set_framegrabber_param() can also be accessed by get_framegrabber_param().