pylon-ros-camera

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.
• (blaze cameras only) 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. If this package is not installed, blaze support is automatically disabled at build time and all other camera types (GigE, USB, DART) remain fully functional.
• 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 Known 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 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 resources) for faster iteration (refer to the ROS2 documentation).

Note: The packages are built in Release by default. The build type can be modified 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.

Docker

Ready-to-use Docker images are available for Humble, Jazzy, and Kilted.
They bundle the driver and all its dependencies into a self-contained container, so no local ROS 2 installation is required.

For build instructions, run options, and troubleshooting, refer to the docker/README.md.

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

From version 3.1.0, the driver allows free run as well as sequentially triggered acquisition by software trigger.

When starting the driver, the maximum acquisition frame rate that can be reached according to the current camera settings is displayed (for further information, please refer to the Basler documentation). If this frame rate is lower than the one specified in the driver configuration file, the latter is updated accordingly. Except for the blaze, it is not possible to change the acquisition frame rate when the driver is running.

Free run acquisition is set when the driver starts and loads the Default user set. Otherwise, if another user set is loaded, including CurrentSetting, the driver does not modify any parameter related to the acquisition, keeping the ones defined by the user. Setting a specific user set can be specified in the driver launch file. By default, the driver load the CurrentSetting user set.

• Free run is enabled by setting the following parameters:

AcquisitionMode = Continuous
TriggerSelector = FrameStart
TriggerMode = Off

• Software triggering is enabled by setting the following parameters:

TriggerSelector = FrameStart
TriggerSource = Software
TriggerMode = On

More information about acquisition modes can be found here. The driver does not currently give access to the AcquisitionMode parameter and if the TriggerSource parameter is not modified, switching from free run to software triggering can be done by setting the TriggerMode parameter from Off to On, and vice versa.

Generally speaking, to increase the acquisition frame rate when using the driver, consider when possible and applicable:

• Switch to free run.
• Changing the image encoding to Bayer or Mono ones.
• Setting a region of interest.
• Decreasing the exposure time.
• Decreasing the inter-packet delay and setting it to 0 if possible.
• Setting the enable_current_params_publisher parameter to false (it is set to false by default).
• Following the additional suggestions specified in the Basler documentation.
• Commenting and modifying the different 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. Beware though that the frame rate increase will not be significant and that the standard driver behaviors will not be guaranteed.

The interested readers can refer to the following discussions for more information: #21, #28, #29, #81, #116, #147, #200.

Image pixel encoding (not for the blaze)

The pylon ROS2 driver support currently the following ROS2 image pixel formats :

* mono8	        (Basler Format : Mono8)
* mono16	(Basler Format : Mono16, Mono12)        (Notes 1&2)
* bgr8 		(Basler Format : BGR8)
* rgb8 		(Basler Format : RGB8)
* bayer_bggr8 	(Basler Format : BayerBG8)
* bayer_gbrg8 	(Basler Format : BayerGB8)
* bayer_rggb8 	(Basler Format : BayerRG8)
* bayer_grbg8 	(Basler Format : BayerRG8)
* bayer_rggb16	(Basler Format : BayerRG16, BayerRG12)  (Notes 1&2)
* bayer_bggr16 	(Basler Format : BayerBG16, BayerB