7.1. 从 main 分支迁移到开源 v2-main 分支
7.1.1. 引言
最初，奥比中光提供了一个闭源 SDK — Orbbec SDK v1，它构成了 OrbbecSDK ROS2 Wrapper main 分支的基础。虽然 ROS 封装层本身是开源的，但它依赖于闭源的底层 SDK。这种架构限制了灵活性，阻碍了社区驱动的改进。
随着开发者越来越需要透明性、可维护性和更广泛的设备支持，奥比中光发布了全新的开源 v2-main — Orbbec SDK_v2 (GitHub 链接)。基于此 SDK，OrbbecSDK ROS2 的开源 v2-main 分支现在完全开源，提供了更好的可扩展性，并与奥比中光未来的产品路线图保持一致。
本文档介绍了将 ROS 包从 main 分支（基于 SDK v1）迁移到 v2-main 分支（基于 Orbbec SDK_v2）的动机和好处。它重点介绍了启动文件、参数、话题和服务的主要差异，并提供迁移指南帮助开发者顺利过渡。
注意： 在以下内容中，main 指闭源分支，而 v2-main 指开源 v2-main 分支。
7.1.2. 从 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 的迁移带来以下关键优势：
7.1.2.1. 全面的设备支持
v2-main 分支支持所有符合 UVC 标准的奥比中光 USB 相机，并将成为支持所有新发布设备的主要平台。
7.1.2.2. 透明性和可扩展性
Orbbec SDK_v2 完全开源，允许开发者直接访问底层实现，便于调试、优化和二次开发。相比之下，SDK v1 是闭源的，引入了"黑盒"约束。
7.1.2.3. 维护和更新优势
v2-main 分支提供全功能支持，包括新功能开发、性能优化和错误修复。main 分支已进入仅维护模式，只有关键错误可能获得有限更新，不再开发新功能。
7.1.2.4. 社区和生态系统支持
有了开源 SDK，开发者可以直接在 GitHub 或 Gitee 上提交问题和拉取请求，为功能演进做出贡献。这不仅加速了问题解决，还促进了更开放和活跃的奥比中光生态系统。
7.1.3. main 和 v2-main 分支的比较
7.1.3.1. 启动文件差异
在 v2-main 中，为 Gemini 330 系列添加了新的低功耗启动文件：
gemini_330_series_low_cpu.launch.py
v2-main 引入了对 Gemini 435Le、Gemini 345 和 Gemini 345Lg 相机的支持。
由于 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 设备（大白、得雅） | 对应型号独立文件 | 不支持 |
7.1.3.2. 参数差异
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 中仍存在但使用可能已调整 |
7.1.3.3. 话题差异
v2-main 在 main 基础上添加了以下话题：
| 话题 | main | v2-main | 描述 |
|---|---|---|---|
| /camera/device_status | - | 已添加 | 发布设备状态（帧率延迟、设备连接状态等） |
7.1.3.4. 服务差异
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 | - | 已添加 | 设置深度/点云滤波器 |