HALCON 9.0 Image Acquisition Interface for Lumenera USB 2.0 and GigE Vision Cameras

This page provides the documentation of the HALCON LuCam image acquisition interface for the USB 2.0 and GigE Vision cameras from Lumenera Corporation. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.2

System Requirements

• Intel compatible PC with Windows 2000, Windows XP, Windows XP x64, Windows Vista, Windows Vista x64 and USB 2.0 card or a Gigabit Ethernet network adapter.
• Installed LuCam Software v6.1 (or higher) from Lumenera.
• HALCON image acquisition interface hAcqLuCam.dll or hAcqLuCamxl.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.

Features

• Multiple cameras.
• Image cropping.
• External trigger.
• Support of the Lumenera GigE Vision cameras.
• Software control of exposure.
• Software control of focus, gain, iris and white balancing.
• Software control of the strobe parameters.
• Software control of the digital input/output signals.

Limitations

• grab_image_start and grab_image_async not supported. Note that the grab_image operator behaves similar to grab_image_async if an external trigger is used and the parameter 'buffer_last_frame' is enabled.
• grab_data and grab_data_async not supported.
• RGB color images only with 8 Bit.
• No LUTs.

Description

Parameters for open_framegrabber():

	Name		'LuCam'		The name of the HALCON image acquisition interface.
	HorizontalResolution		1, 2, 4		The desired image resolution. Use '1' for full resolution, '2' for subsampling by factor 2, and '4' for subsampling by factor 4. Default: 1.
	VerticalResolution		1, 2, 4		The desired image resolution. Use '1' for full resolution, '2' for subsampling by factor 2, and '4' for subsampling by factor 4. Default: 1.
	ImageWidth		0, width		The width of the desired image part ('0' stands for the complete image). The value of 'ImageWidth' will be set to the next smaller value divisible by 8. Default: 0.
	ImageHeight		0, height		The height of the desired image part ('0' stands for the complete image). The value of 'ImageHeight' will be set to the next smaller value divisible by 8. Default: 0.
	StartRow		0, row		The row coordinate of the upper left pixel within the desired image part. The value of 'StartRow' will be set to the next smaller value divisible by 8. Default: 0.
	StartColumn		0, column		The column coordinate of the upper left pixel within the desired image part. The value of 'StartColumn' will be set to the next smaller value divisible by 8. Default: 0.
	Field		---		Ignored.
	BitsPerChannel		8, bits_per_channel		The desired pixel depth of the image. The value must be supported by the camera, e.g., 12. Default: 8.
	ColorSpace		'default', 'gray', 'rgb', 'bayer'		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 is only valid for Bayer color cameras, and causes the camera to produce the raw Bayer pattern image as output. Default: 'default'.
	Generic		-1, 'post_dual_tap_correction=state'		post_dual_tap_correction With state set to 0 the post dual tap correction will be disabled. The option can just be used, if the camera is based on a dual tap sensor.
	ExternalTrigger		'true', 'false'		Activate/deactivate external triggering. Default: 'false'.
	CameraType		---		Ignored.
	Device		'usb:<ID>', 'gige:<ID>', DeviceId		The device string must contain the prefix 'usb:' in case of Lumenera USB camera models, and 'gige:' in case of Lumenera GigE Vision camera models. After the prefix the ID or logical number of the desired camera must be set (the complete information is passed as a string!). The logical number is assigned by the operating system ('1' for the first camera, '2' for second camera and so on). For example, the first GigE Vision camera can be set via 'gige:1'. If no prefix is set, the USB interface is used. Default: '1'.
	Port		---		Ignored.
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

	'acquisition_mode'		'fast_frame', 'snapshot'		Sets the internal used acquisition mode. In special cases the 'snapshot' mode is needed e.g. to set very long exposure times. Default: 'fast_frame'.
	'buffer_last_frame'		'enable', 'disable'		If set to 'enable', the last acquired frame is stored for later retrieval. Only useful when used with a HW trigger. Default: 'disable'.
	'clock_speed'		'fast', 'medium', 'slow', 'very_slow'		The clock speed of the camera. Default: 'fast'.
	'correction_matrix'		'none', 'fluorescent', 'daylight', 'incandescent', 'xenon_flash', 'halogen', 'identity'		Color correction used, when converting the raw camera data to RGB24 (see documentation from Lumenera for details).
	'demosaicing_method'		'none', 'fast', 'high_quality', 'higher_quality', 'simple'		Demosaicing method used, when converting raw bayer data from the camera to RGB24 (see documentation from Lumenera for details). Default: 'simple'.
	'do_calibrate_auto_lens'		---		Perform auto calibration of the lens (not supported by all cameras).
	'do_abort_grab'		---		Abort the current image acquisition.
	'do_flush_buffer'		---		Flushes the image buffer of the camera. This is useful, when you acquire images via HW trigger with the 'buffer_last_frame' option set. Use of this parameter will force the camera to acquire a new image upon the subsequent grab.
	'do_reset_camera'		---		Resets the camera to the power-on default state.
	'exposure'		0.0, min ... max (float)		Specifies the desired exposure time of the camera in ms. The value range can be queried by get_framegrabber_param(...,'exposure_range',...).
	'exposure_delay'		0.0 ... 32768 (float)		Time interval from when the trigger occurs to when the exposure starts.
	'external_trigger'		'true', 'false'		Enables/disables the trigger mode. Default: 'false'.
	'focus'		min ... max (float)		Specifies the desired uncalibrated focus of the lens (not supported by all cameras). The value range can be queried by get_framegrabber_param(...,'focus_range',...).
	'focus_abs'		min ... max (float)		Specifies the desired calibrated focus of the lens (not supported by all cameras). Note that you cannot access this parameter without calling set_framegrabber_param(...,'do_calibrate_auto_lens',...) before. The value range can be queried by get_framegrabber_param(...,'focus_abs_range',...).
	'frame_rate'		fps (float)		Sets the desired frame rate. The available frame rates can be queried by get_framegrabber_param(..,'frame_rate_values', ...).
	'gain_b'		min ... max (float)		Gain for blue pixels as a multiplicative factor. The value range can be queried by get_framegrabber_param(...,'gain_b_range',...).
	'gain_g1'		min ... max (float)		Gain for green pixels on red rows as a multiplicative factor. The value range can be queried by get_framegrabber_param(...,'gain_g1_range',...).
	'gain_g2'		min ... max (float)		Gain for green pixels on blue rows as a multiplicative factor. The value range can be queried by get_framegrabber_param(...,'gain_g2_range',...).
	'gain_master'		min ... max (float)		Overall gain as a multiplicative factor. The value range can be queried by get_framegrabber_param(...,'gain_master_range',...).
	'gain_r'		min ... max (float)		Gain for red pixels as a multiplicative factor. The value range can be queried by get_framegrabber_param(...,'gain_r_range',...).
	'gamma'		min ... max (float)		Sets the gamma value of the camera. The value range can be queried by get_framegrabber_param(...,'gamma_range',...).
	'gpio_configure'		byte		Configures the digital input/output lines of the camera.
	'gpio_write'		byte		Writes the specified byte value to the digital output of the camera.
	'gpo_select'		byte		Selects the digital output lines of the camera.
	'grab_timeout'		100 ... 32768		Specifies the desired timeout in milliseconds for aborting a pending grab. Default: 5000.
	'image_height'		height (long)		Sets the height of the output image.
	'image_width'		width (long)		Sets the width of the output image.
	'iris'		min ... max (float)		Specifies the desired iris of the lens (not supported by all cameras). The value range can be queried by get_framegrabber_param(...,'iris_range',...).
	'start_column'		column (long)		Sets the column coordinate of the upper left corner of the output image.
	'start_row'		row (long)		Sets the row coordinate of the upper left corner of the output image.
	'strobe'		'enable', 'disable'		Enables or disables the strobe mode. Default: 'disable'.
	'strobe_delay'		0.0 ... 32768 (float)		Time interval from when exposure starts to the time the flash is fired in milliseconds.
	'strobe_duration'		min ... max (float)		Length of the strobe signal in milliseconds.
	'strobe_from_start_of_exposure'		'enable', 'disable'		Identifies the strobe signal from the start of the exposure of the sensor. Please be aware that this parameter is not used in the Lumenera Capture application (see as an example the Lumenera Snapshot sample application).
	'white_balance_u'		min ... max (float)		Perform white balance. The value range can be queried by get_framegrabber_param(...,'white_balance_u_range',...).
	'white_balance_v'		min ... max (float)		Perform white balance. The value range can be queried by get_framegrabber_param(...,'white_balance_v_range',...).

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'].

	'color_format'		color format (string)		Color format of the camera, e.g., 'mono', or 'bayer_rggb'.
	'gpio_read'		byte (integer)		Reads the digital input of the camera.
	'host_ip_address'		ip_address		Gets the ip address of the network interface card. The parameter is only accessible if the LuCam GigE Vision cameras are used.
	'host_subnet_mask'		subnet_mask		Gets the subnet mask of the network interface card. The parameter is only accessible if the LuCam GigE Vision cameras are used.
	'ip_address'		ip_address		Gets the ip address of the camera. The parameter is only accessible if the LuCam GigE Vision cameras are used.
	'revision'		revision		The revision number of the HALCON LuCam interface.
	'sensor_height'		height (integer)		Returns the vertical sensor size in pixel.
	'sensor_width'		width (integer)		Returns the horizontal sensor size in pixel.
	'subnet_mask'		subnet_mask		Gets the subnet mask of the camera. The parameter is only accessible if the LuCam GigE Vision cameras are used.

Release Notes

• Revision 4.2 (Sep 19, 2011):
  • Adapted to SDK version 6.1.
  • Added support of LuCam GigE Vision cameras.
  • Added new parameters 'acquisition_mode', 'ip_address', 'subnet_mask', 'host_ip_address', and 'host_subnet_mask'.
  • Added generic parameter 'post_dual_tap_correction'.
  • Implemented query info_framegrabber(...,'device',...). The query returns now a dynamic list of all detected USB and GigE Vision devices.
  • Adapted query info_framegrabber(...,'info_boards',...). The actually available GigE Vision and USB cameras are now identified via the prefix 'usb' or 'gige'.
• Revision 4.1 (Mar 12, 2009):
  • New parameters 'do_abort_grab' and 'strobe_from_start_of_exposure'.
• Revision 4.0 (Dec 1, 2008):
  • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
• Revision 3.4 (Nov 27, 2008):
  • Support of Windows XP x64 (using LuCam SDK version 5.0).
  • Accelerate the execution time of the parameters 'gpio_write', 'gpio_configure', 'gpo_select'.
  • Cleanup temporary memory in close_framegrabber.
• Revision 3.3 (Aug 12, 2008):
  • New read-only parameters 'sensor_width' and 'sensor_height' to query the actual size of the sensor.
  • New parameters 'frame_rate' and 'frame_rate_values'.
  • All range queries of get_framegrabber_param provided the range values incorrectly in the order [min, max, default, step] instead of [min, max, step, default]. This bug has been fixed.
• Revision 3.2 (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.1 (Mar 31, 2008):
  • Adaptation to SDK version 4.5.
  • New parameters 'focus', 'focus_abs', 'iris', and 'do_calibrate_auto_lens' for focus and iris control.
  • New parameter 'strobe_duration'.
  • New parameters 'gpio_read', 'gpio_write', 'gpio_configure', and 'gpo_select' for software control of the digital input/output signals.
• Revision 3.0 (May 15, 2007):
  • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
• Revision 2.1 (Jan 12, 2007):
  • Adaption to SDK version 4.0.
  • Added parameters 'do_flush_buffer', 'gamma', and 'gamma_range'.
  • Renamed parameter 'do_camera_reset' to 'do_reset_camera'. For backward compatibility the old name still works.
• Revision 2.0 (Jun 27, 2006):
  • First official release.