7. FAQ

Frequently Asked Questions and Solutions for pyorbbecsdk.

7.1. Table of Contents

7.2. Installation Issues

7.2.1. No device found on Linux

Question: When running examples, I get “No device found” or the camera is not detected.

Solution:

This is typically a USB permission issue. The current user doesn’t have permission to access the USB device.

Quick Fix - Run the environment setup script:

# Option 1: From repository
python scripts/env_setup/setup_env.py

# Option 2: From installed package (v2.1.0+)
# 1. Get pyorbbecsdk installation path
python -c "import pyorbbecsdk, os; print(os.path.dirname(pyorbbecsdk.__file__))"
# Example output: /path/to/site-packages/pyorbbecsdk
# 2. Run setup.py(replace with the path from step 1)
python /path/to/site-packages/pyorbbecsdk/shared/setup_env.py

Manual Fix - Install udev rules:

  1. Check your device’s PID:

    lsusb | grep 2bc5

  2. Edit the udev rules file:

    sudo nano /etc/udev/rules.d/99-obsensor-libusb.rules

  3. Add the following line (replace your_pid_here with the actual PID):

    SUBSYSTEM=="usb", ATTR{idProduct}=="your_pid_here", ATTR{idVendor}=="2bc5", MODE:="0666", OWNER:="root", GROUP:="video"

  4. Reload udev rules:

    sudo udevadm control --reload-rules && sudo service udev restart && sudo udevadm trigger

Note: If you don’t install udev rules, you’ll need to use sudo every time you run SDK scripts.

7.2.2. Permission denied on macOS

Question: I get Permission denied or Library not loaded errors when running on macOS.

Solution:

Use sudo -E to preserve environment variables (especially important when using virtual environments):

sudo -E python examples/beginner/02_depth_visualization.py

The -E flag preserves your Python environment variables, ensuring your virtualenv packages are accessible.

7.2.3. ImportError on Windows

Question: I get ImportError: DLL load failed or similar errors on Windows.

Solution:

  1. Ensure you’re using 64-bit Python (required):

    python -c "import struct; print(struct.calcsize('P') * 8)"
# Should output: 64

  2. Install Visual C++ Redistributable (usually pre-installed, but may need reinstallation)

  3. Verify Python version matches the wheel (e.g., cp311 = Python 3.11):

    python --version

7.2.4. Python version mismatch

Question: I get No matching distribution found error when installing.

Solution:

Check your Python version matches supported versions (3.8-3.13):

python3 --version

If using a version manager (pyenv, conda), ensure you’re using the correct Python:

which python3

Supported Python versions: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13

7.2.5. Offline installation fails

Question: Wheel installation fails with platform tag error.

Solution:

Ensure you download the correct wheel for your:

  • Operating system (Linux/macOS/Windows)

  • Architecture (x86_64/ARM64)

  • Python version (cp38, cp39, cp310, cp311, cp312, cp313)

Check platform tags:

# For Linux/macOS
python3 -c "import platform; print(platform.machine()); print(platform.system())"
# For Windows
python -c "import platform; print(platform.machine()); print(platform.system())"

Wheel naming convention:

  • Linux x86_64: pyorbbecsdk-*-cp3X-cp3X-linux_x86_64.whl

  • Linux ARM64: pyorbbecsdk-*-cp3X-cp3X-linux_aarch64.whl

  • macOS ARM64: pyorbbecsdk-*-cp3X-cp3X-macosx_13_0_arm64.whl

  • Windows x64: pyorbbecsdk-*-cp3X-cp3X-win_amd64.whl

7.2.6. Package name confusion

Question: Should I install pyorbbecsdk or pyorbbecsdk2? The import is different from the package name.

Solution:

Starting from version 2.0.18, both online (PyPI) and offline packages use the name pyorbbecsdk2:

# Install from PyPI
pip install --upgrade pyorbbecsdk2

# Install offline wheel
pip install pyorbbecsdk2-2.x.x-xxx.whl

Import in code: import pyorbbecsdk (module name remains unchanged)

Verify installation:

pip show pyorbbecsdk2 | grep Version

7.2.7. Open3D and NumPy version compatibility

Question: Why are there version restrictions for Open3D and NumPy? I get compatibility errors when using them together.

Solution:

Open3D has specific NumPy version requirements due to ABI (Application Binary Interface) compatibility. Using incompatible versions can cause runtime errors or crashes.

Key points:

  1. Open3D’s NumPy dependency: Open3D is compiled against specific NumPy versions. Using a different NumPy version than what Open3D was built with can cause:

    • RuntimeError when calling Open3D functions

    • Segmentation faults

    • Incorrect computation results

  2. Recommended compatible versions: | Open3D Version | Compatible NumPy Version | |:—|:—| | 0.16.x | 1.21 - 1.23 | | 0.17.x | 1.21 - 1.24 | | 0.18.x | 1.22 - 1.26 |

  3. Best practice: Always check Open3D’s official getting started guide for the latest compatibility information: Open3D Getting Started Guide

  4. If you encounter issues:

    # Check your current versions
python -c "import numpy; print(f'NumPy: {numpy.__version__}')"
python -c "import open3d; print(f'Open3D: {open3d.__version__}')"

# Install compatible versions
pip install numpy==1.23.5 open3d==0.17.0

7.3. Build Issues

7.3.1. uv command not found

Question: When running the build script, I get “uv: command not found”.

Solution:

Ensure uv is installed and in your PATH:

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc

7.3.2. CMake configuration failed

Question: Build fails with “CMake configuration failed” error.

Solution:

Verify CMake version and Python development headers:

# Check CMake version (requires 3.15.0+)
cmake --version

# Install Python development headers (Linux)
# Ubuntu/Debian:
sudo apt-get install python3-dev build-essential

# CentOS/RHEL/Fedora:
sudo yum install python3-devel gcc-c++

7.3.3. pybind11 not found in offline mode

Question: Offline build fails with “pybind11 not found” error.

Solution:

Ensure virtual environments are set up correctly before copying to the offline machine:

# On a machine with internet access, prepare the offline environment:
for ver in 3.8 3.9 3.10 3.11 3.12 3.13; do
    uv venv venv${ver//./} --python $ver
    uv pip install pybind11 -e . --python venv${ver//./}/bin/python
done

# Then copy the entire project directory (including venv* directories) to the offline machine

7.3.4. Build fails on Windows with Visual Studio not found

Question: Build fails with “Visual Studio not found” or generator errors on Windows.

Solution:

Ensure Visual Studio 2019 or 2022 with C++ build tools is installed, or specify the generator explicitly:

# In the PowerShell script, modify the cmake command
cmake -G "Visual Studio 17 2022" -A x64 ...

Required components:

  • Visual Studio 2019 or 2022

  • C++ build tools

  • Windows SDK

7.4. Runtime Issues

7.4.1. Empty frames or frames is None

Question: frames is always None or frames don’t contain data.

Solution:

  1. Check timeout: Increase the timeout in wait_for_frames():

    frames = pipeline.wait_for_frames(5000)  # Wait up to 5 seconds

  2. Verify streams are available: Run the hello camera example to check supported streams:

    python examples/beginner/01_hello_camera.py

  3. Ensure frames are valid before processing:

    if frames is None:
    continue
color_frame = frames.get_color_frame()
if color_frame is None:
    continue

  4. Try the quick start: The zero-config approach handles defaults automatically:

    python examples/quick_start.py

7.4.2. Display issues with OpenCV

Question: OpenCV window doesn’t appear or shows blank images.

Solution:

  1. Check OpenCV installation:

    python -c "import cv2; print(cv2.__version__)"

  2. Ensure frames are valid before displaying:

    if color_frame is not None:
    color_image = frame_to_bgr_image(color_frame)
    if color_image is not None:
        cv2.imshow("Color", color_image)

  3. Install dependencies (for versions < 2.1.0):

    pip install opencv-python numpy

7.4.3. Jetson Nano illegal instruction

Question: When running python examples/beginner/02_depth_visualization.py on Jetson Nano, the following error occurs:

illegal instruction (core dumped)

Solution:

Check your OpenCV installation. If you encounter the same error when running:

import cv2

Set the OPENBLAS_CORETYPE environment variable before launching Python:

OPENBLAS_CORETYPE=ARMV8 python

To make this setting permanent, edit your .bashrc file:

nano ~/.bashrc

Add the following line at the end of the file:

export OPENBLAS_CORETYPE=ARMV8

Refer to this Stack Overflow post for more information.

7.4.4. Import Error ModuleNotFoundError

Question: I get ModuleNotFoundError: No module named 'pyorbbecsdk'.

Solution:

Install the SDK and verify installation:

# Install the SDK
pip install --upgrade pyorbbecsdk2

# Verify installation
pip show pyorbbecsdk2 | grep Version

If using a virtual environment, ensure it’s activated:

source orbbec_env/bin/activate  # Linux/macOS
.\orbbec_env\Scripts\activate  # Windows

7.5. Platform-Specific Issues

7.5.1. USB device access permission error on Linux

Question: When running python examples/beginner/02_depth_visualization.py, the following error occurs:

msg:failed to open usb device!  error: OB_USB_STATUS_ACCESS
 - type:St13runtime_error
[2023-07-04 17:09:19.891859][warning][117523][EnumeratorLibusb.cpp:342] failed to create usb device at index: 1, url:2-1.4.1-6
[2023-07-04 17:09:20.391989][error][117523][DeviceLibusb.cpp:109] failed to open usb device!  error: OB_USB_STATUS_ACCESS
...
pyorbbecsdk.OBError: usbEnumerator createUsbDevice failed!

Solution:

The current user does not have permission to access the device. See No device found on Linux for the solution.

7.5.2. Metadata or timestamp issues on Windows

Question: Timestamps are abnormal or frame synchronization fails on Windows.

Solution:

Run the environment setup script to register UVC metadata:

python scripts/env_setup/setup_env.py

Or manually (PowerShell as Administrator):

cd C:\path\to\pyorbbecsdk\scripts\env_setup
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
.\obsensor_metadata_win10.ps1 -op install_all

Note: This must be run once per device/computer.

7.5.3. macOS camera and terminal authorization

Question: On macOS, the first time I run examples that access the camera, I get permission errors or the camera doesn’t work. The terminal doesn’t seem to have camera access.

Solution:

macOS requires explicit permission grants for applications to access camera and other hardware resources. When you first run a Python script from the terminal that accesses the camera, macOS will prompt you to grant permission.

Steps to grant terminal camera access:

  1. First run: When you run a camera example for the first time, macOS will show a system dialog:

    “Terminal” would like to access the camera.

    Click “Allow” or “OK”.

  2. If you accidentally denied permission:

    • Open System Settings (or System Preferences on older macOS)

    • Go to Privacy & Security → Input Monitoring

    • Find Terminal (or iTerm2 if using that) in the list

    • Toggle the switch to ON

  3. Verify permission is granted:

    # Run any camera example
python examples/beginner/01_hello_camera.py

    If the camera works without permission prompts, authorization is complete.

Note: You only need to authorize once per terminal application. After granting permission, all subsequent camera operations from that terminal will work without additional prompts.

7.6. Camera and Streaming

7.6.1. Frame synchronization failures

Question: Color and depth frames are not synchronized or timestamps don’t match.

Solution:

  1. Use wait_for_frames() to get synchronized frames:

    frames = pipeline.wait_for_frames(1000)  # Returns synchronized FrameSet
color = frames.get_color_frame()
depth = frames.get_depth_frame()

  2. On Windows, ensure metadata registration is complete (see Metadata issues on Windows)

  3. Check timestamp metadata:

    color_timestamp = color_frame.get_timestamp()
depth_timestamp = depth_frame.get_timestamp()
diff = abs(color_timestamp - depth_timestamp)

7.6.2. Resolution or FPS configuration issues

Question: I can’t set a specific resolution or FPS, or the configuration fails.

Solution:

Check available stream profiles first:

from pyorbbecsdk import Config, OBSensorType, OBFormat

config = Config()
profiles = pipeline.get_stream_profile_list(OBSensorType.COLOR_SENSOR)

# List all available profiles
for i in range(profiles.get_count()):
    profile = profiles.get_profile(i)
    print(f"{profile.width()}x{profile.height()} @ {profile.fps()}fps")

# Try specific profile with fallback
try:
    color_profile = profiles.get_video_stream_profile(1280, 720, OBFormat.RGB, 30)
except:
    color_profile = profiles.get_default_video_stream_profile()

config.enable_stream(color_profile)
pipeline.start(config)

7.7. Configuration

7.7.1. How to configure or disable SDK logging

Question: How do I change the log level or disable SDK logging?

Solution:

Modify the log level by editing the OrbbecSDKConfig.xml configuration file.

Steps:

  1. Locate the configuration file

    For pip-installed packages, run pip show pyorbbecsdk2 to get the installation path. The XML file is located at <Location>/OrbbecSDKConfig.xml

    pip show pyorbbecsdk2
# Output: Location: /Users/me/.../site-packages
# Full path: /Users/me/.../site-packages/OrbbecSDKConfig.xml

  2. Modify the log level

    Open the XML file and find the <Log> section:

    <Log>
    <FileLogLevel>1</FileLogLevel>          <!-- Change this from 1 to 5 -->
    <ConsoleLogLevel>3</ConsoleLogLevel>
</Log>

    Change FileLogLevel to 5:

    <Log>
    <FileLogLevel>5</FileLogLevel>          <!-- 5 = NONE, disables logging -->
    <ConsoleLogLevel>3</ConsoleLogLevel>
</Log>

Log Level Values:

Value Level Description
0 DEBUG Debug information
1 INFO General information (default)
2 WARN Warning messages
3 ERROR Error messages
4 FATAL Fatal errors
5 NONE Disables logging

7.8. Firmware

7.8.1. Firmware version mismatch

Question: I encounter errors related to firmware version mismatch or the device doesn’t work correctly.

Solution:

Use the automated firmware update assistant to check and update your device firmware:

python scripts/auto_update_firmware.py

This script will:

  1. Check your current device firmware version

  2. Guide you to download the correct firmware

  3. Perform the firmware update safely

Important: Most new devices come with compatible firmware pre-installed and work out-of-the-box. Starting from October 2025 (Orbbec SDK v2.5.5), devices using the OpenNI protocol will be upgraded to UVC protocol.

7.8.2. How to update firmware

Question: How do I update the camera firmware?

Solution:

Use the firmware update example:

python examples/beginner/09_device_firmware_update.py

Or use the automated update script:

python scripts/auto_update_firmware.py

The update process:

  1. Connect your camera via USB

  2. Run the update script/example

  3. Follow the prompts to download and flash the firmware

  4. Wait for the update to complete (do not disconnect during the process)

Supported devices for OTA update: Gemini series, Femto series, Astra series (see device documentation for specific models).

7.9. Additional Resources