pyorbbecsdk Python Wrapper for Orbbec SDK

When troubleshooting why a feature (like hole filling) is not working, distinguish between hardware-level device properties and SDK software filters:

1. Device Properties: Accessed via property IDs like OB_PROP_DEPTH_HOLEFILTER_BOOL. These represent hardware-level configurations. If supported=False for a specific device, this property cannot be used.
2. Software Filters: These are SDK-provided algorithms (e.g., HoleFillingFilter, SpatialAdvancedFilter, TemporalFilter) found in the post_processing_filter section of a JSON preset. These are applied to the frame data in software and are independent of hardware property support.

The SDK v2.x series (v2-main branch) is a rewrite targeting Orbbec SDK v2.7.6+. It uses the UVC protocol for newer devices. The core API is organized into several functional groups:

• Lifecycle & Discovery: Use Context as the SDK entry point for device enumeration and lifecycle management. Use Device, DeviceList, and DeviceInfo to access device identity, firmware information, and properties.
• Streaming: Use Pipeline and Config to manage stream configuration and the frame acquisition loop.
• Sensors: Use Sensor and SensorList to enumerate specific sensors like depth, color, IR, or IMU.
• Stream Configuration: Use StreamProfile, VideoStreamProfile, AccelStreamProfile, or GyroStreamProfile to configure resolution, FPS, and data formats.

The Orbbec SDK uses an XML configuration file (OrbbecSDKConfig_v1.0.xml) to define global settings.

When initializing the Context, you can specify a custom configuration file by passing its path to the Context constructor.

Loading Logic:

1. If a path is provided to the constructor, the SDK loads that file.
2. If no path is provided (or an empty string is passed), the SDK looks for OrbbecSDKConfig.xml in the current working directory.
3. If neither is found, the SDK falls back to its built-in default configuration.

For spatial calculations and coordinate transformations, use the following classes:

• Intrinsics & Distortion: OBCameraIntrinsic (focal length, principal point, dimensions) and OBCameraDistortion (radial and tangential coefficients).
• Extrinsics: OBExtrinsic (rotation matrix and translation vector between sensor frames).
• Full Calibration: OBCalibrationParam provides the complete set of calibration parameters for all sensors.
• Transforms: CoordinateTransformHelper provides utilities for converting between 2D, 3D, depth, and color coordinate systems.

The SDK provides specialized frame classes to handle different sensor data types:

• Base Frames: Frame and VideoFrame provide access to timestamps, metadata, and the raw data buffer.
• Depth: DepthFrame provides depth data; note that you must apply a scale factor to convert raw uint16 values to millimeters.
• Color: ColorFrame supports RGB, MJPEG, and Y8 formats.
• Infrared: IRFrame provides left and right IR frames for stereo cameras.
• 3D Data: PointsFrame provides 3D point cloud data.
• IMU: AccelFrame and GyroFrame provide accelerometer and gyroscope data.
• Multi-stream: FrameSet is a container used when calling Pipeline.wait_for_frames() to retrieve multiple synchronized streams at once.

The SDK includes several filters to process and enhance sensor data:

• Alignment: AlignFilter for software-based depth-to-color or color-to-depth alignment.
• Noise Reduction: TemporalFilter (averaging across frames), SpatialAdvancedFilter (edge-preserving smoothing), NoiseRemovalFilter (removing isolated pixels), and HoleFillingFilter (interpolating invalid pixels).
• Data Manipulation: ThresholdFilter (clipping depth range), DecimationFilter (reducing resolution), and FormatConvertFilter (converting frame formats).
• Advanced Processing: PointCloudFilter (generating colored 3D point clouds), HDRMergeFilter (merging alternating-exposure frames), and SequenceIdFilter (selecting specific frames for sequences like HDR).

The Orbbec SDK uses an XML configuration file (OrbbecSDKConfig_v1.0.xml) to define global settings.

Loading the configuration:

• Custom Path: Pass the file path to the Context constructor during initialization.
• Default Path: If no path is provided (or an empty string is passed), the SDK looks for OrbbecSDKConfig.xml in the current working directory.
• Fallback: If neither a specified file nor the default file is found, the SDK uses its built-in default configuration.

// Example concept: passing a custom config path to the Context constructor
// context = Context("path/to/your/config.xml")

You can programmatically control the SDK's logging behavior using the Context class. This allows you to set the verbosity for both console and file logging using OBLogLevel values.

Available Log Levels

from pyorbbecsdk import Context, OBLogLevel

# Set console logger level
Context.set_logger_to_console(OBLogLevel.INFO)

# Set file logger with custom path
Context.set_logger_to_file(OBLogLevel.DEBUG, "/path/to/logs")

# Disable console logging
Context.set_logger_to_console(OBLogLevel.NONE)

If you are installing the package from PyPI, type stubs (.pyi files) are automatically included. You can ensure you have the latest version with the following command:

pip install --upgrade pyorbbecsdk2

To verify that the stubs are present in your installation directory, run the following command to print the package path and check for .pyi files.

The fastest way to verify your camera connection is to run the quick_start.py script. This immediately opens a side-by-side viewer showing both color and depth streams without requiring manual configuration.

python examples/quick_start.py