MVTec Software GmbH
 

Dokumentation

ABS / HALCON 12.0 / MVTec Software GmbH

Image Acquisition Interface for the ABS UK11xx/31xxx Camera Family

Interface: ABS
Revision: 6.0
Date: 2014-10-31
HALCON Version: 12.0

General

This page provides the documentation of the HALCON ABS image acquisition interface for the ABS UK11xx/31xxx cameras from ABS GmbH. Registered customers can download the latest revision of this interface from the MVTec WWW server.

System Requirements

  • Intel compatible PC with Windows Vista/7 or Windows Vista/7 x64, also WoW64 (using 32-bit HALCON on 64-bit Windows).
  • USB 2.0 / 3.0 interface hardware.
  • ABS-USB-Driver:
    • Windows Vista / 7 / 8 -> USBGenVs driver USBGenVs.sys version 1.5.5 or higher.
      Typically, this file resides in the directory %WINDIR%\system32\drivers.
  • ABS Runtime Library: This DLL must be within your search path %PATH% (typically, it resides in Windows\system32 directory):
    • ABS USB 2.0 Interface: CamUsb_API_hal.dll (32 bit) or CamUSB_API_hal64.dll (64 bit) version 1.10 or higher.
    • ABS USB 3.0 Interface: ABS-USB-Interface DLL: CamUsb_API_hal.dll (32 bit) or CamUSB_API_hal64.dll (64 bit) version 1.11 or higher
  • HALCON image acquisition interface hAcqABS.dll or hAcqABSxl.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

  • Usage of multiple cameras (up to 16).
  • Grabbing images in synchronous or asynchronous modes.
  • Hardware trigger (external) and software trigger for multiple cameras.
  • Simultaneous software-trigger feature for multiple cameras.
  • Control of exposure and auto exposure and gain by software.
  • Control of color correction and white balance by software.
  • Software control of all sensor key parameters (exposure, gain, gamma, contrast, white balance, etc.).
  • Load/restore camera profiles created with the Image Capture software from ABS.
  • Control of digital input and output ports.

Limitations

  • No hardware cropping of images.
  • Volatile is not yet supported.

Using Multiple Cameras

When using multiple ABS cameras please make sure that each camera has an unique device ID.
You can manually set these device IDs by use of the auxiliary program ABSCameraConfig.exe which is part of the ABS driver installation.
For each camera to be used in HALCON one framegrabber has to be opened by calling open_framegrabber with the previously defined internal device ID as 'Device' parameter.
The Port and LineIn parameters are not supported because each single camera is a separate HALCON device.
To get some information about the currently attached camera devices, the operator
info_framegrabber(...,'info_boards', ...) can be called.
Some of the values delivered with a 'set_' operator may differ from the values that can be set effectively on the sensor hardware. In such cases the nearest possible value will be chosen and set on the hardware.
A subsequent call with a 'get_' operator will deliver the value that has effectively been set on the hardware.

Parameters for info_framegrabber

Parameter Value List Type Kind Description
'bits_per_channel' [8, 10, 12, 14] integer pre-defined Values for bits per channel.
'camera_type' [] Unused.
'color_space' ['gray', 'rgb'] string pre-defined Values for color space.
'defaults' [1, 1, 0, 0, 0, 0, 'progressive', 8, 'default', -1.0, 'false', 'default', '-1', 0, 0] mixed pre-defined Default values for open_framegrabber.
'device' ['-1', '0', '1', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15'] string pre-defined Returns a pre-defined list of possible device numbers. open_framegrabber will try to find a camera with a matching 'DeviceID' string. This ID has to be set with an external application 'ABSCameraConfig' before the camera can be used in HALCON. Make sure that each of the connected cameras has its unique 'DeviceID', otherwise the function will return an error 'wrong device'.
'external_trigger' ['false', 'true'] string pre-defined Values for the external trigger.
'field' [] Unused.
'general' '<version>' string dynamic Information about the HALCON ABS interface.
'generic' [] Unsupported query.
'horizontal_resolution' [1, 2, 4] integer pre-defined Value list for horizontal resolution.
'image_height' [] Unsupported query.
'image_width' [] Unsupported query.
'info_boards' ['Device:<device> camera_name:<camera_name> camera_serial:<camera_serial> user_serial:<user_serial> horizontal_resolution:<horizontal_resolution> vertical_resolution:<vertical_resolution> high_speed:<high_speed>'] string dynamic A list of the available devices including additional information.
'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 ABS interface.
'start_column' [] Unsupported query.
'start_row' [] Unsupported query.
'vertical_resolution' [1, 2, 4] integer pre-defined Value list for vertical resolution.

Parameters for open_framegrabber

Parameter Values Default Type Description
Name 'ABS' string Name of the HALCON interface.
HorizontalResolution 1, 2, 4 1 integer
  • 1: full horizontal resolution
  • 2: subsampling by factor 2
  • 4: subsampling by factor 4
Any other value (if dividable by 4) will result in an image with that value as image width. In that case the pixels in the middle of the sensor will be read out (if StartColumn = 0).
VerticalResolution 1, 2, 4 1 integer
  • 1: full vertical resolution
  • 2: subsampling by factor 2
  • 4: subsampling by factor 4
Any other value (if dividable by 4) will result in an image with that value as image height. In that case the pixels in the middle of the sensor will be read out (if StartRow = 0).
ImageWidth 0, <width> 0 integer
  • 0: ImageWidth results from the resolution settings (and depends on the settings of horizontal/vertical_resolution).
  • <width>: If another value is specified, the image will have this width and will not be subsampled (width has to be a multiple of 4).
ImageHeight 0, <height> 0 integer
  • 0: ImageHeight results from the resolution settings (and depends on the settings of horizontal/vertical_resolution).
  • <height>: If another value is specified, the image will have this height and will not be subsampled (height has to be a multiple of 4).
StartRow 0, <row> 0 integer
  • 0: StartRow will be calculated to center the resulting image in column direction of the sensor area.
  • <row>: The coordinate of the upper pixel line (row has to be a multiple of 4).
StartColumn 0, <column> 0 integer
  • 0: StartColumn will be calculated to center the resulting image in row direction of the sensor area.
  • <column>: The coordinate of the most left pixel (column has to be a multiple of 4).
Field --- Ignored.
BitsPerChannel 8, 10, 12, 14 8 integer Number of bits per channel of the resulting HALCON image. In case of -1 the current bit depth of the camera is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images.
ColorSpace 'default', 'gray', 'rgb' 'default' string Desired color space and thus the number of image channels of the resulting HALCON image.
Generic --- Ignored.
ExternalTrigger 'false', 'true' 'false' string Status of the external trigger.
CameraType --- 'default' Ignored (use 'default').
Device '-1','<device_id>' '-1' string open_framegrabber will try to find a camera with a matching 'DeviceID' string. This ID has to be set with an external application 'ABSCameraConfig' before the camera can be used in HALCON. Make sure that each of the connected cameras has its unique 'DeviceID', otherwise the function will return an error 'wrong device'.
Port --- Ignored.
LineIn --- Ignored.

Parameters for set_framegrabber_param

Parameter Values Type Description
'autoexposure' 'disable', 'enable' string Use 'enable' to turn the autoexposure feature on or 'disable' to turn it off.
'autoexposure_control' [<timeout>, <max. exposure> (opt.), <max. gain> (opt.)] mixed Autoexposure control parameters. These parameters are autoexposure timeout, optional maximum exposure and maximum gain, they control the autoexposure algorithm's behavior. By setting the timeout value you guarantee not to trigger any images within that time from grabbing the last image onwards. Maximum exposure and gain are the highest values which will be used by autoexposure algorithm to control the brightness. Set these values to zero to let the camera decide.
'autoexposure_roi' [<left>, <top>, <right>, <bottom>] integer These are the pixel coordinates of the measure window for the autoexposure feature, they are only valid if the feature has been enabled before (default: image coordinates). Valid values have to be multiples of 4.
'autoexposure_target' 0.0 ... 1.0 float Current target value which is to be used for the autoexposure feature.
'color_correction' 'disable', 'enable' string Use 'enable' to switch the color correction feature on or 'disable' to switch it off.
'continuous_grabbing' 'disable', 'enable' 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.
'contrast' -100 ... 100 integer Contrast value within the possible range.
'do_fire_global_sw_trigger' --- Triggers all cameras, which are setup for global software trigger, simultaneous. ('grab_async_with_global_sw_trigger' and grab_image_start must be called).
'do_whitebalance' 'false', 'true' Starts a one-time whitebalance calculation. For optimal results a white or gray surface should be placed in front of the camera covering the whole object plane.
'exposure_time' <microseconds> integer Exposure time within the possible range in microseconds.
'flip_horizontal' 'disable', 'enable' string Use 'enable' to switch the feature on or 'disable' to switch it off.
'flip_vertical' 'disable', 'enable' string Use 'enable' to switch the feature on or 'disable' to switch it off.
'framerate_mode' 'freerun', 'controlled' string Use 'controlled' to set a specific frame rate. With 'freerun' the maximum possible frame rate is set.
'gain' <gain> float A gain value within the possible range for monochrome cameras.
Use 'gain_xxx_channel' to set the separate gain value of the color channels for color cameras, by using 'gain' all channels will be set to the same amount.
'gain_blue' <gain_blue> float Gain value for the blue channel.
'gain_global' <gain_global> float Gain value for the global channel.
'gain_green' <gain_green> float Gain value for the green channel.
'gain_red' <gain_red> float Gain value for the red channel.
'gamma' <gamma> float Gamma value within the possible range.
'grab_async_with_global_sw_trigger' 'false', 'true' string If set to 'true' the next call to grab_image_start setup the camera for async image capture with simultaneous global software trigger. The trigger will be fired if you call the parameter 'do_fire_global_sw_trigger'.
'grab_timeout' <milliseconds> integer Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE.
'outport0' 'false', 'true' string State of the outport. If output is high it is 'true' or if output is low it is 'false'.
'outport1' 'false', 'true' string State of the outport. If output is high it is 'true' or if output is low it is 'false'.
'profile_load' 'none', <profile> string Load / restore previously saved camera configuration settings. You can use the Image Capture software from ABS to create a new profile.
'roi' [<left>, <top>, <right>, <bottom>] integer These are the pixel coordinates on the sensor specifying a window where the image is to be taken from. Valid values have to be multiples of 4.
'start_column' <column> integer
  • 0: StartColumn will be calculated to center the resulting image in row direction of the sensor area.
  • <column>: The coordinate of the most left pixel (column has to be a multiple of 4).
'start_row' <row> integer
  • 0: StartRow will be calculated to center the resulting image in column direction of the sensor area.
  • <row>: The coordinate of the upper pixel line (row has to be a multiple of 4).
'timestamp_overlay' 'disable', 'enable' string Use 'enable' to switch the timestamp overlay feature on or 'disable' to switch it off.
'trigger_mode' 'active_high', 'active_low' string Level or edge triggering.
'trigger_port' '<port>' string Number of the port which is to be used for external trigger.
'trigger_signal' 'active_high', 'active_low', 'inverted', 'normal' string Trigger signal which has one of the possible values. The default setting may vary on different camera models.

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

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
'autoexposure' 'disable', 'enable' 'disable' string pre-defined Use 'enable' to turn the autoexposure feature on or 'disable' to turn it off.
'autoexposure_control' [<timeout>, <max. exposure> (opt.), <max. gain> (opt.)] mixed dynamic Autoexposure control parameters. These parameters are autoexposure timeout, optional maximum exposure and maximum gain, they control the autoexposure algorithm's behavior. By setting the timeout value you guarantee not to trigger any images within that time from grabbing the last image onwards. Maximum exposure and gain are the highest values which will be used by autoexposure algorithm to control the brightness. Set these values to zero to let the camera decide.
'autoexposure_roi' [<left>, <top>, <right>, <bottom>] integer dynamic These are the pixel coordinates of the measure window for the autoexposure feature, they are only valid if the feature has been enabled before (default: image coordinates). Valid values have to be multiples of 4.
'autoexposure_target' 0.0 ... 1.0 0.5 float dynamic Current target value which is to be used for the autoexposure feature.
'bits_per_channel' 8, 10, 12, 14 8 integer pre-defined Number of bits per channel of the resulting HALCON image. In case of -1 the current bit depth of the camera is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images.
'camera_type' '<default>' 'default' string pre-defined The value is not used, so a default value is returned.
'color_correction' 'disable', 'enable' string pre-defined Use 'enable' to switch the color correction feature on or 'disable' to switch it off.
'color_space' '<color_space>' 'default' 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.
'contrast' -100 ... 100 0 integer dynamic Contrast value within the possible range.
'device' '<device_id>' '-1' string pre-defined Current device id.
'exposure_time' <microseconds> integer dynamic Exposure time within the possible range in microseconds.
'external_trigger' 'false', 'true' 'false' string pre-defined Status of the external trigger.
'field' '<default>' 'progressive' string pre-defined The value is not used, so a default value is returned.
'flip_horizontal' 'disable', 'enable' string pre-defined Use 'enable' to switch the feature on or 'disable' to switch it off.
'flip_vertical' 'disable', 'enable' string pre-defined Use 'enable' to switch the feature on or 'disable' to switch it off.
'framerate_mode' 'freerun', 'controlled' string pre-defined Use 'controlled' to set a specific frame rate. With 'freerun' the maximum possible frame rate is set.
'gain' <gain> -1.0 float dynamic A gain value within the possible range for monochrome cameras.
Use 'gain_xxx_channel' to set the separate gain value of the color channels for color cameras, by using 'gain' all channels will be set to the same amount.
'gain_blue' <gain_blue> float dynamic Gain value for the blue channel.
'gain_global' <gain_global> float dynamic Gain value for the global channel.
'gain_green' <gain_green> float dynamic Gain value for the green channel.
'gain_red' <gain_red> float dynamic Gain value for the red channel.
'gamma' <gamma> 1.0 float dynamic Gamma value within the possible range.
'generic' <default> -1 mixed pre-defined The value is not used, so a default value is returned.
'grab_async_with_global_sw_trigger' 'false', 'true' 'false' string pre-defined If set to 'true' the next call to grab_image_start setup the camera for async image capture with simultaneous global software trigger. The trigger will be fired if you call the parameter 'do_fire_global_sw_trigger'.
'grab_timeout' <milliseconds> 5000 integer pre-defined Current grab timeout in milliseconds.
'horizontal_resolution' <horizontal_resolution> 1 integer pre-defined Current value of horizontal resolution.
'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).
'inport0' 'false', 'true' string dynamic Returns 'true' if a high signal is on inport0, otherwise 'false'.
'inport1' 'false', 'true' string dynamic Returns 'true' if a high signal is on inport1, otherwise 'false'.
'line_in' <default> 0 integer pre-defined The value is not used, so a default value is returned.
'maximum_framerate' <max_framerate> integer dynamic Maximum framerate achievable by the sensor when using 'contiuous_grabbing'. This value may change on different image sizes.
'name' 'ABS' string pre-defined Name of the HALCON interface.
'outport0' 'false', 'true' string pre-defined State of the outport. If output is high it is 'true' or if output is low it is 'false'.
'outport1' 'false', 'true' string pre-defined State of the outport. If output is high it is 'true' or if output is low it is 'false'.
'port' <default> 0 integer pre-defined The value is not used, so a default value is returned.
'profile_load' 'none', <profile> string pre-defined Load / restore previously saved camera configuration settings. You can use the Image Capture software from ABS to create a new profile.
'revision' '<revision>' string pre-defined Revision number of the ABS interface.
'roi' [<left>, <top>, <right>, <bottom>] integer dynamic These are the pixel coordinates on the sensor specifying a window where the image is to be taken from. Valid values have to be multiples of 4.
'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.
'timestamp_overlay' 'disable', 'enable' string pre-defined Use 'enable' to switch the timestamp overlay feature on or 'disable' to switch it off.
'trigger_mode' 'active_high', 'active_low' string pre-defined Level or edge triggering.
'trigger_port' '<port>' 'TTL Trigger-Input' string dynamic Number of the port which is to be used for external trigger.
'trigger_signal' 'active_high', 'active_low', 'inverted', 'normal' string pre-defined Trigger signal which has one of the possible values. The default setting may vary on different camera models.
'vertical_resolution' <vertical_resolution> 1 integer pre-defined Current value of vertical resolution.

Operator set_framegrabber_lut

Not supported by this interface.

Operator get_framegrabber_lut

Not supported by this interface.

Operator set_framegrabber_callback

Not supported by this interface.

Operator get_framegrabber_callback

Not supported by this interface.

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:
  • abs.hdev - Benchmark
  • abs_crop.hdev - Grabbing images using image cropping.
  • abs_multiple_cameras.hdev - The example shows how to trigger multiple cameras.
  • abs_parameters.hdev - Lists all parameters of a device.
  • abs_simple.hdev - A simple example to show the usage of the interface.

Release Notes

  • Revision 6.0 (Oct 31, 2014):
    • HALCON 12 version of the interface.
  • Revision 5.1 (May 23, 2014):
    • Added support for USB 3.0 devices.
    • Added parameter 'framerate_mode'.
    • Fixed bug in info_framegrabber parameter 'parameters_readonly'. The parameter 'revision' was not listed by this query.
    • Fixed bug in set_framegrabber_param when trying to set a parameter without specifying a value.
    • Improved info_framegrabber parameter 'device'. The returned value is now queried dynamically and could be directly used by open_framegrabber.
  • Revision 5.0 (May 15, 2012):
    • HALCON 11 version of the interface (included in HALCON 11 DVD).
    • Updated to UK11xx camera API version 1.10.
    • Added support for Windows x64.
    • Added parameter 'profile_load'.
    • Added read-only parameters with postfix '_description', '_range', and '_values' to enable the easy parameterization via a generic graphical user interface.
    • Fixed bug in grab_image and grab_image_async: The first image grab now returns no longer a black image.
    • Fixed some errors with I/O port handling.
    • Removed obsolete parameters 'brightness' and 'framerate' from the documentation.
  • 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.0 (Apr 25, 2008):
    • First official release.