Version
中文 | English

6.6. Diagnostic and Latency Analysis Tools

This section describes frame continuity, timestamp, topic statistics, end-to-end latency, and debugging helper tools.

6.6.1. Frame Drop Log and Timestamp CSV Recording

After enable_frame_drop_log is enabled, the camera node prints frame drop statistics for color, depth, left color, right color, left IR, and right IR in the log. This helps locate frame drops at the SDK receive stage and ROS publish stage. When frame_timestamp_csv_file is set, the camera node records timestamp data for color, depth, left_color, right_color, left_ir, right_ir, and enabled IMU streams to CSV files for analyzing frame continuity, publish latency, and timestamp anomalies. When frame synchronization (enable_frame_sync:=true) is enabled, color and depth timestamps are combined into one CSV file; otherwise, they are written to separate <stem>_color.csv and <stem>_depth.csv files. Left color, right color, left IR, and right IR are always written to separate files with the corresponding stream-name suffix. Synchronized accelerometer and gyroscope data are written to <stem>_imu.csv, while standalone accelerometer and gyroscope data are written to <stem>_accel.csv and <stem>_gyro.csv. All CSV files follow the same rotation rule.

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

The CSV contains SDK frame index, hardware frame number, sensor timestamp, device/global/system timestamp, steady arrival/publish delta, ROS publish duration, and SDK delay fields.

6.6.1.1. CSV Rotation

Each CSV file contains at most 1,024,575 frame rows plus the header. When the limit is reached, the logger automatically starts the next indexed file, for example frame_timestamp_1.csv and frame_timestamp_2.csv.

6.6.1.2. Field Description

The CSV contains groups of identically structured fields for each image stream. In synchronized records, the color and depth groups use the color_ and depth_ prefixes; standalone records also use prefixes such as left_color_, right_color_, left_ir_, and right_ir_. The groups have identical definitions and differ only in data source.

Field suffix Description Unit / Notes
_sdk_frame_index SDK frame index frame->index()
_hardware_frame_number Hardware frame number frame->getMetadataValue(OB_FRAME_METADATA_TYPE_FRAME_NUMBER)
_sensor_ts_sec Sensor timestamp Seconds, usually exposure midpoint
_sensor_ts_delta_us Delta between adjacent sensor timestamps us
_device_ts_sec Device clock timestamp Seconds
_device_ts_delta_us Delta between adjacent device timestamps us
_global_ts_sec Global timestamp Seconds
_global_ts_delta_us Delta between adjacent global timestamps us
_system_ts_sec SDK system timestamp Seconds
_system_ts_delta_us Delta between adjacent SDK system timestamps us
_arrival_steady_delta_us Delta between adjacent host steady arrival times us
_publish_steady_delta_us Delta between adjacent host steady times before publishing us
_arrival_to_publish_steady_us Time from ROS receiving the frame to publishing it (steady) publish_steady - arrival_steady
_sdk_delay_from_global_us SDK publish delay (global reference) arrival_system - global_ts
_sdk_delay_from_system_us SDK publish delay (system reference) arrival_system - sdk_system_ts

6.6.1.3. Analysis Methods

6.6.1.3.1. Hardware Frame Drop Detection

  • Check whether _hardware_frame_number is continuous.

  • Plot _sensor_ts_delta_us as a line chart or scatter plot and check for obvious jumps.

  • For example, at 30 fps, the adjacent frame interval should usually be close to 33333 us.

6.6.1.3.2. SDK / ROS Frame Drop Detection

  • Check whether _sdk_frame_index is continuous.

  • Plot _device_ts_delta_us, _global_ts_delta_us, and _system_ts_delta_us as line charts or scatter plots and check for jumps.

  • After enable_frame_drop_log is enabled, stage=SDK_RECEIVE in the log indicates frame drops detected at the SDK receive stage, and stage=ROS_PUBLISH indicates frame drops detected at the ROS publish stage.

6.6.1.3.3. Latency Analysis

  • SDK latency: check _sdk_delay_from_global_us and _sdk_delay_from_system_us as line charts or scatter plots to observe delay changes from the low-level timestamp to arrival at the ROS node.

  • ROS latency: check _arrival_to_publish_steady_us as a line chart or scatter plot to measure the time from the SDK callback receiving a frame to publishing the image on the ROS side.

  • If you need a value closer to real processing time, prefer fields related to the steady clock.

6.6.1.3.4. Synchronization Note

This CSV is mainly used to analyze continuity and latency for each image stream. It cannot directly measure synchronization between color and depth.

6.6.2. topic_statistics_node

topic_statistics_node uses ROS 2 topic statistics to collect image topic age and period statistics and writes statistics.csv in the current directory. The camera node must be running before using it.

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 subscribes to a specified topic and calculates end-to-end latency from the message header stamp, while also printing FPS. It supports image, points, imu, metadata, camera_info, rgbd, imu_info, and tf topic types. The camera node must be running before using it.

ros2 run orbbec_camera frame_latency_node \
--ros-args \
-p topic_name:=/camera/color/image_raw \
-p topic_type:=image

Point cloud topic example:

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 prints the file descriptor count of the component_container process once per second. It is useful for checking file descriptor leaks. The target process must be running before using it.

cd orbbec_camera/scripts
./monitor_fd.sh

6.6.5. plot_stat.py

plot_stat.py reads statistics.csv from the current directory and plots age and period curves from topic statistics. It is usually used together with topic_statistics_node.

cd <directory-containing-statistics.csv>
python3 /path/to/orbbec_camera/scripts/plot_stat.py

6.6.6. receive_pc.py

receive_pc.py subscribes to /camera/depth/points and quickly verifies whether a Python node can receive the point cloud topic. Start the camera node and enable point cloud before using it.

python3 orbbec_camera/scripts/receive_pc.py