当前位置： 首页 > ai >正文

C++开发---奥比中光(Orbbec)的ob库

ai 2025/7/25 12:11:18

Orbbec SDK（奥比中光软件开发工具包）是面向深度视觉开发的专业工具，支持旗下Astra、Gemini、Femto等全系列深度相机。其API设计遵循设备抽象、流管理、数据处理的分层架构，提供了从设备枚举到三维重建的完整功能链。

ob 命名空间

所有 Orbbec SDK 的类和函数都封装在 ob 命名空间下，使用时需包含头文件 <ob.h> 并引入该命名空间。

一、基础架构与初始化类

  1. ob::Context 全局上下文类
    作为SDK的入口点，Context负责管理全局资源、设备枚举、许可证验证和日志系统，采用单例模式设计。

    • 核心函数：
      • static std::shared_ptr<Context> create()：创建上下文实例，内部初始化USB驱动、设备管理器等底层模块。
      • std::shared_ptr<DeviceList> queryDeviceList()：刷新并返回当前连接的设备列表（支持热插拔检测）。
      • void setLoggerSeverity(OBLogSeverity severity)：设置日志级别（OB_LOG_SEVERITY_VERBOSE至OB_LOG_SEVERITY_FATAL），默认输出至控制台。
      • void setLoggerCallback(OBLogCallback callback, void* userData)：注册自定义日志回调，可将日志写入文件或远程服务器。
      • void setLicense(const char* licenseKey)：激活商业许可证，解锁高精度深度计算、长距离模式等高级功能。
      • std::shared_ptr<Playback> createPlayback(const char* filePath)：创建回放实例，用于解析录制的数据流文件（.obrec格式）。

    使用场景：程序启动时必须先创建Context，所有设备操作依赖其生命周期。

  2. ob::Version 版本信息类
    提供SDK版本查询功能，用于兼容性校验。

    • uint32_t major()/uint32_t minor()/uint32_t patch()：返回主/次/修订版本号（如v2.3.1对应2、3、1）。
    • std::string fullVersion()：返回完整版本字符串（含编译日期和Git哈希）。
二、设备管理与属性控制

  1. ob::DeviceList 设备列表类
    存储检测到的Orbbec设备集合，支持多设备枚举。

    • uint32_t deviceCount()：返回当前连接的设备数量。
    • std::shared_ptr<Device> getDevice(uint32_t index)：通过索引获取设备实例（索引从0开始）。
    • std::shared_ptr<Device> getDeviceBySerialNumber(const char* serial)：通过序列号精确匹配设备（多设备场景必备）。
    • bool contains(const char* serial)：检查指定序列号的设备是否存在。
    • void refresh()：刷新设备列表（处理热插拔事件）。

  2. ob::Device 设备控制类
    代表物理设备，提供硬件级操作接口。

    • 设备信息查询：

      • std::string getSerialNumber()：获取唯一序列号（如Astra-123456）。
      • std::string getModelName()：返回设备型号（如Gemini 2L）。
      • std::string getFirmwareVersion()：获取固件版本（格式vX.Y.Z）。
      • std::string getHardwareVersion()：返回硬件版本（如HW v2.0）。
      • uint16_t vendorId()/uint16_t productId()：获取USB设备的厂商ID和产品ID（用于USB权限配置）。

    • 传感器管理：

      • std::shared_ptr<SensorList> getSensorList()：获取设备搭载的传感器列表（如深度、RGB、红外、IMU）。
      • std::shared_ptr<Pipeline> createPipeline()：创建与设备绑定的数据流管道（推荐使用，简化流管理）。

    • 属性配置：

      • void setProperty(OBPropertyID id, const void* value, uint32_t size)：设置设备属性（如激光功率、曝光参数）。
      • void getProperty(OBPropertyID id, void* value, uint32_t* size)：读取属性当前值。
      • bool isPropertySupported(OBPropertyID id)：检查设备是否支持某属性（如低端设备可能无激光调节功能）。

      常用属性ID：

      • OB_PROP_DEPTH_LASER_POWER：激光功率（0-100，默认80），影响深度测距范围。
      • OB_PROP_COLOR_EXPOSURE_MODE：曝光模式（OB_EXPOSURE_MODE_AUTO/OB_EXPOSURE_MODE_MANUAL）。
      • OB_PROP_DEPTH_GAIN：深度增益（影响图像亮度，过高会引入噪声）。
      • OB_PROP_IR_PROJECTOR_MODE：红外投影模式（OB_IR_MODE_OFF/OB_IR_MODE_AUTO）。

    • 高级功能：

      • std::shared_ptr<CalibrationParam> getCalibrationParam()：获取设备内参/外参校准数据（用于坐标转换）。
      • void setPowerState(OBPowerState state)：控制设备电源状态（OB_POWER_STATE_NORMAL/OB_POWER_STATE_STANDBY）。

  3. ob::SensorList 传感器列表类
    管理设备上的传感器集合，支持按类型筛选。

    • uint32_t sensorCount()：返回传感器数量（如Astra Pro含深度、RGB、红外3个传感器）。
    • std::shared_ptr<Sensor> getSensor(OBSensorType type)：按类型获取传感器（OB_SENSOR_DEPTH/OB_SENSOR_COLOR/OB_SENSOR_IR/OB_SENSOR_IMU）。
    • std::shared_ptr<Sensor> getSensorByIndex(uint32_t index)：按索引获取传感器。

  4. ob::Sensor 传感器控制类
    操作单个传感器的参数配置与流管理。

    • OBSensorType type()：返回传感器类型（如OB_SENSOR_DEPTH）。
    • std::shared_ptr<StreamProfileList> getStreamProfileList()：获取该传感器支持的所有流配置（分辨率、帧率、格式）。
    • bool supportsFrameSync()：检查传感器是否支持帧同步（多传感器数据时间对齐）。
三、流配置与数据格式

  1. ob::StreamProfileList 流配置列表类
    存储传感器支持的所有输出模式，用于筛选最佳配置。

    • uint32_t count()：返回可用配置数量。
    • std::shared_ptr<StreamProfile> getProfile(uint32_t index)：按索引获取配置。
    • 筛选方法：
      • std::shared_ptr<StreamProfile> getVideoStreamProfile(int width, int height, OBFormat format, int fps)：精确匹配视频流参数（常用）。
      • std::shared_ptr<StreamProfile> getProfileByType(OBStreamType type)：按流类型筛选（如OB_STREAM_VIDEO/OB_STREAM_IR）。
      • std::shared_ptr<StreamProfile> getDefaultProfile()：获取传感器默认配置（如深度默认640x480@30fps）。

  2. ob::StreamProfile 流配置类
    描述单一流的具体参数，是流启动的核心配置项。

    • 基础参数：

      • int width()/int height()：图像宽度/高度（如640x480）。
      • int fps()：帧率（帧/秒，如30、60）。
      • OBFormat format()：像素格式（深度常用OB_FORMAT_DEPTH_16U，彩色常用OB_FORMAT_RGB888）。
      • OBStreamType type()：流类型（OB_STREAM_VIDEO/OB_STREAM_IR/OB_STREAM_IMU）。

    • 扩展方法：

      • std::shared_ptr<StreamProfile> clone(int width, int height, OBFormat format, int fps)：复制并修改配置参数（快速生成新配置）。
      • bool isSameAs(const std::shared_ptr<StreamProfile>& other)：判断两个配置是否完全一致。

  3. ob::VideoStreamProfile 视频流配置类
    继承自StreamProfile，专用于视频类传感器（深度、RGB、红外）。

    • OBVideoType videoType()：返回视频类型（OB_VIDEO_DEPTH/OB_VIDEO_COLOR/OB_VIDEO_IR）。
    • float horizontalFov()：水平视场角（弧度，如Astra的深度FOV约1.047rad=60°）。
    • float verticalFov()：垂直视场角。

  4. ob::IMUStreamProfile IMU流配置类
    继承自StreamProfile，用于惯性测量单元（加速度计+陀螺仪）。

    • OBIMUSampleRate sampleRate()：采样率（如OB_IMU_SAMPLE_RATE_200HZ）。
    • OBIMUType imuType()：IMU类型（OB_IMU_TYPE_ACCEL/OB_IMU_TYPE_GYRO/OB_IMU_TYPE_COMBINED）。
四、数据流采集与同步

  1. ob::Pipeline 数据管道类
    简化多流同步采集流程，自动处理流的启动、同步和数据聚合，是最常用的采集接口。

    • 配置与启动：

      • std::shared_ptr<PipelineConfig> createConfig()：创建配置对象。
      • void start(const std::shared_ptr<PipelineConfig>& config)：按配置启动流采集（同步启动多流）。
      • void startWithCallback(const std::shared_ptr<PipelineConfig>& config, FrameSetCallback callback, void* userData)：启动并注册回调函数（异步模式）。

    • 数据获取：

      • std::shared_ptr<FrameSet> waitForFrames(uint32_t timeout = 1000)：阻塞等待一帧数据（默认超时1秒）。
      • void stop()：停止所有流采集，释放资源。

    • 高级控制：

      • std::shared_ptr<Device> getDevice()：获取绑定的设备实例。
      • void enableFrameSync(bool enable)：开启/关闭帧同步（多流时间戳对齐）。
      • std::shared_ptr<Playback> getPlayback()：获取回放实例（用于离线数据处理）。

  2. ob::PipelineConfig 管道配置类
    配置Pipeline需要启用的流和参数。

    • 流启用：

      • void enableStream(OBSensorType type, const std::shared_ptr<StreamProfile>& profile)：为指定传感器启用流（推荐显式配置）。
      • void enableAllStreams()：启用所有传感器的默认流（快速测试用）。
      • void disableStream(OBSensorType type)：禁用某类传感器的流。

    • 同步与滤波：

      • void setAlignMode(OBAlignMode mode)：设置对齐模式（OB_ALIGN_DISABLE/OB_ALIGN_DEPTH_TO_COLOR，将深度图对齐到彩色图视角）。
      • void enableFilter(OBFilterType type)：启用内置滤波（如OB_FILTER_BILATERAL双边滤波优化深度图）。

  3. ob::FrameSet 帧集合类
    包含一帧同步的多类型数据（如深度+彩色+IMU），是数据处理的主要载体。

    • std::shared_ptr<Frame> getFrame(OBFrameType type)：按类型获取帧（OB_FRAME_DEPTH/OB_FRAME_COLOR/OB_FRAME_IMU）。
    • uint64_t timestamp()：获取帧集的系统时间戳（毫秒级，与主机时钟同步）。
    • uint64_t systemTimestamp()：获取设备硬件时间戳（微秒级，设备内部时钟）。
    • size_t frameCount()：返回帧集中包含的帧数量。

  4. ob::Frame 基类与派生帧类
    所有帧数据的基类，派生类针对不同数据类型提供专用方法。

    • 基类Frame通用方法：

      • OBFrameType type()：返回帧类型。
      • uint8_t* data()：获取原始数据指针（需按格式解析）。
      • uint32_t dataSize()：数据总字节数。
      • std::shared_ptr<StreamProfile> profile()：获取生成该帧的流配置。

    • ob::DepthFrame 深度帧：

      • uint16_t* data()：返回16位深度数据指针（单位：毫米，0表示无效值）。
      • float getValue(int x, int y)：获取(x,y)处的深度值（单位：米，自动转换）。
      • uint16_t getRawValue(int x, int y)：获取原始16位深度值（毫米）。
      • OBValidDepthRange validDepthRange()：获取有效测距范围（最小/最大距离，米）。

    • ob::ColorFrame 彩色帧：

      • uint8_t* data()：根据格式返回对应指针（如OB_FORMAT_RGB888为3通道字节数组）。
      • OBColorFormat colorFormat()：返回彩色格式（OB_COLOR_FORMAT_RGB/OB_COLOR_FORMAT_BGR等）。
      • std::shared_ptr<DepthFrame> alignedDepthFrame()：获取与该彩色帧对齐的深度帧（需提前启用对齐）。

    • ob::IRFrame 红外帧：

      • uint16_t* data()：16位红外强度数据（值越高表示反射越强）。

    • ob::IMUFrame IMU帧：

      • OBIMUData data()：获取IMU数据结构（包含加速度、角速度、时间戳）。
      • float accelerometerX()/float accelerometerY()/float accelerometerZ()：X/Y/Z轴加速度（m/s²）。
      • float gyroscopeX()/float gyroscopeY()/float gyroscopeZ()：X/Y/Z轴角速度（rad/s）。
五、坐标转换与校准

  1. ob::CalibrationParam 校准参数类
    存储设备的内参、外参和畸变系数，是坐标转换的基础数据。

    • 获取方式：Device::getCalibrationParam()
    • 核心参数：
      • 内参：焦距（fx, fy）、主点（cx, cy）、畸变系数（k1, k2, p1, p2, k3）。
      • 外参：传感器间的旋转矩阵（R）和平移向量（T），用于坐标转换。
    • bool isAvailable()：检查校准参数是否有效（部分设备可能未校准）。

  2. ob::CoordinateTransformer 坐标转换类
    基于校准参数实现多坐标系转换，是三维视觉的核心工具。

    • 创建方式：std::make_shared<CoordinateTransformer>(calibrationParam)
    • 核心转换函数：
      • OBPoint3f depthToCamera(int x, int y, uint16_t depth)：将深度图像素(x,y)转换为相机坐标系3D点（单位：米，相机原点为参考）。
      • OBPoint2f cameraToDepth(OBPoint3f cameraPoint)：将相机坐标系3D点投影到深度图像素坐标。
      • std::shared_ptr<DepthFrame> depthFrameToColorFrame(const std::shared_ptr<DepthFrame>& depthFrame)：将深度帧对齐到彩色帧视角（像素级配准）。
      • OBPoint2f depthToColor(int x, int y, uint16_t depth)：将深度图像素(x,y)映射到彩色图像的对应像素坐标。
      • std::shared_ptr<Frame> undistortFrame(const std::shared_ptr<Frame>& frame)：对图像进行畸变矫正（基于内参）。
六、数据处理与增强

  1. ob::Filter 滤波基类与派生类
    提供深度数据优化功能，降低噪声和空洞。

    • 基类方法：std::shared_ptr<Frame> apply(const std::shared_ptr<Frame>& frame)：对帧数据应用滤波。
    • 常用派生类：
      • ob::BilateralFilter：双边滤波（保留边缘同时降噪，参数：sigmaColor=50, sigmaSpace=10）。
      • ob::MedianFilter：中值滤波（去除椒盐噪声，参数：kernelSize=3/5）。
      • ob::GaussianFilter：高斯滤波（平滑图像，参数：kernelSize=3, sigma=1.0）。
      • ob::ThresholdFilter：阈值滤波（剔除超出有效距离的点，参数：minDepth/maxDepth）。

  2. ob::PointCloud 点云类
    生成和处理三维点云数据。

    • 创建方式：
      • static std::shared_ptr<PointCloud> createFromDepthFrame(const std::shared_ptr<DepthFrame>& depthFrame, const std::shared_ptr<CoordinateTransformer>& transformer)：从深度帧生成点云（带坐标转换）。
      • static std::shared_ptr<PointCloud> createFromColorAlignedDepthFrame(const std::shared_ptr<DepthFrame>& depthFrame, const std::shared_ptr<ColorFrame>& colorFrame, const std::shared_ptr<CoordinateTransformer>& transformer)：生成带彩色信息的点云。
    • 点云操作：
      • uint32_t pointCount()：点数量（等于有效深度像素数）。
      • OBPoint3f* points()：获取3D坐标数组（X/Y/Z，单位：米）。
      • uint8_t* colors()：获取RGB颜色数组（每个点3字节，仅彩色点云有效）。
      • void savePLY(const char* filePath)：保存点云为PLY格式（可被MeshLab等工具打开）。

  3. ob::Recorder 数据录制类
    将实时流数据录制为.obrec文件（包含所有帧数据和配置信息）。

    • static std::shared_ptr<Recorder> create(const char* filePath, const std::shared_ptr<Pipeline>& pipeline)：创建录制器（绑定管道）。
    • void writeFrameSet(const std::shared_ptr<FrameSet>& frameSet)：写入一帧数据。
    • void start()/void stop()：开始/停止录制。
七、错误处理与事件机制

  1. ob::Error 错误类
    封装SDK操作的错误信息，支持异常和错误码两种处理方式。

    • OBErrorCode code()：返回错误码（OB_SUCCESS=0，非0为错误）。
    • std::string message()：返回人类可读的错误描述（如“设备已断开连接”）。
    • 常用错误码：
      • OB_ERROR_DEVICE_NOT_CONNECTED：设备未连接。
      • OB_ERROR_INVALID_PARAM：参数无效（如分辨率不支持）。
      • OB_ERROR_TIMEOUT：操作超时（如waitForFrames超时）。

  2. ob::DeviceStateCallback 设备状态回调
    监听设备插拔事件：

    context->setDeviceStateCallback([](OBDeviceState state, const char* serial, void* userData) {if(state == OB_DEVICE_STATE_CONNECTED) {std::cout << "设备连接: " << serial << std::endl;}else if(state == OB_DEVICE_STATE_DISCONNECTED) {std::cout << "设备断开: " << serial << std::endl;}
}, nullptr);
八、开发流程与最佳实践

  1. 标准开发流程：

    // 1. 初始化上下文
auto context = ob::Context::create();
context->setLoggerSeverity(OB_LOG_SEVERITY_INFO);// 2. 枚举设备并选择
auto deviceList = context->queryDeviceList();
if(deviceList->deviceCount() == 0) {throw std::runtime_error("未发现设备");
}
auto device = deviceList->getDevice(0);// 3. 创建管道并配置流
auto pipeline = device->createPipeline();
auto config = pipeline->createConfig();// 配置深度流（640x480@30fps，16位深度）
auto depthSensor = device->getSensorList()->getSensor(OB_SENSOR_DEPTH);
auto depthProfiles = depthSensor->getStreamProfileList();
auto depthProfile = depthProfiles->getVideoStreamProfile(640, 480, OB_FORMAT_DEPTH_16U, 30);
config->enableStream(OB_SENSOR_DEPTH, depthProfile);// 配置彩色流（1280x720@30fps，RGB格式）
auto colorSensor = device->getSensorList()->getSensor(OB_SENSOR_COLOR);
auto colorProfiles = colorSensor->getStreamProfileList();
auto colorProfile = colorProfiles->getVideoStreamProfile(1280, 720, OB_FORMAT_RGB888, 30);
config->enableStream(OB_SENSOR_COLOR, colorProfile);// 启用深度到彩色的对齐
config->setAlignMode(OB_ALIGN_DEPTH_TO_COLOR);// 4. 启动流采集
pipeline->start(config);// 5. 循环获取并处理数据
while(true) {auto frameSet = pipeline->waitForFrames(1000);if(!frameSet) continue;// 获取深度帧和彩色帧auto depthFrame = frameSet->getFrame<ob::DepthFrame>(OB_FRAME_DEPTH);auto colorFrame = frameSet->getFrame<ob::ColorFrame>(OB_FRAME_COLOR);// 处理帧数据（显示、保存等）processFrames(depthFrame, colorFrame);
}// 6. 停止并释放资源
pipeline->stop();

  2. 性能优化建议：

    • 优先使用Pipeline而非直接操作Sensor，简化同步逻辑。
    • 根据场景选择合适的分辨率（如近距离交互用320x240提升帧率）。
    • 启用对齐模式时，确保彩色和深度流帧率一致（避免同步失效）。
    • 对深度图进行滤波时，优先使用硬件加速的内置滤波（如BilateralFilter）。

Orbbec SDK通过分层设计提供了从设备控制到三维重建的完整接口，核心类涵盖Context（全局管理）、Device（硬件控制）、Pipeline（流采集）、Frame（数据载体）、CoordinateTransformer（坐标转换）五大模块。掌握这些类的使用，可实现深度图像采集、点云生成、SLAM、手势识别等主流应用。实际开发中需结合具体设备型号的特性（如Femto的短距离高精度、Gemini的宽视场角），参考官方示例代码进行优化。

http://www.xdnf.cn/news/16101.html

相关文章：

  • 【CMake】CMake 常用语法总结
  • 到底可不可以用jion？jion如何优化？
  • 力扣-152.乘积最大子数组
  • 自己开发VUE之web网页打包技术毕业论文——仙盟创梦IDE
  • 【科研绘图系列】R语言绘制双侧坐标轴的条形图
  • NPM/Yarn完全指南：前端开发的“基石“与“加速器“
  • 第4章唯一ID生成器——4.1 分布式唯一ID
  • 电脑录屏软件推荐：如何使用oCam录制游戏、教程视频
  • ue4 优化
  • 完成多项问题修复，MaxKB开源企业级智能体平台v1.10.9 LTS版本发布
  • Webpack/Vite 终极指南：前端开发的“涡轮增压引擎“
  • 侯捷---c++面向对象高级编程
  • 制造工厂高效出图新技术——共享云桌面
  • JavaSE：学习输入输出编写简单的程序
  • list 介绍 及 底层
  • ESP32使用 vscode IDF 创建项目到烧录运行全过程
  • Flink-1.19.0源码详解8-ExecutionGraph生成-前篇
  • RabbitMQ简述
  • vue3 el-table 列数据合计
  • 在一个网页浏览器的控制台测试后端java是否支持SSE服务
  • Vulnhub Matrix-Breakout-2-Morpheus靶机攻略
  • 基于规则架构风格对业务的重构
  • 每日算法刷题Day52:7.24:leetcode 栈5道题，用时1h35min
  • RPG64.制作敌人攻击波数四:优化
  • 让复杂 AI 应用构建就像搭积木：Spring AI Alibaba Graph 使用指南与源码解读
  • 企业级数据分析创新实战：基于表格交互与智能分析的双引擎架构
  • es0102---语法格式、数据类型、整合springboot、创建库、创建映射、新增数据、自定义查询
  • 【Qt开发】信号与槽（一）
  • node.js中的fs与path模块
  • 主流摄像头协议及其开源情况，GB/T 28181协议介绍