# 诊断与延迟分析工具 本节介绍帧连续性、时间戳和运行状态诊断工具。 ## 诊断工具:帧丢失日志与时间戳 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 文件中;未启用时分别写入 `_color.csv` 和 `_depth.csv`,左右彩色和左右 IR 始终分别写入带对应流名称后缀的文件。同步加速度计和陀螺仪数据写入 `_imu.csv`,独立加速度计和陀螺仪数据分别写入 `_accel.csv` 和 `_gyro.csv`。所有 CSV 文件遵循相同的分片规则。 ```bash 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 等字段。 ### CSV 分片 每个 CSV 文件最多保存 `1,024,575` 行帧数据和 1 行表头。达到上限后,日志器会自动写入下一个带序号的文件,例如 `frame_timestamp_1.csv`、`frame_timestamp_2.csv`。 ### 时间戳 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` | ### 时间戳 CSV 分析方法 #### 通过 CSV 判断硬件丢帧 - 查看 `_hardware_frame_number` 是否连续。 - 查看 `_sensor_ts_delta_us` 的折线图或散点图,观察是否存在明显跳变。 - 例如在 30 fps 下,相邻帧时间差通常应接近 33333 us。 #### 通过 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 发布阶段检测到丢帧。 #### 通过 CSV 判断延迟 - SDK 延迟:查看 `_sdk_delay_from_global_us` 和 `_sdk_delay_from_system_us` 的折线图或散点图,用于观察帧从底层时间戳到到达 ROS 节点之间的延迟变化。 - ROS 延迟:查看 `_arrival_to_publish_steady_us` 的折线图或散点图,用于统计 ROS 侧从 SDK 回调拿到帧到发布图像的耗时。 - 如果需要更接近真实处理耗时,优先参考 steady 时钟相关字段。 #### 时间戳 CSV 同步说明 当前这份 CSV 主要用于分析各图像流的连续性和延迟,不能直接用于统计彩色与深度之间的同步效果。 ## monitor_fd.sh `monitor_fd.sh` 用于每秒打印相机相关进程的文件描述符数量,适合检查长时间运行时是否存在文件描述符泄漏。 ```bash cd src/OrbbecSDK_ROS1/scripts ./monitor_fd.sh ```