HALCON 10 Image Acquisition Interface for ELTEC PC_EYE and p3i Boards

This page provides the documentation of the HALCON p3i2 image acquisition interface for the ELTEC PC_EYE (PCI Express) and p3i (PCI) frame grabber boards. 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 ELTEC PC_EYE or p3i board and driver: PC_EYE/ASYNC, PC_EYE/MONO, PC_EYE/QUADRO, PC_EYE/RGB, p3i_ASYNC, p3i_MONO, p3i_QUADRO, p3i_RGB (or any combination of those).
• HALCON image acquisition interfacehAcqp3i2.dll or hAcqp3i2xl.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.
• Configuration files for your boards, created with the p3i configuration tool.

Features

• Multiple frame grabber boards (different board types may be mixed).
• Synchronous and asynchronous grabbing.
• Cropping of image parts.
• External trigger.
• Software control of 'black' and 'white' levels.
• Software control of the digital output lines.

Limitations

• grab_data and grab_data_async not supported.
• Support of monochrome 8 bit and RGB 8-8-8 bit mode only.
• No support of quadro mode.

Description

Parameters for open_framegrabber():

	Name		'p3i2'		The name of the HALCON image acquisition interface.
	HorizontalResolution		---		Ignored (value is set via the configuration file).
	VerticalResolution		---		Ignored (value is set via the configuration file).
	ImageWidth		0, width		The width of the desired image part (or 0 for the value set in the configuration file). Default: 0.
	ImageHeight		0, height		The height of the desired image part (or 0 for the value set in the configuration file). Default: 0.
	StartRow		0, row		The row coordinate of the upper left pixel of the desired image part (if ImageWidth and ImageHeight are set to 0, this value is ignored and taken from the configuration file). Default: 0.
	StartColumn		0, column		The column coordinate of the upper left pixel of the desired image part (if ImageWidth and ImageHeight are set to 0, this value is ignored and taken from the configuration file). Default: 0.
	Field		---		Ignored (value is set via the configuration file).
	BitsPerChannel		---		Ignored (value is set via the configuration file).
	ColorSpace		---		Ignored (value is set via the configuration file).
	Generic		---		Ignored.
	ExternalTrigger		---		Ignored (value is set via the configuration file).
	CameraType		'filename'		Name of the configuration file for the board. This has to be a valid '.dat'-file created with the p3i2 configuration tool. All the basic board setup is done using this file. Note that only the 'gray' (8 bit) and 'rgb' (8-8-8 bit) color modes are supported by this interface. A full path name has to be entered (e.g., 'C:\\my_configurations\\my_p3i2_rgb0.dat').
	Device		'id'		The HEX setting of the frame grabber board (passed as a string!). Note that different boards have to use different HEX settings.
	Port		---		Ignored (value is set via the configuration file).
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

All these settings are valid for all input lines (if applicable), i.e., cameras connected to one frame grabber board. Note that not all of these settings may be used with all boards. Some of these settings do not influence the grabbing on all camera inputs (see below).

	'black_level'		min_level ... max_level		The desired voltage level for 'black' pixels in millivolts (floating point number). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'black_level_range',...). Furthermore, 'black_level' must be smaller than 'white_level'.
	'black_level_b'		min_level ... max_level		The desired voltage level for 'black' pixels in millivolts (floating point number) for the blue channel (p3i2 with RGB 24 bits per pixel only). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'black_level_b_range',...). Furthermore, 'black_level_b' must be smaller than 'white_level_b'.
	'black_level_g'		min_level ... max_level		The desired voltage level for 'black' pixels in millivolts (floating point number) for the green channel (p3i2 with RGB 24 bits per pixel only). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'black_level_g_range',...). Furthermore, 'black_level_g' must be smaller than 'white_level_g'.
	'black_level_r'		min_level ... max_level		The desired voltage level for 'black' pixels in millivolts (floating point number) for the red channel (p3i2 with RGB 24 bits per pixel only). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'black_level_r_range',...). Furthermore, 'black_level_r' must be smaller than 'white_level_r'.
	'grab_timeout'		100 ... 327680		Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab. Default: 5000.
	'image_height'		height		The height of the desired image part. width must not be larger than VertcialResolution - StartRow and should be divisible by the 'pixelalign' value (see below); otherwise, 'image_height' is adjusted to a smaller valid value.
	'image_width'		width		The width of the desired image part. width must not be larger than HorizontalResolution - StartColumn and should be divisible by the 'pixelalign' value (see below); otherwise, 'image_width' is adjusted to a smaller valid value.
	'output_reset'		1 ... 15		Set value to 1, 2, 4 or 8 (or any combination) to set output lines 1, 2, 3 and 4 (or any combination) to low state. Note, that the output status can not be read via get_framegrabber_param.
	'output_set'		1 ... 15		Set value to 1, 2, 4 or 8 (or any combination) to set output lines 1, 2, 3 and 4 (or any combination) to high state. Note, that the output status can not be read via get_framegrabber_param.
	'port'		0, 2, 4, 6, 64, 65		Select the desired camera input port for acquisition during runtime. The following values are possible: 0 2 4 6 64 65 input R_A input B_A input R_B input B_B input RGB_A input RGB_B Note that after changing the camera input port the sync input port is also automatically set to the new port 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'.
	'start_column'		column		The column coordinate of the upper left pixel of the desired image part. column must not be larger than HorizontalResolution - ImageWidth and should be divisible by the 'pixelalign' value (see below); otherwise, 'start_column' is adjusted to a smaller valid value.
	'start_row'		row		The row coordinate of the upper left pixel of the desired image part. row must not be larger than VerticalResolution - ImageHeight and should be divisible by the 'pixelalign' value (see below); otherwise, 'start_row' is adjusted to a smaller valid value.
	'switch_buffer'		'enable', 'disable'		This parameter controls the buffer switching after each grab. Usually, two image buffers are allocated, which are used alternately. Default: 'enable'. Attention: Do not disable the buffer switching if you are using the volatile mode!
	'sync_in'		4, 5, 6, 7		Select the desired sync input port for acquisition during runtime. The following values are possible: 4 5 6 7 ADC #0 ADC #1 ADC #2 ADC #3
	'testacq_interval'		1 ... 10		Set time (in milliseonds) between two subsequent test calls while waiting for the end of a current grab. Default: 2.
	'volatile'		'enable', 'disable'		In the volatile mode (8 bit, one channel only!) the two 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'.
	'white_level'		min_level ... max_level		The desired voltage level for 'white' pixels in millivolts (floating point number). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'white_level_range',...). Furthermore, 'white_level' must be larger than 'black_level'.
	'white_level_b'		min_level ... max_level		The desired voltage level for 'white' pixels in millivolts (floating point number) for the blue channel (p3i2 with RGB 24 bits per pixel only). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'white_level_b_range',...). Furthermore, 'white_level_b' must be larger than 'black_level_b'.
	'white_level_g'		min_level ... max_level		The desired voltage level for 'white' pixels in millivolts (floating point number) for the green channel (p3i2 with RGB 24 bits per pixel only). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'white_level_g_range',...). Furthermore, 'white_level_g' must be larger than 'black_level_g'.
	'white_level_r'		min_level ... max_level		The desired voltage level for 'white' pixels in millivolts (floating point number) for the red channel (p3i2 with RGB 24 bits per pixel only). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'white_level_range',...). Furthermore, 'white_level_r' must be larger than 'black_level_r'.

Parameters for get_framegrabber_param():

Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param (except 'output_set' and 'output_reset') 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'].

	'pixelalign'		bits (long)		Alignment of the desired acquisition window in the memory: The parameter values for 'start_row', 'start_column', 'image_width', and 'image_height' must be divisible by bits.
	'revision'		revision (string)		The revision number of the HALCON p3i2 interface.
	'revision_drv'		revision (string)		The revision number of the ELTEC driver.
	'revision_fw'		revision (string)		The revision number of the PCI- and the Application-Xilinx.
	'revision_hw'		revision (string)		The revision number of the board hardware.
	'revision_sw'		revision (string)		The revision number of the ELTEC software.

Release Notes

• Revision 4.1 (Sep 3, 2010):
  • Added support for PC_EYE (PCI Express) boards.
  • Increased speed for the conversion of the RGB image data into the corresponding three-channel HALCON image objects on most modern PC architectures.
  • HALCON 10 version of the interface (included in HALCON 10 DVD).
• Revision 4.0 (Dec 1, 2008):
  • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
• Revision 3.1 (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.0 (May 15, 2007):
  • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
• Revision 2.2 (Jul 27, 2005):
  • HALCON 7.1 version of the interface (included in HALCON 7.1 CD).
  • Speed-up for acquisition of RGB images (avoiding cache alignment failures when converting the interleaved image data into HALCON image objects).
• Revision 2.1 (Dec 1, 2004):
  • The query types 'bits_per_channel', 'camera_type', 'color_space', 'device', 'external_trigger', 'field', and 'port' for info_framegrabber provide now specific value lists for the corresponding parameters in open_framegrabber.
  • New parameter 'start_async_after_grab_async'.
• Revision 2.0 (Sep 26, 2003):
  • HALCON 7.0 version of the interface (included in HALCON 7.0 CD).
  • First official release.