search

FraunhoferIOSB / camera_aravis2

ROS2 camera driver for GenICam-based GigEVision and USB3Vision cameras.
BSD 3-Clause "New" or "Revised" License
15 stars 2 forks source link

readme

camera_aravis2

An actively maintained ROS 2 camera driver for GenICam-based (GigEVision and USB3Vision) cameras. It is a subsequent development of camera_aravis, but in order to clean up some legacy code and, in turn, support new features mor easily, we opted to implement it with a new code-base. It is open sourced under the 3-clause BSD license.

It relies on the Aravis library to access the GigEVision and USB3Vision cameras. Aravis is a glib/gobject based library for video acquisition using GenICam cameras. It currently implements the gigabit ethernet and USB3 protocols used by industrial cameras.

Acknowledgement: This software was developed as part of the project ROBDEKON – Robotic Systems for Decontamination in Hazardous Environments, funded by the Federal Ministry of Education and Research (BMBF) under the German Federal Government’s Research for Civil Security program.

Continuous Integration:

Service devel main
GitHub Humble Hawksbill
Iron Irwini
Jazzy Jalisco		 Humble Hawksbill
Iron Irwini
Jazzy Jalisco

Contents:

Running the Camera Driver

In camera_aravis2 the actual camera driver is implemented in two nodes:

Configuration

The configuration of the camera driver is divided into a driver-specific and GenICam-specific parameterization as described below.

Driver-specific Parameters

GenICam-Specific Parameters

To configure the camera, camera_aravis2 relies on the GenICam Standard Feature Naming Convention (SNFC) which can be found here. The SNFC groups the individual features into numerous catagories (e.g. Image Format Control, Acquisition Control, Analog Control, ...). Camera_aravis2 explicitly looks for a number of features in a couple of categories to be specified and tries to set the features accordingly. If specified as launch parameter, camera_aravis2 will set the following features in the same order as listed below:

In the sections where a certain order of predefined parameters is considered and implemented, the user can specify a list of additional GenICam parameters nested underneath the parameter BEGIN and END, respectively, which are not explicitly evaluated as part of the list above. This allows for the user to specify parameters which are not known to camera_aravis2. Similar holds for the parameters within the 'DeviceControl' category. It is to be noted, however, that the nested parameters are evaluated in alphabetical order, which might lead to unintended behavior, depending on the camera device.

The example values that are given in case of string parameters are given in accordance with the GenICam SNFC. The possible values might differ according to the actual implementation by the camera manufacturer.

Parameters marked with * are evaluated and set per stream/channel. Meaning, that for a multi-channel or multi-source camera one can either specify a single parameter or a list of parameters (see 'PixelFormat' in the example below). In case a single parameter is specified, the corresponding value is set for all channels. If a list of parameters is given, for each channel the value with the corresponding channel index will be set. If the list is smaller than the available channels, the value of the last entry will be set for the remaining channels. Please note, that the flexibility of setting different parameters values for the individual channels depends on the actual implementation by the camera manufacturer.

When launching the camera driver, the features are to be configured as nested launch parameters. While the parameters are evaluated by camera_aravis2 in the specific order which is listed above, they can be specified in an arbitrary order in the launch file.

For example ... ```Python ... parameters=[{ # Driver-specific parameters ... # GenICam-specific parameters "DeviceControl": { "DeviceLinkThroughputLimit": 125000000, "DeviceLinkThroughputLimitMode": "On" }, "TransportLayerControl": { "GevSCPSPacketSize": 9000, "PtpEnable": True }, "ImageFormatControl": { "BEGIN": { "BinningSelector": "Digital" }, "PixelFormat": "BayerRG8", "Width": 1920, "Height": 1200 }, "AcquisitionControl": { "ExposureMode": "Timed", "ExposureAuto": "Continuous", "AcquisitionFrameRate": 30.0 }, "AnalogControl": { "GainAuto": "Continuous", "BalanceWhiteAuto": "Off", "BalanceRatio": { "Red": 1.6, "Blue": 2.0 } } }] ... ```


If a feature is omitted but supported by the camera, it will default to the value that is currently set on the device.

To find the features that are available for configuration on the camera, together with their feature names and their value ranges, look into the documentation of the manufacturer or extract the camera-specific GenICam XML file.

Example Launch Files

Finding Available Cameras

Camera_aravis2 provides the node camera_finder to find available cameras and print out the corresponding GUIDs. These, in turn, are needed to run the camera drivers or to export the camera specific GenICam XML.

ros2 run camera_aravis2 camera_finder

Alternatively, you can use aravis-tools: 

sudo apt install aravis-tools
arv-tool-0.8

Extracting Camera-specific GenICam XML

Each camera model has a specific XML data stored inside the device memory which describes the GenICam interface of the camera. In this XML data the supported features of the camera are documented and can help to configure the camera. To extract this XML data and write it into a file, camera_aravis2 provides the node camera_xml_exporter which can be invoked as shown below:

ros2 run camera_aravis2 camera_xml_exporter --ros-args -p guid:=<camera_guid> -p xml_file:=<output_file>

If guid is omitted, the XML data will be read from any of the cameras which are connected and found by camera_aravis2. As a xml_file, either a relative or absolute path can be provided in which the XML data is to be saved. If omitted, the data is saved into a file in the current working directory with the 'guid' as filename.

Example launch file: camera_aravis2/launch/camera_xml_exporter_example.launch.py.

Alternatively, you can use aravis-tools to see the feature list and the XML file: 

sudo apt install aravis-tools
arv-tool-0.8 --name=<camera_guid> features
arv-tool-0.8 --name=<camera_guid> genicam

Building from Source

Requirements

camera_aravis2:

camera_aravis2_msgs:

Build

Install aravis:

sudo apt install libaravis-dev

Initialize rosdep and install dependencies:

sudo rosdep init
rosdep update
rosdep install --from-paths src -y --ignore-src

Run colcon to build from source:

colcon build --symlink-install --packages-up-to camera_aravis2

To build in 'Debug' mode add --cmake-args -DCMAKE_BUILD_TYPE=Debug to colcon command. If omitted, camera_aravis2 will be build in 'Release' mode.

Test

To run tests after build, additionally call:

colcon test --event-handlers=console_direct+
colcon test-result --all

FAQ

How to use PTP

GigEVision Cameras Only

Some GigEVision cameras support the use of the Precision Time Protocol (PTP) to set the timestamps of the captured images. To activate and use it just set the launch parameter 'TransportLayerControl.PtpEnable' to 'True' as seen blow:

    ...
    parameters=[{
                    ...
                    "TransportLayerControl": {
                        "PtpEnable": True
                    }
                    ...
                }]
    ...

How to set specific analog control values (e.g. balance ratios)

Typically GenICam cameras support three different modes for automatic control of analog settings (e.g. gain, black level, white balance), namely 'Continuous', 'Once', and 'Off'. These can be set via the launch parameter and corresponding feature names, i.e. 'GainAuto', 'BlackLevelAuto', 'BalanceWhiteAuto'. As the names suggest, the first mode will continuously adjust the white balance, while the second mode will measure the white balance once and then freeze the ratio parameters. In case, of the third mode, the ratios of the different color channels can and need to be set manually.

Use the launch parameters of camera_aravis2 to manually set the ratio parameters and configure the analog control, by

In this, the key will be set as value to the corresponding selector (e.g. 'GainSelector', 'BalanceRatioSelector') and the value will be set to the feature.

For example:

    ...
    parameters=[{
                    ...
                    "AnalogControl": {
                        "GainAuto": "Continuous",
                        "BalanceWhiteAuto": "Off",
                        "BalanceRatio": {
                            "Red": 1.6,
                            "Blue": 2.0
                        }
                    }
                    ...
                }]
    ...

How to manually trigger calculation of white balance ratios

To trigger an automatic white balance computation and a subsequent setting of BalanceWhiteAuto to Once, camera_aravis2 provides a service called calculate_white_balance_once. Calling this service will trigger a one shot computation of the white balance parameters and return the newly computed balance ratios. This can be called no matter which mode has been set previously.

How to dynamically change camera parameters

Camera_aravis allows to customize the camera parameters that are to be made dynamically changeable, for example, by utilizing rqt_reconfigure. The parameters that are to be changed dynamically can be specified within a yaml file which, in turn, is to be passed to camera_aravis through the launch parameter:

This file should hold a list of FeatureName, representing the camera parameter that is to be changed, together with a corresponding Type (bool, float, int, or string). In addition to the feature name and the type an optional Description can be specified. Furthermore, for integer and floating point parameters a lower and upper bound can optionally be specified through the fields Min and Max.

For example, the following snippet will declare the parameter 'AcquisitionFrameRate' as dynamically changeable and set the possible value range to [0.1, 50.0]:

    ...
    - FeatureName: AcquisitionFrameRate
      Type: float
      Min: 0.1
      Max: 50.0
      Description: Controls the acquisition rate (in Hertz) at which the frames are captured.
    ...

During the declaration of floating point or integer parameters, camera_aravis will additionally try to extract the lower and upper bounds of the feature from the device and compare it to the possibly declared bounds by the user. In this, camera_aravis will set the intersection of both ranges as the range for the corresponding parameter.

An example of this yaml file is given in dynamic_parameters_example.yaml.

How to publish camera diagnostics / status

Camera_aravis allows to periodically monitor custom camera features and publish them in a designated topic named ~/diagnostics in a message type as specified in CameraDiagnostics.msg. In order to configure and customize this status monitoring, two launch parameters are provided:

An example of such a diagnostic yaml file is given in camera_diagnostics_example.yaml. This file should hold a list of FeatureName together with a corresponding Type (bool, float, int, or string) for each feature which is to be monitored. If a feature is associated with a feature selector, one can additionally specify a list of Selectors. Each entry in this list should again have a FeatureName and Type, as well as a Value to set.

For each feature a key-value pair is constructed and published in the data field of the message stated above. If a feature as a list of selectors, one key-value pair is constructed for each Feature-Selector pair.

Known Issues