HALCON 9.0 Image Acquisition Interface for 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, PC2-Vision, Viper, and Bandit-II and also the Genie GigE Vision camera series from DALSA. Note that the interface version for Windows x64 supports only the PCI Express boards, e.g., Xcelera-CL and X64-CL Express . Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.3

System Requirements

• Intel compatible PC with Windows XP/Vista or Windows x64.
• Successfully installed Sapera LT software library (Windows 2000/XP/Vista: version 6.0 or higher, Windows x64: version 6.11 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 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). Please note that you need administrator privileges to access the GigE Transport Layer of the network, i.e., even your application needs these settings to access the camera!

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

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		Ignored (the actual image resolution is set via the camera configuration file specified in the CameraType parameter!). Default: 1.
	VerticalResolution		1		Ignored (the actual image resolution is set 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		---		Ignored (the desired pixel depth will be set accordingly to the parameter settings in the camera configuration file).
	Generic		---		Ignored.
	ExternalTrigger		'true', 'false'		Activate/deactivate external triggering. Note that the setting in the camera configuration file is ignored! Default: 'false'.
	CameraType		'default'		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 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. 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 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.
	'do_force_trigger'		---		Sends a software trigger.
	'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.
	'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 DALSA boards
These parameters are only supported by DALSA frame grabber boards.

	'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.
	'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.
	'flat_field'		'enable', 'disable'		Enable or disable the flat field resource.
	'flat_field_select'		0...(n-1)		Select the active flat field.
	'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).
	'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.
	'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 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',...).

	'acquisition_handle'		handle		Returns the handle of the current acquisition device to give the user the possibility to write his own functions, if they are not supported by the HALCON interface.
	'available_param_descriptions'		description		In case of a Genie GigE Vision camera the description of the available parameters supported by the current camera are returned. If a frame grabber board is used, a static list with all parameter names is returned.
	'available_param_names'		parameters		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.
	'available_param_types'		types		In case of a Genie GigE Vision camera the types of the available parameters supported by the current camera are returned. If a frame grabber board is used, this list is static.
	'image_available'		0, 1		Shows if a grabbed image is completely written and available.
	'revision'		revision		The revision number of the HALCON SaperaLT interface.

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

	'bayer_hardware_decoder'		status		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		The name of the camera model.
	'camera_vendor'		vendor		The name of the camera vendor.

Lookup tables:

Split channel mode:

Release Notes

• 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 SaperaLT 6.0.
  • Added support for 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.