HALCON 10 Image Acquisition Interface for MESA Imaging SR4000 Cameras

This page provides the documentation of the HALCON SwissRanger interface for the MESA Imaging SR4000 cameras. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.1

System Requirements

• Intel compatible PC with Windows XP/Vista/7.
• Successfully installed SwissRanger drivers libusb0.sys or libeth0.sys.
  If you do not have these drivers, please contact MESA Imaging or the vendor from which you bought the camera.
• SwissRanger DLLs libusb0.dll or libeth0.dll.
  These DLLs must be in your search path %PATH%. If you do not have these DLLs, please contact MESA Imaging or the vendor from which you bought the camera.
• HALCON image acquisition interface hAcqSwissRanger.dll or hAcqSwissRangerxl.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.
• Synchronous and asynchronous grabbing.
• External trigger.
• Software control of all parameters.
• Access to distance, amplitude and xyz images via grab_data and grab_data_async.

Limitations

• get_framegrabber_lut, and set_framegrabber_lut not supported.

Grabbing images using grab_data and grab_data_async

When using the standard grabbing operators grab_image and grab_image_async, only the calibrated z image is returned. To get access to the all available data, grab_data or grab_data_async can be used. These operators return the following images is one image tuple:

• calibrated x image (float)
• calibrated y image (float)
• calibrated z image (float)
• distance image (uint2)
• amplitude image (uint2)
• confidence image (uint2)

Description

Parameters for open_framegrabber():

	Name		'SwissRanger'		The name of the HALCON image acquisition interface.
	HorizontalResolution		---		Ignored.
	VerticalResolution		---		Ignored.
	ImageWidth		---		Ignored.
	ImageHeight		---		Ignored.
	StartRow		---		Ignored.
	StartColumn		---		Ignored.
	Field		---		Ignored.
	BitsPerChannel		---		Ignored.
	ColorSpace		---		Ignored.
	Generic		'num_buffers=num', -1		The desired number of buffers for the image acquisition can be set with the string 'num_buffers=x', where x must be a number greater or equal 1. We recommend to use at least two buffers, which is also the default setting. Default: -1.
	ExternalTrigger		'false', 'true'		If set to 'true', external triggering (AM_HW_TRIGGER+AM_SW_TRIGGER) is activated, see also parameter 'acquire_mode'. Default: 'false'.
	CameraType		'eth', 'usb', 'file'		This parameter is used to specify if the camera type is USB or ETH, or if a SwissRanger stream (SRS) file should be used for data acquisition. Default: 'usb'.
	Device		'<serial_number>', '<ip_address>', '<srs_file>', 'default'		If more than one USB device is connected, the serial number of the desired device has to be set here (last 8 digits in hexadecimal). In case of an ethernet device, the IP address of the device has to be set. If the user wants to read data from a SwissRanger stream (SRS) file, this paramter should be set to the absolute file name of the SRS file. Default: '0'.
	Port		---		Ignored.
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

For further details on supported parameters, please refer to the user's manual of the used SwissRanger camera.

	'acquire_mode'		-1, <mode> (long)		Sets the AcquireMode of the camera to control a number of characteristics of the image acquisition process. The value concatenates the values of the enumerator AcquireMode with a logical 'or', see the SwissRanger API manual for more details. Note that this parameter affects the number and the content of the image objects that are returned by grab_data and grab_data_async. Please note that this setting might also affect the current value of the parameter 'median_filter'. To specify a good default value which is suitable for most applications, you can specify the value -1 which sets the following characteristics: AM_COR_FIX_PTRN | AM_CONV_GRAY | AM_DENOISE_ANF.
	'amplitude_threshold'		threshold (long)		Sets the amplitude threshold.
	'auto_exposure'		'disable', 'enable' (string)		Enables/disables the auto exposure. Note that the corresponding auto exposure values have to be set before setting this parameter to 'enable'. Default: 'disable'.
	'auto_exposure_desired_pos'		min...max (long)		Sets the desired pos of the auto exposure.
	'auto_exposure_max_int_time'		max_time (long)		Sets the maximum integration time for the auto exposure.
	'auto_exposure_min_int_time'		min_time (long)		Sets the minimum integration time for the auto exposure.
	'auto_exposure_percent_over_pos'		min...max (long)		Sets the percent over pos value for the auto exposure.
	'integration_time'		0...255 (long)		Sets the integration time of the camera. Note that this value is converted into milliseconds by 0.300ms + <value>*0.100ms, i.e., the minimum value is 0.300ms and the maximum value is 25.8ms.
	'median_filter'		'enable', 'disable' (string)		Sets the median filter on the camera. Please note that this setting will also affect the current value of the parameter 'acquire_mode'. Default: 'disable'.
	'modulation_frequency'		'MF_14_5MHz', 'MF_15MHz', 'MF_15_5MHz', 'MF_29MHz', 'MF_30MHz', 'MF_31MHz' (string)		Sets the modulation frequency of the LEDs. Please make sure the SwissRanger camera is calibrated at the corresponding frequency.
	'start_async_after_grab_async'		'enable', 'disable' (string)		By default, at the end of an asynchronous grab a new request for an asynchronous grab command is automatically given to the camera. If the parameter 'start_async_after_grab_async' is set to 'disable' this new grab command is omitted. Default: 'enable'.
	'timeout'		msec (long)		Sets the timeout for reading and writing to the USB/ETH port in milliseconds.

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. Note that all parameters of get_framegrabber_param return an empty tuple if they are not supported by the used camera.

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

For further details on supported parameters, please refer to the user's manual of the used SwissRanger camera.

	'available_param_names'		[parameters] (string)		Returns a list containing the names of all available parameters.
	'device_info'		height (string)		Identification string of the device.
	'num_buffers'		number (long)		The number of buffers used for the image acquisition.
	'revision'		revision (long)		The revision of the HALCON SwissRanger interface.

Release Notes

• Revision 4.1 (Oct 06, 2011):
  • Added functionality to read SwissRanger stream (SRS) files.
  • Added new parameter 'median_filter'.
  • Extended documentation by new paragraph about grab_data and grab_data_async.
  • Added default value for parameter 'acquire_mode'.
• Revision 4.0 (Mar 30, 2011):
  • First official release.