资料
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
- System Requirements
- Features
- Limitations
- Parameters for info_framegrabber
- Parameters for open_framegrabber
- Parameters for set_framegrabber_param
- Parameters for get_framegrabber_param
- Additional parameters for set_framegrabber_param:
Line Scan, Strobe, Digital Input/Output, DOMINO and PICOLO, DOMINO and GRABLINK, PICOLO and QUICKPACK Parameters - Additional parameters for get_framegrabber_param:
Line Scan, Strobe, Digital Input/Output, DOMINO and PICOLO, DOMINO and GRABLINK, PICOLO and QUICKPACK Parameters - Operator set_framegrabber_lut
- Operator get_framegrabber_lut
- Operator set_framegrabber_callback
- Operator get_framegrabber_callback
- Operator grab_image_start
- Operator grab_image
- Operator grab_image_async
- Operator grab_data
- Operator grab_data_async
- Operator close_framegrabber
- HDevelop Examples
- C++ Examples
- C# Examples
- Release Notes
General
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 |
|
'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' | 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
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).
|
'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
- '_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
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).
|
'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).
|
'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:
|
Additional parameters for get_framegrabber_param:
Line Scan, Strobe, Digital Input/Output,
DOMINO and PICOLO, DOMINO and GRABLINK,
PICOLO and QUICKPACK 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
Operator get_framegrabber_lut
Operator set_framegrabber_callback
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
Operator grab_image_start
Operator grab_image
Operator grab_image_async
Operator grab_data
Operator grab_data_async
Operator close_framegrabber
HDevelop Examples
- 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
C# Examples
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):
- Fixed thread safety problem in grab_image and grab_image_async that could occur if a pending grab was aborted via the 'do_abort_grab' parameter of set_framegrabber_param.
- 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.