MVTec Software GmbH
  Building Vision For Business
Halcon

HALCON 9.0 Image Acquisition Interface for IDS uEye USB 2.0 and Gigabit Ethernet Cameras

This page provides the documentation of the HALCON uEye image acquisition interface for accessing the uEye USB 2.0 and Gigabit Ethernet cameras from IDS Imaging Development Systems GmbH. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.7

System Requirements

  • Intel compatible PC with Windows XP/Vista/7, Windows XP/Vista/7 x64, Linux x86, or Linux x86_64 with kernel 2.6.9 (or higher), and USB 2.0 interface or Gigabit Ethernet network adapter, respectively.
  • Windows 32bit: uEye driver (version 3.70.0000 or higher) uEye_usb.sys or uEye_eth.sys. Typically, these files reside in the directory %WINDIR%\system32\drivers.
    Windows 64bit: uEye driver (version 3.70.0000 or higher) uEye_usb_64.sys or uEye_eth_64.sys. Typically, these files reside in the directory %WINDIR%\system32\drivers.
    Linux: uEye driver (version 3.70.0000 or higher) ueyeusbd or ueyeethd. Typically, these files reside in the directories /usr/local/share/ueye/ueyeethd or /usr/local/share/ueye/ueyeusbd.
    If you do not have this driver, please contact IDS Imaging Development Systems GmbH or the vendor from which you bought the camera.
  • Windows 32bit: uEye DLL uEye_api.dll version 3.70.0000 or higher. This DLL must be within your search path %PATH% (typically, it resides in the directory %WINDIR%\system32).
    Windows 64bit: uEye DLL uEye_api_64.dll version 3.70.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 3.70.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 image acquisition interface hAcquEye.dll or hAcquEyexl.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 hAcquEye.so or hAcquEyexl.so, respectively. Both files should reside in the directory lib/$HALCONARCH within the HALCON base directory %HALCONROOT%.

Features

  • Multiple cameras.
  • Synchronous and asynchronous grabbing.
  • Image cropping.
  • External trigger with adjustable trigger delay.
  • Supports uEye timestamp (time of image creation).
  • 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.
  • Support of lookup tables.
  • FALCON/EAGLE compatibility mode.

Limitations

  • grab_data and grab_data_async not supported.

Using Multiple Cameras

If using multiple uEye cameras, please make sure that each camera has an unique device ID. You can manually set these device IDs by use of the auxiliary program uEye Camera Manager 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',....).

Using Multiple Threads

If using multiple threads, call open_framegrabber and the corresponding close_framegrabber always in the same thread to avoid unpredictable behavior of your application.

Image Timestamp

The HALCON operator get_image_time typically returns the creation time of the HALCON image object. Since revision 4.6 of the uEye interface, the creation time of the camera image is returned (see is_GetImageInfo() in the uEye manual).

Reaching Full Frame Rates With USB Cameras

Modern processors and operating systems are designed to be energy efficient. This can also have unwanted effects. In the modern Core i3/i5/i7 Intel processors, the USB bus is also optimized to operate in a power-saving, energy-efficient manner.
As a result, uEye USB cameras cannot be operated using the maximum available frame rate in this mode. Use IDS Camera Manager's CPU Idle-States settings (accessible via 'Additional functions' button) to ensure the full performance of the USB bus in connection with a uEye industrial camera.

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 image acquisition interface.
HorizontalResolution 1, 2, 3, 4, 5, 6, 8, 16 The desired horizontal image resolution. Use 1 for full resolution, or 2 - 16 for subsampling (or binning, depends on what the camera model supports) by factor 2 - 16, respectively. Note that this is the minimum possible horizontal resolution factor for this instance. Note that not all uEye models support subsampling or binning. If both is supported, subsampling is chosen because of frame rate advantages. Default: 1.
VerticalResolution 1, 2, 3, 4, 5, 6, 8, 16 The desired vertical image resolution. Use 1 for full resolution, or 2 - 16 for subsampling (or binning, depends on what the camera model supports) by factor 2 - 16, respectively. Note that this is the minimum possible vertical resolution factor for this instance Note that not all uEye models support subsampling or binning. If both is supported, subsampling is chosen because of frame rate advantages. 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 4 (specific models may have further limits). 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 (specific models may have further limits). 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, 10, 12, 16 Number of bits per image channel: Grayscale (8, 12, and 16 bits) or color (5, 8, and 10 bit). Specifying 5 and 10 bits per channel is only allowed in combination with ColorSpace = 'rgb'. A value of 5 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. Note that not all models support more than 8 bits per channel. Default: 8.
ColorSpace 'default', 'gray', 'raw', 'rgb', 'rgby' 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, and to 'gray' otherwise. The 'raw' color space causes a color camera to produce the raw Bayer pattern image as output. If 'rgby' is specified, a 8-8-8-8 four channel HALCON image with brightness information in the fourth channel is returned (if this format is supported by your camera). Default: 'default'.
Generic 'num_buffers=num', -1 Specify number of used internal sequence buffers in a range between 3 and 19 used buffers. Default: 3.
ExternalTrigger 'true', 'false' Activate/deactivate external triggering. Default: 'false'.
CameraType 'default', 'falcon', '/cam/set1', '/cam/set2', ueye_model_name 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 CameraType specifies an EEPROM userset (by '/cam/set1' or '/cam/set2') or a path to an ini file suitable for the selected camera the properties are restored from this file or userset. To store such a file see parameter 'do_save_parameters'. Note that the properties specified in this file will overwrite all other parameters supplied with open_framegrabber except Device. Default: 'default'.
Device '0', DeviceId, SerialNumber The ID of the desired camera (passed as a string!), see also 'Using Multiple Cameras' above.
If Device specifies a serial number, the camera with the specified serial number will be opened. Default: '0' (searches for the first available camera).
Note that, if a valid DeviceId or serial number is given, always the matching device will be opened, ignoring if the specified CameraType does not match this device.
Port --- Ignored.
LineIn --- Ignored.

Parameters for set_framegrabber_param():

'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'.
'api_timeout' 0,4...429496729 (long) Sets the internal timeout used by uEye API functions in steps of 10 ms (4 = 40ms). Note that this timeout may be different from the timeout set with the parameter 'grab_timeout' and will influence only uEye's internal behavior. Default: 0 (= uEye API's default timeout of 60 seconds).
'auto_blacklevel_comp' 'enable', 'disable' Enables or disables automatic blacklevel compensation. A given blacklevel offset (see parameter 'offset'.) will be added to the compensation value.
'auto_brightness_max_exp' 0.0, min ... max (float) Upper limit of the exposure time when used to control the image brightness automatically.
'auto_brightness_max_gain' min ... max (long) Upper limit of gain when used to control the image brightness automatically.
'auto_brightness_reference' 0 ... 255 (long) Specifies the brightness reference value which should be achieved by auto gain and auto exposure. Default: 128.
'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. Note that changes to the image roi reset the auto brightness roi to the same coordinates. Default: the current image roi.
'auto_brightness_speed' 0 ... 100 (long) Specifies the speed (percentage of examined images) of the automatic brightness control unit.
'auto_whitebalance_max_gain' min ...100 (long) Limits the maximum gain for red, green and blue channels, when used by the automatic whitebalance control unit. Note that this parameter is only available with color cameras.
'auto_whitebalance_min_gain' 0 ...max (long) Limits the minimum gain for red, green and blue channels, when used by the automatic whitebalance control unit. Note that this parameter is only available with color cameras.
'auto_whitebalance_offset_r' red_offset  Specifies the offset for the red gain channel relative to the green one when used by the automatic whitebalance control unit. Note that this parameter is only available with color cameras.
'auto_whitebalance_offset_b' blue_offset  Specifies the offset for the blue gain channel relative to the green one when used by the automatic whitebalance control unit. Note that this parameter is only available with color cameras.
'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. Note that this parameter is only available with color cameras. Note that changes to the image roi reset the auto whitebalance roi to the same coordinates. Default: the current image roi.
'auto_whitebalance_speed' 0 ... 100 (long) Specifies the speed (percentage of examined images) of the automatic whitebalance control unit. Note that this parameter is only available with color cameras.
'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.
'camera_led' 'on', 'off', 'toggle' Switches the led at the cameras back to the specified state. Note that only the USB uEye SE/RE and ME series supports led switching.
'color_conversion' '3x3', '5x5', 'hw' Selects the Bayer conversion mask, and thus the quality and performance of the image color conversion. If set to 'hw' the camera itself outputs the desired color format which may result in increased bandwidth.
'color_correction' 'enable', 'disable', 'bg40', 'hq' Enables or disables the color correction mode. Note that this parameter is only available with color cameras. Default: 'enable'.
  • 'bg40': Enable color correction for cameras with optical IR filter glasses of the BG40 type.
  • 'disable': Disable color correction.
  • 'enable': Enable simple color correction.
  • 'hq': Enable color correction for cameras with optical IR filter glasses of the HQ type.
'color_temperature' min...max  (long) Sets the color temperature for auto white balance. You can fix a setting (in Kelvin) for the color temperature of an image when you are using a color camera. The function will use the sensor's hardware gain controls for the setting, as far as possible.
Using rgb_color_model you can choose between different color spaces. A specific color temperature will result in slightly differing RGB values, depending on the selected color space.
Note that this function cannot be used simultaneously with the automatic white balance function.
'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. Please also note that the usage of grab_image disables the continuous mode. Default: 'disable'.
'convert_to_gray' 'enable', 'disable' Enables/disables conversion to gray scale image using camera's capabilities. Note that this feature will only be available if a camera LUT is enabled (GigE HE cameras only).
'digital_io_capabilities' [ports (long), input (long), output (long), flash (long)] Returns bitmasks containing available additional (general purpose) IO-ports (ports), IO-ports available as input ports (input), IO-ports available as output ports (output) and IO-ports usable for flash output (flash).
'digital_io_direction' direction (long) Sets the individual direction of the additional digital (general purpose) IO port pins. A single pin is configured to act as output by writing a 1 to the correspondent bit position. Which pins are capable of acting as input or output can be queried using 'digital_io_capabilities'.
'digital_io_port' status (long) Sets (or queries) the digital IO port. Note that only output pins can be set. The amount and connection of available (general purpose) IO pins is model dependent. The available pins can be queried using 'digital_io_capabilities' and its direction can be set with 'digital_io_direction'.
'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_abort_grab' --- Cancels a pending asynchronous or continuous grab. Note that cancelling a grab may take some time, especially in triggered mode, see uEye documentation for further details.
'do_force_trigger' --- Forces an event trigger when using the external trigger. This might be useful for testing purposes.
'do_load_parameters' ini_file_name Loads parameter set of the used camera from the camera EEPROM or from an ini file. To load the parameters from one of two usersets, specify '/cam/set1' or '/cam/set2', respectively.
'do_save_parameters' ini_file_name Stores the current parameter set of the used camera into the camera EEPROM or into an ini file. To store the parameters as one of two usersets, specify '/cam/set1' or '/cam/set2', respectively. This file can be used to restore this parameters by calling open_framegrabber with the file name in the parameter CameraType or calling set_framegrabber_param(...,'do_load_parameters',...).
If the button in the HDevelop Image Acquisition Assistant is used, an ini file with the name of the used camera model will be saved to the current %HALCONROOT% directory.
'edge_enhancement' 'disable', 'strong', 'weak' Specifies edge enhancement mode. Default: 'disable'.
'eeprom_content' content (string) Lets you read and write the user accessible 64 bytes of camera eeprom.
'exposure' 0.0, min ... max (float), 'auto', 'manual' Specifies the desired exposure time (in milliseconds) 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. Default: 'false'.
'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. Note that this parameter is only available with color cameras.
'gain_boost' 'enable', 'disable' Enables or disables the additional gain boost feature of some uEye models. Default: 'disable'.
'gain_factor_b' 100 ... max (long) Specifies a linear blue gain multiplier of the camera. A value of 357 means a factor of 3.57. The maximum value can be queried by get_framegrabber_param(...,'gain_factor_b_range',...). Note that this parameter is only available with color cameras.
'gain_factor_g' 100 ... max (long) Specifies a linear green gain multiplier of the camera. A value of 357 means a factor of 3.57. The maximum value can be queried by get_framegrabber_param(...,'gain_factor_g_range',...). Note that this parameter is only available with color cameras.
'gain_factor_master' 100 ... max (long) Specifies a linear master gain multiplier of the camera. A value of 357 means a factor of 3.57. The maximum value can be queried by get_framegrabber_param(...,'gain_factor_master_range',...).
'gain_factor_r' 100 ... max (long) Specifies a linear red gain multiplier of the camera. A value of 357 means a factor of 3.57. The maximum value can be queried by get_framegrabber_param(...,'gain_factor_r_range',...). Note that this parameter is only available with color cameras.
'gain_g' 0 ... 100 (long) Specifies the green gain multiplier of the camera in percent. Note that this parameter is only available with color cameras.
'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. Note that this parameter is only available with color cameras.
'gamma' 0.01 ... 10.0 (float) Specifies the gamma correction value of the camera. Default: 1.0.
'global_shutter' 'enable', 'disable' Enables or disables the global (start) shutter mode of some models. Note that such models are always operating in rolling shutter mode when in free-run.
'grab_timeout' 100 ... 214748360 (long) Specifies the desired timeout (milliseconds passed as an integer) for aborting a pending grab. Default: 5000.
'horizontal_resolution' 1, 2, 3, 4, 5, 6, 8, 16 Changes the horizontal resolution by subsampling the sensor image by the given factor. The possible factors vary with the camera model. The parameter 'subsampling_method' determines the applied method to achieve that resolution. Note that no smaller resolution than the one given at the open_framegrabber call can be set. Note that by changing this value in asynchronous mode all images in the image queue, which i are not already grabbed, will be discarded.
'image_height' min ... max (long) Alters the captured image part by changing the height component. Note that image height can not be greater than specified with open_framegrabber call. Note that by changing this value in asynchronous mode all images in the image queue, which are not already grabbed, will be discarded.
'image_part' [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 there are model dependant grids for row1 and col1 as well as for resulting width and height. The function automatically aligns the values if they are within the valid range.
'image_width' min ... max (long) Alters the captured image part by changing the width component. Note that image width can not be greater than specified with open_framegrabber call. Note that by changing this value in asynchronous mode all images in the image queue, which are not already grabbed, will be discarded.
'lut' 'enable', 'disable', 'identity', 'negative', 'glow1', 'glow2', 'astro1', 'rainbow1', 'map1', 'cold_hot', 'sepic', 'only_red', 'only_green', 'only_blue' Enables, disables the lookup table, or activates one of the presets. You have to use a hardware color processing mode in order to use lookup tables. (Use parameter 'color_conversion' with value 'hw'). Note that setting a lookup table with the operator set_framegrabber_lut the lookup table is implicitly enabled.
'offset' 0 ... 255 (long) See parameter 'black_level_compensation'.
'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',...).
'rgb_color_model' 'sRGB 5000K', 'sRGB 6500K', 'CIE-RGB Norm E', 'ECI-RGB 5000K', 'Adobe RGB 6500K' Choose between different color spaces. A specific color temperature will result in slightly differing RGB values, depending on the selected color space.
Using color_temperature you can fix a setting (in Kelvin) for the color temperature of an image when you are using a color camera.
Default: 'sRGB 5000K'.
  • 'sRGB 5000K': sRGB (standard RGB) color space with a white point of 5000 Kelvin (warm light).
  • 'sRGB 6500K': sRGB (standard RGB) color space with a white point of 6500 Kelvin (mid daylight)
  • 'CIE-RGB Norm E': CIE-RGB color space with standard illumination E
  • 'ECI-RGB 5000K': ECI-RGB color space with a white point of 5000 Kelvin (warm light)
  • 'Adobe RGB 6500K': Adobe RGB color space with a white point of 6500 Kelvin (mid daylight). The Adobe RGB color space is larger than the sRGB color space, but not all devices can render it.
'roi' [row1 (long), col1 (long), row2 (long), col2 (long)] See parameter 'image_part'.
'show_internal_errors' 'true', 'false' Enables error messages sent by uEye driver. Errors will be displayed in a separate message box.
'standby' 'enable', 'disable' Enabling the standby parameter turns the camera into a power saving mode. This parameter can only be set with uEye driver version 3.10 or higher.
'start_async_after_grab_async' 'enable', 'disable' By default, at the end of grab_image_async a new asynchronous grab command is automatically executed. If this parameter is set to 'disable' this new grab command is omitted. Default: 'enable'.
'start_column' 0 ... max - width (long) Altering the captured image part by moving the start column horizontally. Default: 0.
'start_row' 0 ... max - height (long) Altering the captured image part by moving the start row vertically. Default: 0.
'strobe_delay' usec (long) Specify the delay in usec of the flash signal on the digital output. If set to 0 flash delay is deactivated. 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' If set to 'true', the strobe signal is inverted. Default: 'false'.
'strobe_io_port' strobe_outs (long) Allows to set the digital i/o ports to act as strobe output by writing 1 to the corresponding bit position. 'digital_io_capabilities' can be used to query which pins are able to act as strobe out.
'strobe_mode' 'enable', 'disable', 'enable_freerun', 'simulate_global_shutter' Enables or disables the strobe mode. Setting 'enable_freerun' activates the strobe output during free-run mode, while 'enable' activates for triggered operations only. 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, thus changing any of them may cause the active strobe signal to miss the global exposure window. Default: 'disable'.
Note that a return value of 'disable(output)' indicates that flash port is or was used as digital output port (see parameter 'digital_output').
'subsampling_method' 'skipping', 'binning', 'prefer_skipping', 'prefer_binning' Chooses the mode used when horizontal and/or vertical resolution is set to a value greater than one. If you choose one of the 'prefer_*' modes the desired resolution is tried to be achieved using the specified method first. A value without a 'prefer_' prefix will refuse any resolutions that can not be achieved by the selected method. Default: 'prefer_skipping' because of possible frame rate advantages.
'trigger_delay' usec (long) Adjustable time in usec to wait after the trigger edge before the acquisition begins. If set to 0 trigger delay is deactivated. Default: 0.
'trigger_signal' 'falling', 'rising', 'software', 'sync_falling', 'sync_rising' Specifies the desired type of the trigger signal. Models which support trigger synchronisation enable you to synchronize several cameras in free-run mode.
Note that setting a trigger signal enables trigger mode (see parameter 'external_trigger' = true).
'trigger_debouncing_delay' usec (long) Suppresses disturbances at the digital input if you are running a GigE uEye camera in trigger mode. The signal at the digital input is only recognized as a trigger if the signal level remains constant at the target level for a user-selectable delay time. The signal edge can be set using parameter 'trigger_debouncing_mode'.
Note that this function is currently only supported by the GigE uEye camera series.
'trigger_debouncing_mode' 'automatic', 'both edges', 'disable', 'falling edge', 'rising edge' Sets the signal edge used for the trigger debounce function. The delay can be set using 'trigger_debouncing_delay'. It is recommend to use automatic signal edge selection.
Note that this function is currently only supported by the GigE uEye camera series.
  • 'disable': disables debouncing the digital input.
  • 'falling edge': debounces the digital input for falling edge signals.
  • 'rising edge': debounces the digital input for rising edge signals.
  • 'both edges': debounces the digital input for rising or falling edge signals.
  • 'automatic': debounces the digital input with automatic edge selection. The edge is selected based on the set trigger edge (see parameter 'trigger_signal').
Default: 'disable'.
'vertical_resolution' 1, 2, 3, 4, 5, 6, 8, 16 Changes the vertical resolution by subsampling the sensor image by the given factor. The possible factors vary with the camera model. The parameter 'subsampling_method' determines the applied method to achieve that resolution. Note that no smaller resolution than the one given at the open_framegrabber call can be set. Note that by changing this value in asynchronous mode all images in the image queue, which are not already grabbed, will be discarded.
'volatile' 'enable', 'disable' Grayscale only. In the volatile mode the 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!
Note that due to different line pitch and alignment, the volatile mode is only possible with full resolution for this session (the one specified in open_framegrabber). Please also note that this parameter can not be set if the Generic parameter 'num_buffers' is used with a value different from the default value. Default: 'disable'.
'white_balance' 'disable', 'auto', 'auto_once', 'user' Specifies the white balance mode:
  • 'disable': Disable white balancing.
  • 'auto': Automatic white balance using the rgb gain if the camera has one
  • 'auto_once': Use automatic white balance only once.
  • 'user': Enable manual white balancing, see set_framegrabber_param(...,'white_balance_X',...).

Deprecated Parameters:

Parameters or parameter values in this section will be removed in future releases. Consider this using these parameters.

'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.
'brightness' 0 ... 255 (long) Specifies the brightness value of the image. Use parameter 'black_level_compensation' instead.
'contrast' 0 ... 511 (long) Specifies the contrast value of the image between 0% and 200%. Default: 215. Use parameter 'gain_master' instead.
'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'.
'white_balance' 'auto_next_frame', 'cool_white', 'daylight', 'illuminant_a', 'horizon', 'u30' Specifies the white balance mode:
  • 'auto_next_frame': Automatic white balance on next frame.
  • 'cool_white': 4150 K, industry standard CWF (Cool White Fluorescent).
  • 'daylight': 6500 K, industry standard Daylight 65.
  • 'horizon': 2300 K, industry standard Horizon.
  • 'illumimant_a': 2856 K, industry standard Illuminant A.
  • 'u30': 3000 K, industry standard Ultralume 30.
'white_balance_b' 0.0 ... 5.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'! Note that this parameter is only available with color cameras. Use parameter 'gain_b' instead.
'white_balance_g' 0.0 ... 5.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'! Note that this parameter is only available with color cameras. Use parameter 'gain_g' instead.
'white_balance_r' 0.0 ... 5.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'! Note that this parameter is only available with color cameras. Use parameter 'gain_r' instead.

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. 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'].
All these postfixed parameter names are not returned when calling info_framegrabber(..,'parameters',..) and are used to enable the easy parameterization via a generic graphical user interface, particularly the HDevelop Image Acquisition Assistant.

'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.
'camera_info' camera_info (string) Serial number, type, version, and date of QC of the camera.
'digital_input' 0, 1 (long) Read the digital input of the uEye camera. Note that the digital input is physically shared with the trigger input pin.
'digital_io_capabilities' [supported (long), input_capable (long), output_capable (long), flash_capable (long)] Bit masks corresponding to the digital i/o port capabilities.
'driver_version' version (string) Version number of the installed uEye driver.
'image_available' 0, 1 (long) Returns the status of the last asynchronous grab command. A value of 1 means, that the image is already acquired and thus can be fetched by grab_image_async without delay.
Note that a value of 1 is also returned if a timeout or transfer failure occurred.
last_error error_code (long) Returns the last error code returned by the uEye API for the current device.
If no camera is opened, use info_framegrabber('uEye','info_boards',...) to retrieve information about all connected uEye devices and their last errors (if one occurred).
'num_buffers' 3...19 (long) Number of internal used sequence buffers. Default: 3.
'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.
'temperature' temperature (float) Returns the actual temperature of the camera in °C.
Note that this parameter is currently only supported by the GigE uEye camera series.
'timestamp_int' [timestamp_value0 (long), timestamp_value1 (long), timestamp_value2 (long), timestamp_value3 (long)] Returns the uEye SDK's internal timestamp of the last grabbed image as a tuple containing four long values containing the decimal number representation of the 16-bit parts of the timestamp (from highest to lowest part).
'timestamp_str' timestamp (string) Returns the uEye SDK's internal timestamp of the last grabbed image as a tuple containing a hexadecimal string representation of the 64-bit unsigned value.
'trigger_event_count' number of events (long) Returns the camera's internal number of external trigger events. Note that this parameter is only available for USB cameras.
'trigger_missed_count' number of missed trigger signals (long) Returns the number of missed trigger signals. Note that this value is set back to 0 after each call and that that using a GigE camera the value is only set if an image was captured or a timeout occurred.

Lookup tables:

Lookup tables can be set using the operator set_framegrabber_lut or can be chosen from a preset with a call to set_framegrabber_param(..,'lut',<preset>). Note that support of lookup tables is only available for GigE uEye cameras and can only be enabled when the hardware color processing is active.
The number of values to pass depends on the current color space. The camera itself works with finite sections with linear slope instead of a full table. Therefore a queried lookup table might vary from the one set.

Release Notes

  • Revision 4.7 (Nov 15, 2011):
    • Fixed problem in grab_image_async: 'continuous_grabbing' was set to 'disable' if do_abort_grab was called. grab_image_async now re-enables continuous mode if grabbing was stopped and parameter 'continuous_grabbing' is still enabled.
    • New parameters 'trigger_event_count', 'trigger_missed_count' to retrieve information about occurred and missed trigger events.
    • New parameter 'api_timeout' to set internal uEye API's timeout.
    • New Generic parameter 'num_buffers' to set the number of internal used buffers in open_framegrabber.
    • New parameters 'timestamp_int' and 'timestamp_str' to get uEye API's internal timestamp of the last grabbed image.
    • Changed documentation of parameters 'continuous_grabbing', 'do_abort_grab', 'image_available', 'trigger_debouncing_mode', and 'trigger_debouncing_delay'.
    • Day-of-the-Year field is now set in uEye timestamp information.
  • Revision 4.6 (Apr 15, 2011):
    • Adapted to uEye driver 3.70.0000.
    • Added possibility to open a device via its serial number.
    • Added uEye timestamp information directly to captured images objects, i.e., the HALCON operator get_image_time no more returns the creation time of the HALCON image object, but the the creation time of the camera image (see is_GetImageInfo() in the uEye manual).
    • New parameters trigger_debouncing_mode and trigger_debouncing_delay to suppress disturbances at the digital input running a GigE uEye camera in trigger mode.
    • New parameter auto_blacklevel_comp to control the camera's auto blacklevel compensation feature.
    • New parameters rgb_color_model and color_temperature to have additional features on the camera's white balancing.
    • New parameter convert_to_gray to optionally convert colored images to gray scale images if using camera LUT (GigE HE only).
    • New parameter temperature to query the camera's temperature value (GigE only).
    • New parameter last_error to query last error returned by uEye API function call.
    • Added support of HDR sensor's auto features.
    • Changing vertical or horizontal resolution, image width or image height is now possible in continuous and asynchronous mode.
    • Fixed behavior in open_framegrabber when ColorSpace was set to 'default' and BitsPerChannel to 16.
    • Fixed bug under Linux, where the function FGInit was not found.
    • Added driver version, serial number and error information to result of querying boards using info_framegrabber('uEye','info_boards',...).
    • Added paragraphs in HTML documentation regarding timestamp, sleepstates tool and multiple threads.
  • Revision 4.5 (Aug 27, 2010):
    • Adapted to uEye driver 3.50.0000.
    • Added support for Linux x64 architecture (with gcc-4.x).
    • Parameter 'show_internal_errors' now only controls the uEye SDK-specific error reporting. To enable and disable the HALCON low-level error messages please use use set_system('do_low_error', ...) instead.
  • Revision 4.4 (Feb 12, 2010):
    • Added support for Windows x64.
    • User-defined white balance parameters 'white_balance_b', 'white_balance_g' and 'white_balance_r' work correctly now.
    • New parameter 'do_load_parameter' to load a camera parameter ini-file with set_framegrabber_param.
    • New parameters 'gain_factor_b', 'gain_factor_g', 'gain_factor_master', 'gain_factor_r' to set hardware gains by a given linear factor.
    • New convenience parameter 'offset' as an alias for 'black_level_compensation'.
    • Added new parameter values 'hq' and 'bg40' for parameter 'color_correction'.
    • Added missing parameter values for parameter 'trigger_signal' in HTML documentation.
    • Added section 'Deprecated Parameters'.
  • Revision 4.3 (Sep 9, 2009):
    • Adaptation to uEye driver 3.40.0000.
    • Fixed 'trigger_signal' incompatibility when using uEye driver 3.40.0000.
    • Fixed behavior of grab_image, which did not abort all pending grabs.
    • Distorted images in monochrome roi modes have been fixed.
    • 'out of buffer' situation when grabbing continuous will no longer be caught in an error loop.
    • The combination of 10 or 5 BitsPerChannel and roi doesn't lead to crashes anymore.
    • Setting an unsupported resolution will no longer resize the image to full session size.
    • Parameter 'Device' in open_framegrabber could have been ignored in some cases.
    • New parameter 'subsampling_method' to choose whether binning or decimation is used.
  • Revision 4.2 (July 28, 2009):
    • Adaptation to uEye driver 3.32.0000 (Windows) or 3.25.0007 (Linux), respectively.
    • Fixed crash when calling set_framegrabber_param with an empty tuple.
    • Added support of lookup tables for some camera models.
    • New parameter 'lut' to enable or disable the usage of lookup table on supported models, or to pick a pre-selection.
    • New parameter 'do_abort_grab' to cancel a pending asynchronous grab.
    • New parameter 'global_shutter' to enable global start shutter mode of some camera models.
    • New parameter 'camera_led' enables the user to toggle the led on some cameras back.
    • New parameter 'start_async_after_grab_async' to disable new asynchronous grab at the end of grab_image_async.
    • New parameter 'image_part' replaces the parameter 'roi'. The old parameter name and values still work for backwards compatibility.
    • New values 'sync_falling' and 'sync_rising' for parameter 'trigger_signal' to enable free-run synchronisation on some models.
    • New value 'hw' for parameter 'color_conversion', which enables the onboard color conversion of some camera models.
    • Triggered capture now also works when grabbing continuously (if driver version supports this.)
    • Image resolution is now changeable within an open instance and not only at open_framegrabber.
    • Redone the grab_image_async routine to avoid busy waiting, which reduces CPU load.
  • Revision 4.1 (Mar 05, 2009):
    • Bugfix in open_framegrabber, which ignored the parameter 'Device' when 'CameraType' was set to 'default'. Also corrected the use of the parameters 'horizontal_resolution' and 'vertical_resolution'.
    • Bugfix in parameter 'strobe_invert' which deactivated 'strobe_mode' when called a second time.
    • Bugfix in querying the parameter 'roi' which returned swapped coordinates for row and column.
    • Bugfix in grab_image_async where the image size was occasionally miscalculated.
    • Fixed return value of parameter 'color_conversion' which had incomplete type information.
    • Added support of browsing camera files with the HDevelop Image Acquisition Assistant.
    • Changed alignment of parameter 'roi' from simple cut to nearest possible position.
  • Revision 4.0 (Dec 1, 2008):
    • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
    • Support of new color formats and pixel depths (12 and 16 bit 'gray' and 'bayer' as well as 10bit 'rgb' and 8 bit 'rgby').
    • New parameter 'image_available' to query the presence of an beforehand asynchronously grabbed image.
    • New parameter 'color_conversion', which replaces the parameter 'bayer_conversion'. The old parameter name and values still work for backwards compatibility.
    • New value 'raw' in parameter 'ColorSpace', which replaces the value 'bayer'. The old value still works for backwards compatibility.
    • Additional Subsampling/Binning by factor 6, 8 and 16 available (if supported by camera).
    • Bugfix in 'auto_*_roi' which caused the x and y coordinates to be swapped.
    • Bugfix setting 'roi' to original size, if start row and start column were set to zero beforehand.
    • Bugfix in 'flip_vertical' and 'flip_horizontal'. Results were swapped.
    • Bugfix in 'digital_output' which returns with error, if 'strobe_mode' was not explicitly disabled right before.
    • Bugfix trying to load an ini file had no effect when its name starts with some special keywords (e.g 'ueye').
    • Bugfix in 'do_save_parameter' with the HDevelop Image Acquisition Assistant.
  • Revision 3.3 (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.2 (Oct 30, 2007):
    • New parameter 'standby' to enter a powersaving mode.
    • New parameters 'digital_io_capabilities', 'digital_io_direction', 'digital_io_port', to achieve further i/o control for supporting models.
    • Additional Subsampling/Binning factors 3 and 5 available (if supported by the camera).
    • Added ability to save/restore parameters from/to the cameras EEPROM.
    • New value 'enable_freerun' for parameter 'strobe_mode', which enables flash output functionality in free-run mode.
    • Introduced '*_range' and '*_values' functions for most parameters, to achieve a smarter behavior when using the Image Acquisition Assistant of HALCON 8.0.
    • Bugfix in 'trigger_signal' ('rising' was not available for uEye Gigabit Ethernet cameras).
  • Revision 3.1 (Jul 27, 2007):
    • Support of additional uEye camera models.
    • Adaptation to uEye driver 2.40.0000 (USB 2.0) or 3.00.0000 (Gigabit Ethernet), respectively.
    • Updated vertical flipping capabilities to newer driver version.
    • New parameters 'auto_brightness_max_exp', 'auto_brightness_max_gain', and 'auto_brightness_speed' to allow further control over the automatic brightness control unit.
    • New parameters 'auto_whitebalance_gain_min', 'auto_whitebalance_gain_max', 'auto_whitebalance_offset_b', 'auto_whitebalance_offset_r', and 'auto_whitebalance_speed' to allow further control over the automatic whitebalance control unit.
    • Additional value 'auto_once' for parameter 'white_balance', which performs an automatic whitebalance till we are in a steady state.
    • New parameter 'bayer_conversion' to select the conversion matrix.
    • New parameter 'gain_boost' to control the additional gain amplification.
    • New parameter 'eeprom_content' to allow to access the camera eeprom.
    • Bugfix in grab_image (after an asynchronous grab the first call of grab_image returned an old image).
  • Revision 3.0 (May 15, 2007):
    • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
  • 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 step sizes 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):
    • 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.
    • 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.

© Copyright 2012, MVTec Software GmbH, corporate/legal/privacy information






Last modified: Tue Nov 15 13:06:26 CET 2011