ROS2-Driver for Basler Cameras

The official pylon ROS2 driver for Basler GigE Vision, Basler USB3 Vision and Basler blaze 3D cameras (Jazzy Jalisco)

This driver provides many functionalities available through the Basler pylon Camera Software Suite C++ API.

Please Note: This project is offered with no technical support by Basler AG. You are welcome to post any questions or issues on GitHub

Installation

Prerequisites

• From Ubuntu 24.04 Noble Numbat
• From ROS2 Jazzy Jalisco. Your ROS2 environment must be configured, your workspace created, and colcon, used to build the packages, installed.
• rosdep. rosdep must be installed as a debian package (sudo apt update && sudo apt install python3-rosdep && sudo rosdep init && rosdep update).
• From pylon Camera Software Suite version 7.5.0 or newer. The latest APi libraries must be installed manually. Download and install the latest pylon Camera Software Suite Linux Debian Installer Package for your architecture. You may be experiencing some problems with the codemeter debian package installation. Just drop it for now and install only the pylon debian package in this case.
• From pylon Supplementary Package for blaze version 1.6.0 or newer (compatibility with the installed pylon Camera Software Suite needs to be ensured, please refer to the documentation). The latest APi libraries must be installed manually. Download and install the latest pylon Supplementary Package for blaze Linux Debian Installer Package for your architecture.
• Git. Git must be installed as a debian package (sudo apt update && sudo apt install git).
• xterm. The xterm terminal emulator must be installed (refer to the Know Issues section below) as a debian package (sudo apt update && sudo apt install xterm).

Install and build the packages

This repository including the pylon ROS2 packages must be cloned in your workspace (e.g., dev_ws for instance):

cd ~/dev_ws/src && git clone -b jazzy_beta https://github.com/basler/pylon-ros-camera pylon_ros2_camera

Install the ROS2 dependencies required by the pylon ROS2 packages:
cd ~/dev_ws && rosdep install --from-paths src --ignore-src -r -y
You may experience some problems with the diagnostic_updater and pcl_ros dependencies. In this case, install them by executing the following commands:

sudo apt install ros-jazzy-diagnostic-updater
sudo apt install ros-jazzy-pcl-ros

Compile the workspace using colcon:
cd ~/dev_ws && colcon build

Note: The –symlink-install flag can be added to the colcon build command. This allows the installed files to be changed by changing the files in the source space (e.g., Python files or other not compiled resourced) for faster iteration (refer to the ROS2 documentation).

Note: The packages are built in Release by default. The build type can be modfied by using the --cmake-args flag (for instance colcon build --symlink-install --cmake-args=-DCMAKE_BUILD_TYPE=Debug).

Source the environment:
cd ~/dev_ws && . install/setup.bash

Note: This step can be skipped if the setup.bash file is sourced in your .bashrc.

Start the driver:
ros2 launch pylon_ros2_camera_wrapper pylon_ros2_camera.launch.py or
ros2 launch pylon_ros2_camera_wrapper my_blaze.launch.py to start the acquisition through the blaze.

Usage in a nutshell

Starting the pylon_ros2_camera_node starts the acquisition from a given Basler camera. The nodes allow as well to access many camera parameters and parameters related to the grabbing process itself.

The pylon_ros2_camera_node can be started thanks to a dedicated launch file thanks to the command:
ros2 launch pylon_ros2_camera_wrapper pylon_ros2_camera.launch.py or
ros2 launch pylon_ros2_camera_wrapper my_blaze.launch.py for the blaze
Several parameters can be set through the launch file and the user parameter file loaded through it (the pylon_ros2_camera_wrapper/config/default.yaml user parameter file is loaded by default, pylon_ros2_camera_wrapper/config/my_blaze.yaml for the blaze).

Acquisition from a specific camera is possible by setting the device_user_id parameter. If no specific camera is specified, the first available camera is connected automatically.

The pylon node defines the different interface names according to the following convention:
[Camera name (= my_camera or my_blaze by default)]/[Node name (= pylon_ros2_camera_node)]/[Interface name]
The camera and the node names can be set thanks respectively to the camera_name and node_name parameters.

Acquisition images are published through the [Camera name]/[Node name]/[image_raw] topic, only if a subscriber to this topic has been registered.
To visualize the images, rqt can be used. Add an image viewer plugin through thanks to the contextual menu (Plugin -> Visualization -> Image View) and select the [Camera name]/[Node name]/[image_raw] topic to display the acquired and published images. Beware that if you are using rviz2 to visualize the acquired images, this tool is not able not vizualize correctly images encoded in Bayer.
The 3d point clouds acquired by the blaze can be visualized thanks to rviz2.

For camera models other than the blaze, specific user set can be specified thanks to the startup_user_set parameter.
ros2 launch pylon_ros2_camera_wrapper pylon_ros2_camera.launch.py startup_user_set:=Default or ros2 launch pylon_ros2_camera_wrapper pylon_ros2_camera.launch.py startup_user_set:=UserSet1 or ros2 launch pylon_ros2_camera_wrapper pylon_ros2_camera.launch.py startup_user_set:=UserSet2 or ros2 launch pylon_ros2_camera_wrapper pylon_ros2_camera.launch.py startup_user_set:=UserSet3

Through the driver, the camera image acquisition is sequentially triggered by software trigger. It is not possible in the current implementation to change this acquisition mode. In other words, it is not possible through the driver to configure for free run and hardware triggered image acquisition.

Beware that some parameters implemented by the driver, like for instance the parameter startup_user_set, can be set through 1. the pylon_ros2_camera_wrapper/config/default.yaml user parameter file, 2. the pylon_ros2_camera.launch.py driver launch file, and 3. the command line arguments of the launch command to start the driver. A parameter value set as an argument of the launch command to start the driver will overwrite the value set in the driver launch file itself, that will overwrite the value set in the user parameter file.

Acquisition mode and frame rate

The driver uses software triggering to acquire images. This sequential triggering approach inherently limits the achievable frame rate and makes it impossible to reach the camera’s maximum frame rate achievable with free-run or hardware-triggered acquisition modes. Currently, the driver does not support switching to free-run or hardware-triggered acquisition mode.

At driver startup, the maximum achievable frame rate with the current camera settings and software triggering is calculated and logged (for further information, please refer to the Basler documentation). If this value is lower than the frame rate specified in the launch or configuration file, the configured frame rate will be automatically adjusted to the achievable value. Note that this behavior does not apply to the blaze camera, where frame rate adjustment during runtime may be supported.

To increase the acquisition frame rate when using the driver, consider the following measures when possible and applicable:

• Use a lower-bandwidth image encoding (e.g., Mono8 or BayerRG8)
• Define a smaller region of interest (ROI)
• Reduce the exposure time
• Set the enable_current_params_publisher parameter to false (it is set to false by default)
• Follow performance recommendations in the official Basler documentation.
• For advanced use cases, comment or optimize the operations executed in PylonROS2CameraNode::spin(). In addition to grabbing, it checks if the camera is disconnected, publishes images and current settings if there are some subscribers, rectifies images if calibration parameters are available, etc.). Be aware though that the frame rate increase may not be significant and that these changes may affect driver stability and compatibility.

The interested readers can refer to the following discussions for more information: #21, #28, #29, #81, #116, #147, #200. Feel free to reach out and submit pull requests if you are implementing suitable ways to acquire images in a continuous way or through hardware trigger. We will make sure to review them and integrate them if relevant.

Image pixel encoding (not for the blaze)

File truncated at 100 lines see the full file