HALCON 8.0 Image Acquisition Interface for Euresys DOMINO, GRABLINK, PICOLO and QUICKPACK Boards

This page provides the documentation of the HALCON MultiCam image acquisition interface. This interface is based on the Euresys MultiCam driver and supports the DOMINO Iota/Alpha/Gamma/Delta, the DOMINO Melody/Harmony, the GRABLINK Value/Avenue/Expert/Express and PICOLO frame grabber boards. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 3.2

System Requirements

• Intel compatible PC with Windows 2000, Windows XP or Windows Vista.
• Successfully installed Euresys multicam.sys driver (version 6.0 or higher).
• Euresys DLL multicam.dll (version 6.0 or higher).
  This DLL must be within your search path %PATH%. If you do not have this DLL, please contact Euresys or the vendor from which you bought the board.
• HALCON image acquisition interface hAcqMultiCam.dll or parhAcqMultiCam.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

• Support of the volatile mode for multi-channel images.
• Synchronous and asynchronous grabbing.
• Multiple cameras connected to multiple boards.
• Support of line scan cameras (GRABLINK only).
• Support of rgb line scan cameras (QUICKPACK and GRABLINK only).
• Support of StereoVision for DOMINO Alpha boards.
• Support of different board topologies for DOMINO boards.
• External trigger, asynchronous camera reset.
• Software control of strobe and exposure.
• Software control of digital input and output lines.

Limitations

• grab_data and grab_data_async not supported.
• LUTs only for QUICKPACK ColorScan boards.
• No cropping of image parts.

Description

Parameters for open_framegrabber():

	Name	'MultiCam'	The name of the HALCON image acquisition interface.
	HorizontalResolution	---	Ignored.
	VerticalResolution	---	Ignored.
	ImageWidth	0, 64, 65, ...	The width of the desired image part ('0' stands for the complete image). Default: 0.
	ImageHeight	area scan: 0, 64, 65, ... line scan: 0, 1, ..., 16384	The height of the desired image part ('0' stands for the complete image). Accessing an area scan camera the height has to be equal or smaller than the maximum image height (defined in the .cam camera file) but at least 64 pixels. Using a line scan camera the height defines the page length. '0' specifies the default value defined in the .cam camera file (see the MULTICAM documentation). Default: 0.
	StartRow	0, 1, ...	The row coordinate of the upper left pixel within the desired image part. This value is ignored. Default: 0.
	StartColumn	0, 1, ...	The column coordinate of the upper left pixel within the desired image part. This value is ignored. Default: 0.
	Field	---	Ignored.
	BitsPerChannel	---	Ignored.
	ColorSpace	'rgb', 'rg', 'rb', 'gb', 'r', 'g', 'b' 'gray'	Select special color channels for the output image. This parameter is only important for color images with planar storage (not in volatile mode). PICOLO only: Specifies a gray value image with 1 channel. Default: 'rgb'.
	Generic	---	Ignored.
	ExternalTrigger	'true', 'false'	Activate/deactivate external triggering. When accessing a line scan camera 'true' enables an external page trigger with page delay 0. Default: 'false'.
	CameraType	'mpf_file:cam_file' or 'mpf_file:topology:cam_file'	This parameter specifies the mpf and camera file, separated by a ':' (e.g., 'Alpha_Y:Generic_I50SA', 'Alpha_STEREOXY:CS8530_P30SM', 'Alpha_YBIS:11_11:InterlaceFR_IxxSA', 'Iota:InterlaceFR_IxxSA', 'Picolo_VID1:PAL', 'Picolo_Diligent_VID4:NTSC', 'Value:CV-M4CL_P24SC' or 'Expert_A:L101k_L2048RG'. The frame grabber needs these auxiliary files to specify a proper camera and to define the mode to run it. For further information and a listing of camera file names or valid topologies please refer to your MULTICAM documentation. Default: 'Alpha_X:CS8530_P30SM'. Valid values for mpf_file: 'Alpha_X', 'Alpha_Y', 'Alpha_XBIS', 'Alpha_YBIS', 'Alpha_STEREOXY', 'Gamma_X', 'Gamma_Y', 'Gamma_Z', 'Gamma_XBIS', 'Gamma_YBIS', 'Gamma_ZBIS', 'Iota', 'Melody', 'Harmony_X', 'Harmony_Y', 'Delta_X1', 'Delta_X2', 'Delta_Y1', Delta_Y2', 'Value', 'Avenue', 'Expert_M', 'Expert_A', 'Expert_B', 'Picolo_VID1', 'Picolo_VID2', 'Picolo_VID3', ... 'Picolo_VID16', 'Picolo_YC', 'Colorscan', 'Express'. Valid values for cam_file in case of PICOLO: 'PAL', 'NTSC'. DOMINO Alpha/Gamma/Harmony only: Optionally, the board topology can be set with the first call of open_framegrabber (default topology: '1_1'/'1_1_1').
	Device	'0', '1', ... or 'identifier'	There are two possibilities to address a specific board: the number assigned by the MultiCam driver (passed as a string!) or the identifier string of the frame grabber board. You can yield the number and identifier of the installed boards by the 'info_boards' parameter of the info_framegrabber operator. Default: '0'.
	Port	---	Ignored.
	LineIn	---	Ignored.

Parameters for set_framegrabber_param():

Attention: The specified default values might be overwritten by the used camera file!

General Parameters

	'channel_state'		'idle', 'active'		This parameter gives access to the state of the channel. When channel_state is set to 'idle' the channel is not currently used by the application.
	'color_space'		'rgb', 'rg', 'rb', 'gb', 'r', 'g', 'b'		Select special color channels for the output image. This parameter is only important for color images with planar storage (not in volatile mode). Default: 'rgb'.
	'continuous_grabbing'		'enable', 'disable'		Sets grabbing mode from single frame capture to continuous mode. If the continuous mode is enabled, the frame grabber board will grab all the time (Note that in this mode grab_image will behave like grab_image_async!). In case of disabling this mode, the channel will be new initialized. Default: 'disable'.
	'external_trigger'		'true', 'false'		For backward compatibility only: Enables/disables the frame/page trigger mode for area scan/line scan cameras. If line scan cameras are used, no 'delayed' triggering can be specified. See also 'external_frame_trigger' and 'external_page_trigger'. Default: 'false'.
	'grab_timeout'		milliseconds		Specify the desired time-out (milliseconds passed as a long) for aborting a pending grab. -1 means to abort never. Default: 5000.
	'line_period'		1, ..., 1047552		Area/line scan cameras: The parameter specifies the desired line period in TCU (Timing Clock Unit= 1/channel clock frequency). Line scan cameras: the real line period can be slightly different because it is adjusted by the driver to meet technical constraints. This only applies when 'external_line_trigger' is set to 'false'. Default: 10000.
	'num_buffers'		number		Specifies the desired number of image buffers holding the grabbed images of the frame grabber. See also 'max_buffers'. Default: 3.
	'start_async_after_grab_async'		'enable', 'disable'		By default, at the end of grab_image_async a new request for an 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 random switching between several connected cameras. Default: 'enable'.
	'trigger_filter'		0, 1, ...		Applies an edge cleaner to external frame/line trigger signal on line 8. DOMINO/GRABLINK: You can only enable (0) or disable (>0) the electrical noise removal filter. For further details see also your frame grabber documentation. Default: 16.
	'trigger_signal'		'ttl_rising', 'ttl_falling', '12V_rising', '12V_falling'		Selection of the style of the external frame/line trigger on line 8 (A8 or B8). 'ttl_rising', 'ttl_falling' means a frame/line is acquired when the hardware line 8 goes high/low (TTL compliant with a 3000 Ohm pull-up resistor). '12V_rising', '12V_falling' has respectively meaning whereas the line is 12 V compliant with a 2000 Ohm pull-down resistor. Domino Iota/Alpha/Gamma and GrabLink Value/Expert boards support only the first 2 values (TTL compliant with a 4700 Ohm pull-up resistor). For details see also your frame grabber documentation. Default: 'ttl_falling'.
	'volatile'		'enable', 'disable'		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 (not available for multi-channel images in packed format). However, be aware that older images are overwritten again while calling grab_image or grab_image_async. Thus, you can only process one image while you grab another image. Older images are invalid! Default: 'disable'.
	'do_abort_grab'		---		Cancel current grab.
	'do_force_trigger'		---		Forces an event trigger from the application, when external_trigger='true'. This might be useful for testing purposes.

Line Scan Parameters
These parameters are only supported by line scan cameras which are connected to a GRABLINK/QUICKPACK board.

	'cross_pitch'		1...10000		QUICKPACK only: The cross pitch parameter controls the crossweb resolution in arbitrary length units. This is the distance between two locations focusing on adjacent pixel on the CCD sensor.
	'encoder_pitch'		1...1000		The encoder pitch parameter controls the rate converter. It is expressed in arbitrary length unit. The length unit has to be the same as the one of the 'line_pitch' parameter. This parameter is only used when 'external_line_trigger' is set to 'rate_converted'. See your MULTICAM documentation (especially the 'Programming the Rate Converter' chapter) for details. Default: 100.
	'line_pitch'		1...1000		The line pitch parameter controls the rate converter. It is expressed in arbitrary length unit. The length unit has to be the same as the one of the 'encoder_pitch' parameter. This parameter is only used when 'external_line_trigger' is set to 'rate_converted'. See your MULTICAM documentation (especially the 'Programming the Rate Converter' chapter) for details. Default: 500.
	'page_delay'		0...65535		A delay programmable as a line count can be inserted between the page trigger detection and the effective start of page acquisition. The page trigger can occur while the previous page is not yet fully acquired. This parameter is only used when 'external_page_trigger' parameter is set on 'delayed'. Default: 10.

Strobe Parameters
A pulse can be generated over the hardware line 9 (A9 or B9) to control an illumination device during the expose period. The strobe may be used only when the page trigger for line scan cameras is not used, i.e. 'external_page_trigger' is 'false'. The following parameters uses the expose timer as the time basis for the strobe pulse timing. Note that the QUICKPACK and PICOLO boards do not support any strobe parameters.

	'strobe_duration'		0...100		The duration of the strobe pulse relative to the full exposure window duration (a value of 50% means that the duration of the strobe pulse is half the duration of the exposure window). Default: 50.
	'strobe_level'		'disable', 'ttl', 'open_collector', 'open_emitter', 'ittl'		GRABLINK only: Selection of the digital level of the strobe output line 9 (A9 or B9). 'disable' uses line 9 not as an output, 'ttl' provides a TTL compliant signal, actively tied to the high or low state, 'ittl' provides an isolated TTL compliant signal; 'open_collector' provides a TTL compliant signal, actively tied to the low state and passively tied to the high state through a 3000 Ohm pull-up resistor; 'open_emitter' a TTL compliant signal actively tied to the high state and passively tied to the low state through a 2000 Ohm pull-down resistor a according to the 'strobe_type' parameter. Default: 'ttl'.
	'strobe_line'		'nom', 'alt1', 'alt2', 'alt3', 'alt4', 'io1', 'io2', 'io3', 'io4', 'isoa1', 'isoa2', 'st', 'sta', 'stx', 'sty', 'stz'		DOMINO/GRABLINK only: Selection of the line of the strobe output. See your MULTICAM documentation for more details. Default: 'nom'.
	'strobe_position'		0...100		The position of the middle of the strobe pulse relative to the full exposure window (a value of 50% means that the strobe pulse is situated in the middle of the exposure window). Default: 50.
	'strobe_type'		'low_pulse', 'high_pulse'		Selection of the style of the strobe output line 9 (A9 or B9). 'low_pulse'/'high_pulse' provides a negative/positive going pulse strobe. Default: 'high_pulse'.

Digital Input/Output Parameters
The digital input and output lines are configured and controlled by the following parameters. Each input/output line has an unique index, as described in the MULTICAM documentation.

	'digital_input_config:XX'		'soft', 'free'		Configures the input line (with XX = 1, 2, .. 39 as unique index of the input line, i.e., XX = 28 for a GRABLINK Value board).
	'digital_output_config:XX'		'soft', 'free'		Configures the output line (with XX = 1, 2, .. 39 as unique index of the output line, i.e., XX = 28 for a GRABLINK Value board).
	'digital_input_style'		'ttl', 'ittl', 'i12V', 'channellink', 'cmos', 'lvds', 'auto', 'relay', '5V', '12V'		Selects the electrical style of input lines. See your MULTICAM documentation for the board specific values.
	'digital_output_style'		'ttl', 'ittl', 'ssrly', 'oc', 'ioc', 'ioe', 'relay', 'lvds', 'opto'		Selects the electrical style of output lines. See your MULTICAM documentation for the board specific values.
	'digital_input:XX'		'low', 'wentlow', 'high', 'wenthigh', 'none'		Only supported by get_framegrabber_param. Queries the desired state of one of the digital input lines (with XX = 1, 2, .. 39 as unique index of the input line, i.e., XX = 28 for a GRABLINK Value board). Note that you have to set 'digital_input_config:XX' and 'digital_input_style' for this line before!
	'digital_output:XX'		'low', 'high', 'toggle'		Only supported by set_framegrabber_param. Specifies the desired state of one of the digital output lines (with XX = 1, 2, .. 39 as unique index of the output line, i.e., XX = 28 for a GRABLINK Value board). Note that you have to set 'digital_output_config:XX' and 'digital_output_style' for this line before!

DOMINO and PICOLO Parameters

	'gain_control'		'linear', '+3db', '+2db', '+1db', '0db', '-1db', '-2db', '-3db'		Selection between linear and logarithmical gain control for all camera channels. Default: '0db'.
	'gain_value'		700...1400 (DOMINO), 0...8000 (DOMINO Melody+Harmony), 0...2000 (PICOLO)		Gain adjustment for all camera channels. Default: 1000.
	'offset'		-500...500		Establishing the linear common offset for all camera channels. Default: 0.

PICOLO Parameters

	'gain_color'		0...2000		Control of the color saturation for all camera channels. Default: 1000.

DOMINO and GRABLINK Parameters

	'exposure_trim'		-6...12		Trimming of the exposure time, expressed in dB (adding 6 dB doubles the value, subtracting 6dB divides it by two and subtracting 12 dB divides it by four). Default: 0.
	'exposure_us'		microseconds		Desired frame exposure time expressed in microseconds. The value 0 means permanent exposure condition. Default: 0.

QUICKPACK Parameters

	'activate_lut'		0...4		Activate the LUT with the specified index. Note that up to four different LUTs can be stored per image acquisition handle, see parameter 'do_generate_lut'. If index is set to 0, no LUT is used. Default: 0.
	'activate_shc'		0...4		Activate the shading correction with the specified index. Note that up to four different shading corrections can be stored per image acquisition handle, see parameter 'do_calibrate_shc'. If index is set to 0, no shading correction is used. Default: 0.
	'do_calibrate_shc'		[index, dark_ptr_red, dark_ptr_green, dark_ptr_blue, light_ptr_red, light_ptr_green, light_ptr_blue]		Computes a specific shading correction and stores it with the given index. The shading corrector applies a multiplicative (gain) and an additive (offset) correction individually to each pixel issued in the scanned image. For more details please see the MultiCam documentation. Note that the six image pointers must point to actual image buffers that contain the desired dark or light data. Typically, these pointers can be provided by grabbing an an image and calling get_image_pointer3 afterwards. Note that you can also specify 0 for either all the dark or all the light pointers if you don't want to make use of them.
	'do_generate_lut'		[index, contrast_r, contrast_g, contrast_b, brightness_r, brightness_g, brightness_b, visibility_r, visibility_g, visibility_b, negative_r, negative_g, negative_b]		Generate a lookup table with the specified index. Note that up to four different LUTs can be stored per image acquisition handle. To (de-)activate a pre-generated LUT the parameter 'activate_lut' has to be called. The generation of the LUT is controlled by the following 13 parameters: 1 < index < 4 0.0 < contrast_r/g/b < 2.0 -1.0 < brightness_r/g/b < 1.0 0.0 < visibility_r/g/b < 1.0 0 < negative_r/g/b < 1 For more details about the semantics of all parameters please see the MultiCam documentation.

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

	'exposure_width'		exp_width		Effective exposure width expressed in TCU (Timing Clock Unit= 1/channel clock frequency).
	'elapsed_images'		0, 1 (, 2, ...)		Returns the number of grabbed images. The value 1 means that the image is already acquired and thus can be fetched by grab_image_async without delay. Note that this parameter is especially useful in combination of continuous mode with external triggering to check if you missed a trigger. Note that in continuous mode the value does not toggle between 0 and 1, but increases with every acquired image!
	'image_available'		0, 1		Returns the status of the last asynchronous grab command. The value 1 means that the image is already acquired and thus can be fetched by grab_image_async without delay. Note that this parameter is only useful in combination with external triggering!
	'max_buffers'		number		The maximal settable number of destination image buffers for the frame grabber. See also 'num_buffers'.
	'max_image_height'		max_height		Using area scan cameras the parameter returns the maximal settable height of the desired image part. For line scan cameras this means the maximal settable page length.
	'max_image_width'		max_width		The maximal settable width of the desired image part.
	'min_encoder_frequency'		min_freq		Indicates the computed minimum encoder frequency in the application (in Hz). See 'max_line_frequency' and your MULTICAM documentation.
	'min_line_frequency'		min_freq		Indicates the computed minimum line frequency of the camera in the application (in Hz). See 'max_line_frequency' and your MULTICAM documentation.
	'reset_width'		rst_width		Effective reset width expressed in TCU (Timing Clock Unit= 1/channel clock frequency).
	'revision'		revision		The revision number of the HALCON MultiCam image acquisition interface.
	'surface_index'	0 .. num_buffers-1	Returns the index of the destination image buffer of the last grab command.

Release Notes

• Revision 3.2 (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.1 (Nov 20, 2007):
  • Support of GRABLINK Express boards.
  • Adaptation to MultiCam driver version 6.0.
  • New parameters for digital input/output control: 'digital_input_config:XX', 'digital_input_style', 'digital_output_config:XX', 'digital_output_style', 'digital_input:XX', and 'digital_output:XX'.
• Revision 3.0 (May 15, 2007):
  • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
• Revision 2.17 (May 3, 2007):
  • Support of absolute paths in camera file names.
  • After a channel initialization in continuous mode the channel remains now in continuous mode.
  • New parameter 'elapsed_images' to get the number of grabbed images in continuous mode.
  • Adaptation to MultiCam driver version 5.5.
• Revision 2.16 (Nov 28, 2006):
  • Support of the PICOLO board family.
  • Adaptation to MultiCam driver version 5.0.
• Revision 2.15 (Dec 6, 2005):
  • Support of planar mode for color images.
  • New parameter 'color_space' to select specific color channels.
  • More accurate image timestamp: The call of get_image_time now returns the time at which the image was transmitted to the host (instead of time at which the HALCON image object was created).
• Revision 2.14 (Apr 29, 2005):
  • HALCON 7.1 version of the interface (included in HALCON 7.1 CD).
  • Adaptation to MultiCam driver version 4.5.
  • Support of the DOMINO Melody/Harmony, DOMINO Delta, and GRABLINK Avenue boards.
  • Support of QUICKPACK ColorScan boards. To support the special functionality of these boards new parameters 'cross_pitch', 'activate_lut', 'activate_shc', 'do_calibrate_shc', and 'do_generate_lut' are provided.
  • New parameter 'do_abort_grab' to cancel a pending grab command.
  • New parameter 'image_available' to query the status of the ongoing asynchronous grab command.
  • Speed-up for acquisition of RGB images (faster algorithm to convert the interleaved image data into HALCON image objects).
• Revision 2.13 (Dec 8, 2004):
  • Color storage changed from BGR to RGB for color images.
  • Support of blanks in camera file names.
  • 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.
• Revision 2.12 (September 3, 2004):
  • Adaptation to MultiCam driver version 4.2.
• Revision 2.11 (Jul 7, 2004):
  • Minor improvements for DOMINO Alpha/Gamma boards.
• Revision 2.10 (April 28, 2004):
  • Support of StereoVision for Domino Alpha boards.
  • Support of different board topologies for DOMINO Alpha/Gamma boards.
  • Adaptation to MultiCam driver version 4.1.2.
• Revision 2.9 (Jun 27, 2003):
  • HALCON 7.0 version of the interface (included in HALCON 7.0 CD).
  • Bugfix in open_framegrabber for Multi boards.
  • Bugfix in grab_image to prevent time-out problems.
  • Adaptation to MultiCam driver version 2.9.2.
• Revision 2.8 (May 14, 2003):
  • Adaptation to MultiCam driver version 2.9.1.
• Revision 2.7 (Mar 13, 2003):
  • Supports now also the Domino Iota/Alpha2 boards (Alpha2 board is treated as Alpha board).
  • Adaptation to MultiCam driver version 2.9.
• Revision 2.6 (Aug 21, 2002):
  • Bugfix in grabbing images with more than 8 bits per channel (GrabLink boards only).
• Revision 2.5 (Jul 17, 2002):
  • Supports now also the GrabLink Value/Expert boards.
  • Adaptation to MultiCam driver version 2.8.2.
• Revision 2.4 (Jun 28, 2002):
  • New parameter for channel state.
  • Enabling parameter control during runtime in continuous mode.
  • Renaming parameter 'force_trigger' to 'do_force_trigger'.
• Revision 2.3 (Mar 27, 2002):
  • HALCON 6.1 version of the interface (included in HALCON 6.1 CD).
  • Enabling trigger control during runtime in continuous mode.
• Revision 2.2 (Jan 9, 2002):
  • Renaming from 'Multi' into 'MultiCam' (supports now also the Domino Alpha and Domino Gamma boards).
  • Adaptation to MultiCam driver version 2.6.
  • Renaming of several strobe, trigger, and exposure parameters to ensure uniform prefixes.
  • New parameters for strobe and exposure control.
  • New parameters for gain and offset (Domino only).
• Revision 2.1 (Nov 28, 2001):
  • Support of line scan cameras.
  • Support of strobe functionality.
  • Bugfix in support of more than 8 bits per channel.
  • Bugfix in volatile grabbing.
• Revision 2.0 (Jun 18, 2001):
  • First official version of the interface.