MVTec HALCON 9.0: PixeLINK Image Acquisition Interface for PixeLINK IEEE 1394 (FireWire), USB, and GigE Cameras

This page provides the documentation of the HALCON PixeLINK Image Acquisition Interface. With this interface you can acquire images from PixeLINK 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.
• An OHCI compliant IEEE 1394 adapter, a USB 2.0 port, or a Gigabit Ethernet (GigE) network interface card.
• Successfully installation of the PixeLINK Camera Kit or PixeLINK Developer Kit version 6.21 or later. Note: GigE cameras require version 7 or later.
• HALCON image acquisition interface hAcqPixeLINK.dll or hAcqPixeLINKxl.dll
  If you have properly installed the interface, both DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% chosen during the installation of HALCON.

Features

• Supports PixeLINK cameras.
• Multiple cameras.
• External camera triggering.

Limitations

• Hot plugging is not supported.
• grab_data and grab_data_async not supported.
• PixeLINK cameras do not support asynchronous grabbing. Therefore grab_image_start and grab_image_async are supported, but are merely wrappers around grab_image.
• No LUTs.
• Software cropping not currently supported.

Hardware Cropping of Images

For cameras that support hardware cropping, you can crop images by changing the camera sensor size with the following parameters:

• horizontal_offset
• horizontal_resolution (also in open_framegrabber)
• vertical_offset
• vertical_resolution (also in open_framegrabber)

Note that sensor size will affect frame rate.

Software cropping via 'image_height', 'image_width', 'start_column' and 'start_row' is currently not supported. They are read-only, and when queried will reflect the corresponding sensor parameter. (e.g. Reading 'image_width' will return the current value for 'horizontal_resolution')

Description

Parameters for open_framegrabber():

	Name		'PixeLINK'		The name of the HALCON PixeLINK image acquisition interface.
	HorizontalResolution		1, 2, width		If the camera supports sensor image cropping, sets the horizontal resolution of the image sensor. A value of 1 means to use the full sensor width. A value of 2 means use half the sensor width. The horizontal offset can be set by calling set_framegrabber_param(..,'horizontal_offset',..). If sensor image cropping is not supported by a camera, the value is ignored. Default: 1. Note: The value may be 'rounded' to a width supported by the camera.
	VerticalResolution		1, 2, height		If the camera supports sensor image cropping, sets the vertical resolution of the image sensor. A value of 1 means to use the full sensor height. A value of 2 means use half the sensor height. The vertical offset can be set by calling set_framegrabber_param(..,'vertical_offset',..). If sensor image cropping is not supported by a camera, the value is ignored. Default: 1. Note: The value may be 'rounded' to a height supported by the camera.
	ImageWidth		---		Not currently supported. Ignored. Default: 0.
	ImageHeight		---		Not currently supported. Ignored. Default: 0.
	StartRow		---		Not currently supported. Ignored. Default: 0.
	StartColumn		---		Not currently supported. Ignored. Default: 0.
	Field		---		Ignored. Default: 'default'
	BitsPerChannel		-1, 8, 10, 12		The number of significant bits per channel. -1 means to adopt the highest value supported by the camera. Colour cameras currently support only 8 bits per channel. All monochrome cameras support 8 bits per pixel. All monochrome cameras also support either 10 or 12 bits. Default: -1.
	ColorSpace		'default', 'gray', 'rgb'		Sets the desired color space of the resulting HALCON image. 'default' means to adopt the camera setting. Default: 'default'
	Generic		---		Ignored.
	ExternalTrigger		'true', 'false'		Activate/deactivate hardware triggering. Default: 'false'. If 'true', the default triggering configuration is: 'trigger_mode' 0 'trigger_polarity' 'positive' 'trigger_delay' 0 These parameters can be changed via set_framegrabber_param after a successful call to open_framegrabber.
	CameraType		---		Ignored.
	Device		'0', 'serial number'		Select the desired camera. To get a list of cameras you can call info_framegrabber('PixeLINK','device',...). '0' selects any camera. i.e. The PixeLINK API will choose a camera. Default: '0'.
	Port		---		Ignored.
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

Note that most of the following parameters (and also the valid parameter values!) depend on the capabilities of the specific camera in use.

'bits_per_channel'	8, 10, 12	The number of significant bits per channel. Color cameras currently only support RGB24, i.e. 8 bits per channel. All mono cameras support 8. Mono cameras support either 10 or 12.
'brightness'	min ... max	On cameras that support brightness, adjusts the analog black level offset.
'color_temperature	min ... max	On color cameras, used to control the color temperature. Temperature is in degrees Kelvin. 'color_temperature_enable' must be set to 'enable' for this to take effect.
'color_temperature_enable	'disable', 'enable' Settable with 0 or 1, respectively.	On color cameras, used to enable or disable color temperature.
'do_auto_exposure'	---	Perform an auto-exposure.
'do_white_balance'	---	Perform a white balance.
'exposure'	min ... max, 'auto', 'one_push', 'off'	Sets the exposure mode of the camera if a string value is passed. In case of an double value the exposure value is set. Note that changing the exposure may change the frame rate limits.
'frame_rate'	min ... max	Sets the frame rate. 'frame_rate_enable' must be set to 'enable' for this to take effect. Note that changing the frame rate may change the exposure limits.
'frame_rate_enable'	'disable', 'enable' Settable with 0 or 1, respectively.	Enables/disables frame rate control.
'external_trigger'	'true', 'false'	Enables/disables the trigger mode.
'flip_horizontal'	'disable', 'enable' Settable with 0 or 1, respectively.	When supported, flips the image horizontally. (i.e. about the vertical axis).
'flip_vertical'	'disable', 'enable' Settable with 0 or 1, respectively.	When supported, flips the image vertically. (i.e. about the horizontal axis)
'gain	min ... max	Sets the analog gain. Gain values are discrete and can be queried via 'gain_values'.
'gain_red'	min ... max	For color cameras, adjusts the red channel of the digital channel gains.
'gain_green'	min ... max	For color cameras, adjusts the green channel of the digital channel gains.
'gain_blue'	min ... max	For color cameras, adjusts the blue channel of the digital channel gains.
'gamma'	min ... max	On color cameras, sets the gamma. Gamma must be enabled with 'gamma_enable'.
'gamma_enable'	'disable', 'enable' Settable with 0 or 1, respectively.	On color cameras, enables or disables gamma.
'horizontal_offset'	0 ... max	When supported by the camera, sets the horizontal offset of the image sensor.
'horizontal_resolution'	0, 1, 2 ... max width	When supported by the camera, sets the horizontal resolution of the image sensor. Setting to a value of 1 indicates to use the entire width. Setting to a value of 2 indicates to use half of the entire width.
'pixel_addressing_mode	'decimate', 'average', 'bin', 'resample'	When supported by the camera, sets the pixel addressing mode. Modes supported by the camera can be queried by reading 'pixel_addressing_mode_values'.
'pixel_addressing_value'	min ... max	When supported by the camera, sets the pixel addressing value. Pixel addressing is disabled by setting this to 1. Supported pixel addressing modes can be queried by reading 'pixel_addressing_value_values'. Note that pixel addressing values other than 1 will affect the size of a grabbed image, but not sensor ROI parameters such as 'horizontal_resolution' or 'vertical_offset'.
'saturation'	min ... max	On color cameras that support saturation, sets the saturation.
'trigger_delay'	min ... max	Sets the trigger delay value. See PixeLINK documentation for information on which trigger modes support delay.
'trigger_mode'	number	Sets the trigger mode. See the PixeLINK documentation for more information on triggering.
'trigger_parameter'	number	Sets the trigger parameter needed for various trigger modes. See the PixeLINK documentation for more information on triggering and which triggering modes support a triggering parameter. Note: Before changing to a mode that uses the parameter, set the triggering parameter before setting the triggering mode.
'trigger_polarity'	'negative', 'positive' Settable with 0 or 1, respectively.	Sets the trigger polarity and distinguishes whether the rising or falling edge triggers the camera. 0: low active 1: high active
'vertical_offset'	0 ... max	Sets the vertical offset of the image sensor.
'vertical_resolution'	0, 1, 2 ... max height	When supported by the camera, sets the vertical resolution of the image sensor. Setting to a value of 1 indicates to use the entire height. Setting to a value of 2 indicates to use half of the entire height.

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 error (H_ERR_FGPARAM) if they are not supported by the used camera. Parameters supported by set_framegrabber_param may also support read-only parameters with the following suffixes:

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

'available_param_descriptions'	available_param_descriptions (tuple of strings)	A set of descriptions for each parameter supported by the camera.
'available_param_names'	available_param_names (tuple of strings)	A set of names of the parameters supported by the camera.
'camera_name'	camera_name (string)	Camera name. See the PixeLINK documentation for the camera_name field of the CAMERA_INFO struct.
'color_space'	'gray', 'rgb' (string)	Camera color space. Currently a read-only parameter.
'firmware_version'	firmware_version (string)	Camera firmware version.
'fpga_version'	fpga_version (string)	Camera FPGA version.
'image_height'	fpga_version (long)	Returns 'vertical_resolution' value. Currently a read-only parameter.
'image_width'	image_width (long)	Returns 'horizontal_resolution' value. Currently a read-only parameter.
'model_name'	model_name (string)	Camera model name.
'revision'	revision (string)	The revision of the Halcon PixeLINK interface.
'start_column'	model_name (string)	Returns 'horizontal_offset' value. Currently a read-only parameter.
'serial_number'	serial_number (string)	Camera serial number.
'start_row'	model_name (string)	Returns 'vertical_offset' value. Currently a read-only parameter.
'temperature'	temperature (float)	Sensor temperature, in degrees Celsius.
'vendor_name'	vendor_name (string)	Camera vendor name.

Release Notes

• Revision 4.1 (Aug 20, 2010):
  • Fixed bug in implementation of parameter 'trigger_mode_values' to avoid a possible application crash caused by accessing uninitialized memory.
• Revision 4.0 (Dec 1, 2008):
  • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).