# 从 main 分支迁移到开源 v2-main 分支 ## 引言 最初，奥比中光提供了一个**闭源 SDK — Orbbec SDK v1**，它构成了 [OrbbecSDK ROS2 Wrapper main 分支](https://github.com/orbbec/OrbbecSDK_ROS2/tree/main)的基础。虽然 ROS 封装层本身是开源的，但它依赖于闭源的底层 SDK。这种架构限制了灵活性，阻碍了社区驱动的改进。 随着开发者越来越需要透明性、可维护性和更广泛的设备支持，奥比中光发布了全新的开源 v2-main **— Orbbec SDK_v2** ([GitHub 链接](https://github.com/orbbec/OrbbecSDK/tree/v2-main))。基于此 SDK，[OrbbecSDK ROS2 的开源 v2-main 分支](https://github.com/orbbec/OrbbecSDK_ROS2)现在完全开源，提供了更好的可扩展性，并与奥比中光未来的产品路线图保持一致。 本文档介绍了将 ROS 包从 main 分支（基于 SDK v1）迁移到 v2-main 分支（基于 Orbbec SDK_v2）的动机和好处。它重点介绍了**启动文件、参数、话题和服务**的主要差异，并提供迁移指南帮助开发者顺利过渡。 **注意：** 在以下内容中，**main** 指闭源分支，而 **v2-main** 指开源 v2-main 分支。 ## 从 main 迁移到 v2-main 的优势 2024年10月，奥比中光发布了重大更新：**OrbbecSDK ROS2 Wrapper v2**，它完全基于开源的 Orbbec SDK_v2。与传统的 main 分支（SDK v1.x）相比，v2-main 分支（Orbbec SDK_v2.x）提供了更大的灵活性和可扩展性，同时为所有符合 UVC 标准的奥比中光 USB 产品提供全面支持。从 main --> v2-main 的迁移带来以下关键优势： ### **全面的设备支持** v2-main 分支支持所有符合 UVC 标准的奥比中光 USB 相机，并将成为支持所有新发布设备的主要平台。 ### **透明性和可扩展性** Orbbec SDK_v2 完全开源，允许开发者直接访问底层实现，便于调试、优化和二次开发。相比之下，SDK v1 是闭源的，引入了"黑盒"约束。 ### 维护和更新优势 v2-main 分支提供全功能支持，包括新功能开发、性能优化和错误修复。main 分支已进入仅维护模式，只有关键错误可能获得有限更新，不再开发新功能。 ### **社区和生态系统支持** 有了开源 SDK，开发者可以直接在 GitHub 或 Gitee 上提交问题和拉取请求，为功能演进做出贡献。这不仅加速了问题解决，还促进了更开放和活跃的奥比中光生态系统。 ## main 和 v2-main 分支的比较 ### **启动文件差异** 1. 在 v2-main 中，为 Gemini 330 系列添加了新的低功耗启动文件： - `gemini_330_series_low_cpu.launch.py` 2. v2-main 引入了对 **Gemini 435Le**、**Gemini 345** 和 **Gemini 345Lg** 相机的支持。 3. 由于 **OrbbecSDK_v2 仅支持 UVC 设备**，v2-main 中支持的相机型号范围比 main 略窄。详细信息见下表。 | **相机** | **main** | **v2-main** | | ---------------------------------- | ------------------------------------ | -------------------------------------------------- | | Gemini 435Le | 不支持 | gemini435_le.launch.py | | Gemini 345 | 不支持 | gemini345.launch.py | | Gemini 345Lg | 不支持 | gemini345_lg.launch.py | | Gemini 330 系列 | gemini_330_series.launch.py | gemini_330_series.launch.py | | Gemini 330 低CPU | - | gemini_330_series_low_cpu.launch.py | | Gemini 210 | gemini210.launch.py | gemini210.launch.py | | Gemini 2 | gemini2.launch.py | gemini2.launch.py | | Gemini 2L | gemini2L.launch.py | gemini2.launch.py | | Gemini 2XL | gemini2XL.launch.py | - | | Femto Bolt | femto_bolt.launch.py | femto_bolt.launch.py | | Femto Mega | femto_mega.launch.py | femto_mega.launch.py | | Femto | femto.launch.py | femto.launch.py | | Astra 2 | astra2.launch.py | astra2.launch.py | | Astra | astra.launch.py | astra.launch.py | | Astra Mini Pro / S Pro | astra_mini_pro.launch.py ... | astra.launch.py | | 多相机（同步） | multi_camera_synced.launch.py | multi_camera_synced.launch.py | | 多相机（通用/通用） | multi_camera.launch.py | multi_camera.launch.py 或 orbbec_multicamera.launch.py | | 单相机通用启动 | ob_camera.launch.py | orbbec_camera.launch.py | | OpenNI 设备（大白、得雅） | 对应型号独立文件 | 不支持 | ### **参数差异** **v2-main 中的新参数（main 中不可用）** | **参数名称** | **main** | **v2-main** | **描述** | | -------------------------------------- | -------- | ----------- | ---------------------------------------------- | | upgrade_firmware | - | 已添加 | 固件升级路径 | | preset_firmware_path | - | 已添加 | 预设固件文件路径 | | load_config_json_file_path | - | 已添加 | 加载 JSON 配置 | | export_config_json_file_path | - | 已添加 | 导出 JSON 配置 | | uvc_backend | - | 已添加 | libuvc / v4l2 后端选择 | | enable_color_auto_exposure_priority | - | 已添加 | AE 优先级控制 | | color_flip | - | 已添加 | 彩色图像垂直翻转 | | color_mirror | - | 已添加 | 彩色图像水平镜像 | | depth_flip | - | 已添加 | 深度图像垂直翻转 | | depth_mirror | - | 已添加 | 深度图像水平镜像 | | left_ir_flip | - | 已添加 | 左红外垂直翻转 | | left_ir_mirror | - | 已添加 | 左红外水平镜像 | | right_ir_flip | - | 已添加 | 右红外垂直翻转 | | right_ir_mirror | - | 已添加 | 右红外水平镜像 | | enable_left_ir_sequence_id_filter | - | 已添加 | 左红外序列 ID 滤波器 | | enable_right_ir_sequence_id_filter | - | 已添加 | 右红外序列 ID 滤波器 | | enable_accel_data_correction | - | 已添加 | 加速度计数据校正 | | enable_gyro_data_correction | - | 已添加 | 陀螺仪数据校正 | | enumerate_net_device | - | 已添加 | 自动枚举网络设备 | | net_device_ip | - | 已添加 | 网络设备 IP 地址 | | net_device_port | - | 已添加 | 网络设备端口 | | exposure_range_mode | - | 已添加 | 曝光范围模式：default / ultimate / regular | | disparity_to_depth_mode | - | 已添加 | 硬件视差到深度转换 | | ldp_power_level | - | 已添加 | LDP 功率级别 | | time_sync_period | - | 已添加 | 时间同步周期 | | gmsl_trigger_fps | - | 已添加 | GMSL 触发帧率 | | enable_gmsl_trigger | - | 已添加 | GMSL 触发启用 | | disparity_range_mode | - | 已添加 | 视差范围模式 | | disparity_search_offset | - | 已添加 | 视差搜索偏移 | | disparity_offset_config | - | 已添加 | 视差偏移配置 | | offset_index0 | - | 已添加 | 视差偏移索引 0 | | offset_index1 | - | 已添加 | 视差偏移索引 1 | | interleave_ae_mode | - | 已添加 | AE 交错模式 | | interleave_frame_enable | - | 已添加 | 交错帧启用 | | interleave_skip_enable | - | 已添加 | 跳过红外帧启用 | | interleave_skip_index | - | 已添加 | 跳过红外帧索引 | | hdr_index1_laser_control | - | 已添加 | HDR 激光控制参数 | | hdr_index1_depth_exposure | - | 已添加 | HDR 深度曝光 | | hdr_index1_depth_gain | - | 已添加 | HDR 深度增益 | | hdr_index1_ir_brightness | - | 已添加 | HDR 红外亮度 | | hdr_index1_ir_ae_max_exposure | - | 已添加 | HDR 红外最大 AE | | hdr_index0_laser_control | - | 已添加 | HDR 激光控制参数 | | hdr_index0_depth_exposure | - | 已添加 | HDR 深度曝光 | | hdr_index0_depth_gain | - | 已添加 | HDR 深度增益 | | hdr_index0_ir_brightness | - | 已添加 | HDR 红外亮度 | | hdr_index0_ir_ae_max_exposure | - | 已添加 | HDR 红外最大 AE | | laser_index1_laser_control | - | 已添加 | 激光交错控制 | | laser_index1_depth_exposure | - | 已添加 | 激光深度曝光 | | laser_index1_depth_gain | - | 已添加 | 激光深度增益 | | laser_index1_ir_brightness | - | 已添加 | 激光红外亮度 | | laser_index1_ir_ae_max_exposure | - | 已添加 | 激光红外最大 AE | | laser_index0_laser_control | - | 已添加 | 激光交错控制 | | laser_index0_depth_exposure | - | 已添加 | 激光深度曝光 | | laser_index0_depth_gain | - | 已添加 | 激光深度增益 | | laser_index0_ir_brightness | - | 已添加 | 激光红外亮度 | | laser_index0_ir_ae_max_exposure | - | 已添加 | 激光红外最大 AE | | software_trigger_enabled | - | 已添加 | 软件触发启用 | | enable_ptp_config | - | 已添加 | PTP 配置（Gemini 335Le） | | align_target_stream | - | 已添加 | 对齐目标流 | | spatial_fast_filter_radius | - | 已添加 | 快速空间滤波器半径 | | spatial_moderate_filter_diff_threshold | - | 已添加 | 中等空间滤波器差异阈值 | | spatial_moderate_filter_magnitude | - | 已添加 | 中等空间滤波器幅度 | | spatial_moderate_filter_radius | - | 已添加 | 中等空间滤波器半径 | | color.image_raw.enable_pub_plugins | - | 已添加 | 彩色图像传输插件 | | depth.image_raw.enable_pub_plugins | - | 已添加 | 深度图像传输插件 | | left_ir.image_raw.enable_pub_plugins | - | 已添加 | 左红外传输插件 | | right_ir.image_raw.enable_pub_plugins | - | 已添加 | 右红外传输插件 | | force_ip_enable | - | 已添加 | 强制 IP 功能 | | force_ip_mac | - | 已添加 | 强制 IP MAC 地址 | | force_ip_dhcp | - | 已添加 | DHCP 自动分配 | | force_ip_address | - | 已添加 | 强制 IP 静态地址 | | force_ip_subnet_mask | - | 已添加 | 强制 IP 子网掩码 | | force_ip_gateway | - | 已添加 | 强制 IP 网关 | **已移除参数（仅 main 有，v2-main 中已移除）** | **参数** | **描述** | | ------------------------------------ | ------------------------------------------------------------ | | enable_3d_reconstruction_mode | 3D 重建模式已弃用 | | enable_hardware_reset | 硬件重置接口已弃用 | | enable_hardware_noise_removal_filter | 硬件噪声去除滤波器已弃用 | | laser_on_off_mode | 旧激光开关接口，由 interleave / laser_index 替换 | | enable_3d_reconstruction_mode | 3D 重建模式重复；v2-main 中不再使用 | | device_preset | 部分逻辑迁移到新固件 / 交错参数 | | enable_trigger_out | 旧软件触发接口由 software_trigger_enabled 替换 | | retry_on_usb3_detection_failure | 可选；v2-main 中逻辑已调整或移除 | | enable_color_undistortion | 旧接口逻辑集成到其他地方；v2-main 中仍存在但使用可能已调整 | ### **话题差异** **v2-main** 在 main 基础上添加了以下话题： | **话题** | **main** | **v2-main** | **描述** | | --------------------- | -------- | ----------- | ------------------------------------------------------------ | | /camera/device_status | - | 已添加 | 发布设备状态（帧率延迟、设备连接状态等） | ### **服务差异** **v2-main** 在 main 基础上添加了以下服务： | **服务** | **main** | **v2-main** | **描述** | | ------------------------- | -------- | ----------- | ------------------------ | | get_ptp_config | - | 已添加 | 获取 PTP 配置 | | set_ptp_config | - | 已添加 | 设置 PTP 配置 | | get_streams_enable | - | 已添加 | 获取每个流的启用状态 | | set_streams_enable | - | 已添加 | 设置每个流的启用状态 | | get_user_calib_params | - | 已添加 | 获取用户校准参数 | | set_user_calib_params | - | 已添加 | 设置用户校准参数 | | read_customer_data | - | 已添加 | 读取用户存储的自定义数据 | | write_customer_data | - | 已添加 | 写入用户存储的自定义数据 | | send_software_trigger | - | 已添加 | 发送软件触发 | | set_color_ae_roi | - | 已添加 | 设置彩色图像的 AE ROI | | set_depth_ae_roi | - | 已添加 | 设置深度图像的 AE ROI | | set_color_flip | - | 已添加 | 设置彩色图像垂直翻转 | | set_depth_flip | - | 已添加 | 设置深度图像垂直翻转 | | set_color_rotation | - | 已添加 | 设置彩色图像旋转 | | set_depth_rotation | - | 已添加 | 设置深度图像旋转 | | set_left_ir_ae_roi | - | 已添加 | 设置左红外的 AE ROI | | set_right_ir_ae_roi | - | 已添加 | 设置右红外的 AE ROI | | set_left_ir_flip | - | 已添加 | 左红外垂直翻转 | | set_right_ir_flip | - | 已添加 | 右红外垂直翻转 | | set_left_ir_rotation | - | 已添加 | 左红外旋转 | | set_right_ir_rotation | - | 已添加 | 右红外旋转 | | set_reset_timestamp | - | 已添加 | 重置时间戳 | | set_sync_hosttime | - | 已添加 | 同步主机时间 | | set_sync_interleaverlaser | - | 已添加 | 交错激光同步 | | set_filter | - | 已添加 | 设置深度/点云滤波器 |