interfaces mvtec

Dokumentation

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

Interface: MultiCam
Revision: 6.5
Date: 2016-09-26
HALCON Version: 12.0

General

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/Symphony, the GRABLINK Avenue/Base/DualBase/Expert /Express/Full/Value and PICOLO frame grabber boards. Registered customers can download the latest revision of this interface from the MVTec WWW server.

System Requirements

  • Intel compatible PC with Windows Vista/7/8 or Windows Vista/7/8 x64.
  • Successfully installed Euresys device driver (version 6.7 or higher).
  • Euresys DLL multicam.dll (version 6.7 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 hAcqMultiCamxl.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.
  • Support of user-specific callback functions.

Limitations

  • LUTs only for QUICKPACK ColorScan boards.
  • No cropping of image parts.

Parameters for info_framegrabber

Parameter Value List Type Kind Description
'bits_per_channel' [] Unused.
'camera_type' 'CAMFILE:', 'cam', <camera_path>, 'Alpha_STEREOXY', 'Alpha_X', 'Alpha_XBIS', 'Alpha_Y', 'Alpha_YBIS', 'Avenue', 'Base', 'ColorScan', 'Delta_X1', 'Delta_X2', 'Delta_Y1', 'Delta_Y2', 'DualBase_A', 'DualBase_B', 'Expert_A', 'Expert_B', 'Expert_M', 'Express', 'Full', 'Gamma_X', 'Gamma_XBIS', 'Gamma_Y', 'Gamma_YBIS', 'Gamma_Z', 'Gamma_ZBIS', 'Harmony_X', 'Harmony_Y', 'Symphony_A', 'Symphony_B', 'Symphony_C', 'Symphony_D', 'Iota', 'Melody', 'Picolo_VID1', 'Picolo_VID2', 'Picolo_VID3', 'Picolo_Yc', 'ScanMonoCam', 'SyncMonoCam', 'Value', 'VcamMonoCam' string pre-defined Syntax for the camera configuration file and possible values for camera type.
'color_space' 'default', 'gray', 'rgb' string pre-defined Values for color space.
'defaults' [1, 1, 0, 0, 0, 0, 'interlaced', 8, 'default', -1.0, 'false', 'Alpha_X:CS8530_P30SM', '0', 1, 1] mixed pre-defined Default values for open_framegrabber.
'device' '0', '1', '2', '3' string pre-defined Returns a pre-defined list of possible device numbers.
'external_trigger' ['false', 'true'] string pre-defined Values for the external trigger.
'field' [] Ignored.
'general' [] string pre-defined Information about the HALCON MultiCam interface.
'generic' [] Unsupported query.
'horizontal_resolution' 1 integer pre-defined Value list for horizontal resolution.
'image_height' [] Unsupported query.
'image_width' [] Unsupported query.
'info_boards' ['device:board_id identifier:<identifier> boardName:<name> serial:<serial_number> boardType:<type>'] string dynamic A list of the available devices.
'parameters' ['<parameters>'] string pre-defined Pre-defined parameters of the HALCON interface.
'parameters_readonly' ['<parameters>'] string pre-defined Pre-defined read-only parameters of the HALCON interface.
'parameters_writeonly' ['<parameters>'] string pre-defined Pre-defined write-only parameters of the HALCON interface.
'port' [] Unused.
'revision' '<revision>' string pre-defined Revision number of the MultiCam interface.
'start_column' [] Unsupported query.
'start_row' [] Unsupported query.
'vertical_resolution' 1 integer pre-defined Value list for vertical resolution.

Parameters for open_framegrabber

Parameter Values Default Type Description
Name 'MultiCam' string Name of the HALCON interface.
HorizontalResolution --- Ignored.
VerticalResolution --- Ignored.
ImageWidth --- integer The image size values must be defined in the .cam camera file. In open_framegrabber the parameter image_width is ignored. The width has to be equal or smaller than the maximum image width but at least 8 pixels. Furthermore, the image widht should be divisable by 4, otherwise the value will be adapted to the next higher value divisable by 4 (see the also the MULTICAM documentation).
ImageHeight --- integer The image size values must be defined in the .cam camera file. In open_framegrabber the parameter image_height is ignored. When accessing an area scan camera, the height has to be equal or smaller than the maximum image height but at least 8 pixels. Furthermore, the image height should be divisable by 4, otherwise the value will be adapted to the next higher value divisable by 4. Using a line scan camera, the height defines the page length (see the also the MULTICAM documentation).
StartRow 0, <row> 0 integer Row coordinate of the upper left pixel within the desired image part.
StartColumn 0, <column> 0 integer Column coordinate of the upper left pixel within the desired image part.
Field --- Ignored.
BitsPerChannel --- Ignored.
ColorSpace 'default', 'rgb', 'rg', 'rb', 'gb', 'r', 'g', 'b', 'gray' 'gray' string 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.
Generic --- Ignored.
ExternalTrigger 'false', 'true' 'false' string Activate/deactivate external triggering. When accessing a line scan camera, 'true' enables an external page trigger with page delay 0.
CameraType
  • '<mpf_file:cam_file>'
  • '<mpf_file:topology:cam_file>'
'Alpha_X:CS8530_P30SM' string 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.
Valid values for mpf_file: 'Alpha_X', 'Alpha_Y', 'Alpha_XBIS', 'Alpha_YBIS', 'Alpha_STEREOXY', 'Delta_X1', 'Delta_X2', 'Delta_Y1', Delta_Y2', 'Gamma_X', 'Gamma_Y', 'Gamma_Z', 'Gamma_XBIS', 'Gamma_YBIS', 'Gamma_ZBIS', 'Harmony_X', 'Harmony_Y', 'Symphony_A', 'Symphony_B', 'Symphony_C', 'Symphony_D', 'Iota', 'Melody', 'Avenue', 'Base', 'DualBase_A', 'DualBase_B', 'Expert_A', 'Expert_B', 'Expert_M', 'Express', 'Full', 'Value', 'Picolo_VID1', 'Picolo_VID2', 'Picolo_VID3', ... 'Picolo_VID16', 'Picolo_YC', 'ColorScan',
Valid values for cam_file in case of PICOLO: 'PAL', 'NTSC'.
GRABLINK Full only: To use 10 taps, the following board topology can be set with the first call of open_framegrabber: 'MONO_DECA'(default topology: 'MONO').
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', ...
  • '<identifier>'
'0' string 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.
Port --- Ignored.
LineIn --- Ignored.

Parameters for set_framegrabber_param

Attention: The specified default values might be overwritten by the used camera file!
Parameter Values Default Type Description
'channel_state' 'active', 'idle', 'free', 'ready' string 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' 'rgb' Select special color channels for the output image. This parameter is only important for color images with planar storage (not in volatile mode).
'continuous_grabbing' 'disable', 'enable' 'disable' string If the continuous grabbing mode is enabled, the camera grabs all the time. In this mode the operator grab_image does not grab synchronously, but behaves similar to grab_image_async. Using this mode you can achieve full frame rate. If the continuous grabbing mode is disabled, the camera is set to single frame capture.
'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.
'external_trigger' 'false', 'true' 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'.
'grab_timeout' <milliseconds> 10000 integer Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE.
'line_period' 1, ..., 1047552 10000 integer 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'.
'num_buffers' <number> 3 integer Number of image buffers holding the grabbed images of the frame grabber. See also 'max_buffers'.
'start_async_after_grab_async' 'disable', 'enable' 'enable' string By default a new asynchronous grab command is automatically given to the acquisition device at the end of grab_image_async. If the parameter 'start_async_after_grab_async' is set to 'disable', this new grab command is omitted.
'trigger_filter' 0, 1, ... 16 integer 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.
'trigger_signal' '12V_falling', '12V_rising', 'ttl_falling', 'ttl_rising' 'ttl_falling' string Selection of the style of the external frame/line trigger on line 8 (A8 or B8).
  • '12V_rising', '12V_falling' has respectively meaning whereas the line is 12 V compliant with a 2000 Ohm pull-down resistor. Note: DOMINO Iota/Alpha/Gamma and GRABLINK Value/Expert boards don't support these two values (TTL compliant with a 4700 Ohm pull-up resistor).
  • '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).
For details see also your frame grabber documentation.
'volatile' 'disable', 'enable' 'disable' string Grayscale only. In the volatile mode 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!

Parameters for get_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(.., 'Shutter_range', ..) will return the output tuple [min, max, step, default].
  • '_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'].

All these postfixed parameter names are not returned when calling info_framegrabber(.., 'parameters', ..) and are used to enable the easy parameterization via a generic graphical user interface, particularly the HDevelop Image Acquisition Assistant.

Parameter Values Default Type Kind Description
'available_callback_types' ['<callback_type>'] string dynamic Query all callback types which are supported by this interface.
'bits_per_channel' '<default>' 8 integer pre-defined The value is not used, so a default value is returned.
'camera_type' '<camera_type>' 'Alpha_X:CS8530_P30SM' string pre-defined Current camera type.
'channel_state' 'active', 'idle', 'free', 'ready' string dynamic 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', 'gray' 'gray' string pre-defined Desired color space and thus the number of image channels of the resulting HALCON image.
'continuous_grabbing' 'disable', 'enable' 'disable' string pre-defined If the continuous grabbing mode is enabled, the camera grabs all the time. In this mode the operator grab_image does not grab synchronously, but behaves similar to grab_image_async. Using this mode you can achieve full frame rate. If the continuous grabbing mode is disabled, the camera is set to single frame capture.
'device' '<device>' '0' string dynamic Returns the current device id.
'elapsed_images' 0, 1 (, 2, ...) integer dynamic 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!
'exposure_width' <exp_width> integer dynamic Effective exposure width expressed in TCU (Timing Clock Unit= 1/channel clock frequency).
'external_trigger' 'false', 'true' 'false' string pre-defined Status of the external trigger.
'field' '<default>' 'interlaced' string pre-defined The value is not used, so a default value is returned.
'generic' <default> -1 integer pre-defined The value is not used, so a default value is returned.
'grab_timeout' <milliseconds> 10000 integer pre-defined Current grab timeout in milliseconds.
'horizontal_resolution' <resolution> 1 integer pre-defined Current value of horizontal resolution.
'image_available' 0, 1 integer dynamic 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 especially useful in combination with external triggering.
'image_height' <height> 0 integer pre-defined Height of the desired image part ('0' stands for the complete image).
'image_width' <width> 0 integer pre-defined Width of the desired image part ('0' stands for the complete image).
'line_in' <default> 1 integer pre-defined The value is not used, so a default value is returned.
'line_period' 1, ..., 1047552 10000 integer dynamic 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'.
'max_buffers' <number> 10 integer dynamic Maximal settable number of destination image buffers for the frame grabber. See also 'num_buffers'.
'max_image_height' <max_height> integer dynamic 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> integer dynamic Maximal settable width of the desired image part.
'min_encoder_freqency' <Hz> integer dynamic Indicates the computed minimum encoder frequency in the application (in Hz). See 'max_line_frequency' and your MULTICAM documentation.
'min_line_freqency' <Hz> integer dynamic Indicates the computed minimum line frequency of the camera in the application (in Hz). See 'max_line_frequency' and your MULTICAM documentation.
'name' 'MultiCam' string pre-defined Name of the HALCON interface.
'num_buffers' <number> 3 integer pre-defined Number of image buffers holding the grabbed images of the frame grabber. See also 'max_buffers'.
'port' <default> 1 integer pre-defined The value is not used, so a default value is returned.
'reset_width' <TCU> integer dynamic Effective reset width expressed in TCU (Timing Clock Unit= 1/channel clock frequency).
'revision' '<revision>' string pre-defined Revision number of the MultiCam interface.
'start_async_after_grab_async' 'disable', 'enable' 'enable' string pre-defined Status of 'start_async_after_grab_async'.
'start_column' <column> 0 integer pre-defined Returns the current start column of the HALCON image.
'start_row' <row> 0 integer pre-defined Returns the current start row of the HALCON image.
'surface_index' 0 .. <num_buffers>-1 integer dynamic Index of the destination image buffer of the last grab command.
'trigger_filter' 0, 1, ... 16 integer pre-defined 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.
'trigger_signal' '12V_falling', '12V_rising', 'ttl_falling', 'ttl_rising' 'ttl_falling' string pre-defined Style of the external frame/line trigger on line 8 (A8 or B8).
'vertical_resolution' <resolution> 1 integer pre-defined Current value of vertical resolution.
'volatile' 'disable', 'enable' 'disable' string pre-defined Grayscale only. In the volatile mode 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!

Additional parameters for set_framegrabber_param:
Line Scan, Strobe, Digital Input/Output, DOMINO and PICOLO, DOMINO and GRABLINK, PICOLO and QUICKPACK Parameters

Line Scan Parameters
These parameters are only supported by line scan cameras which are connected to a GRABLINK/QUICKPACK board
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 use 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.
Digital Input/Output Parameters
The digital input and output lines are configured and controlled by the following parameters. Each input/output line has a unique index, as described in the MULTICAM documentation.

Parameter Values Default Type Description
'cross_pitch' 1...10000 integer Line Scan Parameter 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 100 integer Line Scan Parameter 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.
'line_pitch' 1...1000 500 integer Line Scan Parameter 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.
'page_delay' 0...65535 10 integer Line Scan Parameter 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'.
'strobe_duration' 0...100 50 integer Strobe Parameter
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).
'strobe_level' 'disable', 'ittl', 'open_collector', 'open_emitter', 'ttl' 'ttl' string Strobe Parameter
GRABLINK only: Selection of the digital level of the strobe output line 9 (A9 or B9).
  • 'disable' uses line 9 not as an output.
  • '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 according to the 'strobe_type' parameter.
  • 'ttl' provides a TTL compliant signal, actively tied to the high or low state.
'strobe_line' 'alt1', 'alt2', 'alt3', 'alt4', 'io1', 'io2', 'io3', 'io4', 'isoa1', 'isoa2', 'nom', 'st', 'sta', 'stx', 'sty', 'stz' 'nom' string Strobe Parameter
DOMINO/GRABLINK only: Selection of the line of the strobe output. See your MULTICAM documentation for more details.
'strobe_position' 0...100 50 integer Strobe Parameter
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).
'strobe_type' 'high_pulse', 'low_pulse' 'high_pulse' string Strobe Parameter
Selection of the style of the strobe output line 9 (A9 or B9).
  • 'low_pulse' provides a negative going pulse strobe.
  • 'high_pulse' provides a positive going pulse strobe.
'digital_input_config:XX' 'free', 'soft' string Digital Input/Output Parameter
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' 'free', 'soft' string Digital Input/Output Parameter
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' '5V', '12V', 'auto', 'channellink', 'cmos', 'diff', 'dttl', 'iso', 'ittl', 'i12V', 'lvds', 'powerstate', 'relay', 'rs485', 'ttl', 'ttlpd' string Digital Input/Output Parameter
Electrical style of input lines. See your MULTICAM documentation for the board specific values.
'digital_output_style' 'ioc', 'ioe', 'ittl', 'lvds', 'oc', 'opto', 'relay', 'ssrly', 'ttl' string Digital Input/Output Parameter
Electrical style of output lines. See your MULTICAM documentation for the board specific values.
'digital_output:XX' 'low', 'high', 'toggle' string Digital Input/Output Parameter
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!
'gain_control' 'linear', '+3db', '+2db', '+1db', '0db', '-1db', '-2db', '-3db' '0db' string DOMINO and PICOLO Parameters
Selection between linear and logarithmical gain control for all camera channels.
'gain_value' 1000 integer DOMINO and PICOLO Parameters
Gain adjustment for all camera channels.
'offset' -500...500 0 integer DOMINO and PICOLO Parameters
Establishing the linear common offset for all camera channels.
'gain_color' 0...2000 1000 integer PICOLO Parameters
Control of the color saturation for all camera channels.
'exposure_trim' -6...12 0 integer DOMINO and GRABLINK Parameter
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).
'exposure_us' <microseconds> 0 integer DOMINO and GRABLINK Parameter
Desired frame exposure time expressed in microseconds. The value 0 means permanent exposure condition.
'activate_lut' 0...4 0 integer QUICKPACK Parameters
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.
'activate_shc' 0...4 0 integer QUICKPACK Parameters
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.
'do_calibrate_shc' [<index, dark_ptr_red, dark_ptr_green, dark_ptr_blue, light_ptr_red, light_ptr_green, light_ptr_blue>] integer QUICKPACK Parameters
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 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>] mixed QUICKPACK Parameters
Generate a look-up 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.

Additional parameters for get_framegrabber_param:
Line Scan, Strobe, Digital Input/Output, DOMINO and PICOLO, DOMINO and GRABLINK, PICOLO and QUICKPACK Parameters

Line Scan Parameters
These parameters are only supported by line scan cameras which are connected to a GRABLINK/QUICKPACK board
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 use 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.
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.

Parameter Values Default Type Kind Description
'cross_pitch' 1...10000 integer dynamic Line Scan Parameter 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 100 integer dynamic Line Scan Parameter 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.
'line_pitch' 1...1000 500 integer dynamic Line Scan Parameter 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.
'page_delay' 0...65535 10 integer dynamic Line Scan Parameter 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'.
'strobe_duration' 0...100 50 integer dynamic Strobe Parameter
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).
'strobe_level' 'disable', 'ittl', 'open_collector', 'open_emitter', 'ttl' 'ttl' string pre-defined Strobe Parameter
GRABLINK only: Digital level of the strobe output line 9 (A9 or B9).
'strobe_line' 'alt1', 'alt2', 'alt3', 'alt4', 'io1', 'io2', 'io3', 'io4', 'isoa1', 'isoa2', 'nom', 'st', 'sta', 'stx', 'sty', 'stz' 'nom' string pre-defined Strobe Parameter
DOMINO/GRABLINK only: Selection of the line of the strobe output. See your MULTICAM documentation for more details.
'strobe_position' 0...100 50 integer dynamic Strobe Parameter
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).
'strobe_type' 'high_pulse', 'low_pulse' 'high_pulse' string pre-defined Strobe Parameter
Style of the strobe output line 9 (A9 or B9).
'digital_input_config:XX' 'free', 'soft' string dynamic Digital Input/Output Parameter
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' 'free', 'soft' string dynamic Digital Input/Output Parameter
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' '5V', '12V', 'auto', 'channellink', 'cmos', 'diff', 'dttl', 'iso', 'ittl', 'i12V', 'lvds', 'powerstate', 'relay', 'rs485', 'ttl', 'ttlpd' string dynamic Digital Input/Output Parameter
Electrical style of input lines. See your MULTICAM documentation for the board specific values.
'digital_output_style' 'ioc', 'ioe', 'ittl', 'lvds', 'oc', 'opto', 'relay', 'ssrly', 'ttl' string dynamic Digital Input/Output Parameter
Electrical style of output lines. See your MULTICAM documentation for the board specific values.
'digital_input:XX' 'high', 'low', 'none', 'wenthigh', 'wentlow' string dynamic Digital Input/Output Parameter
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!
'gain_control' 'linear', '+3db', '+2db', '+1db', '0db', '-1db', '-2db', '-3db' '0db' string pre-defined DOMINO and PICOLO Parameters
Selection between linear and logarithmical gain control for all camera channels.
'gain_value' 1000 integer dynamic DOMINO and PICOLO Parameters
Gain adjustment for all camera channels.
'offset' -500...500 0 integer dynamic DOMINO and PICOLO Parameters
Establishing the linear common offset for all camera channels.
'gain_color' 0...2000 1000 integer dynamic PICOLO Parameters
Control of the color saturation for all camera channels.
'exposure_trim' -6...12 0 integer dynamic DOMINO and GRABLINK Parameter
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).
'exposure_us' <microseconds> 0 integer dynamic DOMINO and GRABLINK Parameter
Desired frame exposure time expressed in microseconds. The value 0 means permanent exposure condition.
'activate_lut' 0...4 0 integer pre-defined QUICKPACK Parameters
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.
'activate_shc' 0...4 0 integer pre-defined QUICKPACK Parameters
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.

Operator set_framegrabber_lut

This operator is only valid for QUICKPACK ColorScan boards. Set the look-up table values, which must be 256 values.

Operator get_framegrabber_lut

Not supported by this interface.

Operator set_framegrabber_callback

All actually supported callback types of a specific image acquisition device can be queried by calling get_framegrabber_param with the parameter 'available_callback_types'. Once the callback is registered, on every occurrence of the underlying event (e.g., the notification that the exposure has finished) the specified callback function will be called. If the callback function is set to NULL, the corresponding callback will be unregistered.

The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) and uses the following parameters:
  • AcqHandle Acquisition handle of the corresponding image acquisition instance.
  • Context Optional context data of the specific callback. In the MultiCam interface this parameter is not used, i.e., Context is set to NULL.
  • UserContext User context as set via set_framegrabber_callback.

Using user-callback functions
Note that the execution time of a user-specific callback function should always be as short as possible since during the execution of a callback function the handling of further internal callbacks might be blocked. This can be achieved by removing the current processing from the user-specific callback function to a separate thread that is controlled via signals or events.

Type Description
'exposure_end' Corresponds to the MC_SIG_END_EXPOSURE signal function inside MultiCam.
'exposure_start' Corresponds to the MC_SIG_START_EXPOSURE signal function inside MultiCam.
'transfer_end' Corresponds to the MC_SIG_SURFACE_FILLED signal function inside MultiCam.

Operator get_framegrabber_callback

This interface supports device specific events via the operators set_framegrabber_callback and get_framegrabber_callback. For more information see set_framegrabber_callback.

Operator grab_image_start

Starts a new asynchronous grab. See also grab_image_start.

Operator grab_image

grab_image starts a new synchronous grab. See also grab_image. Note that the interface converts the image from the device to the desired image format specified by the parameters 'image_width', 'image_height', 'start_row', 'start_column', 'bits_per_channel', and 'color_space'.

Operator grab_image_async

grab_image_async returns an image and starts the next asynchronous grab. See also grab_image_async. Note that the interface converts the image from the device to the desired image format specified by the parameters 'image_width', 'image_height', 'start_row', 'start_column', 'bits_per_channel', and 'color_space'.

Operator grab_data

Not supported by this interface.

Operator grab_data_async

Not supported by this interface.

Operator close_framegrabber

This operator closes the device. See also close_framegrabber.

HDevelop Examples

For this interface there are the following examples available:
  • multicam_2cameras.hdev - Example for the usage of an Euresys MultiCam board with 2 cameras (DOMINO Alpha/Gamma/Harmony, GRABLINK Expert).
  • multicam.hdev - Benchmark.
  • multicam_parameters.hdev - Lists all parameters of a device.
  • multicam_picolo.hdev - Simple example for the usage of an Euresys PICOLO board.
  • multicam_quickpack.hdev - Shows usage of an Euresys QUICKPACK board.
  • multicam_simple.hdev - A simple example to show the usage of the interface.
  • multicam_split_cable.hdev - Split cable example for the usage of an Euresys MultiCam board DOMINO Alpha/Gamma.
  • multicam_stereo.hdev - Stereo vision example for the usage of an Euresys MultiCam board DOMINO Alpha/Alpha2.

C++ Examples

For this interface there is also a further C++ Visual Studio Project to demonstrate the usage of the operators get_framegrabber_callback and set_framegrabber_callback. Please check the directory %HALCONEXAMPLES%\cpp\console\vs2005\. If you prefer building the example via the console, please check the following folder %HALCONEXAMPLES%\cpp\console\. With a Linux OS please use $HALCONEXAMPLES/cpp/console/.

C# Examples

For this interface there is also a further C# Visual Studio Project to demonstrate the usage of the operators get_framegrabber_callback and set_framegrabber_callback. Please check the directory %HALCONEXAMPLES%\cpp\console\vs2005\.

Release Notes

  • Revision 6.5 (Sep 26, 2016):
    • Grabbing images crashed when using 64-bit on Windows 8.0 or higher. This problem has been fixed.
    • Setting an empty value in set_framegrabber_param led to a crash. This problem has been fixed.
  • Revision 6.4 (Jul 13, 2016):
    • If the board identifier contained more than one underscore it was not possible to use the device identifier as device string in open_framegrabber. The call of open_framegrabber failed with error 5302. This problem has been fixed.
    • The call of set_framegrabber_callback might have crashed when a callback function was de-registered. This problem has been fixed.
    • In rare cases the call of close_framegrabber might have crashed when a callback was registered previously. This problem has been fixed.
  • Revision 6.3 (Oct 20, 2015):
    • In case of timeout in combination with hardware trigger, every succeeding call of grab_image_async returned a timeout. This problem has been fixed.
    • The call of grab_image and grab_image_async might have crashed when the parameter 'num_buffers' had been set to a value greater than 10. This problem has been fixed.
    • This documentation did not list all available callback types. This problem has been fixed.
  • Revision 6.2 (Feb 26, 2015):
    • Camera configurations specifying unsupported color formats crashed on GRABLINK series. This problem has been fixed, an appropriate error message is returned now.
  • Revision 6.1 (Jan 30, 2015):
    • Improved performance of color format conversion function.
    • Removed beta tag in the file properties of the interface DLLs which was erroneously added in the last revision.
  • Revision 6.0 (Oct 31, 2014):
    • HALCON 12 version of the interface.
  • Revision 5.3 (Jan 27, 2014):
    • Bug fix with multiple framegrabbers. In case of a grab timeout the wrong configuration data was read. In rare cases this bug led into a dead-lock situation.
    • Bug fix with multiple frame grabber boards. After a grab timeout the internal used channel state was reset twice. This bug could cause a crash after several iterations.
    • Bug fix with multiple frame grabber boards. If open_framegrabber was called with the board identifier as device parameter, the last opened frame grabber board was configured
  • Revision 5.2 (Mar 25, 2013):
    • Bug fix in setting the board topology to MONO_DECA for GRABLINK Full boards during open_framegrabber.
    • Bug fix in grab_image_start. A pending grab was not aborted.
    • Bug fix in grab_image. A previously started grab was not aborted.
    • Bug fix in using an image height or image width smaller than 64 inside the configuration file. Now, the smallest possible value is 8.
    • Review and update of the documentation, in particular the description of the image width and image height parameters.
  • Revision 5.1 (Nov 15, 2012):
    • Bug fix in determining the used image size in case of a bit-depth greater than 8.
  • Revision 5.0 (May 15, 2012):
    • HALCON 11 version of the interface (included in HALCON 11 DVD).
  • Revision 4.5 (Apr 30, 2012):
  • Revision 4.4 (Dec 5, 2011):
    • Support of DOMINO Symphony boards.
    • Added new board topology MONO_DECA for GRABLINK Full boards to support devices with 10 taps.
    • Bug fix in setting the image width in open_framegrabber by the use of the configuration file. In case of analog cameras and an incomplete configuration file, the wrong alignment was set.
    • Bug fix in clean up a previous registered callback function during close_framegrabber.
  • Revision 4.3 (Aug 30, 2011):
    • Bug fix in open_framegrabber if an analog frame grabber was used in combination with a color camera.
  • Revision 4.2 (Jun 9, 2011):
    • Adaptation to MultiCam driver version 6.7.0.1456.
    • Support of GRABLINK Base/DualBase/Full boards.
    • Added functionality to handle 'exposure_end', 'exposure_start', and 'transfer_end' callbacks.
  • Revision 4.1 (Dec 14, 2010):
    • Support also of Windows XP/Vista/7 x64 Editions.
    • Adaptation to MultiCam driver version 6.4.3.686.
    • New buffer memory management to support more than 4GB system memory.
    • Bug fix in info_framegrabber(...'info_boards'...).
    • Extended HTML documentation about how to handle bayer decoding.
  • Revision 4.0 (Dec 1, 2008):
    • HALCON 10 version of the interface (included in HALCON 10 DVD).
    • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
  • 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).
    • Bug fix in open_framegrabber for Multi boards.
    • Bug fix 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):
    • Bug fix 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.
    • Bug fix in support of more than 8 bits per channel.
    • Bug fix in volatile grabbing.
  • Revision 2.0 (Jun 18, 2001):
    • First official version of the interface.