HALCON 9.0 Image Acquisition Interface for Teledyne DALSA Boards and Genie Cameras via Sapera LT library

This page provides the documentation of the HALCON SaperaLT interface for analog and digital frame grabber boards like Xcelera-CL, X64-CL, X64-AN Quad, and PC2-Vision, and also the Genie GigE Vision camera series from Teledyne DALSA. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.11

System Requirements

• Intel compatible PC with Windows XP/Vista/7 or Windows XP x64/Vista x64/7 x64.
• Successfully installed Sapera LT software library (Windows XP/Vista/7: version 7.0 or higher, Windows x64: version 7.10 or higher) as well as the camera configuration and demo executable CamExpert. Make sure that the environment variable %SAPERADIR% is set correctly to the particular installation directory. Note that for using the HALCON SaperaLT interface you need a valid .ccf file for your specific camera configuration, which must be created using the Teledyne DALSA CamExpert application!
• HALCON image acquisition interface hAcqSaperaLT.dll or hAcqSaperaLTxl.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.
• Genie cameras: Successfully installed Genie Framework for SaperaLT and Sapera Network Imaging Package (versions 1.20 or higher).

Features

• Synchronous and asynchronous grabbing.
• Support of multiple cameras and multiple boards.
• Support of a wide range of area and line scan cameras varying among the different models of Teledyne DALSA frame grabber boards.
• External trigger and asynchronous camera reset.
• Cropping of image parts.
• Setting of lookup tables.
• Software bayer decoding.
• Software control of a wide range of configuration parameters.
• Support of user-specific callback function.

Limitations

• grab_data and grab_data_async not supported.
• Genie cameras: YUV color format currently not supported.

Description

Parameters for open_framegrabber():

	Name		'SaperaLT'		The name of the HALCON image acquisition interface.
	HorizontalResolution		1, 2, 4		Use '1' for full resolution, '2' for half resolution or '4' for quarter resolution. If you want to use other values for the image resolution, set it via the camera configuration file specified in the CameraType parameter. Default: 1.
	VerticalResolution		1, 2, 4		Use '1' for full resolution, '2' for half resolution or '4' for quarter resolution. If you want to use other values for the image resolution, set it via the camera configuration file specified in the CameraType parameter. Default: 1.
	ImageWidth		0, width		The width of the desired image part ('0' stands for the maximum image height). This value has to be equal or smaller than the maximum image height. Default: 0.
	ImageHeight		0, height		The height of the desired image part ('0' stands for the maximum image height). This value has to be equal or smaller than the maximum image height. Default: 0.
	StartRow		row		The row coordinate of the upper left pixel of the desired image part. Default: 0.
	StartColumn		column		The column coordinate of the upper left pixel of the desired image part. Default: 0.
	Field		---		Ignored.
	BitsPerChannel		---		Ignored (the desired pixel depth will be set accordingly to the parameter settings in the camera configuration file).
	ColorSpace		'default', 'rgbx'		If not set to 'rgbx', the parameter is ignored and the desired pixel depth will be set accordingly to the parameter settings in the camera configuration file. Otherwise, a 4-channel image will be created, see also the parameter 'pixel_arrangement'. Please note that a 4-channel RGB image looks like a gray value image in HDevelop as by default only the first image channel will be displayed.
	Generic		'num_buffers=<number>', -1		num_buffers: To set the number of buffers used in the HALCON acquisition interface a value between 2 and 65535 has to be set. Note that depending on the image size of the used camera a high number of buffers can exceed the available memory size of your computer. Default: 2.
	ExternalTrigger		'true', 'false'		Activate/deactivate external triggering. Note that the setting in the camera configuration file is ignored! Default: 'false'.
	CameraType		'configuration'		Specify the name (including the full path name) of the desired camera configuration file, i.e., the .ccf file. A camera configuration file can be created with the help of the camera configuration tool CamExpert; using that tool you can test and save an appropriate configuration for your camera and pass the complete file name (e.g., 'C:\Program Files\DALSA\Sapera\CamFiles\User\myCameraConfig.ccf').
	Device		'default', 'Bandit-II_CV_1', 'Bandit-II_MV_1', 'Bandit-II_RGB_1', 'Genie_C640_1', 'Genie_C640-S3_1','Genie_M640_1', 'Genie_M640-S3_1', 'Genie_HM_640_1', 'Genie_C1024_1', 'Genie_M1024_1', 'Genie_HM1024_1', 'Genie_C1400_1', 'Genie_C1400-S3_1', 'Genie_M1400_1', 'Genie_M1400-S3_1', 'Genie_HM1400_1', 'PC2-Vision_1', 'PC2-CamLink_1' 'Viper_CamLink_1', 'Viper_Digital_1', 'Viper_Quad_1', 'Viper_RGB_1', 'X64-AN_Quad_1', 'X64_1', 'X64-CL_iPro_1', 'X64-CL_Dual_1', 'X64-LVDS_1', 'Xcelera-CL_PX4_1', ...		The name of one of the desired Teledyne DALSA image acquisition device. If you have more than one device with the same name, the number at the end of the device name is counted upwards to access each device separately. If 'default' is specified, the interface will refer to the first device that can be found. A list of available devices can be queried by calling info_framegrabber(..,'device',...). Default: 'default'.
	Port		-1, 0, 1, 2, 3, 4, 5		Specifies the number of the desired camera port. If -1 is selected, the port will be selected from the configuration file. If this fails, the first active device found is selected (analog boards only). In case of Genie GigE Vision cameras this parameter will be ignored. Default: -1.
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

General Parameters
Parameters for Teledyne DALSA boards and Genie cameras. Please note that the Genie cameras have additional parameters, which depend on the camera model and are not listed in this manual. A list of all available parameters is returned by get_framegrabber_param(...,'available_param_names',...).

	'continuous_grabbing'		'enable', 'disable'		Sets grabbing mode from single frame capture to continuous mode. If the continuous mode is enabled, the acquisition device grabs all the time (Note that in this mode grab_image_async behaves like grab_image!). Default: 'disable'.
	'do_abort_grab'		---		Aborts the current grab. Please note that depending on your actually used Sapera LT version the corresponding SDK function may not work correctly.
	'grab_timeout'		msec		Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab. The value -1 means to never abort. Default: 5000.
	'image_part'		[row1,col1,row2,col2]		Allows you to crop a defined part of the image. In order to define a rectangular region for image acquisition, the point on the left top and the point on the right bottom has to be entered. If -1 is passed to every value, the values will be set to their default values. If a value exceeds the image size, it is set to the maximum allowable value.
	'multiple_image_num'		1, 2, 3, ...		Enables a special grabbing mode for line scan cameras. If this parameter is set to a value x (bigger than 1), grab_image splits the image in x parts. In the camera config file the full height has to be set. With every call of grab_image or grab_image_async the next part is returned. The next image is acquired, if all parts are returned. The parameter 'continuous_grabbing' has to be disabled to use this mode.
	'num_buffers'		number (long)		The number of buffers used for the image acquisition in HALCON. Only values between 2 and 65535 are valid.
	'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'.
	'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! Default: 'disable'.

Parameters for Teledyne DALSA boards
These parameters are only supported by Teledyne DALSA frame grabber boards.

	'bayer_hardware_decoder'			'enable', 'disable'	Enables or disables the hardware bayer decoder (if available). The setting takes effect with the next call of 'grab_image' or 'grab_image_async'.
	'bayer_hardware_decoder_method'			1, 2, 3	Sets the method for data conversion of the hardware bayer decoder.
	'bayer_software_decoder'			'enable', 'disable'	Enables or disables the software bayer decoder. The setting takes effect with the next call of 'grab_image' or 'grab_image_async'.
	'bayer_software_decoder_alignment'			'gb_rg', 'bg_gr', 'rg_gb', 'gr_bg'	Sets the alignment of the upper left 2x2 square of the camera`s bayer scheme. Default: 'gb_rg'.
	'bayer_software_decoder_format'			'RGB888', 'RGB8888', 'RGB101010'	Sets the output buffer format of the software bayer decoder. 'RGB101010' is only available, if the input format is MONO16! Default: RGB888.
	'bayer_software_decoder_method'			1, 2, 3	Sets the method for data conversion of the software bayer decoder. method 1: Fast, based on bilinear interpolation method 2: Advanced, preserves image edges. Works only good, if the image has a strong green content. method 3: Advanced, preserves image edges, independent of image green content. Default: 1.
	'bayer_software_decoder_whitebalance'			[wb.red, wb.green, wb.blue]	Sets the white balance gain for each color channel. You always have to set all three values (floating point). If all values are set to 1.0, no white balance is used for the software bayer conversion. Default: [1.0, 1.0, 1.0].
	'bit_ordering'			'std', '9_10', msb_10', 'msb_12', 'inv'	The digital bit ordering of the camera. std: Standard digital bit ordering. 9_10: Video data bits 9 and 10 are swapped with bits 0 and 1 (required by some 10-bit digital cameras). msb_10: Video data bits 0-7 connect to the acquisition device input bits 2-9 (required by some 8-bit digital cameras). msb_12: Video data bits 4-11 are directed to the input bits 0-7 of the acquisition device (required by some 12-bit digital cameras). inv: The video data bits are inverted (logical NOT).
	'brightness'			min...max	Specifies the brightness of the video signal. Represents the percentage of brightness to add or subtract to the composite video signal (analog only).
	'brightness_blue'			min...max	Specifies the brightness of the blue video signal. Represents the percentage of brightness to add or subtract to the blue video signal (analog only).
	'brightness_green'			min...max	Specifies the brightness of the green video signal. Represents the percentage of brightness to add or subtract to the green video signal (analog only).
	'brightness_red'			min...max	Specifies the brightness of the red video signal. Represents the percentage of brightness to add or subtract to the red video signal (analog only).
	'cam_reset'			'enable', 'disable'	Enables or disables the reset pulse to the camera. You must have set the signal properties and the method first.
	'cam_reset_delay'			0...max	Reset pulse delay (in µs). After receiving a trigger pulse, the acquisition device will wait this delay before generating the reset pulse.
	'cam_reset_duration'			1...65535000	Duration of the reset pulse.
	'cam_reset_signal'			'active_low', 'active_high'	Defines the reset pulse signal.
	'cam_trigger_delay'			min...max	Represents the delay (in µs) the acquisition device will wait, before generating the trigger pulse (external, internal or software).
	'cam_trigger_duration'			min...max	The effect of this value differs addicted to the selected method.
	'cam_trigger'			'enable', 'disable'	Enables or disables the frame trigger pulse to the camera (area scan only).
	'cam_trigger_method'			1, 2	Defines the trigger method of the camera, see Sapera LT documentation for more details.
	'cam_trigger_signal'			'active_low', 'active_high'	Defines the camera trigger signal.
	'channel_height'			height	Specifies the channel height in the split channel mode.
	'contrast'			min...max	Specifies the contrast of the video signal. Represents the percentage of contrast to be applied to the composite video signal (analog only). Step: 1000 (1%).
	'contrast_blue'			min...max	Specifies the contrast of the blue video signal. Represents the percentage of contrast to be applied to the blue video signal (analog only). Step: 1000 (1%).
	'contrast_green'			min...max	Specifies the contrast of the green video signal. Represents the percentage of contrast to be applied to the green video signal (analog only). Step: 1000 (1%).
	'contrast_red'			min...max	Specifies the contrast of the red video signal. Represents the percentage of contrast to be applied to the red video signal (analog only). Step: 1000 (1%).
	'decimate_count'			0...max	Specifies the number of fields or frames to decimate per second.
	'decimate_method'			'disable', 'field', 'frame', 'even', 'odd'	Defines the decimation method, see Sapera LT documentation for more details.
	'do_force_trigger'			---	Sends a software trigger.
	'ext_frame_trigger'			'enable', 'disable'	Enables or disables external frame trigger (line scan cameras only). You must have set the signal properties first.
	'ext_frame_trigger_level'			'TTL', 'RS-422', 'LVDS'	Defines the external frame trigger level connected to the acquisition device (line scan cameras only).
	'ext_frame_trigger_signal'			'active_low', 'active_high', 'falling', 'rising', 'double_rising', 'double_falling'	Defines the external frame trigger signal connected to the acquisition device (line scan cameras only). 'double_rising/falling' means to start the acquisition on the rising/falling edge of trigger 1 and to end on the rising/falling edge of trigger 2.
	'ext_frame_trigger_source'			0...max	Specifies the physical input source the external frame trigger is connected to on the acquisition device, in the case where the acquisition device has more than one input. Default: 0.
	'ext_line_trigger'			'enable', 'disable'	Enables or disables external line trigger (line scan cameras only). You must have set the signal properties first.
	'ext_line_trigger_level'			'TTL', 'RS-422', 'LVDS'	Defines the external line trigger level connected to the acquisition device (line scan cameras only).
	'ext_line_trigger_signal'			'falling', 'rising'	Defines the external line trigger signal connected to the acquisition device (line scan cameras only).
	'ext_line_trigger_source'			0...max	Specifies the physical input source the external line trigger is connected to on the acquisition device, in the case where the acquisition device has more than one input. Default: 0.
	'external_trigger'			'true', 'false'	Specifies if external triggering is used. Default: 'false'.
	'ext_trigger_delay'			0 ... max	Represents the delay of the external trigger signal in units specified by 'ext_trigger_delay_time_base'. Default: 0.
	'ext_trigger_delay_time_base'			0 ... max	Represents the granularity of units required to adjust the delay of the external trigger signal with 'ext_trigger_delay'. Default: 0.
	'ext_trigger_duration'			0 ... max	Minimum external trigger pulse duration. For details please refer to the 'Sapera Acquisition Parameter' manual. Default: 0.
	'ext_trigger_level'			'TTL', 'RS-422', 'LVDS'	Defines the external trigger level connected to the acquisition device. Default: 'TTL'.
	'ext_trigger_signal'			'active_low', 'active_high', 'falling', 'rising'	Defines the external trigger signal connected to the acquisition device. Default: 'rising'.
	'ext_trigger_source'			0, 1, 2	Specifies the physical input source the external trigger is connected to on the acquisition device, in the case where the acquisition device has more than one input. Default: 0.
	'frame_integration'			'enable', 'disable'	Enables or disables the frame integration control (area scan cameras only). You must have set the signal properties and the method first.
	'frame_integration_count'			1...(2^32)-1	Specifies the number of frames to integrate.
	'frame_integration_method'			1, 2	Defines the frame integration method, see Sapera LT documentation for more details.
	'frame_integration_signal'			'active_low', 'active_high'	Defines the frame integration signal.
	'hue'			min...max	Specifies the phase change in degrees applied to the hue control (analog composite or Y/C only).
	'int_frame_trigger'			'enable', 'disable'	Enables or disables internal frame trigger (area scan cameras only). You must have set the trigger frequency first.
	'int_frame_trigger_freq'			min...max	Defines the internal frame trigger frequency in milli-Hz (area scan cameras only).
	'int_line_trigger'			'enable', 'disable'	Enables or disables internal line trigger. You must have set the trigger frequency first.
	'int_line_trigger_freq'			min...max	Defines the internal line trigger frequency in Hz.
	'line_integration'			'enable', 'disable'	Enables or disables the line integration signal pulse to the camera (line scan cameras only). You have to set the signal properties and the method first.
	'line_integration_duration'			min...max	Specifies the line integration pulse width in µs (line scan cameras only).
	'line_integration_method'			1, 2, 3, 4, 7	Defines the line integration method, see Sapera LT documentation for more details (line scan cameras only).
	'line_integration_pulse0_delay'			min...max	Line integration delay (in µs) of pulse 0. After receiving a trigger pulse, the acquisition device will wait this delay before generating the line integration pulse 0 (line scan cameras only).
	'line_integration_pulse1_delay'			min...max	Line integration delay (in µs) of pulse 1. After receiving a trigger pulse, the acquisition device will wait this delay before generating the line integration pulse 1 (line scan cameras only).
	'line_integration_pulse0_duration'			min...max	Specifies the line integration pulse 0 width (in µs) (line scan cameras only).
	'line_integration_pulse1_duration'			min...max	Specifies the line integration pulse 1 width (in µs) (line scan cameras only).
	'line_integration_pulse0_signal'			'active_low', 'active_high'	Defines the line integration signal of pulse 0 (line scan cameras only).
	'line_integration_pulse1_signal'			'active_low', 'active_high'	Defines the line integration signal of pulse 1 (line scan cameras only).
	'linescan_direction'			'enable', 'disable'	Enables or disables the linescan direction (line scan cameras only).
	'linescan_direction_output'			'forward', 'reverse'	Sets the linescan direction (line scan cameras only). Note that the value can only be set to 'reverse', if the parameter 'linescan_direction' is enabled.
'linescan_direction_signal'	'active_low', 'active_high'	Sets the signal of the linescan direction (line scan cameras only).
'lut'	'enable', 'disable'	Enables or disables the lookup table. Default: disable. Caution: On some acquisition devices, the LUT can not be disabled.
'pixel_arrangement'	'line_interleaved', 'pixel_interleaved'	In case of 4-channel images this parameter is used to set the pixel arrangement, if the output format differs from an RGB format. Default: 'pixel_interleaved'.
'pixel_clock_detection'	'falling', 'rising'	Specifies the type of pixel clock detection of the video source.
'pixel_clock_ext'	min...max	Specifies the external pixel clock frequency in Hz. Note that this parameter is valid only if parameter 'pixel_clock_source' specifies that an external pixel clock is needed.
'pixel_clock_int'	min...max	Specifies the internal pixel clock frequency in Hz. Note that this parameter is valid only if parameter 'pixel_clock_source' specifies that an internal pixel clock is needed.
'pixel_clock_source'	'ext', 'ext_int', 'int'	Specifies the source of the acquisition device pixel clock. 'ext_int' means that the external pixel clock is used while the acquisition device simultaneously outputs its own internal pixel clock for other use.
'port'	0, 1, 2, 3, 4, 5	Specifies the number of the desired camera port.
'saturation'	min...max	Specifies the color saturation percentage control (analog composite only).
'shaft_encoder'	'enable', 'disable'	Enables or disables shaft encoder support of the acquisition device.
'shaft_encoder_drop'	0...max	Specifies the number of dropped signal edges using a shaft encoder.
'shaft_encoder_level'	'TTL', 'RS-422', 'LVDS'	Shaft encoder level fed to the acquisition device (line scan cameras only).
'shaft_encoder_multiply'	min...max	Number of signal edges generated for each shaft encoder signal edge, when video acquisitions are controlled by an external shaft encoder trigger.
'sharpness'	min...max	Specifies the sharpness control applied to the video signal (analog composite only).
'strobe'	'enable', 'disable'	Enables or disables the strobe pulse. You must have set the signal properties and the method first.
'strobe_delay'	min...max	Specifies the strobe pulse delay 1 (in µs).
'strobe_delay2'	min...max	Specifies the strobe pulse delay 2 (in µs).
'strobe_duration'	min...max	Specifies the strobe pulse width (in µs).
'strobe_level'	'TTL', 'RS-422', 'LVDS'	Strobe signal level output by the acquisition device.
'strobe_method'	1, 2	Selects the strobe pulse output method, see Sapera LT documentation for more details.
'strobe_signal'	'active_low', 'active_high'	Defines the strobe pulse signal.
'time_integration'	'enable', 'disable'	Enables or disables the time integration signal pulse to the camera (area scan cameras only). You have to set the signal properties and the method first.
'time_integration_delay'	min...max	Time integration delay (in µs). After receiving a trigger pulse, the acquisition device will wait this delay before generating the time integration pulse(s).
'time_integration_duration'	min...max	Specifies the time integration pulse width in µs (area scan cameras only).
'time_integration_method'	1, 2, 3, 4, 5, 6, 7, 8	Defines the time integration method, see Sapera LT documentation for more details.
'time_integration_pulse0_delay'	min...max	Time integration delay (in µs) of pulse 0. After receiving a trigger pulse, the acquisition device will wait this delay before generating the time integration pulse 0.
'time_integration_pulse1_delay'	min...max	Time integration delay (in µs) of pulse 1. After receiving a trigger pulse, the acquisition device will wait this delay before generating the time integration pulse 1.
'time_integration_pulse0_duration'	min...max	Specifies the time integration pulse 0 width (in µs).
'time_integration_pulse1_duration'	min...max	Specifies the time integration pulse 1 width (in µs).
'time_integration_pulse0_signal'	'active_low', 'active_high'	Defines the time integration signal of pulse 0.
'time_integration_pulse1_signal'	'active_low', 'active_high'	Defines the time integration signal of pulse 1.

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 tool-tip of the corresponding parameter as a string.
• '_range': These parameters provide the minimum, maximum, step width, 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'].

General Parameters
Parameters for Teledyne DALSA boards and Genie cameras. Please note that the Genie cameras have additional parameters, which depend on the camera model and are not listed in this manual. A list of all available parameters is returned by get_framegrabber_param(...,'available_param_names',...).

	'available_callback_types'		callback_type		Query all callback types which are supported by this interface.
	'available_param_names'		parameters (string)		In case of a Genie GigE Vision camera the available parameters supported by this camera are returned. If a frame grabber board is used, a static list of all parameters is returned.
	'image_available'		0, 1 (long)		Shows if a grabbed image is completely written and available.
	'internal_device_pointer'		handle (string)		Returns the internal SDK handle of the current acquisition device which enables direct device access.Use on your own risk!
	'revision'		revision (string)		The revision number of the HALCON SaperaLT interface.

Parameters for Teledyne DALSA boards
These parameters are only for Teledyne DALSA frame grabber boards.

	'bayer_hardware_decoder'		status (long)		Gets the status of the hardware bayer decoder of the acquisition device. When present and enabled, the bayer video data is converted into the specified output format (from the camera configuration file). Note that this feature is not supported by all board types!
	'camera_model'		model (string)		The name of the camera model.
	'camera_vendor'		vendor (string)		The name of the camera vendor.
	'image_height'		height (long)		The height of the image.
	'image_width'		width (long)		The width of the image.
	'pixel_clock_11'		frequency (long)		The pixel clock frequency in Hz, so that the camera image has an 1:1 aspect ratio.
	'signal_status'		status (long)		The current signal status of the camera.

Lookup tables:

Waiting time after special functions:

Split channel mode:

Parameters for set_framegrabber_callback():

The following callback types are supported by this interface:

'transfer_end'

If a frame grabber is used, the 'transfer_end' callback corresponds to the CorXferRegisterCallback(...,COR_XFER_VAL_EVENT_TYPE_END_OF_FRAME, ...) command. The callback will be signaled after the image data is written into the local PC buffer. In case of a GigEVision device, the 'transfer_end' callback corresponds to the CorAcqDeviceRegister(...,'End of Readout',...) command. Note that the buffer is completely acquired by the device but not yet finally transferred to the PC.

All actually supported callback types of a specific image acquisition device can be queried by calling get_framegrabber_param with the parameter 'available_callback_types'. Once the callback is registered the specified callback function will be called. If the callback function is set to NULL, the corresponding callback will be unregistered.

The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) for Windows operating systems. All other operating systems use their native calling convention instead of __stdcall.
The callback function uses the following parameters:

	AcqHandle		Acquisition handle of the corresponding image acquisition instance.
	Context		Optional context data of the specific callback. In the SaperaLT interface, this parameter is not used, i.e., Context is set to NULL.
	UserContext		User context as set via set_framegrabber_callback.

Note that the execution time of a user-specific callback function should always be as short as possible since during the execution of a callback function the handling of further internal callbacks might be blocked. This can be achieved by removing the actual processing from the user-specific callback function to a separate thread that is controlled via signals or events.

Release Notes

• Revision 4.11 (Nov 28, 2011):
  • Fixed problem with delay and duration parameters with some frame grabber boards, where valid values could not be set.
  • Corrected return values of parameter 'color_space' in info_framegrabber.
  • Added section 'Waiting time after special functions' to this document.
• Revision 4.10 (Oct 18, 2011):
  • Added description for parameter 'available_callback_types'.
  • Reduced needed memory in case of using a frame grabber.
  • Removed obsolete parameters 'flat_field' and 'flat_field_select'.
• Revision 4.9 (Jul 27, 2011):
  • Adapted to Sapera LT library version 7.0.
  • Fixed problem grabbing images on computers with 64-bit operating system and more than 4GB RAM.
  • Fixed performance problem with Genie cameras, so that the full frame rate can be reached, if 'continuous_grabbing' is enabled.
  • Fixed error message under Windows 7 (H_ERR_FGWP), if a Camera Link camera is used.
  • Fixed wrong return values of parameter 'image_available'.
  • Fixed timeout error when setting parameter 'grab_timeout' to -1.
  • Fixed problem with parameter 'internal_device_pointer' on 64-bit systems with more than 4 GB RAM. Now, the value is returned as a string.
  • Fixed error in open_framegrabber on Windows 7 to prevent timing problems when detecting the camera port on frame grabber boards.
  • Improved internal buffer handling.
  • Improved search path for camera configuration file.
  • Added parameter 'multiple_image_num' to split a buffer in multiple images.
  • Added parameter 'num_buffers' to change the number of used buffers.
  • Added parameters 'line_integration', 'line_integration_duration', 'line_integration_method', 'line_integration_pulse0_delay', 'line_integration_pulse1_delay', 'line_integration_pulse0_duration', 'line_integration_pulse1_duration', 'line_integration_pulse0_signal', and 'line_integration_pulse1_signal' for line scan cameras.
  • Added parameters 'pixel_clock_11', 'pixel_clock_detection', 'pixel_clock_ext', 'pixel_clock_int, and 'pixel_clock_source' to control the pixel clock values.
  • Added 'transfer_end' callback functionality.
  • Added description of the parameter 'bayer_hardware_decoder' to this document.
• Revision 4.8 (Oct 27, 2010):
  • Fixed timeout error when setting parameter 'grab_timeout' to -1.
• Revision 4.7 (Sep 10, 2010):
  • Fixed problem with parameter 'continuous_grabbing', which can now be set even if no Xfer has been started. Internally, the buffers will be allocated before the transfer starts.
  • Fixed problem when setting parameters 'TriggerEnable' or 'continuous_grabbing'.
• Revision 4.6 (Jul 30, 2010):
  • Added support of 4-channel RGB images. Therefor it is now possible to specify 'rgbx' in open_framegrabber as a value for ColorSpace. If the output format of the ccf file is no RGB format, the parameter 'pixel_arrangement' has to be set accordingly.
  • Added parameters 'int_line_trigger', 'int_line_trigger_freq', and 'signal_status'.
  • Fixed problem with image transfer connection when using the parameter 'image_part'.
• Revision 4.5 (May 17, 2010):
  • Fixed crash of HDevelop, when using the Image Acquisition Assistant together with Teledyne DALSA Genie cameras.
  • Fixed image acquisition problem when using PixelFormat 'Bayer Raw10' or color_space 'yuv'.
  • Fixed problem in grab_image_start when using Teledyne DALSA Genie cameras.
  • Separated parameters for Teledyne DALSA Genie cameras and frame grabber boards in get_framegrabber_param and set_framegrabber_param.
  • Fixed problem when setting parameter 'external_trigger' after an image has already been acquired.
  • The dynamic setting of 'Height', 'PixelFormat', 'OffsetX', 'OffsetY' and 'Width' has been improved.
  • The allocation of the image buffers is now done, when a grab is requested and not in open_framegrabber anymore.
  • Changed return value of info_framegrabber(...,'info_boards',..).
  • info_framegrabber(...,'device',..) now returns the currently available devices instead of a statical list.
  • Moved parameter 'bayer_software_decoder_whitebalance' to hidden parameters for the HDevelop Image Acquisition Assistant.
  • Updated example programs.
• Revision 4.4 (Mar 16, 2010):
  • The internal memory for the Sapera LT server names was not released in close_framegrabber. This problem has been fixed.
  • Added read-only parameters 'image_height' and 'image_width' for Teledyne DALSA boards.
  • Renamed parameter 'acquisition_handle' to 'internal_device_pointer' to avoid confusion with the parameter AcqusitionHandle in open_framegrabber. For backward compatibility the old parameter name still works.
• Revision 4.3 (Jan 14, 2010):
  • Fixed bug in open_framegrabber to ensure the proper use of multiple cameras, if device parameter is set to 'default'.
  • Added parameter 'do_force_trigger' to allow software triggering.
• Revision 4.2 (Nov 10, 2009):
  • Fixed bugs in open_framegrabber, grab_image, and grab_image_async to ensure the proper use of multiple Genie cameras in one application.
  • Fixed bug in general parameter handling to enable the use of all parameters in the HDevelop Image Acquisition Assistant.
  • Added support for RGB161616 color format.
  • Corrected transformation of BGR101010 pixel data to ensure the correct alignment of the pixel values.
• Revision 4.1 (Mar 5, 2009):
  • Added parameters 'linescan_direction', 'linescan_direction_output', and 'linescan_direction_signal'.
• Revision 4.0 (Dec 1, 2008):
  • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD). Note that the split channel mode is no more necessary in combination with HALCON XL.
• Revision 3.4 (Jul 15, 2008):
  • Bugfix in grab_image and grab_image_async in case of an error. Now the next grab returns always the correct image.
  • The HDevelop Image Acquisition Assistant now shows also the HALCON specific parameters in case of Genie cameras.
  • Added buffer rotation mode 'NEXT_EMPTY' with fallback to 'ASYNCHRONOUS'.
  Revision 3.3 (May 28, 2008):
  • Added support of Windows x64 Edition.
  • Bugfix regarding sporadic timeouts.
  • Added automatic rotation of Sapera buffers.
  • Bugfix regarding parameterization of Genie cameras via the HDevelop Image Acquisition Assistant.
• Revision 3.2 (Apr 22, 2008):
  • Bugfix in registering/unregistering the end-of-frame callback.
  • Bugfix in parameter 'external_trigger'.
  • Added read-only parameters with postfix '_description', '_range', and '_values' to enable the easy parameterization via a generic graphical user interface.
• Revision 3.1 (Oct 16, 2007):
  • Adapted to Sapera LT library version 6.0.
  • Added support for Teledyne DALSA Genie GigE Vision camera series.
  • Bugfix in buffer handling.
  • Added parameters 'available_param_descriptions', 'available_param_names', and 'available_param_types'.
  • Added parameters 'continuous_grabbing', 'continuous_grabbing_values', 'start_async_after_grab_async_values', and 'volatile_values'.
• Revision 3.0 (May 15, 2007):
  • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
• Revision 2.2 (Mar 28, 2007):
  • Added support for acquiring images with more than 32767 lines by using the so-called split channel mode.
  • Added software bayer encoder.
  • Added the following parameters: 'bayer_software_decoder_alignment', 'bayer_software_decoder_format', 'bayer_software_decoder_whitebalance', 'bayer_software_decoder', 'bayer_software_decoder_method', and 'channel_height'.
  • Changed name of the parameter 'bayer_decoding' and 'bayer_decoder_method' to 'bayer_hardware_decoder' and 'bayer_hardware_decoder_method'.
  • Fixed bug in ring buffer handling.
  • Fixed bugs in parameters 'do_abort_grab', 'flat_field_select', and 'image_available'.
• Revision 2.1 (Nov 28, 2005):
  • Added support of LUTs.
  • Added the following parameters: 'acquisition_handle', 'do_abort_grab, 'image_available', and 'lut'.
  • Fixed bug in RGB8888 output format.
• Revision 2.0 (Oct 26, 2005):
  • First official release.