Version

6.6. 诊断与延迟分析工具

本节介绍帧连续性、时间戳和运行状态诊断工具。

6.6.1. 诊断工具:帧丢失日志与时间戳 CSV 记录

开启 enable_frame_drop_log 后,相机节点会在日志中输出彩色、深度、左右彩色和左右 IR 帧丢失统计,用于定位 SDK 接收阶段和 ROS 发布阶段的丢帧。设置 frame_timestamp_csv_file 后,相机节点会将 color、depth、left_color、right_color、left_ir、right_ir 以及已启用 IMU 流的时间戳记录到 CSV 文件,用于分析帧连续性、发布延迟和时间戳异常。启用帧同步(enable_frame_sync:=true)时,color 和 depth 时间戳会汇聚到同一个 CSV 文件中;未启用时分别写入 <stem>_color.csv 和 <stem>_depth.csv,左右彩色和左右 IR 始终分别写入带对应流名称后缀的文件。同步加速度计和陀螺仪数据写入 <stem>_imu.csv,独立加速度计和陀螺仪数据分别写入 <stem>_accel.csv 和 <stem>_gyro.csv。所有 CSV 文件遵循相同的分片规则。

roslaunch orbbec_camera gemini_330_series.launch \
enable_frame_drop_log:=true \
frame_timestamp_csv_file:=/tmp/frame_timestamp.csv

CSV 中包含 SDK frame index、hardware frame number、sensor timestamp、device/global/system timestamp、steady arrival/publish delta、ROS 发布耗时以及 SDK delay 等字段。

6.6.1.1. CSV 分片

每个 CSV 文件最多保存 1,024,575 行帧数据和 1 行表头。达到上限后,日志器会自动写入下一个带序号的文件,例如 frame_timestamp_1.csv、frame_timestamp_2.csv。

6.6.1.2. 时间戳 CSV 字段说明

当前 CSV 按图像流包含同构字段组。同步记录中的 color 和 depth 字段分别以 color_ 和 depth_ 为前缀;独立记录还会使用 left_color_、right_color_、left_ir_ 和 right_ir_ 等流名称前缀。每组字段定义一致,仅数据来源不同。

字段后缀 描述 单位/说明
_sdk_frame_index SDK 帧序号 frame->index()
_hardware_frame_number 硬件帧序号 frame->getMetadataValue(OB_FRAME_METADATA_TYPE_FRAME_NUMBER)
_sensor_ts_sec 传感器时间戳 秒,通常为曝光时间中点
_sensor_ts_delta_us 传感器时间戳相邻帧差值 us
_device_ts_sec 设备时钟时间戳 秒
_device_ts_delta_us 设备时钟相邻帧差值 us
_global_ts_sec global 时间戳 秒
_global_ts_delta_us global 时间戳相邻帧差值 us
_system_ts_sec SDK 的 system 时间戳 秒
_system_ts_delta_us SDK system 时间戳相邻帧差值 us
_arrival_steady_delta_us 到达主机 steady 时间相邻帧差值 us
_publish_steady_delta_us 发布前主机 steady 时间相邻帧差值 us
_arrival_to_publish_steady_us ROS 收到帧到发布的耗时(steady) publish_steady - arrival_steady
_sdk_delay_from_global_us SDK 发布延迟(global 参照) arrival_system - global_ts
_sdk_delay_from_system_us SDK 发布延迟(system 参照) arrival_system - sdk_system_ts

6.6.1.3. 时间戳 CSV 分析方法

6.6.1.3.1. 通过 CSV 判断硬件丢帧

  • 查看 _hardware_frame_number 是否连续。

  • 查看 _sensor_ts_delta_us 的折线图或散点图,观察是否存在明显跳变。

  • 例如在 30 fps 下,相邻帧时间差通常应接近 33333 us。

6.6.1.3.2. 通过 CSV 判断 SDK/ROS 丢帧

  • 查看 _sdk_frame_index 是否连续。

  • 查看 _device_ts_delta_us、_global_ts_delta_us 和 _system_ts_delta_us 的折线图或散点图,观察是否存在跳变。

  • 开启 enable_frame_drop_log 后,日志中的 stage=SDK_RECEIVE 表示 SDK 接收阶段检测到丢帧,stage=ROS_PUBLISH 表示 ROS 发布阶段检测到丢帧。

6.6.1.3.3. 通过 CSV 判断延迟

  • SDK 延迟:查看 _sdk_delay_from_global_us 和 _sdk_delay_from_system_us 的折线图或散点图,用于观察帧从底层时间戳到到达 ROS 节点之间的延迟变化。

  • ROS 延迟:查看 _arrival_to_publish_steady_us 的折线图或散点图,用于统计 ROS 侧从 SDK 回调拿到帧到发布图像的耗时。

  • 如果需要更接近真实处理耗时,优先参考 steady 时钟相关字段。

6.6.1.3.4. 时间戳 CSV 同步说明

当前这份 CSV 主要用于分析各图像流的连续性和延迟,不能直接用于统计彩色与深度之间的同步效果。

6.6.2. monitor_fd.sh

monitor_fd.sh 用于每秒打印相机相关进程的文件描述符数量,适合检查长时间运行时是否存在文件描述符泄漏。

cd src/OrbbecSDK_ROS1/scripts
./monitor_fd.sh