HALCON 7.1 Frame Grabber Interface for IDS FALCON and EAGLE Boards
This page provides the documentation of the HALCON 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: 2.7
System Requirements
- Intel compatible PC with Windows NT 4.0 (Service Pack 4), Windows 2000/XP 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, the kernel module 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 libfalcon.so version 4.40.0012 (or higher).
Typically, the shard 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 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.
Linux: HALCON frame grabber interface HFGIDS.so, which should reside in the directory lib/i586-linux2.2-gcc33 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.
- Image scaling and image cropping is not possible simultaneously.
- grab_region() and grab_region_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('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.
Description
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' |
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 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.
| '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 IDS frame grabber interface. | |||
Release Notes
-
Revision 2.7 (Jul 27, 2007):
- 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 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.
