6.6. 诊断与延迟分析工具
本节介绍帧连续性、时间戳、topic statistics、端到端延迟和调试辅助工具。
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 文件遵循相同的分片规则。
ros2 launch orbbec_camera gemini_330_series.launch.py \
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 按图像流包含同构字段组。同步记录中的 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. 分析方法
6.6.1.3.1. 硬件丢帧判断
查看
_hardware_frame_number是否连续。查看
_sensor_ts_delta_us的折线图或散点图，观察是否存在明显跳变。例如在 30 fps 下，相邻帧时间差通常应接近 33333 us。
6.6.1.3.2. 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. 延迟判断
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 主要用于分析各图像流的连续性和延迟，不能直接用于统计彩色与深度之间的同步效果。
6.6.2. topic_statistics_node
topic_statistics_node 使用 ROS 2 topic statistics 统计图像 topic 的 age 和 period，并在当前目录生成 statistics.csv。使用前需要先启动相机节点。
ros2 run orbbec_camera topic_statistics_node \
--ros-args \
-p image_topic:=/camera/color/image_raw \
-p statistics_topic:=/statistics
6.6.3. frame_latency_node
frame_latency_node 订阅指定 topic，按消息 header stamp 计算端到端延迟并输出 FPS。它支持 image、points、imu、metadata、camera_info、rgbd、imu_info、tf 等 topic 类型。使用前需要先启动相机节点。
ros2 run orbbec_camera frame_latency_node \
--ros-args \
-p topic_name:=/camera/color/image_raw \
-p topic_type:=image
统计点云 topic：
ros2 run orbbec_camera frame_latency_node \
--ros-args \
-p topic_name:=/camera/depth/points \
-p topic_type:=points
6.6.4. monitor_fd.sh
monitor_fd.sh 每秒统计 component_container 进程的文件描述符数量，用于排查文件描述符泄漏。使用前需要目标进程正在运行。
cd orbbec_camera/scripts
./monitor_fd.sh
6.6.5. plot_stat.py
plot_stat.py 读取当前目录下的 statistics.csv，绘制 topic statistics 中 age 和 period 的曲线。通常与 topic_statistics_node 配合使用。
cd <statistics.csv所在目录>
python3 /path/to/orbbec_camera/scripts/plot_stat.py
6.6.6. receive_pc.py
receive_pc.py 订阅 /camera/depth/points，用于快速验证 point cloud topic 是否可被 Python 节点接收。使用前需要先启动相机节点并开启点云。
python3 orbbec_camera/scripts/receive_pc.py