OrbbecSDK_ROS2/README.MD

OrbbecSDK ROS2 Wrapper v2

English | 中文

Introduction

The OrbbecSDK ROS2 Wrapper provides seamless integration of Orbbec cameras with the ROS 2 ecosystem and supports the ROS2 Foxy, Humble, Jazzy, and Lyrical distributions, with experimental support for Rolling.

• Default branch: v2-main
• For legacy OpenNI devices: use the main branch
• For users in China: use the Gitee repository

branch selection

Here is the device support list of main branch (v1.x) and v2-main branch (v2.x):

Product Series	Product	Branch main	Branch v2-main
Gemini 430	Gemini 435Le	not supported	recommended for new designs
Gemini 301	Gemini 305	not supported	recommended for new designs
	Gemini 305g	not supported	recommended for new designs
Gemini 330	Gemini 335	full maintenance	recommended for new designs
	Gemini 336	full maintenance	recommended for new designs
	Gemini 330	full maintenance	recommended for new designs
	Gemini 335L	full maintenance	recommended for new designs
	Gemini 336L	full maintenance	recommended for new designs
	Gemini 330L	full maintenance	recommended for new designs
	Gemini 335Lg	not supported	recommended for new designs
	Gemini 335Le	not supported	recommended for new designs
Gemini 340	Gemini 345Lg	not supported	recommended for new designs
Gemini 2	Gemini 2	full maintenance	recommended for new designs
	Gemini 2 L	full maintenance	recommended for new designs
	Gemini 2 XL	recommended for new designs	not supported
	Gemini 215	not supported	recommended for new designs
	Gemini 210	not supported	recommended for new designs
Femto	Femto Bolt	full maintenance	recommended for new designs
	Femto Mega	full maintenance	recommended for new designs
	Femto Mega I	full maintenance	recommended for new designs
Astra	Astra 2	full maintenance	recommended for new designs
	Astra+	limited maintenance	not supported
	Astra Pro Plus	limited maintenance	not supported
Astra Mini	Astra Mini Pro	full maintenance	recommended for new designs
	Astra Mini S Pro	full maintenance	recommended for new designs
LiDAR	Pulsar ME450	not supported	recommended for new designs
	Pulsar SL450	not supported	recommended for new designs

Note: LiDAR devices are supported in v2.6.3 and later versions. For usage details, please refer to the LiDAR documentation. If you do not find your device, please contact our FAE or sales representative for help.

Definition:

1. Recommended for new designs: we will provide full supports with new features, bug fix and performance optimization;
2. Full maintenance: we will provide bug fix support;
3. Limited maintenance: we will provide critical bug fix support;
4. Not supported: we will not support specific device in this version;
5. To be supported: we will add support in the near future.

Migration Guide

If you need to migrate existing projects from the main (v1.x) branch to the v2-main (v2.x) branch, please refer to the official migration guide

Installation Instructions

Environment configuration

Install one of the supported ROS 2 distributions according to its official guide:

• Foxy
• Humble
• Jazzy

Source the ROS 2 environment before running the commands below:

source /opt/ros/humble/setup.bash  # Replace humble with foxy or jazzy as needed

Install dependencies:

sudo apt install libgflags-dev nlohmann-json3-dev \
ros-$ROS_DISTRO-image-transport ros-${ROS_DISTRO}-image-transport-plugins ros-${ROS_DISTRO}-compressed-image-transport \
ros-$ROS_DISTRO-image-publisher ros-$ROS_DISTRO-camera-info-manager \
ros-$ROS_DISTRO-diagnostic-updater ros-$ROS_DISTRO-diagnostic-msgs ros-$ROS_DISTRO-statistics-msgs ros-$ROS_DISTRO-xacro \
ros-$ROS_DISTRO-backward-ros libdw-dev libssl-dev mesa-utils libgl1 libgoogle-glog-dev

Enable ROS 2 auto-completion:

eval "$(register-python-argcomplete3 ros2)"
eval "$(register-python-argcomplete3 colcon)"

Linux Binary Package Installation

Check available packages:

sudo apt update
apt list | grep orbbec

If binary packages are available for your ROS 2 distribution, install the OrbbecSDK ROS2 packages with:

sudo apt install ros-${ROS_DISTRO}-orbbec-camera ros-${ROS_DISTRO}-orbbec-description

After installation, you can use it directly without compilation.

Build from Source

Create a colcon workspace:

mkdir -p ~/ros2_ws/src

Clone source and checkout v2-main branch:

cd ~/ros2_ws/src
git clone https://github.com/orbbec/OrbbecSDK_ROS2.git
cd OrbbecSDK_ROS2
git checkout v2-main

Build:

cd ~/ros2_ws
colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release

Registration Script (Required)

To allow the Orbbec cameras to be recognized correctly on Linux, install the udev rules.

Binary Installation

sudo cp /opt/ros/$ROS_DISTRO/share/orbbec_camera/udev/99-obsensor-libusb.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger

Build from Source

cd  ~/ros2_ws/src/OrbbecSDK_ROS2/orbbec_camera/scripts
sudo bash install_udev_rules.sh

This step is mandatory for Linux users.

Note: Without the udev rules, the device may fail to open because of insufficient permissions. Install the rules and reconnect the camera instead of running ROS 2 nodes with sudo.

Getting start

Launch camera node

• On terminal 1

source ~/ros2_ws/install/setup.bash
ros2 run orbbec_camera list_devices_node # Check if the camera is connected
ros2 launch orbbec_camera gemini_330_series.launch.py # Or other launch file, see below table
# Optional: publish OrbbecViewer-style colorized depth on /camera/depth/image_raw
ros2 launch orbbec_camera gemini_330_series.launch.py depth_colorizer_mode:=jet

• On terminal 2

source ~/ros2_ws/install/setup.bash
rviz2

Select the topic you want to display

• List topics / services/ parameters ( On terminal 3)

ros2 topic list
ros2 service list
ros2 param list

• Echo a topic

ros2 topic echo /camera/depth/camera_info

• Call a service

ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString '{}'

For more usage details, please refer to the official OrbbecSDK ROS2 documentation

depth_colorizer_mode is a string render mode:

• none: disable colorization and publish the raw 16UC1 depth image;
• jet: use the OrbbecViewer-style dynamic histogram, gamma, and Jet mapping;
• jet_inv: use the OrbbecViewer-style inverse Jet mapping;
• gray: use the OrbbecViewer-style grayscale mapping;

The jet and jet_inv modes publish rgb8; gray publishes mono8 on depth/image_raw.

Supported Devices

Currently, the following devices are supported by the OrbbecSDK ROS2 Wrapper v2-main branch. More devices support will be added in the near future. If you can not find your device in the table below, try the main branch.

For optimal performance, we strongly recommend updating to the latest firmware version. This ensures that you benefit from the most recent enhancements and bug fixes.

Product Series	Products List	Recommended FW Version	Launch File
Gemini 430	Gemini 435Le	1.3.19	gemini435_le.launch.py
Gemini 301	Gemini 305	1.0.70	gemini_301_series.launch.py
	Gemini 305g	1.0.70	gemini_301_series.launch.py
Gemini 330	Gemini 335	1.8.10	gemini_330_series.launch.py
	Gemini 336	1.8.10	gemini_330_series.launch.py
	Gemini 330	1.8.10	gemini_330_series.launch.py
	Gemini 335L	1.8.10	gemini_330_series.launch.py
	Gemini 336L	1.8.10	gemini_330_series.launch.py
	Gemini 330L	1.8.10	gemini_330_series.launch.py
	Gemini 335Lg	1.8.10	gemini_330_series.launch.py
	Gemini 335Le	1.8.10	gemini_330_series.launch.py
Gemini 340	Gemini 345Lg	1.9.03	gemini345_lg.launch.py
Gemini 2	Gemini 2	1.4.98	gemini2.launch.py
	Gemini 2 L	1.5.2	gemini2L.launch.py
	Gemini 215	1.0.9	gemini210.launch.py
	Gemini 210	1.0.9	gemini210.launch.py
Femto	Femto Bolt	1.1.3	femto_bolt.launch.py
	Femto Mega	1.3.1	femto_mega.launch.py
	Femto Mega I	2.0.4	femto_mega.launch.py
Astra	Astra 2	2.8.20	astra2.launch.py
Astra Mini	Astra Mini Pro	2.0.03	astra.launch.py
	Astra Mini S Pro	2.0.03	astra.launch.py
LiDAR	Pulsar ME450	1.0.0.6	lidar.launch.py
	Pulsar SL450	2.2.4.5	lidar.launch.py

All launch files are essentially similar, with the primary difference being the default values of the parameters set for different models within the same series. Differences in USB standards, such as USB 2.0 versus USB 3.0, may require adjustments to these parameters. If you encounter a startup failure, please carefully review the specification manual. Pay special attention to the resolution settings in the launch file, as well as other parameters, to ensure compatibility and optimal performance.

Tutorial

please refer to the official OrbbecSDK ROS2 documentation

Examples

To explore practical examples and gain insight into how to use the camera in ROS, please navigate to the Examples section for more information.

Other useful links

• OrbbecSDK ROS2 documentation
• OrbbecSDK_v2
• Gemini 330 depth presets

License

Copyright 2024 Orbbec Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an " AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Other names and brands may be claimed as the property of others