Interface Documentation
Image Acquisition Interface for the ABS UK11xx/31xxx Camera Family
Interface: | ABS |
Revision: | 13.0.1 |
Date: | 2016-10-28 |
HALCON Version: | 13.0 |
- General
- System Requirements
- Features
- Limitations
- Using Multiple Cameras
- Parameters for info_framegrabber
- Parameters for open_framegrabber
- Parameters for set_framegrabber_param
- Parameters for get_framegrabber_param
- 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
- Release Notes
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 7 (32-bit or 64-bit) or newer that is also supported by the vendor-specific SDK, 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.
- Windows Vista/7/8 -> USBGenVs driver USBGenVs.sys version
1.5.5 or higher.
- 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.
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 |
|
VerticalResolution | 1, 2, 4 | 1 | integer |
|
ImageWidth | 0, <width> | 0 | integer |
|
ImageHeight | 0, <height> | 0 | integer |
|
StartRow | 0, <row> | 0 | integer |
|
StartColumn | 0, <column> | 0 | integer |
|
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 | Default | Type | Description |
---|---|---|---|---|
'autoexposure' | 'disable', 'enable' | 'disable' | 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 | 0.5 | 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' | '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. |
'contrast' | -100 ... 100 | 0 | 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> | -1.0 | 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> | 1.0 | float | Gamma value within the possible range. |
'grab_async_with_global_sw_trigger' | 'false', 'true' | 'false' | 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> | 5000 | 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 |
|
|
'start_row' | <row> | integer |
|
|
'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>' | 'TTL Trigger-Input' | 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].
- '_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 13.0.1 (Oct 28, 2016):
- HALCON 13 version of the interface.
- 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.