HALCON 10: Image Acquisition Interface for Video4Linux2
This page provides the documentation of the HALCON Video4Linux2 image acquisition interface, which is based on the V4L2 API, a Linux kernel interface for video capture. V4L2 is the second generation of the Video4Linux API. Registered customers can download the latest revision of this interface from the MVTec WWW server. For a description of V4L2, please see the official web page at Video For Linux 2.
Revision: 4.0
System Requirements
- Intel compatible PC with Linux x86 or x86_64 (kernel 2.6.19 or higher) and a working installation of V4L2 with all required kernel modules for the acquisition hardware to be used. The user that will be running HALCON will typically need to be in the video group in order to be able to access the V4L2 devices.
- HALCON image acquisition interface hAcqVideo4Linux2.so or hAcqVideo4Linux2xl.so, respectively. If you have properly installed the interface, the shared objects should reside in lib\$HALCONARCH within the HALCON base directory $HALCONROOT you have chosen during the installation of HALCON.
- The HALCON Video4Linux2 acquisition interface should be able to support any video capture device that provides a V4L2 driver compliant with the V4L2 specification (found at Video For Linux 2). However, the V4L2 specification allows a wide range of behaviours, and individual drivers may violate the specification, so some device/driver combinations may fail to work. Currently, the only device that has been tested is the Logitech QuickCam 9000 Pro with version 0.1.0 of the uvcvideo driver.
Features
- Grabbing from multiple cameras. Attention: Due to the bandwidth allocation enforcement strategy (which is a kernel configuration option) of the Linux kernel it might be necessary to connect each camera to its own physical controller, else the grabbing might fail with I/O errors or timeouts. The easiest way to ensure sufficient bandwidth for each camera is to use dedicated USB controllers for each camera, see also the output of lsusb -v for more information about available USB devices.
- Synchronous and asynchronous grabbing.
- Cropping of image parts.
- Software control of a variety of standard and camera-specific parameters.
Limitations
- Currently only 8 bits/channel HALCON images can be acquired, even if the device is capable of capturing with higher bit depths.
- Not all V4L2 image formats are supported (see below for a list of supported formats).
- External camera triggering is not supported (not part of V4L2).
- grab_data and grab_data_async not supported.
Dynamic Controls
In addition to the standard driver features of the USB Video Class driver uvcvideo, the HALCON Video4Linux2 interface can access additional vendor-specific device features if these are supported and enabled.
The USB Video Class driver uvcvideo offers access to such additional, vendor-specific device features (like the focus control for the Logitech QuickCam 9000 Pro) using dynamic controls that are configured on a per-device basis after the uvcvideo driver has been loaded. The configuration can be done with the program uvcdynctrl, which is part of the libwebcam software package. If the necessary software is not installed on your system or you require further information, please see the QuickCam Team page from Logitech. For information on what (if any) dynamic controls are supported by for a specific device and what configuration files are required, please ask the device manufacturer.
Description
Parameters for open_framegrabber():
| Name | 'Video4Linux2' | The name of the HALCON image acquisition interface. | |||
| HorizontalResolution | 1, 2, 4, resolution |
Set the desired horizontal resolution of the camera image:
|
|||
| VerticalResolution | 1, 2, 4, resolution |
Set the desired vertical resolution of the camera image:
|
|||
| ImageWidth | 0, width | The width of the desired image part ('0' stands for the maximum image width). Default: 0. | |||
| ImageHeight | 0, height | The height of the desired image part ('0' stands for the maximum image height). Default: 0. | |||
| StartRow | 0, row | The row coordinate of the upper left pixel within the desired image part. Default: 0. | |||
| StartColumn | 0, column | The column coordinate of the upper left pixel within the desired image part. Default: 0. | |||
| Field | --- | Ignored. | |||
| BitsPerChannel | 8 | The number of significant bits per channel of the resulting HALCON image. Default: 8. | |||
| ColorSpace | 'default', 'gray', 'raw', 'rgb' | Specify the desired color space and thus the number of image channels of the resulting HALCON image. In case of 'default' the color space which is supported by the device will be used. Default: 'default'. | |||
| Generic | ['capture_format=format'], -1 |
With the generic parameter some important values can be set
before the camera is initialized. Note that the parameter names
including the values must be strings.
|
|||
| ExternalTrigger | --- | Ignored. | |||
| CameraType | --- | Ignored. | |||
| Device | 'default', device_name | To open a specific camera the device name as shown in info_framegrabber('info_boards',...,...) has to be set. All supported device names are enumerated with 'video' followed by the enumerated device number ( e.g., 'video0'). The 'default' opens the first available camera which is 'video0'. Default: 'default'. | |||
| Port | --- | Ignored. | |||
| LineIn | --- | Ignored. | |||
Parameters for set_framegrabber_param():
In general, the HALCON Video4Linux2 interface provides three types of parameters:
- Parameters of the interface itself
- Device-specific parameters provided by the uvcvideo driver
- Vendor-specific device parameters using the dynamic control features
| 'capture_format' | format | The V4L2 image format the acquisition device should use to capture images, see also the generic parameter capture_format. | |||
| 'do_abort_grab' | --- | Aborts the current image acquisition and unlocks parameters, which are locked according to the status of the transport layer. | |||
| 'frame_interval' | sec | The interval (in seconds) between capturing two successive images. Only intervals that the device driver supports can be specified. | |||
| 'grab_timeout' | msec | Specify the desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE. Default: 5000. | |||
| 'volatile' | 'disable', 'enable' |
Raw and grayscale only. In the volatile mode the image
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! Please note that the HDevelop Image Acquisition Assistant offers only the 'enable' value, if the current capture format allows volatile mode. So after changing these parameters, the refresh button has to be used to get the new status of the values for volatile. Default: 'disable'. |
|||
Standard Device Parameters for the Logitech QuickCam 9000 Pro USB camera
The interface provides access to device features using the V4L2 control API. To access a V4L2 control, use the control's name as the parameter name for get_framegrabber_param and set_framegrabber_param. Unfortunately, these names are not standardized and depend on the connected device. Call get_framegrabber_param(..., 'available_param_names', ...) to obtain a tuple containing all available parameters for the connected device.
The following controls/parameters are provided for the Logitech QuickCam 9000 Pro USB camera by the uvcvideo driver directly:
| 'Backlight Compensation' | 0, 1 | Adjusts the backlight compensation in the camera. The value 0 disables backlight compensation. | |||
| 'Brightness' | 0 ... 255 | Sets the brightness value of the image. Default: 128 | |||
| 'Contrast' | 0 ... 255 | Sets the contrast value of the image. | |||
| 'Exposure (Absolute)' | 1 ... 10000 | Sets the absolute exposure value. | |||
| 'Exposure, Auto' | 'Manual Mode', 'Auto Mode', 'Shutter Priority Mode', 'Aperture Priority Mode' | Sets a special auto exposure mode. Note: Only the modes 'Manual Mode' and 'Aperture Priority Mode' are supported by the Logitech Quickcam 9000 Pro. | |||
| 'Exposure, Auto Priority' | 'true', 'false' | Enables/Disables the auto priority mode. | |||
| 'Gain' | 0 ... 255 | Sets the gain control value of the camera. | |||
| 'Power Line Frequency' | 'Disable', '50 HZ', '60 HZ' | Sets power line frequency. | |||
| 'Saturation' | 0 ... 255 | Set the image color saturation. | |||
| 'Sharpness' | 0 ... 255 | Adjusts the sharpness filters in a camera. The minimum value disables the filters, higher values give a sharper picture. | |||
| 'White Balance Temperature' | 0 ... 10000 | This control specifies the white balance settings as a color temperature in Kelvin. A driver should have a minimum of 2800 (incandescent) to 6500 (daylight). | |||
| 'White Balance Temperature, Auto' | 'true', 'false' | When activated, keeps adjusting the white balance temperature. |
Dynamic Device Parameters for the Logitech QuickCam 9000 Pro USB camera
In addition to the standard parameters described in the previous section, the uvcvideo driver for the Logitech QuickCam 9000 Pro can also provide a number of vendor specific device parameters using the dynamic control feature. Please refer to the dynamic controls section for details.
Once the required dynamic controls have been configured, the following additional parameters will be available from the acquisition interface:
| 'Disable video processing' | 'true', 'false' | This parameter should always be 'false', because HALCON can not handle the resulting video format. | |||
| 'Focus' | 0 ... 255 | This control sets the focal point of the camera to the specified position. | |||
| 'LED1 Frequency' | 0 ... 255 | Sets frequency of LED1. | |||
| 'LED1 Mode' | 0 ... 132 |
Sets the mode of LED1. The following modes are available:
|
|||
| 'Raw bits per pixel' | 0, 1 | Specifies how many raw bits per pixel should be used. This value is only relevant if 'Disable video processing' is set to 'true'. |
Parameters for get_framegrabber_param():
Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param except the ones with prefix 'do_' can also be accessed by get_framegrabber_param. Furthermore, corresponding to the parameters supported by set_framegrabber_param, there may exist additional read-only parameters with the following postfixes:
- '_description': These parameters provide the tooltip of the corresponding parameter as a string. These parameters are not available for V4L2 control parameters.
- '_range': These parameters provide the minimum, maximum, stepwidth, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(..,'contrast_range',..) will return the output tuple [min,max,step,default]. Optionally, this tuple can also contain additional valid string values like 'auto' or 'manual'. These parameters are not available for V4L2 controls of the 'menu' type.
- '_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']. These parameters are not available for V4L2 controls of the 'integer' type.
| 'available_param_descriptions' | descriptions | Returns a list containing additional information about all parameters. The order of the entries is equal to the order of the parameter names returned by 'available_param_names'. | |||
| 'available_param_names' | parameters | Returns a list containing the names of all available parameters. | |||
| 'max_height' | height | Gets the maximum image height which is supported by the device. | |||
| 'max_width' | width | Gets the maximum image width which is supported by the device. | |||
| 'revision' | revision | The revision number of the HALCON Video4Linux2 image acquisition interface. |
Release Notes
-
Revision 4.0 (Apr 14, 2011):
- First official release.
