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.

camera_aravis for ROS 1 can be found here: https://github.com/FraunhoferIOSB/camera_aravis

Continuous Integration:

Service	devel	main
GitHub

Contents:

• Running the Camera Driver
  • Configuration
  • Example Launch Files
• Finding Available Cameras
• Extracting Camera-Specific GenICam XML
• Building from Source
  • Requirements
  • Build
  • Test
• FAQ
  • How to use PTP
  • How to set specific analog control values (e.g. balance ratios)
  • How to manually trigger calculation of white balance ratios
  • How to dynamically change camera parameters
  • How to publish camera diagnostics / status
  • How to access GigEVision camera using the IP address
• Known Issues
• Contributing

Running the Camera Driver

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

• camera_driver_gv for GigEVision cameras, and
• camera_driver_uv, for USB3Vision cameras.

Configuration

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

Driver-specific Parameters

• guid: Serial number or IP address (GigEVision Cameras only) of the camera that is to be opened. GUIDs and IP addresses of available cameras can be discovered with camera_finder node.
  • Type: String
  • Default: “”
  • Optional. If omitted a random camera is picked from the list of connected cameras and will be opened.
• stream_names: String list of names that are to be associated with each stream. If multiple streams are available, these names will be appended to the topic names in order to distinguish the different image streams.
  • Type: String-Array
  • Default: {}
  • Optional. If omitted or less names are given than streams available, each stream will get given a name based on its ID, starting with 0.
• camera_info_urls: String list of urls to camera_info files associated with each stream. List should have the same length as the number of streams provided by the camera. If the number of URLs does not correspond to number of streams available, the minimum of both is used to set the number of streams that are to be established.
  • Type: String-Array
  • Default: {}
  • Optional. If omitted, it is constructed from the camera GUID located within the current working directory, with the stream name separated by ‘_’ appended to the file name, if more than one streams are instantiated.
• frame_id: Frame ID that is to be associated with the sensor and, in turn, with the image data. If multiple streams are supported by the camera, the given ID serves as a base string to which the stream name is appended, together with ‘_’ as separator.
  • Type: String
  • Default: “”
  • Optional. If no frame ID is specified, the name of the node will be used.
• dynamic_parameters_yaml_url : URL to yaml file specifying camera parameters that are to be made dynamically changeable. See ‘How to dynamically change camera parameters’ for more info.
  • Type: String
  • Default: “”
  • Optional. If left empty no dynamic parameters, apart from the camera_aravis-specific parameters will be available
• diagnostic_yaml_url : URL to yaml file specifying the camera features which are to be monitored. See ‘How to publish camera diagnostics / status’ for more info.
  • Type: String
  • Default: “”
  • Optional. If left empty no diagnostic features will be read and published.
• diagnostic_publish_rate : Rate (in Hz) at which to read and publish the diagnostic data.
  • Type: double
  • Default: 0.1 (every 10 seconds)

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:

• DeviceControl (List): GenICam parameters of the ‘DeviceControl’ category that are to be set. Here, no specific order is implemented. Nested parameter list is evaluated in alphabetical order.
• TransportLayerControl
  • BEGIN (List): Additional GenICam parameters that are not be set at the beginning of the ‘TransportLayerControl’ section. Nested parameter list is evaluated in alphabetical order.
  • GevSCPSPacketSize (Int) - GigEVision Cameras only : Specifies the packet size, in bytes, which are to be send. This should correspond ‘DeviceStreamChannelPacketSize’ and the maximum transport unit (MTU) of the interface.
  • GevSCPD (Int) - GigEVision Cameras only : Controls the delay (in GEV timestamp counter unit) to insert between

File truncated at 100 lines see the full file

CONTRIBUTING

We are using the Feature Branch Workflow, and prefer contributions as merge requests.

There’s only one rule: anything in the master branch is always deployable.

Create a feature branch:

git checkout -B feat/<feature_name>

Recommended workflow

1. Fork the repository if your are not a collaborator and have direct access to the repository
2. Checkout new branch (branching of devel)
3. Make changes
4. Run tests
5. Commit those changes
6. Push
7. Create a pull request (targeting devel)

Branching Recommendations

• Try to keep two main branches main and devel .

• The devel -branch should be the default branch in which all developments are done and from which new branches are created.

• Each new release with a version tag should be merged into main . Intermediate merges can be made if there is a feature which is to be made available in the default branch prior to an official release.

Commit Conventions

We aim at concise and yet descriptive commit messages. In this, we suggest the following:

Each top line of a commit should be made up of a type and a subject

<type>: <subject>

Allowed types:

• feat: A new feature
• enhance: An enhancement to the current feature set
• fix: A bug fix
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, newline, line endings, etc)
• refactor: A code change that neither fixes a bug or adds a feature
• perf: A code change that improves performance
• test: Adding missing tests
• chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
• release: Committing changes, e.g. to CHANGELOG.rst, for a new release

You can add additional details after a new line to describe the change in detail or automatically close a issue on Github.

Example:

docs: create initial CONTRIBUTING

This closes #73

Versioning Conventions

This repo adheres to semantic versioning: http://semver.org/. Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes,
• MINOR version when you add functionality in a backwards-compatible manner, and
• PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format