2.2. Environment Setup (One-Time Configuration)

Before using the Orbbec SDK Python Wrapper, you need to run the environment configuration script once on each new computer. This ensures:

Linux: Proper device access permissions via udev rules
Windows: UVC metadata registration for correct timestamps and frame synchronization
macOS: No additional configuration needed

This step is only required the first time you set up the SDK on a machine.

2.2.1. Quick Setup (Recommended)

We provide a unified setup_env.py script that automatically detects your platform and performs the necessary configuration.

2.2.1.1. From Repository

First, download the source code from the official GitHub repository.

2.2.1.1.1. Windows (PowerShell)

cd pyorbbecsdk/scripts/env_setup
python setup_env.py

The script will automatically request administrator privileges if needed.

2.2.1.1.2. Linux

cd pyorbbecsdk/scripts/env_setup
python setup_env.py

The script will automatically request sudo privileges for installing udev rules.

2.2.1.1.3. macOS

No setup required. The script will detect macOS and inform you that no additional configuration is needed.

cd pyorbbecsdk/scripts/env_setup
python setup_env.py
# Output: macOS detected. No additional environment setup required.

2.2.1.2. From Installed Package

If you have installed pyorbbecsdk via pip, you can also run the embedded setup script:

# 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

2.2.1.3. Command Options

The setup_env.py script supports the following options:

Option	Description
`--check`	Check the current environment configuration status
`--uninstall`	Remove the configuration (udev rules on Linux, registry entries on Windows)
`-h, --help`	Show help message

Examples:

# Check if environment is properly configured
python setup_env.py --check

# Uninstall/remove configuration
python setup_env.py --uninstall

2.2.2. What This Setup Does

2.2.2.1. Windows

Registers UVC metadata in the Windows registry to enable timestamp extraction
Required for proper frame synchronization and depth-color alignment
Must be run as Administrator
Needs to be re-run when connecting a new device model (the script will detect this)

2.2.2.2. Linux

Installs udev rules to grant user access to Orbbec USB devices
Prevents permission denied errors when opening devices
Reloads udev rules automatically after installation
Requires sudo privileges

2.2.2.3. macOS

No registry or udev configuration needed
Orbbec devices work out of the box on macOS

2.2.3. Manual Configuration (Advanced)

If you prefer to configure the environment manually, or if the automatic script fails, follow these manual steps:

2.2.3.1. Linux - Manual udev Rules Installation

Install udev rules using the following commands:

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

Note: If this script is not executed, opening the device will fail due to permission issues. You would need to run samples with sudo (administrator privileges).

2.2.3.2. Windows - Manual Metadata Registration

To get device metadata (timestamps and other video frame information) through UVC protocol, you need to modify the registry first due to Windows system limitations.

Connect the device and confirm that the device is online
Open PowerShell with administrator privileges, then use the cd command to enter the script directory

Execute the following command and enter Y when prompted:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

If the above fails, try:

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

Execute the following to complete registration:

.\obsensor_metadata_win10.ps1 -op install_all

Note: Users need to run this script every time a new device model is connected. If metadata is not registered, device timestamps will be abnormal, affecting the SDK’s internal frame synchronization functionality.