HALCON 7.0 Frame Grabber Interface for IDS uEye USB 2.0 Cameras
This page provides the documentation of the HALCON uEye frame grabber interface for the uEye USB 2.0 cameras from IDS Imaging Development Systems GmbH. Registered customers can download the latest revision of this interface from the MVTec WWW server.
Revision: 2.8
System Requirements
- Intel compatible PC with Windows 2000/XP or x86 Linux with Kernel 2.6.3 (or higher) and USB 2.0 interface.
-
Windows: uEye driver uEye_usb.sys version 2.20.0000
or higher.
Typically, this file resides in the directory %WINDIR\system32\drivers.
Linux: successfully compiled uEye kernel module ueye_usb_driver.ko version 2.21.0000 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 camera. -
Windows: uEye DLL uEye_api.dll version 2.20.0000
or higher.
This DLL must be within your search path %PATH% (typically, it resides in the directory %WINDIR%\system32).
Linux: uEye shared library libueye_api.so version 2.21.0000 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 camera. -
Windows: HALCON frame grabber interface HFGuEye.dll or
parHFGuEye.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 HFGuEye.so which should reside in the directory lib/i586-linux2.2-gcc33 within the HALCON base directory %HALCONROOT%.
Features
- Multiple cameras.
- Synchronous and asynchronous grabbing.
- Image cropping.
- External trigger with adjustable trigger delay.
- Software control of frame rate, exposure, and pixel clock settings.
- Software control of brightness, contrast, and edge enhancement.
- Software control of gain, gamma correction, and white balancing.
- Software control of the strobe parameters.
- Software control of the digital input and output port.
- FALCON/EAGLE compatibility mode.
Limitations
- grab_region and grab_region_async not supported.
- No LUTs.
Using Multiple Cameras
When using multiple uEye cameras please make sure that each cameras has an unique device ID. You can manually set these device IDs by use of the auxiliary program uEyeID.exe under Windows (or ueyesetid under Linux, respectively) which is part of the uEye driver installation. Note that you can request all actually accessible devices and valid ports by calling the operator info_framegrabber('uEye','info_boards',....).
FALCON/EAGLE Compatibility Mode
The FALCON/EAGLE compatibility mode enables the backward compatibility to the HALCON interface to FALCON and EAGLE boards, i.e., you can easily port an existing application. You can enable the FALCON/EAGLE compatibility mode either by specifying one of the possible camera type values 'auto', 'pal', 'ntsc', 'secam', 's-auto', 's-pal', 's-ntsc' or 's-secam' during open_framegrabber, or by calling set_framegrabber_param(...,'compatibility_mode','enable') explicitly.
If the FALCON/EAGLE compatibility mode has been enabled you can also use all the parameters of the FALCON/EAGLE interface (such as 'hue' or 'synclevel'). However, these settings will have no effect on the uEye cameras. Furthermore, there exist the following limitations:
- Since the frame rate depends on the system performance the actual frame rate can be different.
- The uEye camera provides only one video port, thus port switching is not possible.
- If you use the CameraType values '(s-)pal' and '(s-)secam' the actual sensor size of the uEye camera must be at least [768, 576].
Description
Parameters for open_framegrabber():
| Name | 'uEye' | The name of the HALCON frame grabber interface. | |||
| HorizontalResolution | 1, 2, 4 | The desired horizontal image resolution. Use 1 for full resolution, 2 or 4 for subsampling (or binning, depends on what the camera model supports) by factor 2 or 4, respectively. Note that not all uEye models support subsampling or binning. Default: 1. | |||
| VerticalResolution | 1, 2, 4 | The desired vertical image resolution. Use 1 for full resolution, 2 or 4 for subsampling (or binning, depends on what the camera model supports) by factor 2 or 4, respectively. Note that not all uEye models support subsampling or binning. Default: 1. | |||
| ImageWidth | 0, width | The width of the desired image part ('0' stands for the complete image). Note that ImageWidth must be a multiple of 16 and greater than 64. Note that this is the maximum possible width for this instance! Default: 0 (original width of the camera). | |||
| ImageHeight | 0, height | The height of the desired image part ('0' stands for the complete image). Note that ImageHeight must be a multiple of 2. Note that this is the maximum possible height for this instance! Default: 0 (original height of the camera). | |||
| StartRow | 0, row | The row coordinate of the upper left pixel within the desired image part. The stepsize of StartRow depends on the used camera model. 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. The stepsize of StartColumn depends on the used camera model. If ImageWidth is set to 0, then both the first AND last StartColumn columns of the image matrix are discarded. Default: 0. | |||
| Field | --- | Ignored. | |||
| 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. You will get an 8-8-8 three channel RGB HALCON image in this case, too. Default: 8. | |||
| ColorSpace | 'default', 'gray', 'bayer', 'rgb' | Specify the desired color space and thus the number of image channels of the resulting HALCON image. If ColorSpace is set to 'default', the color space is set to 'rgb' in case of color cameras, otherwise to 'gray'. The 'bayer' color space causes the camera to produce the raw Bayer pattern image as output. Default: 'default'. | |||
| Gain | --- | Ignored. | |||
| ExternalTrigger | 'true', 'false' | Activate/deactivate external triggering. Default: 'false'. | |||
| CameraType |
'default', 'falcon',
'UI121x-M', 'UI121x-C', 'UI122x-M', 'UI122x-C', 'UI141x-M', 'UI141x-C', 'UI144x-M', 'UI144x-C', 'UI145x-C', 'UI146x-C', 'UI148x-C', 'UI154x-M', 'UI154x-C', 'UI1543-M', 'UI1543-C', 'UI221x-M', 'UI221x-C', 'UI222x-M', 'UI222x-C', 'UI223x-M', 'UI223x-C', 'UI224x-M', 'UI224x-C', 'UI225x-M', 'UI225x-C', 'UI231x-M', 'UI231x-C', 'UI233x-M', 'UI233x-C', 'UI234x-M', 'UI234x-C', 'UI241x-M', 'UI241x-C', ini_file_name |
The camera type will be detected automatically ('default'). If
CameraType is set to 'falcon' (or one of the allowed camera
types of the FALCON/EAGLE frame grabber boards) the
'FALCON/EAGLE compatibility mode'
is enabled. If the CameraType specifies a path to an ini file suitable for the selected camera the properties are restored from this file. To store such a file see parameter 'do_save_parameters'. Note that the loading of such files is only supported under Windows, and that the properties specified in this file overwrite the other parameters supplied with open_framegrabber. Default: 'default'. |
|||
| Device | '0', DeviceId | The ID of the desired camera (passed as a string!), see also 'Using Multiple Cameras' above. Default: '0' (searches for the first unused camera). | |||
| Port | --- | Ignored. | |||
| LineIn | --- | Ignored. | |||
Parameters for set_framegrabber_param():
| 'add_user_mem' | 0, mem_ptr (long) | By default the image acquisition uses a ring buffer with three image buffers. With the (repeatedly) call of 'add_user_mem' the user can specify separate image pointers which build a FIFO queue with up to 16 user-allocated buffers. If this FIFO queue is not empty the subsequent calls of grab_image(_async) use these user-allocated buffers, and get_framegrabber_param returns the pointer of the last image buffer. If the FIFO queue is empty the image acquisition uses the internal ring buffer and get_framegrabber_param returns NULL. The FIFO queue is deleted if 'add_user_mem' is called with a NULL pointer as argument. | |||
| 'agc' | 'enable', 'disable' | Enables or disables the auto gain control of the camera to achieve an average brightness value specified with the parameter 'auto_brightness_reference'. Default: 'disable'. | |||
| 'auto_brightness_roi' | [row1 (long), col1 (long), row2 (long), col2 (long)] | Specifies the area of interest in which the average brightness value used for auto gain and auto exposure should be evaluated. Default: the current image roi. | |||
| 'auto_brightness_reference' | 0 ... 255 (long) | Specifies the brightness reference value which should be achieved by auto gain and auto exposure. Default: 128. | |||
| 'auto_whitebalance_roi' | [row1 (long), col1 (long), row2 (long), col2 (long)] | Specifies the area of interest which in which the auto whitebalance function should work. Default: the current image roi. | |||
| 'bad_pixel_correction' | 'enable', 'disable' | Enables or disables the correction of hot pixels of the image sensor. Default: 'disable'. | |||
| 'black_level_compensation' | 0 ... 255 (long) | Specifies the black level offset value of the image sensor. | |||
| 'brightness' | 0 ... 255 (long) | Specifies the brightness value of the image. | |||
| 'color_correction' | 'enable', 'disable' | Enables or disables the color correction mode. Default: 'enable'. | |||
| 'compatibility_mode' | 'enable', 'disable' | Enables or disables the FALCON/EAGLE compatibility mode, see paragraph above. Default: 'disable'. | |||
| 'continuous_grabbing' | 'enable', 'disable' | Sets grabbing mode from single frame capture to continuous mode. If the continuous mode is enabled, the camera will grab all the time. Note that this mode can neither be used together with triggering nor while 'memory_module' is enabled. Default: 'disable'. | |||
| 'contrast' | 0 ... 511 (long) | Specifies the contrast value of the image between 0% and 200%. | |||
| 'digital_output' | 0, 1 (long) | Sets the digital output. Note that the digital output pin is shared with the strobe signal (the strobe signal uses the digital output) and may influence the strobe settings, thus, don't mix them up! Default: 0. | |||
| 'do_force_trigger' | --- | Forces an event trigger when using the external trigger. This might be useful for testing purposes. | |||
| 'do_save_parameters' | ini_file_name | Stores the current parameter set of the used camera in an ini file. This file can be used to restore this parameters by calling open_framegrabber with this file name in the parameter CameraType. Note that this parameter is currently not supported under Linux (as well as loading such ini-files). | |||
| 'edge_enhancement' | 'disable', 'strong', 'weak' | Specifies edge enhancement mode. Default: 'disable'. | |||
| 'exposure' | 0.0, min ... max (float), 'auto', 'manual' | Specifies the desired exposure time of the camera. Note that the value range depends on the current pixel clock and frame rate settings. It can be queried by get_framegrabber_param(...,'exposure_range',...). If the value is equal to 0.0, the exposure time will be set to 1 / (frame_rate). This value may be larger than max. You can leave the 'auto' mode by setting the value to 'manual' or simply enter a valid float value. Please note that if auto exposure is enabled, you can not change the pixel clock setting. | |||
| 'external_trigger' | 'true', 'false' | Enables/disables the trigger mode. Be aware of the settings your camera supplies. | |||
| 'flip_horizontal' | 'true', 'false' | Enables/disables horizontal image flipping (supported by all uEye models). Default: 'false'. | |||
| 'flip_vertical' | 'true', 'false' | Enables/disables vertical image flipping (supported only by some uEye models). If the specific uEye camera does not support horizontal flipping, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). Default: 'false'. | |||
| 'frame_rate' | min ... max (float), 'auto', 'manual' | Specifies the desired frame rate of the camera. Note that the value range depends on the current pixel clock and exposure settings. It can be queried by get_framegrabber_param(...,'frame_rate_range',...). You can leave the 'auto' mode by setting the value to 'manual' or simply enter a valid float value. The 'auto' value can only be set if auto exposure is enabled and 'gain_master' is not set to 'auto'. | |||
| 'gain_b' | 0 ... 100 (long) | Specifies the blue gain multiplier of the camera in percent. | |||
| 'gain_g' | 0 ... 100 (long) | Specifies the green gain multiplier of the camera in percent. | |||
| 'gain_master' | 0 ... 100 (long), 'auto', 'manual' | Specifies the master gain multiplier of the camera in percent. You can leave the 'auto' mode by setting the value to 'manual' or simply enter a valid float value. | |||
| 'gain_r' | 0 ... 100 (long) | Specifies the red gain multiplier of the camera in percent. | |||
| 'gamma' | 0.01 ... 10.0 (float) | Specifies the gamma correction value of the camera. Default: 1.0. | |||
| 'grab_timeout' | 100 ... 327680 | Specifies the desired timeout (milliseconds passed as an integer) for aborting a pending grab. Default: 5000. | |||
| 'memory_module' | 'enable', 'disable' | If the memory module mode is enabled, the grabbed images will first be stored in the memory of the camera. Note that this mode cannot be used together with the continuous grabbing mode. Default: 'disable'. | |||
| 'pixel_clock' | min ... max (long) | Specifies the pixel clock of the camera (MHz passed as an integer). Note that the value range depends on the embedded sensor and can be queried by get_framegrabber_param(...,'pixel_clock_range',...). | |||
| 'roi' | [row1 (long), col1 (long), row2 (long), col2 (long)] | Specifies the upper left (row1, col1) and lower right (row2, col2) corner of the desired rectangular image part which will be actually acquired by the camera. Note that col1 and col2-col1+1 must be a multiple of 16, while row1 and row2-row1+1 must be multiple of 2. col1, col2 as well as row1, row2 step sizes are model dependant. | |||
| 'strobe_delay' | usec (long) | Specify the delay in usec of the flash signal on the digital output. Default: 0. | |||
| 'strobe_duration' | usec (long) | Specify the duration in usec of the flash signal on the digital output. If set to 0 the flash signal is enabled as long as the sensor exposures. Default: 0. | |||
| 'strobe_invert' | 'true', 'false' | When set to 'true', the strobe signal is inverted. Default: 'false'. | |||
| 'strobe_mode' | 'enable', 'disable', 'simulate_global_shutter' | Enables or disables the strobe mode. The value 'simulate_global_shutter' sets the parameters 'strobe_delay' and 'strobe_duration' to hit the global exposure time slice on a rolling shutter camera. Default: 'disable'. | |||
| 'trigger_delay' | usec (long) | Adjustable time in usec to wait after the trigger edge before the acquisition begins. Default: 0. | |||
| 'trigger_signal' | 'falling', 'rising', 'software' | Specifies the desired type of the trigger signal. Note that old uEye cameras do not support the value 'rising'. Default: 'falling'. | |||
| 'volatile' | 'enable', 'disable' | Grayscale only. In the volatile mode the 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'. | |||
| 'white_balance' | 'disable', 'auto', 'auto_next_frame', 'cool_white', 'daylight', 'illuminant_a', 'horizon', 'user' |
Specifies the white balance mode:
|
|||
| 'white_balance_b' | 0.0 ... 4.0 (float) | Specifies the white balance multiplier for the blue channel. Note that this setting only works when the white balance mode is set to 'user'! | |||
| 'white_balance_g' | 0.0 ... 4.0 (float) | Specifies the white balance multiplier for the green channel. Note that this setting only works when the white balance mode is set to 'user'! | |||
| 'white_balance_r' | 0.0 ... 4.0 (float) | Specifies the white balance multiplier for the red channel. Note that this setting only works when the white balance mode is set to 'user'! | |||
Parameters for get_framegrabber_param():
Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param except the ones with prefix 'do_' can also be accessed by get_framegrabber_param.
| 'add_user_mem' | mem_ptr (long) | Pointer of the last image buffer in case of user-allocated buffers. If the FIFO queue is empty the image acquisition uses the internal ring buffer and the value 0 (NULL pointer) is returned. | |||
| 'brightness_range' | [min (long), max (long), step (long), current_value (long)] | Possible range for brightness value. | |||
| 'camera_info' | camera_info (string) | Serial number, type, version, and date of QC of the camera. | |||
| 'contrast_range' | [min (long), max (long), step (long), current_value (long)] | Possible range for contrast value. | |||
| 'digital_input' | camera_info | Read the digital input of the uEye camera. Note that the digital input is physically shared with the trigger input pin. | |||
| 'driver_version' | version (string) | Version number of the installed uEye driver. | |||
| 'exposure_range' | [min (float), max (float), step (float), current_value (float), 'auto', 'manual'] | Possible range for exposure value. | |||
| 'frame_rate_range' | [min (float), max (float), step (float), current_value (float), 'auto', 'manual'] | Possible range for camera frame rate. | |||
| 'gain_master_range' | [min (float), max (float), step (float), current_value (float), 'auto', 'manual'] | Possible range for camera gain master. | |||
| 'pixel_clock_range' | [min (long), max (long), step (long), current_value (long)] | Possible range for camera pixel clock. | |||
| 'revision' | revision | The revision number of the HALCON uEye interface. | |||
| 'sensor_capabilities' | [color_info (long), gain_master (long), gain_r (long), gain_g (long), gain_b (long), global_shutter (long)] | Boolean information about the capabilities of the used sensor. | |||
| 'sensor_size' | [width_max (long), height_max (long)] | Maximum image size of the used sensor. | |||
| 'sensor_type' | sensor type | Name of the used sensor type. | |||
Release Notes
-
Revision 2.8 (Dec 14, 2006):
- Bugfix in auto white balance. The white balance mode was never set to newer hardware white balance, although it was available.
-
Revision 2.7 (Oct 11, 2006):
- Support of the Linux driver for uEye cameras.
- Bugfix in auto exposure, auto framerate, and auto gain handling. The auto parameters now return 'auto' while in auto mode and their value otherwise.
- Added support of individual stepsizes in ROI parameter (row and column values are no longer fixed on 4 or 16 increments).
-
Revision 2.6 (Jun 23, 2006):
- Support of additional uEye camera models.
- In open_framegrabber the parameters 'HorizontalResolution' and 'VerticalResolution' can now be set to activate enhanced subsampling or binning modes by factor 4 for some cameras.
- In open_framegrabber the parameter 'CameraType' can be used to specify an ini file from which the previous stored parameters are restored.
- New parameter 'do_save_parameters' to store an ini file which holds the current parameter set.
- New parameters 'agc', 'auto_brightness_roi', 'auto_brightness_reference' and 'auto_whitebalance_roi' for controlling the cameras auto feature parameters. The parameters 'exposure', 'frame_rate', 'gain_master', and 'white_balance' accept the value 'auto' which activates the auto exposure, auto framerate, auto gain, or auto whitebalance, respectively.
- Adaptation to uEye driver 2.20.0000.
-
Revision 2.5 (Dec 21, 2005):
- In open_framegrabber the parameters 'HorizontalResolution' and 'VerticalResolution' can now be set to activate subsampling or binning, depending on what the camera supports.
- New parameters 'strobe_delay' and 'strobe_duration' for further controlling of the strobe output. The parameter 'strobe_mode' can now be called with the value 'simulate_global_shutter' which influences delay and duration. Removed parameter 'strobe_line'.
- New parameters 'digital_input' and 'digital_output' for controlling the I/O ports on the uEye camera directly.
- New parameter 'do_force_trigger' to release a trigger by a software call while waiting for a hardware trigger. The parameter 'trigger_signal' can now also be set to 'rising' to trigger on both edges.
- New parameters 'flip_horizontal' and 'flip_vertical' to set the image orientation.
- New parameter 'driver_version' to query the uEye driver used. If you are trying to open a camera with open_framegrabber, the minimum recommended driver version is checked.
- Bugfix: 'strobe_invert' caused the strobe signal to be static high.
- Bugfix: 'camera_info' crashed when connected to an unprogrammed camera.
- Bugfix: The image looked scattered when using a region of interest.
- Adaptation to uEye driver 1.14.0010. This driver version is compatible with driver 2.0x.xx.
-
Revision 2.4 (Oct 18, 2005):
- Support of additional uEye camera models.
- Changed the capture routine concerning memory board usage.
- Bugfix in set_framegrabber_param when called with a NULL pointer.
- Bugfix grab_image_start to ensure aborting any pending grabs.
- Parameter 'strobe_line' has been made obsolete.
-
Revision 2.3 (Jul 1, 2005):
- New parameters 'strobe_invert', 'strobe_mode', and 'strobe_line' for controlling the strobe output.
- Speed-up for acquisition of RGB images (avoiding cache alignment failures when converting the interleaved image data into HALCON image objects).
-
Revision 2.2 (Apr 4, 2005):
- Support of additional uEye camera models.
-
Revision 2.1 (Dec 13, 2004):
- Allow grabbing of the raw Bayer image in case of color cameras.
- New parameter 'continuous_grabbing'.
- New parameter 'add_user_mem' to allow the use of user-allocated buffers.
- New parameter 'roi' to specify a region of interest.
- 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.
- Adaptation to uEye driver 1.12.
-
Revision 2.0 (Jul 23, 2004):
- First official release.
