This page refers to the development version of the package and releases made AFTER 01.04.2023!
The develop branch of the repository contains the code that IS NOT CURRENTLY RELEASED! Please consider it a beta release-candidate version implementing the new API and configuration policy.
ROS binary package repository is now containing version 0.3.7 available for installation!
Please note that the documentation for previously released (0.3.7 and earlier) versions of this package is available on Old versions' documentation subpage
This package provides a configurable ROS interface to the kernel API of libv4l2 library that implements a common driver for standard USB web cameras. The module uses a monopolistic way of entry point (virtual filesystem) access model with the policy "one device = one node". The ROS node running over the libv4l2 API also queries the kernel about the intrinsic parameters of the camera and provides a flexible configuration model via the standard ROS configuration model. The camera is polled over the intervals of the desired framerate, then the images are decoded and published according to image_transport package specifications in sink-on-demand operating mode. Also, the dynamic_reconfigure specifications are partially supported to publish actual frame parameters.
Supported device access models
Memory Mapping - for the device with direct monopolistic USB port access model implemented via libusb
User Pointer Exchange - for the devices supporting userspace memory pointer requests
Virtual Block Device - for the devices supporting block I/O model via virtual userspace filesystem kernel driver
Published message types
sensor_msgs/CameraInfo for publishing camera calibration matrices
sensor_msgs/Image for uncompressed OpenCV-compatible images
sensor_msgs/CompressedImage for binary packets containing PNG/JPEG-compressed images published under the compressed topic suffix. NOTE: also on-the-fly encoding of the images into 16-bit depth matrices is supported. The PNG-compressed frames are published under compressedDepth topic suffix.
theora_image_transport/Packet for binary packages containing Theora/H.263 YUV420-encoded stacks of images published under theora topic suffix
dynamic_reconfigure/Config for publishing actual frame parameters under parameter_updates topic suffix
Topic names abbreviation policy
The node formulates topic namespaces and affixes using the following policy:
Node name taken from ROS launch server
Transport suffix configured with camera_transport_suffix parameter
image_transport mode suffix
Description suffix provided from dynamic_reconfigure API
For example, if the node runs under the name usb_cam and camera_transport_suffix is set to image_raw (default invocation case), the node will publish the following list of topics:
/usb_cam/camera_info /usb_cam/image_raw /usb_cam/image_raw/compressed /usb_cam/image_raw/compressed/parameter_descriptions /usb_cam/image_raw/compressed/parameter_updates /usb_cam/image_raw/compressedDepth /usb_cam/image_raw/compressedDepth/parameter_descriptions /usb_cam/image_raw/compressedDepth/parameter_updates /usb_cam/image_raw/theora /usb_cam/image_raw/theora/parameter_descriptions /usb_cam/image_raw/theora/parameter_updates
The support for a hardware-accelerated decoder in the package is now experimental. It is implemented in the dedicated branch in the repository. The feature is not enabled by default and it is supported only from libavcodec library version 52.00.100.
The names mentioned <in brackets> are actually the names of parameters configuring the really used names in the ROS system namespace. Thus, most of the names of topics and services mentioned here are configurable. Please see sample config file for reference.
usb_cam_nodeOpens the V4L device handler to poll the camera, recompress and publish the images on demand
Published Topics/<node_name>/camera_info (sensor_msgs/CameraInfo)
- Camera calibration matrices from the specified calibration YAML file provided by the camera's vendor, or obtained with tools from camera_calibration package
- Uncompressed frames
- PNG/JPEG compressed frames according to image_transport specifications
- Latched topic providing compressed frame's parameter descriptions for the nodes supporting image_transport specification and dynamic_reconfigure
- Latched topic providing compressed frame's actual parameters for the nodes supporting image_transport specification and dynamic_reconfigure
- PNG-compressed 16-bit depth frames
- Latched topic providing compressed frame's parameter descriptions for depth_image_proc
- Latched topic providing compressed frame's actual parameters for depth_image_proc
- Incrementally encoded stacks of frames compatible with theora_image_transport package specification
- Latched topic providing compressed frame's parameter descriptions for the nodes supporting theora_image_transport specification and dynamic_reconfigure
- Latched topic providing compressed frame's actual parameters for the nodes supporting theora_image_transport specification and dynamic_reconfigure
- Call this service to start the suspended capture of frames from the device
- Call this service to stop the active capture of frames from the device
- Returns the "|"-separated string containing the list of intrinsic controls (parameters) the camera supports, queried from V4L kernel driver. In case of presence, the first "|" symbol should be ignored.
- Returns the "|"-separated string containing the list of image formats/encodings the camera supports, queried from V4L kernel driver. In case of presence, the first "|" symbol should be ignored.
Parametersstart_service_name (string, default: start_capture)
- Defines name suffix for std_srvs/Empty service which restarts suspended streaming
- Defines name suffix for std_srvs/Empty service which suspends camera polling timer
- Device driver's entry point in Linux kernel's virtual filesystem
- I/O method (see Available I/O methods for value reference)
- Pixel format for Video4linux device (also selects decoder mode). See Pixel formats for value reference
- On-chip color representation mode for the input frame encoded by hardware. See Color formats for value reference
- Instructs the node whether to start streaming immediately after launch or to wait until the <start_service_name> service will be triggered
- When set to false allows to suppress warning messages generated by libavcodec during MJPEG decoding, cleans log files
- ROS internal name for the camera, used to generate sensor_msgs/CameraInfo message
- Frame ID used to generate coordinate transformations
- Suffix used by image_transport to generate topic names
- URI for camera calibration data (likely a YML file obtained from camera_calibration tools)
- Frame width in pixels, should be supported by hardware! Please refer to supported_formats service for list of possible values
- Frame height in pixels, should be supported by hardware! Please refer to supported_formats service for list of possible values
- Camera polling frequency, Hz (integer)
- Intrinsic controls queried from V4L kernel driver. See Intrinsic Controls to learn how to configure this list, and supported_controls service to retrieve possible values.
I/O modes reference
The node supports the following I/O mode names for the given device:
read - for devices supporting virtual filesystem or block I/O
mmap - for devices supporting direct libusb memory mapping
userptr - for DMA devices supporting userspace pointer exchange
Pixel formats/encodings reference
Selection of the pixel format name automatically selects the decoder library and pixel representation for FFMPEG/libavcodec processing. The node supports the following pixel format names and decoders (all names are case-sensitive):
yuyv - YUV420
yuv - synonym for yuyv
uyvy - UVY240, MESECAM
yuvmono10 - Monochrome 10-bit pseudo-YUV
rgb24 - Linear 8-bit RGB matrix
bgr24 - OpenCV-compatible 8-bit BGR
grey - Grayscale 8-bit linear monochrome matrix
yu12 - YU-reversed YUV420
mjpeg - FFMPEG-decoded MotionJPEG. Requires compatible hardware
h264 - FFMPEG-decoded H.264. Requires compatible hardware. May also require setting color_format parameter to yuv420p
NOTE: In its current state, the node does not support hardware-accelerated decoding!
Color representation formats reference
The node supports the following color representation mode names (case-sensitive):
yuv422p - YUV422 - default, compatible with most MJPEG hardware encoders
yuv420p - YUV420 - may be required by H.264 and H.265 hardware encoders
Intrinsic control configuration
The node queries V4L kernel driver for available intrinsic control names and data types they require, in the same way, that one can query from terminal with the following command:
v4l2-ctl --device=/dev/video<ID> -L
The node supports the following types of intrinsic controls provided by libv4l2:
- Integers (32-bit)
- Integers (64-bit)
- Menus (integer-indexed sets of operating modes)
- Integer/Menu multiparams (menus with manual adjustment possibility)
The data type for the given parameter is determined automatically.
The queried names become ROS parameters and are placed under intrinsic_controls multilist of the configuration file. Its main namespace contains:
Unique names of the generated ROS parameters. NOTE: if the parameter name reported from V4L kernel driver exists but not mentioned here, it will be processed and set up with default value, also provided by the driver.
ignore - the string list containing control names that should be ignored. If the existing intrinsic control is mentioned here, its value will be left intact.
This example configuration is obtained using Logitech HD Pro Webcam C920 web camera with standard V4L2 kernel driver from Ubuntu 22.04 with 5.15.0 kernel installed. The manually queried control names:
v4l2-ctl --device=/dev/video0 -L brightness 0x00980900 (int) : min=0 max=255 step=1 default=128 value=128 contrast 0x00980901 (int) : min=0 max=255 step=1 default=128 value=128 saturation 0x00980902 (int) : min=0 max=255 step=1 default=128 value=128 white_balance_temperature_auto 0x0098090c (bool) : default=1 value=1 gain 0x00980913 (int) : min=0 max=255 step=1 default=0 value=155 power_line_frequency 0x00980918 (menu) : min=0 max=2 default=2 value=1 (50 Hz) 0: Disabled 1: 50 Hz 2: 60 Hz white_balance_temperature 0x0098091a (int) : min=2000 max=6500 step=1 default=4000 value=5485 flags=inactive sharpness 0x0098091b (int) : min=0 max=255 step=1 default=128 value=128 backlight_compensation 0x0098091c (int) : min=0 max=1 step=1 default=0 value=0 exposure_auto 0x009a0901 (menu) : min=0 max=3 default=3 value=3 (Aperture Priority Mode) 1: Manual Mode 3: Aperture Priority Mode exposure_absolute 0x009a0902 (int) : min=3 max=2047 step=1 default=250 value=200 flags=inactive exposure_auto_priority 0x009a0903 (bool) : default=0 value=1 pan_absolute 0x009a0908 (int) : min=-36000 max=36000 step=3600 default=0 value=0 tilt_absolute 0x009a0909 (int) : min=-36000 max=36000 step=3600 default=0 value=0 focus_absolute 0x009a090a (int) : min=0 max=250 step=5 default=0 value=0 flags=inactive focus_auto 0x009a090c (bool) : default=1 value=1 zoom_absolute 0x009a090d (int) : min=100 max=500 step=1 default=100 value=100
The corresponding YAML configuration multilist looks like:
intrinsic_controls: focus_auto: true exposure_auto_priority: true exposure_auto: 3 white_balance_temperature_auto: true power_line_frequency: 1 ignore: [ brightness, contrast, saturation, gain, sharpness, backlight_compensation, white_balance_temperature, exposure_absolute, pan_absolute, tilt_absolute, focus_absolute, zoom_absolute ]
Here are the following intrinsic controls that are mentioned in the root namespace of the intrinsic_controls multilist, so they will be processed and set up:
All the other intrinsic control names reported by v4l2-ctl are enumerated in the ignore string list, so their values will be left intact.