OrbbecSDK_v2

Open Source Orbbec SDK

• LiDAR devices are supported in OrbbecSDK v2.6.2 and later , For detailed instructions on using the LiDAR, please refer to the LiDAR_README.md.

• LingBot Enhanced Depth Filter uses color and depth information to reduce noise, fill depth holes, and refine object edges. This feature is supported on NVIDIA Jetson running JetPack 6.2. For requirements and usage instructions, see the Enhanced Depth Filter guide.

Here is the device support list of OrbbecSDK v1 (v1.x) and Orbbec SDK v2 (v2.x):

Product Series	Product	Orbbec SDK v1	Orbbec SDK v2
Gemini 305	Gemini 305	not supported	recommended for new designs
Gemini 305g	Gemini 305g	not supported	recommended for new designs
Gemini 340	Gemini 345	not supported	recommended for new designs
	Gemini 345Lg	not supported	recommended for new designs
Gemini 435Le	Gemini 435Le	not supported	recommended for new designs
Gemini 330	Gemini 335Le	not supported	recommended for new designs
	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 338Lg	not supported	recommended for new designs
	Gemini 338Le	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:

1. If you do not find your device, please contact our FAE or sales representative for help.
2. If a device is supported by both Orbbec SDK v1 and Orbbec SDK v2, the minimum supported firmware version may differ between the two SDKs. Please refer to Supported Devices list for detailed information. In particular, note that the Astra Mini Pro and Astra Mini S Pro use different communication protocols in firmware v1.x.x and v2.x.x, Orbbec SDK v1 supports only v1.x.x firmware, while Orbbec SDK v2 supports only v2.x.x firmware. Upgrading from v1.x.x to v2.x.x, please refer to Upgrading from OpenNI Protocol to UVC Protocol.

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.

1. Introduction

This is the open-source library of Orbbec SDK v2.x. The Orbbec SDK is a cross-platform library for interfacing with Orbbec RGB-D cameras, providing C/C++ APIs as well as wrappers for various other languages and frameworks.

1.1 Migration from Orbbec SDK v1 to Open-Source Orbbec SDK v2

To enhance performance and meet the diverse needs of our customers, the Orbbec SDK has been open-sourced since version 2.0.0.

Upgrade Recommendation

For projects currently utilizing version Orbbec SDK v1.x that are considering an upgrade to Orbbec SDK v2.x, we advise using the pre-compiled binaries available in the Release page. This ensures a seamless transition and maintains consistency with your existing setup.

API Compatibility

We have made every effort to maintain backward compatibility with the previous API. However, in pursuit of higher performance and an improved user experience, several updates have been introduced. Some interfaces were modified or removed due to infrequent use or design limitations. These adjustments were made carefully to minimize disruption and do not affect the SDK’s standard functionality.

Migration Resources

• Migration guidance: orbbecsdkv1_to_openorbbecsdkv2.md
• Comprehensive API Changes Overview: api_changes_at_v2.x.x.md

Continued using for Orbbec SDK v1.x

If you wish to continue using Orbbec SDK v1.x, the pre-compiled binaries remain available in our OrbbecSDK v1 repository. Nonetheless, we strongly encourage migration to Orbbec SDK v2.x, which offers enhanced features, better performance, and ongoing support. Our commitment to SDK v2.x reflects Orbbec’s long-term strategy to provide robust support, foster an open-source community, and drive continuous innovation.

1.2 Upgrading from OpenNI Protocol to UVC Protocol

Timeline and Scope

Starting from October 2025 (Orbbec SDK v2.5.5), we will begin upgrading devices that use the OpenNI protocol to the UVC protocol, enabling full compatibility with Orbbec SDK v2.

Already upgraded devices and future upgrade schedule:

Already Upgraded Devices	Future Upgrade Schedule
- Astra Mini S Pro - Astra Mini Pro	- Gemini E, Gemini UW, Gemini EW - DaBai Max, DaBai Max Pro - DaBai DW, DaBai DCW, DaBai DCW2, DaBai DW2

OpenNI-to-UVC Firmware Upgrade Tool

Orbbec provides a dedicated firmware upgrade tool that enables devices to switch from the OpenNI protocol to the UVC protocol. Please select the firmware download link for your device type and follow the corresponding upgrade guide to update the firmware.

Upgrade Instructions

If you are currently using the OpenNI SDK, please refer to the How to Upgrade OpenNI Protocol Devices to UVC Protocol and API Usage Guide for detailed instructions on switching to Orbbec SDK v2 after updating your device firmware. After upgrading to the UVC protocol, these devices will have a firmware major version number of 2 (for example: v2.x.xx).

Important Notes

• Firmware version v2.x.x (major version 2) indicates a UVC protocol device, which requires Orbbec SDK v2.
• Firmware version v1.x.x (major version 1) indicates an OpenNI protocol device, which requires either the OpenNI SDK or Orbbec SDK v1.

1.3 Supported Platforms

• Windows 10 or later: x86 and x64 architectures
• Linux x64: tested on Ubuntu 20.04, 22.04 and 24.04
• Linux ARM64: tested on NVIDIA Jetson AGX Orin , NVIDIA Jetson Orin NX , NVIDIA Jetson Orin Nano , NVIDIA Jetson AGX Xavier , NVIDIA Jetson Xavier NX, NVIDIA Jetson Thor
• Android: tested on Android 13
• macOS: tested on M2 chip, OS version 13.2

1.4 Supported Devices

Products List	Minimal Firmware Version	Recommended Firmware Version
Gemini 305	1.0.30	1.1.20
Gemini 305g	1.0.70	1.1.20
Gemini 345	1.7.04	1.9.03
Gemini 345Lg	1.7.04	1.9.03
Gemini 435Le	1.2.4	1.3.19
Gemini 335Le	1.5.31	1.8.10
Gemini 330	1.2.20	1.8.10
Gemini 330L	1.2.20	1.8.10
Gemini 335	1.2.20	1.8.10
Gemini 335L	1.2.20	1.8.10
Gemini 336	1.2.20	1.8.10
Gemini 336L	1.2.20	1.8.10
Gemini 335Lg	1.3.46	1.8.10
Gemini 338Lg	1.8.17	1.8.17
Gemini 338Le	1.8.17	1.8.17
Femto Bolt	1.1.2	1.1.3
Femto Mega	1.3.0	1.3.1
Femto Mega I	2.0.4	2.0.5
Astra 2	2.8.20	2.8.20
Gemini 2 L	1.4.53	1.5.2
Gemini 2	1.4.92	1.4.98
Gemini 215	1.0.9	1.0.9
Gemini 210	1.0.9	1.0.9
Astra mini Pro	2.0.03	2.0.03
Astra mini S Pro	2.0.03	2.0.03
Pulsar SL450	2.2.4.5	2.2.4.5
Pulsar ME450	1.0.0.6	1.0.0.6

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.

More devices support will be added in the near future. If you can not find your device in the table above currently, try the version v1.x.y at Orbbec SDK v1

2. Documentation

The Orbbec SDK documentation is available on GitHub Pages.

2.1 Environment Setup

windows

For windows, you need to register the metadata associated with frames (this includes things like timestamps and other information about the video frame).

• Metadata registration follow this:/scripts/env_setup/obsensor_metadata_win10.md

Notes: If the metadata is not registered, the device timestamp will be abnormal, thereby affecting the SDK’s internal frame synchronization functionality.

Linux

For Linux, we have provided a script to help you set up the environment. You can run the script as follows:

cd scripts/env_setup
  sudo chmod +x ./install_udev_rules.sh
  sudo ./install_udev_rules.sh
  sudo udevadm control --reload && sudo udevadm trigger

Notes: If this script is not executed, open the device will fail due to permission issues. You need to run the sample with sudo (administrator privileges).

2.2 How to Use install package

If you do not want to compile the Orbbec SDK, you can use the SDK installation package. First download the corresponding installation package for your platform.

1. The file OrbbecSDK_vx.x.x_win64.exe serves as the installation package for the Orbbec SDK and Orbbec Viewer tools on Windows.
2. The file OrbbecSDK_vx.x.x_amd64.deb serves as the installation package for the Orbbec SDK and Orbbec Viewer tools on Linux x86_64, likes ubuntu.
3. The file OrbbecSDK_vx.x.x_arm64.deb serves as the installation package for the Orbbec SDK and Orbbec Viewer tools on ARM64, likes NVIDIA Jetson AGX Orin , NVIDIA Jetson Orin NX , NVIDIA Jetson Orin Nano , NVIDIA Jetson AGX Xavier , NVIDIA Jetson Xavier NX.

Linux Install via .deb Package

• On the Linux x64 (ubuntu) platform, install using the following command. (If you are using the Arm64 platform, please use OrbbecSDK_vx.x.x_arm64.deb)

sudo dpkg -i OrbbecSDK_v2.x.x_amd64.deb

• Check the entire package path of the Orbbec SDK using dpkg -L orbbecsdk, while the header files and library files of the Orbbec SDK will be installed in the /usr/local path.

dpkg -L orbbecsdk

• Run the Orbbec Viewer.

sudo ./OrbbecViewer

Windows Install via .exe Package

On the windows platform, Double-click OrbbecSDK_vx.x.x_win64.exe directly to install, After installation is complete, run OrbbecViewer or the Orbbec SDK from the installation directory.

2.3 Quick Start

If you do not intend to modify the SDK itself, it is recommended to use a pre-compiled distribution. For a comprehensive guide on installing the SDK, setting up your development environment, and developing applications, please consult the Tutorial section for detailed information.

To explore practical examples and gain insights on utilizing the SDK, please navigate to Examples section for more information.

Orbbec Viewer is an all-in-one graphical user interface (GUI) built on the Orbbec SDK, offering a suite of features including data stream preview, camera configuration, post-processing, and more. To learn how to effectively use the Orbbec Viewer, please refer to the Orbbec Viewer User Guide.

2.4 API Reference

Orbbec SDK v2 API User Guide, this document provides an overview of key features in the Orbbec SDK v2 and demonstrates how to use its most commonly used APIs. For more detailed APIs, please refer to Orbbec SDK v2 API Reference

2.5 Camera Parameters and Value Ranges

For common depth, IR, and color camera parameters and their value ranges, refer to orbbec_camera_params.html

2.6 Camera Distortion

For each device’s Original depth and color distortions, as well as depth distortion after D2C, color distortion after C2C, and point cloud distortion, refer to orbbec_camera_distortion.md.

2.7 Timestamp

For an explanation of device, system, and global timestamps, including clock selection, device clock synchronization, and C++ usage examples, see the Timestamp Usage Guide.

2.8 Performance tuning

For different use cases, the SDK can be tuned to achieve optimal performance. Please refer to the performance tuning guide for more information.

2.9 Building from Source

If you would like to modify the SDK itself, you can build the SDK from source. Please refer to the build guide for more information.

2.10 FAQ

Most frequently asked questions can be found in the FAQ file.

More asked and answered questions can be found in the issues channel. Use key words for searching may help you find the answer you are looking for.

3. Gallery

3.1 The QuickStart Example

// Create a pipeline.
ob::Pipeline pipe;

// Start the pipeline with default config.
pipe.start();

// Create a window for showing the frames, and set the size of the window.
ob_smpl::CVWindow win("QuickStart", 1280, 720, ob_smpl::ARRANGE_ONE_ROW);

while(win.run()) {
    // Wait for frameSet from the pipeline, the default timeout is 1000ms.
    auto frameSet = pipe.waitForFrameset();

    // Push the frames to the window for showing.
    win.pushFramesToView(frameSet);
}

// Stop the Pipeline, no frame data will be generated
pipe.stop();

3.2 The Orbbec Viewer

• Notes

If the Orbbec Viewer is used under Linux OS and is used for updating any camera firmware, users may encounter the issue that the firmware file selection window is not poping up. Users are unable to proceed with the firmware update work flow and are unable to update the camera firmware.

• Solution:

1. Exit the Orbbec Viewer under Linux OS .
2. Run the following command as root in a terminal for installing the necessary tool Zenity.

sudo apt-get install zenity

3. Start the Orbbec Viewer under Linux OS and proceed with the firmware update work flow.

3.3 DepthQualityTool

Depth Quality Tool enables users to evaluate the camera’s depth quality across key metrics: Depth Accuracy, Spatial Precision, Temporal Precision, and Fill Rate. Users can easily view and interpret these metrics in real time or record the data for offline analysis.

4. Contributing

At present, we are focusing our efforts on the internal development of the SDK and are not accepting external contributions for functionality expansion. However, we value your input and are open to reviewing any pull requests or suggestions you might have.

Should you have any questions or concerns, please feel free to reach out to us through the issues channel.

5. License

This project is licensed under the MIT License with some other licenses for third-party libraries and extensions - see the LICENSE file for details.

6. Links

• Orbbec SDK V2.x Open Source Library
• Orbbec SDK V1.x Pre-Compiled Library
• Orbbec Company Main Page
• Orbbec 3D Club