奥比中光Gemini相机Python SDK配置

一、环境准备阶段

1.1 安装 uv 工具
Windows (PowerShell)

# 方法 1: 使用官方安装脚本（推荐）powershell-ExecutionPolicyByPass-c"irm https://astral.sh/install.ps1 | iex"# 方法 2: 使用 pip 安装pipinstalluv# 验证安装uv--version# 输出示例: uv 0.5.0

Linux/macOS

# 方法 1: 官方安装脚本（推荐）curl-LsSfhttps://astral.sh/install.sh|sh# 方法 2: 使用 pippipinstalluv# 添加到 PATH（如果提示）exportPATH="$HOME/.local/bin:$PATH"# 验证安装uv--version

1.2 安装系统依赖
Windows(PowerShell)

# 1. 安装 Visual Studio Build Tools# 下载地址: https://visualstudio.microsoft.com/downloads/# 选择 "使用 C++ 的桌面开发"# 确保勾选:# - MSVC v143 - VS 2026 C++ x64/x86 生成工具# - Windows 10/11 SDK# 2. 安装 CMake# 下载地址: https://cmake.org/download/# 或使用 Chocolatey:chocoinstallcmake# 验证cmake--version

Linux (Ubuntu/Debian)

# 安装编译工具和依赖sudoaptupdatesudoaptinstall-y\build-essential\cmake\libusb-1.0-0-dev\libudev-dev\pkg-config# 验证cmake--versiongcc--version

1.3 克隆项目

# 克隆仓库gitclone https://github.com/orbbec/pyorbbecsdk.git pyorbbecsdk-v2cdpyorbbecsdk-v2# 查看项目结构ls# 应该看到: src/, sdk/, scripts/, examples/, setup.py, pyproject.toml

二、快速开始

2.1 一键构建单个 Python 版本
Windows PowerShell

# 进入项目目录cdD:\pyorbbecsdk-v2# 构建 Python 3.10 的 wheel（自动处理所有步骤）.\scripts\build_whl\build-whl-uv.ps13.10

Linux/macOS

# 进入项目目录cd/path/to/pyorbbecsdk-v2# 赋予执行权限chmod+x scripts/build_whl/*.sh# 构建 Python 3.10 的 wheel./scripts/build_whl/build-whl-uv.sh3.10

2.2 构建所有 Python 版本

# Windows.\scripts\build_whl\build-whl-uv.ps1 all# Linux/macOS./scripts/build_whl/build-whl-uv.sh all

三、详细构建流程

3.1 检查 uv 管理的 Python 版本

# 查看已安装的 Python 版本uv python list# 如果没有需要的版本，安装它uv pythoninstall3.10uv pythoninstall3.11# 再次确认uv python list# 输出示例:# cpython-3.10.14-windows-x86_64-windows-none# cpython-3.11.9-windows-x86_64-windows-none

3.2 测试 Python 解释器

# 找到 Python 3.10 的路径uv pythonfind3.10# 输出: C:\Users\YourName\AppData\Local\Programs\Python\Python310\python.exe# 测试运行uv run--python3.10python--version# 输出: Python 3.10.14

3.3 清理旧构建目录

Remove-Item-Recurse-Forcebuild_3.10-ErrorActionSilentlyContinue Remove-Item-Recurse-Forceinstall-ErrorActionSilentlyContinue Remove-Item-Recurse-Forcedist-ErrorActionSilentlyContinue# 创建必要目录New-Item-ItemTypeDirectory-Forcebuild_3.10|Out-Null New-Item-ItemTypeDirectory-Forceinstall\lib\pyorbbecsdk\shared|Out-Null New-Item-ItemTypeDirectory-Forcewheel|Out-Null

3.4 CMake 配置

# 创建构建目录mkdirbuild_3.10cdbuild_3.10# 获取 Python 和 pybind11 路径$PYTHON_EXE=uv pythonfind3.10$PYBIND11_DIR=uv run--python3.10--withpybind11 python-c"import pybind11; print(pybind11.get_cmake_dir())"Write-Host"Python path:$PYTHON_EXE"-ForegroundColorCyan Write-Host"pybind11 path:$PYBIND11_DIR"-ForegroundColorCyan# 执行 CMake 配置cmake-G"Visual Studio 18 2026"-Ax64`-DPython3_EXECUTABLE="$PYTHON_EXE"`-Dpybind11_DIR="$PYBIND11_DIR"`-DCMAKE_BUILD_TYPE=Release`-DCMAKE_INSTALL_PREFIX="../install"`..# Linux/macOScmake-DCMAKE_BUILD_TYPE=Release\-DPython3_EXECUTABLE=$(uv pythonfind3.10)\-Dpybind11_DIR="<从步骤3获取的路径>"\-DCMAKE_INSTALL_PREFIX=../install\..

3.6 编译并安装

# Windowscmake--build.--configRelease--targetinstall--parallel# Linux/macOScmake--build.--configRelease--targetinstall--parallel$(nproc)

3.7 复制额外文件

# 返回项目根目录cd..# 复制示例代码Copy-Item-Recurse-Forceexamples install\lib\pyorbbecsdk\# 复制配置文件Copy-Item-Recurse-Forceconfig install\lib\pyorbbecsdk\# 复制 requirements.txtCopy-Item requirements.txt install\lib\pyorbbecsdk\examples\# 复制类型存根文件Copy-Item stubs\__init__.pyi install\lib\pyorbbecsdk\Copy-Item stubs\pyorbbecsdk.pyi install\lib\pyorbbecsdk\# 复制环境设置脚本Write-Host "`nCopying extra files..."-ForegroundColorCyan Copy-Item-Recurse-Forceexamples install\lib\pyorbbecsdk\Copy-Item-Recurse-Forceconfig install\lib\pyorbbecsdk\Copy-Item requirements.txt install\lib\pyorbbecsdk\examples\Copy-Item stubs\__init__.pyi install\lib\pyorbbecsdk\Copy-Item stubs\pyorbbecsdk.pyi install\lib\pyorbbecsdk\Copy-Item scripts\env_setup\setup_env.py install\lib\pyorbbecsdk\shared\-Force-ErrorActionSilentlyContinue

3.8 生成 wheel

# 使用 uv 构建 wheelWrite-Host "`nBuilding wheel..."-ForegroundColorCyan uv build--wheel--python3.10--link-mode copy# 或使用传统方式python3.10 setup.py bdist_wheel

3.9 安装 wheel

pipinstallwheel/pyorbbecsdk2-2.1.1-cp310-cp310-win_amd64.whl