tf_bag_analysis

A small ROS 2 (Humble+) command-line tool that inspects a rosbag2 (.mcap or .db3) and produces a statistics report about its TF2 contents.

It answers questions like:

• How many TF topics are in this bag? How many are at the root (/tf, /tf_static) vs. inside a robot/sub-system namespace (<ns>/tf, <ns>/tf_static)?
• What coordinate frames appear on each TF topic? What is their union, and how do they split by namespace?
• For each parent→child edge: how many times was it broadcast, over what time span, and at what effective rate?
• When does TF publication start and end, and what is the overall duration?

Output goes to the terminal as a plain-text summary, and (optionally) to a Markdown file that also embeds a per-namespace Mermaid TF graph.

Build

As any ROS 2 package, drop it into your workspace src/ and build:

source /opt/ros/humble/setup.bash
colcon build --packages-select tf_bag_analysis
source install/setup.bash

Usage

ros2 run tf_bag_analysis tf_bag_analysis <bag_path> [--md <report.md>]

<bag_path> can be:

• a rosbag2 directory (containing metadata.yaml), or
• a single .mcap / .db3 file.

Examples:

# Plain text report to stdout
ros2 run tf_bag_analysis tf_bag_analysis my_bag/

# Text summary + Markdown report with Mermaid diagrams
ros2 run tf_bag_analysis tf_bag_analysis my_bag.mcap --md tf_report.md

What it reports

• Topic summary: total number of TF topics, split into root vs. namespaced, and tf vs. tf_static. Distinct namespaces are listed.
• Bag time range: first/last message time and duration (seconds).
• Per-topic statistics: message count, total transforms, duration, effective message rate (Hz), number of distinct edges.
• Per-topic frames and edges: the set of frame IDs on each topic and, for every (parent, child) pair, its count, rate and time span.
• All frames: union of frame IDs, and a per-namespace breakdown.
• TF graph (Markdown only): a Mermaid graph LR diagram per namespace, drawn from the union of all edges seen on that namespace's TF topics.

Dependencies

• rclcpp
• rosbag2_cpp, rosbag2_storage (+ default storage plugins)
• tf2_msgs, geometry_msgs

License

BSD-3-Clause. See LICENSE.