Image Acquisition Interface for Video4Linux2

Interface:	Video4Linux2
Revision:	24.11.10
Date:	2025-10-08

General

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.

System Requirements

Intel compatible PC with Linux (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 VideoFor Linux 2). However, the V4L2 specification allows a wide range of behaviors, 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.

Interface Versioning

MVTec interfaces for digital I/O and image acquisition are always compatible to a range of HALCON versions. Therefore, the versioning scheme both describes the compatibility of the interface and also the revision of the interface itself. An interface version always consists of three numbers, separated by dots, i.e. 24.11.5. The first two numbers describe the minimum HALCON version the interface is compatible with. For the example version 24.11.5 this means that the interface is compatible with all HALCON versions since HALCON 24.11. The last number describes the revision of the interface, in this example this is revision 5.

Installation

Only when installing or updating the interface manually follow these steps:

Linux: Extract the archive containing the interface files to the HALCON base directory $HALCONROOT.

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-16 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).
Only some V4L2 image formats can be captured into HALCON images with more than 8 bits/channel.
External camera triggering is not supported (not part of V4L2).
Asynchronously aborting a running grab with 'do_abort_grab' is not possible if the device doesn't use the streaming interface, and may not work even if it does depending on the Video4Linux2 device driver used.

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

Parameters for info_framegrabber

Parameter	Value List	Type	Kind	Description
'bits_per_channel'	[-1, 8]	integer	pre-defined	Values for bits per channel.
'camera_type'	[]			Unused.
'color_space'	['default', 'gray', 'raw', 'rgb']	string	pre-defined	Values for color space.
'defaults'	[1, 1, 0, 0, 0, 0, 'progressive', 8, 'default', -1.0, 'false', 'auto', 'default', 0, 0]	mixed	pre-defined	Default values for open_framegrabber.
'device'	['device:<device_id> \| port:<port_number> \| input_name:<input_name>']	string	dynamic	List of available devices.
'external_trigger'	[]			Unused.
'field'	[]			Unused.
'general'	[]	string	pre-defined	Information about the HALCON Video4Linux2 interface.
'generic'	['', 'capture_format=<format>', 'num_buffers=<buffers>', 'io_method=<read\|mmap>']	string	pre-defined	Value list for the Generic parameter.
'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_id> \| port:<port_number> \| input_name:<input_name>']	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 Video4Linux2 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

Please note the following hints on how to configure the image size properly with open_framegrabber:

HorizontalResolution, VerticalResolution: When 1 is used for both, the interface tries to infer and automatically configure the largest framesize supported by the V4L2 device and driver. If in that case the interface fails to open the device or the resulting image has unexpected size, it should be tried to specify the desired framesize directly, based on the devices documentation. For example some drivers (like the USB video class driver) will report the size of the currently selected capture image size as the maximum framesize.
ImageWidth, ImageHeight, StartRow, StartColumn: This parameters can be used to grab only a sub-part of the full image. However, V4L2 drivers are not required to support cropping or scaling. Therefore if cropping is desired and the driver supports it, the driver is configured accordingly. If it is not supported the interface grabs the complete image from the device, cropping is done in software and the desired image part is delivered to HALCON.

Parameter	Values	Default	Type	Description
Name	'Video4Linux2'		string	Name of the HALCON interface.
HorizontalResolution	1, 2, 4, resolution	1	integer	Desired horizontal resolution of the camera image: 1: Use full resolution. 2: Use half resolution. 4: Use quarter resolution. resolution: User defined horizontal resolution is set.
VerticalResolution	1, 2, 4, resolution	1	integer	Desired vertical resolution of the camera image: 1: Use full resolution. 2: Use half resolution. 4: Use quarter resolution. resolution: User defined vertical resolution is set.
ImageWidth	0, <width>	0	integer	Width of the desired image part ('0' stands for the complete image).
ImageHeight	0, <height>	0	integer	Height of the desired image part ('0' stands for the complete image).
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	8	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', 'raw', 'rgb'	'default'	string	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.
Generic	'', 'capture_format=<format>', 'num_buffers=<buffers>', 'io_method=<read\|mmap>', -1	-1	mixed	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. capture_format: The V4L2 image format the acquisition device should use to capture images, specified as a string of four ASCII characters corresponding to the "four CC" code of the format in the V4L2 specification. The following capture formats are supported by this interface: 'RGBO', 'R444', 'XR12', 'RGB1', 'RGBP', 'RGBQ', 'XR15', 'RGBR', 'BGR3', 'RGB3', 'BGR4', 'XR24', 'RGB4', 'BX24', 'GBRG', 'GRBG', 'RGGB', 'BA81', 'RG10', 'BA10', 'GB10', 'BG10', 'RG12', 'BA12', 'GB12', 'BG12', 'RG16', 'GR16', 'GB16', 'BYR2', 'GREY', 'YUYV', 'UYVY', 'Y10 ', 'Y12 ', and 'Y16 '. In order to be usable, the device needs to support the format as well. If no capture_format is specified, the interface will use the first format supported by both the device and the interface. num_buffers: Set the number of image buffers the interface should use. The number must be at least one; the maximum number of buffers depends on the device driver. If this parameter is not specified, two buffers are used by default. Note that the device driver may decide to use more buffers than requested. io_method: This interface supports acquiring data via the read() method and via memory mapped buffers (also called streaming I/O). If the driver supports both methods, memory mapped buffers are choosen by default because it is assumed to be the most efficient method. However, depending on the hardware and driver used, it is possible that read() is the faster method. Use the values 'read' or 'mmap' to force the interface to use the choosen method.
ExternalTrigger	---			Ignored.
CameraType	---			Ignored.
Device	'default', '<device_id>'	'default'	string	To open a specific camera the device name as shown in info_framegrabber`(...'info_boards', ...)` has to be set. Video4Linux2 devices are named 'video' followed by a number (e.g. 'video0'). Using 'default' here will select the first usable Video4Linux2 capture device found on the system.
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

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 standard controls/parameters are provided for the Logitech QuickCam 9000 Pro USB camera by the uvcvideo driver directly.

In addition to the standard parameters, 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.

Parameter	Values	Default	Type	Description
Backlight Compensation	0, 1		integer	Standard Device Parameter Adjusts the backlight compensation in the camera. The value 0 disables backlight compensation.
'Brightness'	0 ... 255	128	integer	Standard Device Parameter The brightness value of the image.
'capture_format'	'<format>'		string	Interface Parameter The V4L2 image format the acquisition device should use to capture images, see also the generic parameter capture_format. This parameter cannot be changed while asynchroneous acquisition is active.
'Contrast'	0 ... 255		integer	Standard Device Parameter Contrast value of the image.
Disable video processing	'false', 'true'		string	Dynamic Device Parameter This parameter should always be 'false', because HALCON can not handle the resulting video format.
'do_abort_grab'	---			Interface Parameter Aborts the current image acquisition and unlocks parameters, which are locked according to the status of the transport layer.
Exposure (Absolute)	1 ... 10000		integer	Standard Device Parameter Absolute exposure value.
Exposure, Auto	'Aperture Priority Mode', 'Auto Mode', 'Manual Mode', 'Shutter Priority Mode'		string	Standard Device Parameter 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	'false', 'true'		string	Standard Device Parameter Enables/Disables the auto priority mode.
'Focus'	0 ... 255		integer	Dynamic Device Parameter Sets the focal point of the camera to the specified position.
'frame_interval'	<seconds>		integer, float	Interface Parameter Interval (in seconds) between capturing two successive images. Only intervals that the device driver supports can be specified.
'Gain'	0 ... 255		integer	Standard Device Parameter Gain control value of the camera.
'grab_timeout'	<milliseconds>	5000	integer	Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE.
LED1 Frequency	0 ... 255		integer	Dynamic Device Parameter Frequency of LED1.
LED1 Mode	0 ... 132		integer	Dynamic Device Parameter Mode of LED1. The following modes are available: 0: Off. The LED is always off. 1: On. The LED is always on. 2: Blink. The LED blinks with the frequency selected by 'LED1 Frequency'. 3: Auto. The LED is controlled by the camera. This usually means the LED will be off when the camera is not streaming, and will blink with the frequency selected by 'LED1 Frequency' when it is.
'num_buffers'	<buffers>		integer	Interface Parameter The number of buffers the interface should use for image acquisition. A device driver may decide to use more buffers than requested, so this is the minimum number of buffers to use. The value must be at least one, with the maximum number dependent on the device driver and the available system memory. This parameter cannot be changed while asynchroneous acquisition is active.
Power Line Frequency	'Disable', '50 HZ', '60 HZ'		string	Standard Device Parameter Power line frequency.
Raw bits per pixel	0, 1		integer	Dynamic Device Parameter Specifies how many raw bits per pixel should be used. This value is only relevant if 'Disable video processing' is set to 'true'.
'Saturation'	0 ... 255		integer	Standard Device Parameter Image color saturation.
'Sharpness'	0 ... 255		integer	Standard Device Parameter Adjusts the sharpness filters in a camera. The minimum value disables the filters, higher values give a sharper picture.
'timestamp_timebase'	'auto', 'monotonic', 'realtime'	'auto'	string	Interface Parameter When using the streaming interface (io_method 'mmap'), the Video4Linux2 driver records the time the image was acquired with every buffer. This timestamp can be based on either CLOCK_REALTIME or CLOCK_MONOTONIC. The timestamp is used by the interface to determine if an image is too old, so the interface must know the timebase used. The default setting of 'auto' tells the interface to determine the timebase used automatically. For Linux kernels prior to 3.9, this involves some guesswork, as older Linux kernels did not report the timebase used. If the interface guesses wrong, the correct timebase can be specified by setting the parameter to 'monotonic' or 'realtime', depending on which timebase (CLOCK_MONOTONIC or CLOCK_REALTIME) is actually used. When using io_method 'read', this parameter is ignored and the interface generates timestamps based on CLOCK_MONOTONIC.
'volatile'	'disable', 'enable'	'disable'	string	Interface Parameter 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'.
White Balance Temperature	0 ... 10000		integer	Standard Device Parameter 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	'false', 'true'		string	Standard Device Parameter When activated, keeps adjusting the white balance temperature.

Parameters for get_framegrabber_param

There may exist additional read-only parameters with the following postfixes:

'_description': These parameters provide the tool-tip of the corresponding parameter as a string.
'_range': These parameters provide the minimum, maximum, step width, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(.., 'Shutter_range', ..) will return the output tuple [min, max, step, default].
'_values': These parameters provide the valid value list for the corresponding parameter as a tuple, e.g., get_framegrabber_param(.., 'volatile_values', ..) will return the output tuple ['enable', 'disable'].

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

Parameter	Values	Default	Type	Kind	Description
'available_param_names'	['<parameters>']		string	dynamic	The list contains the names of all available parameters.
Backlight Compensation	0, 1		integer	dynamic	Standard Device Parameter Adjusts the backlight compensation in the camera. The value 0 disables backlight compensation.
'bits_per_channel'	-1, 8	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.
'Brightness'	0 ... 255	128	integer	dynamic	Standard Device Parameter The brightness value of the image.
'camera_type'	'<default>'	'auto'	string	pre-defined	The value is not used, so a default value is returned.
'capture_format'	'<format>'		string	dynamic	Interface Parameter The V4L2 image format the acquisition device should use to capture images, see also the generic parameter capture_format. This parameter cannot be changed while asynchroneous acquisition is active.
'color_space'	'gray', 'raw', 'rgb'	'default'	string	pre-defined	Desired color space and thus the number of image channels of the resulting HALCON image.
'Contrast'	0 ... 255		integer	dynamic	Standard Device Parameter Contrast value of the image.
'device'	'<device_id>'	'default'	string	dynamic	Current device ID.
Disable video processing	'false', 'true'		string	dynamic	Dynamic Device Parameter This parameter should always be 'false', because HALCON can not handle the resulting video format.
Exposure (Absolute)	1 ... 10000		integer	dynamic	Standard Device Parameter Absolute exposure value.
Exposure, Auto	'Aperture Priority Mode', 'Auto Mode', 'Manual Mode', 'Shutter Priority Mode'		string	dynamic	Standard Device Parameter 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	'false', 'true'		string	dynamic	Standard Device Parameter Enables/Disables the auto priority mode.
'external_trigger'	'<default>'	'false'	string	pre-defined	The value is not used, so a default value is returned.
'field'	'<default>'	'progressive'	string	pre-defined	The value is not used, so a default value is returned.
'Focus'	0 ... 255		integer	dynamic	Dynamic Device Parameter Sets the focal point of the camera to the specified position.
'frame_interval'	<seconds>		integer, float	dynamic	Interface Parameter Interval (in seconds) between capturing two successive images. Only intervals that the device driver supports can be specified.
'Gain'	0 ... 255		integer	dynamic	Standard Device Parameter Gain control value of the camera.
'generic'	'', 'capture_format=<format>', 'num_buffers=<buffers>', 'io_method=<read\|mmap>', -1	-1	mixed	pre-defined	Values of the Generic parameter.
'grab_timeout'	<milliseconds>	5000	integer	pre-defined	Current grab timeout in milliseconds.
'horizontal_resolution'	1, 2, 4, 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).
'io_method'	'read', 'mmap'		string	pre-defined	Interface Parameter The currently active I/O method used for accessing image data. See also the generic parameter io_method.
LED1 Frequency	0 ... 255		integer	dynamic	Dynamic Device Parameter Frequency of LED1.
LED1 Mode	0 ... 132		integer	dynamic	Dynamic Device Parameter Mode of LED1. The following modes are available: 0: Off. The LED is always off. 1: On. The LED is always on. 2: Blink. The LED blinks with the frequency selected by 'LED1 Frequency'. 3: Auto. The LED is controlled by the camera. This usually means the LED will be off when the camera is not streaming, and will blink with the frequency selected by 'LED1 Frequency' when it is.
'line_in'	<default>	0	integer	pre-defined	The value is not used, so a default value is returned.
'max_height'	<height>		integer	dynamic	Maximum image height which is supported by the device.
'max_width'	<width>		integer	dynamic	Maximum image width which is supported by the device.
'name'	'Video4Linux2'		string	pre-defined	Name of the HALCON interface.
'num_buffers'	<buffers>		integer	pre-defined	Interface Parameter The number of buffers the interface should use for image acquisition. A device driver may decide to use more buffers than requested, so this is the minimum number of buffers to use. The value must be at least one, with the maximum number dependent on the device driver and the available system memory. This parameter cannot be changed while asynchroneous acquisition is active.
'port'	<default>	0	integer	pre-defined	The value is not used, so a default value is returned.
Power Line Frequency	'Disable', '50 HZ', '60 HZ'		string	dynamic	Standard Device Parameter Power line frequency.
Raw bits per pixel	0, 1		integer	dynamic	Dynamic Device Parameter Specifies how many raw bits per pixel should be used. This value is only relevant if 'Disable video processing' is set to 'true'.
'revision'	'<revision>'		string	pre-defined	Revision number of the Video4Linux2 interface.
'Saturation'	0 ... 255		integer	dynamic	Standard Device Parameter Image color saturation.
'Sharpness'	0 ... 255		integer	dynamic	Standard Device Parameter Adjusts the sharpness filters in a camera. The minimum value disables the filters, higher values give a sharper picture.
'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_timebase'	'auto', 'monotonic', 'realtime'	'auto'	string	pre-defined	Interface Parameter When using the streaming interface (io_method 'mmap'), the Video4Linux2 driver records the time the image was acquired with every buffer. This timestamp can be based on either CLOCK_REALTIME or CLOCK_MONOTONIC. The timestamp is used by the interface to determine if an image is too old, so the interface must know the timebase used. The default setting of 'auto' tells the interface to determine the timebase used automatically. For Linux kernels prior to 3.9, this involves some guesswork, as older Linux kernels did not report the timebase used. If the interface guesses wrong, the correct timebase can be specified by setting the parameter to 'monotonic' or 'realtime', depending on which timebase (CLOCK_MONOTONIC or CLOCK_REALTIME) is actually used. When using io_method 'read', this parameter is ignored and the interface generates timestamps based on CLOCK_MONOTONIC.
'vertical_resolution'	1, 2, 4, resolution	1	integer	pre-defined	Current value of vertical resolution.
'volatile'	'disable', 'enable'	'disable'	string	pre-defined	Interface Parameter 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'.
White Balance Temperature	<Kelvin>		integer	dynamic	Standard Device Parameter 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	'false', 'true'		string	dynamic	Standard Device Parameter When activated, keeps adjusting the white balance temperature.

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:

video4linux2_2cameras.hdev - Example for grabbing images with concurrent grabbing from two connected cameras.
video4linux2.hdev - Benchmark
video4linux2_parameters.hdev - Lists all parameters of a device.
video4linux2_simple.hdev - A simple example to show the usage of the interface.

Usage of third-party libraries

This interface depends on third-party libraries. See the file third_party_video4linux2.txt in the HALCON base directory for copyright and license information. Libraries are used without modifications unless explicitly stated in the file.

You can request the source for those third-party libraries licensed under GPL or LGPL via email to info@mvtec.com with the subject "Request source code of third-party libraries".

Release Notes

Revision 24.11.10 (Oct 8, 2025):
- A Software Bill of Materials (SBOM) in the System Package Data Exchange (SPDX) format has been added next to each binary file with the same name extended by ".spdx.json".
Revision 20.11.9 (Aug 4, 2023):
- third_party_video4linux2.txt now contains links to the corresponding software location. See also Usage of third-party libraries.
Revision 18.11.8 (Oct 20, 2021):
- The distribution package of this interface now contains files providing meta information for the HDevelop example browser.
Revision 18.11.7 (Oct 27, 2020):
- This interface couldn't be loaded from .NET Core applications on Linux and macOS. This problem has been fixed.
Revision 13.0.6 (Sep 10, 2020):
- The postfix '_description' to query the tool-tip for an individual parameter was not implemented. This problem has been fixed.
- The obsolete parameter 'available_param_descriptions' has been removed. Instead use the postfix '_description' to get the description for individual parameters.
- When no V4L2 devices are available, in certain cases an error has been returned by info_framegrabber. Now an empty tuple is returned. This is consistent with other HALCON acquisition interfaces.
- The interface did not initialize all structs properly when querying information from the V4L2 driver. This problem has been fixed.
- The pixel formats 'XR12', 'XR15', 'XR24', and 'BX24' are now supported.
- The generic parameter 'io_method' has been added to switch between read and mmap I/O methods, if both methods are supported by the driver.
Revision 13.0.5 (Aug 9, 2019):
- Some parameters had missing access specifiers (read write, read only, write only). This problem has been fixed.
- Section Third party has been added to this document.
- The file third_party_video4linux2.txt has been added to the distribution package of this interface.
Revision 13.0.4 (Jul 30, 2018):
- Add support for the pixel formats 'RG10', 'GB10', 'BG10', 'RG12', 'BA12', 'GB12', 'BG12', 'RG16', 'GR16', and 'GB16'
- Correctly handle a maxDelay parameter of -1 in grab_image_async and grab_image_start for very long intervals between images (> 12 days). Note that as a result, a maxDelay of exactly 1073741824ms will be treated like -1, i.e. no timeout.
- When calling open_framegrabber with Device 'default', there was a leak of file descriptors to /sys/class/video4linux. This problem has been fixed.
Revision 13.0.3 (Nov 28, 2017):
- The technical dependency from the HALCON Library has been removed.
Revision 13.0.2 (Dec 15, 2016):
- Fixed possible crash if V4L2 driver supplied more buffers than requested.
Revision 13.0.1 (Oct 28, 2016):
- HALCON 13 version of the interface.
- Added parameter 'num_buffers' to set the number of image buffers to use.
- Fixed YUYV and UYUV capture formats not working on x86 and x86_64 machines.
Revision 6.3 (Nov 4, 2015):
- Added parameter 'timestamp_timebase'.
- Fixed potential problem with incorrect timeout calculation.
- Added support for the 'Y10 ' and 'Y12 ' pixel formats.
- Added (limited) support for capturing more than 8 bits/channel.
- Added support for open_framegrabber's BitsPerChannel parameter set to -1.
Revision 6.2 (May 6, 2015):
- Fixed bug in conversion of big- and little-endian RGB555 and RGB565 pixel formats.
Revision 6.1 (Feb 23, 2015):
- Fixed bug in handling of various RGB pixel formats.
Revision 6.0 (Oct 31, 2014):
- HALCON 12 version of the interface.
Revision 5.4 (Aug 27, 2014):
- Added support for the 'RGGB' format.
- The interface will no longer assume the 'default' device is video0; instead it will use the first video capture device found.
- If the colorspace is set to 'default', the value of the colorspace parameter is updated to what is actually used internally.
- Fixed bug that could lead to spurious timeouts in rare cases when calling grab_image_async with MaxDelay of -1
Revision 5.3 (Jul 29, 2014):
- Removed debug messages which were unintentionally logged to stderr.
Revision 5.2 (Jun 25, 2014):
- Fixed interface not handling ENOTTY return value correctly for various ioctls.
- Fixed bug in set_framegrabber_param when trying to set a parameter without specifying a value.
- Fixed bug in grab_image timeing out incorrectly.
Revision 5.1 (Nov 27, 2013):
- Fixed incorrect calculation of image parameters if the top left corner of Video4Linux2's bounds_rect did not start at (0, 0).
- Fixed endless loop during open_framegrabber if the VIDIOC_QUERYCTRL ioctl doesn't return any results.
Revision 5.0 (May 15, 2012):
- HALCON 11 version of the interface (included in HALCON 11 DVD).
Revision 4.0 (Apr 14, 2011):
- First official release.

Legal disclaimer regarding hyperlinks: This page may provide users with access by hypertext links to external, non-MVTec websites. Any such access is provided with the understanding that the contents of non-MVTec sites are beyond the control of MVTec Software GmbH, that MVTec Software GmbH makes no representations whatsoever about such sites, and that users shall proceed at their own risk. MVTec Software GmbH is not responsible for the privacy practices or the content of external, non-MVTec websites.

Copyright notes: © Copyright MVTec Software GmbH. All rights reserved. Unless otherwise stated, the copyright and similar rights in the contents of this page, including but not limited to all text, designs and images appearing herein, are copyrighted works owned by MVTec Software GmbH. "MVTec Software GmbH" and "HALCON" are registered trademarks of MVTec Software GmbH. All other brand names, designs, service marks and trademarks (whether or not registered) referenced or used herein are the property of their respective owners.