HALCON 6.1 Frame Grabber Interface for IDS FALCON and EAGLE Boards

This page provides the documentation of the HALCON frame grabber interface HFGIDS.dll for the frame grabber boards FALCON, FALCONplus, FALCONduo, FALCONquattro, EAGLE, EAGLEduo, and EAGLEquattro from IDS Imaging Development Systems GmbH. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 2.5

• Intel compatible PC with Windows NT 4.0 (Service Pack 4), Windows 2000 or Windows XP.
• IDS driver falcon.sys version 4.0 or higher.
  Typically, this file resides in the directory %WINDIR\system32\drivers. If you do not have this driver, please contact IDS Imaging Development Systems GmbH or the vendor from which you bought the frame grabber board.
• IDS DLL falcon.dll version 4.0 or higher.
  This DLL must be within your search path %PATH% (typically, it resides in the directory %WINDIR%\system32). If you do not have this DLL, please contact IDS Imaging Development Systems GmbH or the vendor from which you bought the frame grabber board.
• HALCON frame grabber interface HFGIDS.dll or parHFGIDS.dll, respectively.
  If you have properly installed the interface, both DLLs should reside in bin\i586-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).
• Software control of the strobe parameters (EAGLE only).

• Multiple connected cameras per frame grabber board only possible with duo/quattro boards.
• Image scaling and image cropping is not possible simultaneously.
• grab_region() and grab_region_async() not supported.
• No LUTs.

When using multiple IDS boards please make sure that all boards have different device ids. You can manually set these device ids with the auxiliary program IdsID.exe which is part of the IDS driver installation. Note that you can request all actually accessible devices and valid ports by calling the operator info_framegrabber('IDS','info_boards',....).

Since the duo board types FALCONduo and EAGLEduo behave like two independent boards and the quattro board types FALCONquattro and EAGLEquattro behave like four independent boards, you can call open_framegrabber up to four times (with different device parameter values) and use the frame grabber handles independently within you application.

Parameters for open_framegrabber():

	Name		'IDS'		The name of the HALCON frame grabber interface.
	HorizontalResolution		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.
	VerticalResolution		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 HorizontalResolution=1 and VerticalResolution=2. In this case the Field parameter will specify the desired field type. Default: 1.
	ImageWidth		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.
	ImageHeight		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 ImageHeight 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 ImageWidth 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'		In case of full vertical resolution (VerticalResolution=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'.
	BitsPerChannel		5, 8		Number of bits per image channel: Grayscale (8 bits) or color (5 and 8 bit). Specifying 5 bits per channel is only allowed in combination with ColorSpace='rgb' and enables the 5-6-5 bit encoded RGB raw data transfer (reduced PCI bus load!). You will get an 8-8-8 three channel RGB HALCON image in this case, too. Default: 8.
	ColorSpace		'gray', 'rgb'		Specify the desired color space and thus the number of image channels of the resulting HALCON image. Default: 'rgb'.
	Gain		---		Ignored.
	ExternalTrigger		'true', 'false'		Activate/deactivate external triggering. External triggering is supported by the EAGLE board only. Default: 'false'.
	CameraType		'ntsc', 'pal', 'secam', 'auto', 's-ntsc', 's-pal', 's-secam', 's-auto'		Specify the video signal: 'ntsc', 'pal', 'secam', or 'auto'. The latter will do an automatic analysis of the signal. 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 FALCONduo: 0, 1, 2, 3 FALCONquattro: 0, 1, 2, 3 EAGLE: 0, 1, 2, 3 EAGLEduo: 0, 1, 2, 3 EAGLEquattro: 0, 1, 2, 3		Specifies the video input (together with the parameters BitsPerChannel and CameraType). For a FALCON board '0' and '1' are used for composite video, '2' is used for S-Video. FALCONplus/duo/quattro uses all four ports for composite video input only. An EAGLE (duo/quattro) 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 CameraType parameter. Default: 0.
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

	'agc'		'enable', 'disable'		Enables or disables automatic gain control.
	'brightness'		0 - 255		Changes brightness of an image. Default: 128.
	'camera_sync'		'enable', 'disable'		Turns camera sync-generator on or off (supported by EAGLE boards only).
	'chromU'		0 - 511		Changes U-value of color saturation. Default: 254.
	'chromV'		0 - 511		Changes V-value of color saturation. Default: 180.
	'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'.
	'contrast'		0 - 511		Changes contrast between 0% and 200%.
	'digital_output'		'enable', 'disable'		Sets digital output (supported by EAGLE boards only). Default: 'disable'.
	'gamma'		'enable', 'disable'		Switch gamma correction on ('enable') and off ('disable').
	'grab_timeout'		100 - 327680		Sets a timeout value for grabbing (in ms). After grab_timeout milliseconds the grabbing routine returns with a timeout error. Default: 5000.
	'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.
	'hue'		0 - 255		Changes the hue of a color image (no effect on grayscale images). Default: 128.
	'port'		number		Switch to a camera connected to the specified port number. See also the description of the parameter Port in open_framegrabber().
	'start_async_after_grab_async'		'enable', 'disable'		By default, at the end of grab_image_async a new asynchronous grab command is automatically given to the frame grabber board. If the parameter 'start_async_after_grab_async' is set to 'disable' this new grab command is omitted. This might be useful especially for switching between several connected cameras. Default: 'enable'.
	'strobe_invert'		'true', 'false'		When set to 'true', the strobe signal is inverted (supported by EAGLE boards only). Default: 'false'.
	'strobe_line'		num		Specifies the image line, where the strobe signal should be started (supported by EAGLE boards only).
	'strobe_mode'		'off', 'odd', 'even', 'both'		Specifies the field which activates the strobe (supported by EAGLE boards only). Default: 'off'.
	'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 this parameter to 'true'. Default: 'false'.
	'suppress_errors'		'true', 'false'		When set to 'true', FIFO overruns (resulting from PCI transfer problems) are ignored; otherwise, an error is returned. Default: 'false'.
	'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.
	'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 HorizontalResolution in open_framegrabber().
	'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'.

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.