Orbbec ROS SDK is a wrapper for Orbbec SDK that supports ROS Kinetic, Melodic, and Noetic distributions. It enables smooth integration of Orbbec 3D cameras into ROS projects.
- Orbbec ROS SDK
- Table of Contents
- Install Dependencies
- Create ROS Workspace and Build
- Start the Camera
- Select Topics and Control the Camera
- Launch Parameters
- Depth work mode switch:
- Configuration of depth NFOV and WFOV modes
- Check which profiles the camera supports
- Available Services for Camera Control
- Available Topics
- Building a Debian Package
- Launch files
- Use Nodelet
- Supported hardware products
- Frequently Asked Questions
- Other useful links
- License
- Please refer directly to the ROS wiki for installation instructions.
-
Install dependencies (be careful with your ROS distribution):
# Assuming you have sourced the ROS environment, same below sudo apt install libgflags-dev ros-$ROS_DISTRO-image-geometry ros-$ROS_DISTRO-camera-info-manager \ ros-$ROS_DISTRO-image-transport ros-$ROS_DISTRO-image-publisher libgoogle-glog-dev libusb-1.0-0-dev libeigen3-dev \ ros-$ROS_DISTRO-diagnostic-updater ros-$ROS_DISTRO-diagnostic-msgs
Create a ROS workspace (if you don't have one):
mkdir -p ~/ros_ws/srcGet the source code:
cd ~/ros_ws/src
git clone https://github.com/orbbec/OrbbecSDK_ROS1.gitBuild the package:
cd ~/ros_ws
catkin_makeInstall udev rules:
cd ~/ros_ws
source ./devel/setup.bash
roscd orbbec_camera
cd scripts
sudo cp 99-obsensor-libusb.rules /etc/udev/rules.d/99-obsensor-libusb.rules
sudo udevadm control --reload && sudo udevadm triggerIn terminal 1:
source ./devel/setup.bash
roslaunch orbbec_camera gemini_330_series.launchIn terminal 2:
source ./devel/setup.bash
rvizCheck topics, services, and parameters (open a new terminal):
rostopic list
rosservice list
rosparam listGet camera parameters (MUST start stream first):
rosservice call /camera/get_camera_params "{}"Check camera parameters (please refer to the ROS documentation for the meaning of specific fields in the camera info):
rostopic echo /camera/depth/camera_info
rostopic echo /camera/color/camera_infoCheck device information:
rosservice call /camera/get_device_info "{}"Get the SDK version (includes firmware and Orbbec SDK versions):
rosservice call /camera/get_sdk_version "{}"Set/get (auto) exposure:
rosservice call /camera/set_color_auto_exposure '{data: false}'
rosservice call /camera/set_left_ir_auto_exposure "{data: false}"
# Setting exposure values (be careful with the data range; the following example may not be correct)
rosservice call /camera/set_left_ir_exposure "{data: 2000}"
rosservice call /camera/set_color_exposure "{data: 2000}"
# Get exposure
rosservice call /camera/get_left_ir_exposure "{}"
rosservice call /camera/get_color_exposure "{}"Set/get gain:
# Get gain
rosservice call /camera/get_color_gain '{}'
rosservice call /camera/get_left_ir_gain '{}'
# Setting the gain (be careful with the data range; the following example may not be correct)
rosservice call /camera/set_color_gain "{data: 200}"
rosservice call /camera/set_left_ir_gain "{data: 200}"Set/get (auto) white balance:
rosservice call /camera/set_auto_white_balance "{data: false}"
rosservice call /camera/get_auto_white_balance "{data: false}"Turn on/off laser:
rosservice call /camera/set_laser '{data: true}' # Turn on
rosservice call /camera/set_laser '{data: false}' # Turn offSave images:
rosservice call /camera/save_images "{}"Save point cloud:
rosservice call /camera/save_point_cloud "{}"NOTE: The images are saved under ~/.ros/image and are only available when the sensor is on.
The following launch parameters are available:
connection_delay: The delay time in milliseconds for reopening the device. Some devices require a longer time to initialize, and reopening the device immediately can cause firmware crashes when hot-plugging.enable_point_cloud: Enables the point cloud.enable_colored_point_cloud: Enables the RGB point cloud.color_width,color_height,color_fps: The resolution and frame rate of the color stream.left_ir_width,left_ir_height,left_ir_fps: The resolution and frame rate of the left IR stream.right_ir_width,right_ir_height,right_ir_fps: The resolution and frame rate of the right IR stream.depth_width,depth_height,depth_fps: The resolution and frame rate of the depth stream.enable_color: Enables the RGB camera.enable_depth: Enables the depth camera.enable_left_ir: Enables the left IR camera.enable_right_ir: Enables the right IR camera.depth_registration: Enables hardware alignment of the depth frame to the color frame. This field is required whenenable_colored_point_cloudis set totrue.log_levelfor OrbbecSDK controls console log verbosity, with levelsnone,info,debug,warn,fatal. Logs save in~/.ros/Log. For file logging, adjust<FileLogLevel>inconfig/OrbbecSDKConfig_v1.0.xml.ordered_pc: Whether the point cloud should be organized in an ordered grid (true) or as an unordered set of points (false).device_preset: The default value isDefault. Only the G330 series is supported. For more information, refer to the G330 documentation. Please refer to the table below to set thedevice_presetvalue based on your use case. The value should be one of the preset names listed in the table.enable_decimation_filter: Only the G330 series is supported. This filter effectively reduces the depth scene complexity. The filter runs on kernel sizes [2x2] to [8x8] pixels. The image size is scaled down proportionally in both dimensions to preserve the aspect ratio.enable_hdr_merge: This filter is used jointly with depth HDR function. By merging consecutive depth images of alternating exposure values, we can over come challenges in acquiring depth values for under-illuminated and over-illuminated objects simultaneously.sequence_id_filter_id: This filter is used jointly with depth HDR function and outputs only the sequence with specified sequence ID.enable_threshold_filter: This filter preserves depth values of interest and omits depth values out of scope.enable_noise_removal_filter: This filter removes speckle noise in clusters and gives rise to a less-filled depth map.enable_spatial_filter: This filter performs multiple iterations of processing as specified by the magnitude parameter, to enhance the smoothness of depth data. It is also capable of filling small holes in depth maps.enable_temporal_filter:This filter is intended to improve the depth data persistency by manipulating per-pixel values based on previous frames. The filter performs a single pass on the data, adjusting the depth values while also updating the tracking history.enable_hole_filling_filter: This filter fills all holes in the depth map using the specified mode.depth_precision: The depth precision, should be like1mmformat. The default value is1mm.enable_laser: Whether to enable the laser. The default value istrue.laser_on_off_mode: Laser on/off alternate mode, 0: off, 1: on-off alternate, 2: off-on alternate. The default value is0.retry_on_usb3_detection_failure: If the camera is connected to a USB 2.0 port and is not detected, the system will attempt to reset the camera up to three times. This setting aims to prevent USB 3.0 devices from being incorrectly recognized as USB 2.0. It is recommended to set this parameter tofalsewhen using a USB 2.0 connection to avoid unnecessary resets.
IMPORTANT: Please carefully read the instructions regarding software filtering settings at this link. If you are uncertain, do not modify these settings.
- Before starting the camera, depth work mode (depth_work_mode) can be configured for the corresponding xxx.launch file's support.
- The depth work mode switch is supported by Gemini 2, Gemini 2 L, and Gemini 2 XL cameras.
- The default depth work mode configuration of xxx.launch is the camera's default configuration. If you need to modify it, you can switch to the corresponding mode as needed.
- The specific camera depth work mode support types can be found in the comments of the depth mode.
<!-- Depth work mode support is as follows： -->
<!-- Unbinned Dense Default -->
<!-- Unbinned Sparse Default -->
<!-- Binned Sparse Default -->
<!-- Obstacle Avoidance -->
<arg name="depth_work_mode" default=""/>- View depth work modes:
rosrun orbbec_camera list_depth_work_mode_nodeFor the Femto Mega and Femto Bolt devices, the NFOV and WFOV modes are implemented by configuring the resolution of Depth and IR in the launch file. In launch file, depth_width、depth_height、ir_width、ir_height represents the resolution of the depth and the resolution of the IR. The frame fps and resolution of IR must be consistent with the depth. The correspondence between different modes and resolutions is as follows:
- NFOV unbinned: 640 x 576.
- NFOV binned: 320 x 288.
- WFOV unbinned: 1024 x 1024.
- WFOV binned: 512 x 512.
rosrun orbbec_camera list_camera_profile_mode_nodeThe service names intuitively reflect their purposes. It's crucial to understand that services related to setting or
getting parameters—denoted as set_* and get_*—become available only when the respective enable_* parameters are
activated. For instance, enabling features such as left infrared (IR) with enable_left_ir, right IR
with enable_right_ir, depth sensing with enable_depth, or color processing with enable_color (refer
to Launch Parameters) is a prerequisite for their corresponding services to be operational. This
configuration ensures that services are accessible only when their specific stream is enabled in the
launch file's stream argument.
/camera/get_auto_white_balance/camera/get_camera_params/camera/get_color_auto_exposure/camera/get_color_camera_info/camera/get_color_exposure/camera/get_color_gain/camera/get_depth_auto_exposure/camera/get_depth_camera_info/camera/get_depth_exposure/camera/get_depth_gain/camera/get_device_info/camera/get_device_type/camera/get_left_ir_auto_exposure/camera/get_left_ir_camera_info/camera/get_left_ir_exposure/camera/get_left_ir_gain/camera/get_serial/camera/get_sdk_version/camera/get_white_balance/camera/reset_color_exposure/camera/reset_color_gain/camera/reset_depth_exposure/camera/reset_depth_gain/camera/reset_left_ir_exposure/camera/reset_left_ir_gain/camera/reset_white_balance/camera/save_images/camera/save_point_cloud/camera/set_auto_white_balance/camera/set_color_auto_exposure/camera/set_color_exposure/camera/set_color_gain/camera/set_depth_auto_exposure/camera/set_depth_exposure/camera/set_depth_gain/camera/set_flood/camera/set_left_ir_auto_exposure/camera/set_left_ir_exposure/camera/set_left_ir_gain/camera/set_laser/camera/set_white_balance
/camera/color/camera_info: The color camera info./camera/color/image_raw: The color stream image./camera/depth/camera_info: The depth camera info./camera/depth/image_raw: The depth stream image./camera/depth/points: The point cloud, only available whenenable_point_cloudistrue./camera/depth_registered/points: The colored point cloud, only available whenenable_colored_point_cloudistrue./camera/left_ir/camera_info: The left IR camera info./camera/left_ir/image_raw: The left IR stream image./camera/right_ir/camera_info: The right IR camera info./camera/right_ir/image_raw: The right IR stream image./diagnostics: The diagnostic information of the camera, Currently, the diagnostic information only includes the temperature of the camera.
First, ensure the necessary tools are installed:
sudo apt install debhelper fakeroot python3-bloomTo create the Debian package, execute these commands:
cd ~/ros_ws/src/OrbbecSDK_ROS1
bash .make_deb.sh| product serials | launch file |
|---|---|
| astra+ | astra_adv.launch |
| astra mini/astra mini pro/astra pro | astra.launch |
| astra mini s pro | astra.launch |
| astra2 | astra2.launch |
| astra stereo s | stereo_s_u3.launch |
| astra pro2 | astra_pro2.launch |
| dabai | dabai.launch |
| dabai d1 | dabai_d1.launch |
| dabai dcw | dabai_dcw.launch |
| dabai dw | dabai_dw.launch |
| dabai pro | dabai_pro.launch |
| deeya | deeya.launch |
| femto / femto w | femto.launch |
| femto mega | femto_mega.launch |
| femto bolt | femto_bolt.launch |
| gemini | gemini.launch |
| gemini2 / dabai DCL | gemini2.launch |
| gemini2L | gemini2L.launch |
| gemini e | gemini_e.launch |
| gemini e lite | gemini_e_lite.launch |
| dabai max | dabai_max.launch |
| dabai max pro | dabai_max_pro.launch |
| gemini uw | gemini_uw.launch |
| dabai dcw2 | dabai_dcw2.launch |
| dabai dw2 | dabai_dw2.launch |
| gemini ew | gemini_ew.launch |
| gemini ew lite | gemini_ew_lite.launch |
| gemini 330 series | gemini_330_series.launch |
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.
For users who need to use nodelet, please refer to gemini2_nodelet.launch
Please refer to the OrbbecSDK supported products: Product Support
-
It's possible that the power supply is insufficient. To avoid this, do not connect all cameras to the same hub and use a powered hub instead.
-
It's also possible that the resolution is too high. To resolve this, try lowering the resolution.
-
The current device does not have permission to access the device. Check the PID of the current device:
lsusb | grep 2bc5Your output should look like this:
Bus 002 Device 007: ID 2bc5:your_pid_hereEdit
/etc/udev/rules.d/99-obsensor-libusb.rulesand add the following line:SUBSYSTEM=="usb", ATTR{idProduct}=="your_pid_here", ATTR{idVendor}=="2bc5", MODE:="0666", OWNER:="root", GROUP:="video", SYMLINK+="your_device_name_here"
Replace
your_pid_herewith the PID of your device andyour_device_name_herewith the name you want to create for the device (e.g.,gemini_camera).Then restart the udev service:
sudo udevadm control --reload-rules && sudo service udev restart && sudo udevadm trigger
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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent