camera_aravis

!!! IMPORTANT UPDATE !!!

camera_aravis for ROS 2 is now released as camera_aravis2: https://github.com/FraunhoferIOSB/camera_aravis2

Actively maintained repository for the ROS1 camara_aravis driver. It is open source under the LGPL (like Aravis itself).

The Aravis library 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.

The camera_aravis driver has long history of multiple forks and now abandoned GitHub repositories. This repository is based on https://github.com/florisvb/camera_aravis.git, which in turn was forked from a deleted github repo (https://github.com/CaeruleusAqua/camera_aravis), which was itself forked from https://github.com/ssafarik/camera_aravis.

Tested with Aravis version 0.6.X. Since Ubuntu 20.04 the library can be installed from the official Ubuntu package repository. Install with:

sudo apt install libaravis-dev

The basic command to run camera_aravis:

$ rosrun camera_aravis cam_aravis

To run it in a given namespace:

$ ROS_NAMESPACE=cam1 rosrun camera_aravis cam_aravis

Continuous Integration

Service	Noetic	Master
GitHub
ROS Build Farm		N/A

Configuration

This ROS node publishes messages image_raw and camera_info for a specified camera. It supports a variety of camera features via the ROS reconfigure_gui, including the following:

• ExposureAuto (string: Off, Once, Continuous)
• GainAuto (string: Off, Once, Continuous)
• ExposureTimeAbs (float)
• Gain (float)
• AcquisitionMode (string: Continuous, SingleFrame, MultiFrame)
• AcquisitionFrameRate (float)
• TriggerMode (string: Off, On)
• TriggerSource (string: Any, Software, Line0, Line1, Line2)
• softwaretriggerrate (float)
• frame_id (string)
• FocusPos (integer)
• mtu (integer)

Note that if the camera parameters are to be initialized from the parameters from the dynamic reconfigure server, the launch parameter

``` needs to be set
to 
```true
``` (Default: 
```false
```);

Note that the above are also the ROS parameter names of their respective feature.  You may
set initial values for the camera by setting ROS parameters in the camera's namespace.

In addition to the above features, this driver now supports (almost) every feature of every camera,
you just have to know how the feature is specified; each GenICam-based camera contains
an XML file onboard, and by viewing this file you can determine which ROS parameters to set
for camera_aravis to write to the camera. Details on how to export the camera-specific XML can be found here: [Extracting Camera-Specific GenICam XML](#extracting-camera-specific-genicam-xml). 

Note that for this special feature access, the ROS parameter type must match the feature type.
For example, a Basler ac640 has a boolean feature called "GammaEnable", an integer feature
called "BlackLevelRaw", and a string enum feature called "PixelFormat" that takes values
(Mono8, Mono12, Mono12Packed, YUV422Packed, etc).  The ROS params that you set for these
must be, respectively, a bool, an integer and a string.  Also note that boolean features must
be specified as ROS params false/true, not as integer 0/1.

	$ rosparam set /camera_aravis/GammaEnable false
	$ rosparam set /camera_aravis/BlackLevelRaw 5
	$ rosparam set /camera_aravis/PixelFormat Mono12
	$ rosrun camera_aravis cam_aravis


------------------------
camera_aravis supports multiple cameras, each of which may be specified on the
command-line, or via parameter.  Runs one camera per node.

To specify which camera to open, via the command-line:

	$ rosrun camera_aravis cam_aravis _guid:=Basler-21237813


To specify which camera to open, via a parameter:

	$ rosparam set /camera_aravis/guid Basler-21237813
	$ rosrun camera_aravis cam_aravis


------------------------
It supports the dynamic_reconfigure protocol, and once the node is running, you may adjust
its parameters by running the following and then manipulating the GUI:

	$ rosrun dynamic_reconfigure reconfigure_gui


------------------------
There is an additional nice feature related to timestamps that unifies ROS time with camera time.
We want a stable timestamp on the images that the camera delivers, giving a nice smooth time
delta from frame to frame.  If we were to use the ROS clock on the PC, by the time we get the
image packets from the camera a variable amount of time has passed on the PC's clock due to
variable network and system delays.  The camera's onboard clock is stable but it doesn't match
with the ROS clock on the PC, and furthermore since it comes from a different piece of hardware,
the two clock's rates are slightly different.

The solution is to start with a base of ROS time, and to accumulate the dt's from the camera clock.
To accommodate the difference in clock rates, a PID controller gently pulls the result toward
ROS time.

### Manually Setting White Balance

Typically the cameras support three different modes for auto white balancing, namely 
```Continuous
```,

```Once
```, and 
```Off
```. These can be set via the launch parameter and feature name 
```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 ratio of the different color channels can and need to be
 set manually.

To manually set the white balance, camera_aravis provides a couple of launch parameters:

- 
```wb_ratio_selector_feature
```: Feature name on the camera device to select the color channel for which the ratio is to be set.
	- Type: 
```string

- Default:  ```"" ```

• wb_ratio_selectors : Comma separated list of channel names for which a ratio is to be set. The values of this list are set to the selector given by ‘wb_ratio_selector_feature’ before the actual ratios (‘wb_ratios’) are set. This list should be the same size as the ratio list given in ‘wb_ratios’.
  • Type:

  • Default:

  • Example:

• wb_ratio_feature : Feature name on the camera device to set the ratio for the color channel selected by ‘wb_ratio_selector_feature’.
  • Type:

  • Default:

• wb_ratios : Comma separated list of ratios (float) which are to be set for the channels specified in ‘wb_ratio_selectors’. This list should be the same size as the ratio list given in ‘wb_ratios’.
  • Type:

  • Default:

  • Example:

To trigger an automatic white balance computation and a subsequent setting of

``` to 
```Once
```, camera_aravis provides a service called 
```trigger_one_shot_white_balance
```. 
Calling this service will trigger a one shot computation of the white balance parameters and return the newly computed balance ratio.
This can be called no matter which mode has been set previously.

### Activating PTP Timestamp

Some cameras support the use of the Precision Time Protocol (PTP) to set the timestamps of the 
captured images. To activate it using camera_aravis a couple of launch parameters are available:

- 
```use_ptp_timestamp
```: General switch to activate the use of the PTP timestamp within
camera_aravis. Set to 
```true
``` to activate.
	- Type: 
```bool

- Default:  ```false ``` -  ```ptp_enable_feature_name ```: Feature name on the camera device to enable the use of PTP.
- Type:  ```string ```
- Default:  ```"GevIEEE1588" ``` -  ```ptp_status_feature_name ```: Feature name on the camera device to access the status of the PTP. This is needed to monitor, whether camera_aravis needs to reset the PTP clock.
- Type:  ```string ```
- Default:  ```"GevIEEE1588Status" ``` -  ```ptp_set_cmd_feature_name ```: Feature name of the 'Set-Command' on the camera device for PTP.  On some cameras a 'set' or 'synchronization' command needs to be executed after setting the features above for the PTP to be activated. If this launch parameter is set, the corresponding command will be executed after the parameters above are set.
- Type:  ```string ```
- Default:  ```"" ```

Publishing camera diagnostics / status

Camera_aravis allows to periodically monitor custom camera features and publish them in a designated topic named

``` in a message type as specified in 
[CameraDiagnostics.msg](msg/CameraDiagnostics.msg). In order to configure and customize this 
status monitoring, two launch parameters are provided:

- 
```diagnostic_publish_rate
```: Rate at which to read and publish the diagnostic data.
	- Type: 
```double

- Default:  ```0.1 ``` (10 seconds) -  ```diagnostic_yaml_url ```: URL to yaml file specifying the camera features which are to be  monitored. If left empty (as default) no diagnostic features will be read and published.
- Type:  ```string ```
- Default:  ```"" ```

An example of such a diagnostic yaml file is given in camera_diagnostics.yaml. This file should hold a list of

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

## Ensuring a respawn after failure

<b>Continuously respawning a ROS node:</b>

A node within a launch file can be configured to be automatically respawned in case of failure.
To do so an additional attribute 
```respawn="true"
``` is to be set. 
When running camera_aravis as node this can be directly set for the corresponding node, as shown 
below:


```XML
<node pkg="camera_aravis" type="cam_aravis" name="camera_aravis_node" respawn="true" output="screen">
	...
</node>

Continuously respawning a ROS nodelet:

In case of using camera_aravis as a nodelet withing a nodelet manager, the actual launch file needs to be called from within a simple launch script which, in turn, is called as a respawning node in another launch file. This is exemplarily demonstrated with launch_script.sh and respawning_camera_aravis.launch and shown below:

launch_script.sh

#!/bin/bash

roslaunch "$@"

exit

respawning_camera_aravis.launch

<?xml version="1.0"?>
<launch>
  <node pkg="camera_aravis" type="launch_script.sh" name="respawning_camera_aravis"
        respawn="true" output="screen"
        args="$(find camera_aravis)/launch/camera_aravis.launch"/>
</launch> 

In this, the actual launch file, i.e.

```, is passed as argument to the
respawning launch script in 
```respawning_camera_aravis.launch
```.
Furthermore, in order for the nodelet manager to finish on crash, it is important the attribute 

```required="true"
``` is set to the manager.

**NOTE:** In some cases it is necessary that the shutdown of the node/nodelet is delayed by some
time in order for the camera to be properly disconnected.
The shutdown delay time in secondes can by configured by the parameter 
```shutdown_delay_s
```, 
default: 5 seconds.

## 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_aravis provides the node `export_genicam_xml` which can be invoked as shown below:


```bash
rosrun camera_aravis export_genicam_xml _guid:=<camera_guid> _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_aravis. 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.

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

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

Known Issues

Slow read of white balance and black level values

From PR#22: The white balance and black level values of some cameras (e.g. Basler acA2440-20gc & JAI FS-3200D-10GE ) can be read more efficiently by reading from the exact memory locations of the camera instead of using the Selector features.

However, since we are not sure on how stable these optimizations based on exact memory locations are in terms of firmware updates and how well they generalize to other camera models, we have refrained from merging the pull request into the main repository.

For more information and details on the implementation, please look into the changes and the comments inside the pull request.

Changelog for package camera_aravis

4.1.0 (2024-03-12)

• Feature: Export GenICam XML (#32)
  • Added node export_genicam_xml
• Updated Readme
• Contributors: Boitumelo Ruf

4.0.5 (2024-02-01)

• Added launch parameters allowing to manually set white balance
• Launch configuration, scripts and adjustments to allow raspawning
• Moved execution of set latch command for ptp
• Added parameter init_params_from_dyn_reconfigure and minor bugfix
• Read and publish camera diagnostics
• Improved support for Precision Time Protocol (PTP)
• Minor bugfixes
  • Opened device output
  • Resetting ptp timestamp
• Updated documentation in README.md
• Contributors: Boitumelo Ruf

4.0.4 (2022-12-23)

• Update package maintainer
• Refactor node params (#21)
  • Refactor node params
  • Rename extended_camera_info_ -> pub_ext_camera_info_
  • Move stream parameters to the top of onInit()
• fix: only reset PTP clock when in "Faulty" or "Disabled" state (#23)
• Update industrial_ci default branch to main
• Contributors: Dominik Kleiser, Peter Mortimer, Ruf, Boitumelo

4.0.3 (2022-07-08)

• Refactor image conversion (#20)
• Use plain file names for includes (#17)
• Add verbose flag for feature detection (default = false) (#19)
• Assume num_streams_ = 1 if DeviceStreamChannelCount and GevStreamChannelCount unavailable (#18)
• Add Line0 to Line5 to TriggerSource Enum
• Fix: nodelet namespace
• Fix: onInit deadlock
• Contributors: Dominik Kleiser, Boitumelo Ruf, Thomas Emter, Peter Mortimer, tas, Geoff McIver

4.0.2 (2022-05-04)

• Add optional ExtendedCameraInfo message to publish additional camera acquisition parameters
• Fix: Set reasonable height and width when not given in the CameraInfo
• Contributors: Peter Mortimer

4.0.1 (2022-03-25)

• Add ROS getter/setter services for camera features
• Add support for multistream encoding conversion
• Fix: Pass on the correct encoding for the additional streams of multisource cameras
• Fix: Continuously check the spawning_ flag
• Fix: Check spawning_ flag only once during spawnStream
• Contributors: Peter Mortimer, Thomas Emter, Dominik Kleiser

4.0.0 (2021-10-27)

• Major refactoring
• Add support for ROS Noetic and aravis-0.6
• Fix several bugs (see git history)
• Add new features:
  • Support for multisource cameras
  • Zero-copy transport with ROS nodelets
  • Camera time synchronization
  • Example launch files
• Update package author and maintainer
• Contributors: Dominik Klein, Floris van Breugel, Gaël Écorchard, Thomas Emter, Peter Mortimer, Dominik Kleiser