event_camera_tools

This repository holds ROS tools for displaying and converting event_camera_msgs. These messages are produced by the metavision_driver and the libcaer_driver. For converting legacy dvs_msgs and prophesee_event_msgs messages, see the event_camera_legacy_tools repository.

Supported platforms

NOTE: ROS1 support has been discontinued but the code has been left in place and may still compile. ROS2 is supported for ROS2 Humble and later distros.

How to build

Set the following shell variables:

repo=event_camera_tools
url=https://github.com/ros-event-camera/${repo}.git

and follow the instructions here

Tools

Real-time monitoring tools

• ros2 run event_camera_tools echo [-b <bag>] [-t (only triggers)] [-n (no header printed)] <topic>

  Displays messages in event_camera_msgs format, optionally from a bag file. Example output:

  -------------------------------
  res:  640  height:  480 enc: evt3
  header stamp: 1664227781775114816
  time base:        0
  seqno:   129213
  ---
  6851488000 edge: 1  id:  6
  6851510000  390  223 1
  6851520000   33  326 0
  ...

• ros2 run event_camera_tools perf <topic>

  Sample output:

  msgs:   219.48/s drp:  0 del: 13.72ms drft:  0.0297ms jit:  0.3296ms ev:   0.0823 M/s %ON:  46 tr:  1758.38 1/s %UP:  50
  msgs:   249.01/s drp:  0 del:  4.35ms drft: -0.0031ms jit:  0.2503ms ev:   0.8497 M/s %ON:  52 tr:  1999.56 1/s %UP:  49
   

The meaning of the fields is as follows:

• msgs message rate per seconds
• drp number of drops per second (skip in sequence numbers)
• del delay: average time difference between message header stamp and arrival time. This includes the delay due to the driver aggregating messages.
• drft accumulated (from start of “perf”) drift between message header stamp and sensor-provided time.
• jit measured jitter of ROS time stamps vs sensor time stamps.
• ev event rate in millions/sec
• %ON ratio of ON events to total (ON + OFF) events
• tr rate of trigger messages

• %UP ratio of UP trigger edges to total (UP + DOWN)

• ros2 run event_camera_tools sync_test <cam_0_event_topic> <cam_1_event_topic>

  The output gives the average sensor time difference and how many samples where counted:

  avg sensor diff:  0.00846s, count:   360
  avg sensor diff:  0.00377s, count:   466
  ...
  

• ros2 run event_camera_tools trigger_delay -t <camera_image_topic> [-d (use down trigger edge)] <event_topic>

  Use this tool to verify synchronization setup when the sync pulse from a frame based camera is connected to an event camera. The tool compares the time stamp of the trigger event with that of the image frame, and gives the time by which the trigger event is delayed with respect to the frame. This time is usually negative, meaning the trigger event occurs before the frame based camera driver puts a header stamp on the image. A typical output will look like this:

  [INFO] [1763569527.811228122] [trigger_delay]: frame rate:   1.000 Hz, trigger rate:   1.000 Hz, trigger delay: -3.531 ms +/- 0.497 ms
  [INFO] [1763569528.811002310] [trigger_delay]: frame rate:   1.000 Hz, trigger rate:   1.000 Hz, trigger delay: -3.868 ms +/- 0.418 ms
  

• ros2 run event_camera_tools event_rate [-b bag] [-r <rate_file>] [-t <trigger_file>] [-p period_ns] <ros_topic>

  Counts the number of events in a fixed interval of length period (in nanoseconds), and writes it to rate_file. The first column is the ROS time stamp, the second sensor time, then the number of OFF and ON events, and the number of UP and DOWN edge external trigger events. The external trigger events are also written to a separate file (trigger_file) with

File truncated at 100 lines see the full file

Changelog for package event_camera_tools

3.1.2 (2026-04-07)

• rely on event_camera_codecs and _msgs packages
• Remove unused include of rosbag2_cpp/typesupport_helpers.hpp This header file was removed in Jazzy (rosbag2 release 0.26.10). Since nothing seems to use this header file, let's remove it. This fixes the following compile error: In file included from src/raw_to_bag.cpp:20: include/event_camera_tools/ros_compat.h:29:10: fatal error: rosbag2_cpp/typesupport_helpers.hpp: No such file or directory 29 | #include <rosbag2_cpp/typesupport_helpers.hpp> | \^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
• added sanity checks for event_statistics
• use header for raw_to_bag
• improve trigger delay, compute stddev of delay
• added jitter measurement
• Contributors: Bernd Pfrommer, Michal Sojka

3.1.1 (2025-12-08)

• Merge branch 'master' into release
• added opencv dependency to package file
• Contributors: Bernd Pfrommer

3.1.0 (2025-12-08)

• first release
• Contributors: Bernd Pfrommer, Dhruv Patel, YLFeng