HALCON 10 Image Acquisition Interface for IDS FALCON and EAGLE Boards

This page provides the documentation of the HALCON FALCON image acquisition interface 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: 4.1

System Requirements

• Intel compatible PC with Windows XP/Vista/7 or x86 Linux with Kernel 2.4.19 (or higher).
• Windows: IDS driver falcon.sys version 4.0 or higher.
  Typically, this file resides in the directory %WINDIR\system32\drivers.
  Linux: Successfully compiled FALCON/EAGLE kernel module falcon.ko version 4.40.0012 (or higher).
  Typically, this file resides in the directory /lib/modules/.../kernel/media/video.
  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.
• Windows: 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).
  Linux: FALCON/EAGLE shared library falcon.so version 4.40.0012 (or higher).
  Typically, the shared library resides in the directory /usr/lib.
  If you do not have this file, please contact IDS Imaging Development Systems GmbH or the vendor from which you bought the frame grabber board.
• Windows: HALCON image acquisition interface hAcqFALCON.dll or hAcqFALCONxl.dll, respectively.
  If you have properly installed the interface, both DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
  Linux: HALCON image acquisition interface hAcqFALCON.so or hAcqFALCONxl.so, respectively. Both files should reside in the directory lib/$HALCONARCH within the HALCON base directory $HALCONROOT.

Features

• 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 and FALCONplus only).
• Software control of the strobe parameters (EAGLE only).

Limitations

• Multiple connected cameras per frame grabber board only possible with duo/quattro boards.
• If the image to be grabbed is not yet available when calling grab_image_async, the interface performs busy waiting, i.e., the corresponding program thread is busy until the image is available or a timeout is reached.
• Image scaling and image cropping is not possible simultaneously.
• grab_data and grab_data_async not supported.
• No LUTs.

Using Multiple Boards

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('FALCON','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 image acquisition handles independently within you application.

Description

Parameters for open_framegrabber():

	Name		'FALCON'		The name of the HALCON image acquisition 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'.
	Generic		---		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'		EAGLE: 'enable', 'disable' FALCONplus: 0 - 255		Sets digital output (supported by EAGLE and FALCONplus boards only). Default: 'disable' or 0.
	'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 image acquisition 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. Furthermore, corresponding to the parameters supported by set_framegrabber_param, there may exist additional read-only parameters with the following postfixes:

• '_description': These parameters provide the tooltip of the corresponding parameter as a string.
• '_range': These parameters provide the minimum, maximum, stepwidth, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(..,'exposure_range',..) will return the output tuple [min,max,step,default]. Optionally, this tuple can also contain additional valid string values like 'auto' or 'manual'.
• '_values': These parameters provide the valid value list for the corresponding parameter as a tuple, e.g., get_framegrabber_param(..,'volatile_values',..) will return the output tuple ['enable','disable'].

	'board'		board info		Serial number, type, version, and date of the board.
	'digital_input'		EAGLE: 'enable', 'disable' FALCONplus: 0 - 255		Reads the digital input (supported by EAGLE and FALCONplus boards only).
	'revision'		revision		Revision of the HALCON FALCON image acquisition interface.

Release Notes

• Revision 4.1 (Aug 25, 2010):
  • Parameter 'show_internal_errors' now obsolete; please use set_system('do_low_error', ...) instead.
  • Added note about busy waiting in limitations section.
  • HALCON 10 version of the interface (legacy only).
• Revision 4.0 (Dec 1, 2008):
  • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
• Revision 3.1 (Apr 22, 2008):
  • Added read-only parameters with postfix '_description', '_range', and '_values' to enable the easy parameterization via a generic graphical user interface.
• Revision 3.0 (May 15, 2007):
  • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
  • Renaming the interface name from 'IDS' into 'FALCON' to avoid confusion amongst all available interfaces to IDS products.
  • Support of the Linux driver for FALCON/EAGLE boards.
• Revision 2.6 (Sep 27, 2005):
  • Support of the digital output lines for FALCONplus boards.
• Revision 2.5 (Dec 16, 2004):
  • HALCON 7.1 version of the interface (included in HALCON 7.1 CD).
  • New parameters 'strobe_invert', 'strobe_mode', and 'strobe_line' for controlling the strobe output (supported by EAGLE boards only).
  • New parameter 'start_async_after_grab_async'.
  • The query types 'bits_per_channel', 'camera_type', 'color_space', 'device', 'external_trigger', 'field', and 'port' for info_framegrabber provide now specific value lists for the corresponding parameters in open_framegrabber.
• Revision 2.4 (Jan 21, 2003):
  • HALCON 7.0 version of the interface (included in HALCON 7.0 CD).
  • The continuous grabbing mode no more uses explicit buffer locking to avoid sporadic grabbing failures.
  • Bugfix in entering continuous mode while waiting for a pending asynchronous grab.
  • Initializing sequence counter when entering continuous grabbing mode.
• Revision 2.3 (Feb 20, 2002):
  • HALCON 6.1 version of the interface (included in HALCON 6.1 CD).
  • Bugfix in grabbing color images with BitsPerChannel=5.
  • Enabling non-interlaced mode (Field='progressive') while grabbing in full vertical resolution.
  • Unification of the internal error management (parameter 'show_internal_errors' now obsolete; use operator set_system('do_low_error', 'true') instead).
• Revision 2.2 (Sep 10, 2001):
  • Support of FALCONduo, FALCONquattro, EAGLEduo, EAGLEquattro boards.
  • Adaptation to IDS driver version 4.00.
• Revision 2.1 (Nov 20, 2000):
  • Parameter 'show_internal_errors' now global.
  • Query board information via info_framegrabber() .
• Revision 2.0 (Sep 20, 2000):
  • Adaptation to the HALCON 6.0 frame grabber integration interface.
  • Color mode setting via BitsPerChannel and ColorSpace parameters in open_framegrabber().
• Revision 1.14 (May 12, 2000):
  • Support of FALCONplus boards.
  • New parameter 'port' facilitates port switching via set_framegrabber_param.
  • Field grabbing possible without scaling (set FGWidth=1 and FGHeight=2).
  • Bugfix in continuous mode to avoid "mixed-up" fields.
  • Bugfix in cropping image parts when grabbing color images.
  • Adaptation to IDS driver version 3.00.
• Revision 1.13 (Feb 15, 2000):
  • Bugfix in simultaneous grabbing from two boards in continuous mode.
  • Encapsulation of all beeps and error messages.
• Revision 1.12 (Apr 23, 1999):
  • HALCON 5.2 version of the interface (included in the HALCON 5.2 CD).
  • Bug in evaluation of parameter Field fixed (if set to 'first' while subsampling).
• Revision 1.11 (Mar 25, 1999):
  • Prerelease of HALCON 5.2 version of the interface (included in the HALCON 5.2 prerelease CD).
  • New parameter 'continuous_grabbing' to start round robin.
  • Reading/writing the digital input/output.
  • Camera sync-generator.
• Revision 1.3 (Oct 3, 1998):
  • Multiple frame grabber boards possible now; new parameters 'chromU', 'chromV' to change U- and V- value of color saturation via set_framegrabber_param.
• Revision 1.2 (Aug 3, 1998):
  • First official release.