ROS File System Tools: rosbag | roscreate | rosdep | rosmake | rosmsg | rossrv | rospack | rosstack | roswtf | rxdeps

ROS Graph Tools: rosbag | roscore | rosgraph | roslaunch | rosnode | rosparam | rosplay | rosrecord | rosservice | rostopic | roswtf | rxconsole | rxplot | rxgraph | rxbag

Package Summary

This is a set of tools for recording from and playing back to ROS topics. It is intended to be high performance and avoids deserialization and reserialization of the messages.

• Author: Jeremy Leibs (leibs@willowgarage.com), James Bowman (jamesb@willowgarage.com), Ken Conley (kwc@willowgarage.com), and Tim Field (tfield@willowgarage.com)
• License: BSD
• Repository: ros (https://code.ros.org/svn/ros)

Overview

rosbag is a unified tool for working with bags. It is a replacement for the previous tools in the rosrecord and rosbagmigration packages. See the section on mappings to old tools to learn about how to convert old usages to the new syntax. For technical details on the contents of bag files, please see: bag file format.

Roadmap and Stability

rosbag is new in ROS-0.11. For now it simply works as a wrapper around the existing bag tools. The command line API, however, is intended to remain stable, whereas the other tools such as rosrecord are expected to go away. rosbag does not yet support a programmatic API for bag reading/writing, but this is planned for a future release.

rosbag will be seeing substantial development in the future with the development of a new programmatic API, porting of internals to a first-class implementation using this new API, and introduction of a ROS-API for ROS-based control of recording and playback. Please see the ROS/Roadmap for more information.

Command line API

rosbag supports the following sub-commands:

• info

  • Summarize the contents of a bag file.

  play

  • Play back the contents of one or more bag files in a time-synchronized fashion.

  record

  • Record a bag file with the contents of specified topics.

  check

  • Determine whether a bag is playable in the current system, or if it can be migrated to be played.

  fix

  • Repair a bag file so that it can be played in the current system.

  filter

  • Convert a bag file using Python expressions.

  compress (ROS 1.1+)

  • Compress a bag file.

  decompress (ROS 1.1+)

  • Decompress a bag file.

  reindex (ROS 1.1+)

  • Reindex a broken bag file.

Info

Usage: rosbag info BAGFILE

Summarize the contents of a bag file.

Options:
  -h, --help            show this help message and exit
  --try-future-version  still try to open a bag file, even if the version
                        number is not known to the player

This will output the contents of the bag file in a parsable YAML format.

Example usage:

$ rosbag info foo.bag
bag: foo.bag
version: 1.2
start_time: 1261169208377372000
end_time: 1261169210377295000
length: 1999923000
topics:
  - name: foo
    count: 21
    datatype: std_msgs/String
    md5sum: 1d35f58e160f19a7dc1ed780b6672098

Play

Usage: rosbag play BAGFILE1 [BAGFILE2 BAGFILE3 ...]

Play back the contents of one or more bag files in a time-synchronized
fashion.

Options:
  -h, --help            show this help message and exit
  -q, --quiet           suppress console output
  -i, --immediate       play back all messages without waiting
  --pause               start in paused mode
  --queue=SIZE          use an outgoing queue of size SIZE (defaults to 0)
  --clock               publish the clock time
  --hz=HZ               Use a frequency of HZ when publishing clock time
                        (default: 100)
  -d SEC, --delay=SEC   Sleep SEC seconds after every advertise call (to allow
                        subscribers to connect).
  -r FACTOR, --rate=FACTOR
                        multiply the publish rate by FACTOR
  -s SEC, --start=SEC   start SEC seconds into the bag files
  --try-future-version  Still try to open a bagfile, even if the version
                        number is not known to the player.

rosbag play will take the contents of one or more bag file, and play them back in a time-synchronized fashion. Time synchronization occurs based on the global time-stamps at which messages were received. Playing will begin immediately, and then future messages will be published according to the relative offset times. If two separate bag files are used, they are treated as a single bag with interlaced times according to the timestamps. This means if you record one bag, wait an hour, and record a second bag, when you play them back together you will have an hour-long dead period in the middle of your playback.

If you do not want to observe playback timing, the -i option will playback all messages from the file as fast as possible. Note that for large files this will often lead to exceeding your incoming buffers.

Additionally, during playing, you can pause at any time by hitting space. When paused, you can step through messages by pressing s.

Example usage:

rosbag play demo_log.bag
rosbag play topics1.bag topics2.bag
rosbag play -i demo_log.bag

Record

Usage: rosbag record TOPIC1 [TOPIC2 TOPIC3 ...]

Record a bag file with the contents of specified topics.

Options:
  -h, --help            show this help message and exit
  -a, --all             record all topics
  -q, --quiet           suppress console output
  -o PREFIX, --output-prefix=PREFIX
                        prepend PREFIX to beginning of bag name (name will
                        always end with date stamp)
  -O NAME, --output-name=NAME
                        record to bag with name NAME.bag
  --split=SIZE          split bag into files of size SIZE MB
  -b SIZE, --buffsize=SIZE
                        use in internal buffer of SIZE MB (Default: 256, 0 =
                        infinite)
  -l NUM, --limit=NUM   only record NUM messages on each topic

rosbag record will generate a ".bag" file (so named for historical reasons) with the contents of all topics that you pass to it. The file simply contains interlaced, serialized ROS messages dumped directly to a single file as they come in over the wire. This is the most performance and disk-friendly recording format possible. If you are recording messages at a high bandwidth, such as from cameras, it is strongly recommended you run rosbag record on the same machine as the camera, and specify the file destination as being on the local machine disk.

If you run rosbag record with the -a option, it will attempt to record ALL messages available in the system. However, since this information requires polling the master periodically, it will likely miss the first several messages published on any topic.

Example usage:

rosbag record chatter babble
rosbag record -a

Check

Usage: rosbag check BAG [-g RULEFILE] [EXTRARULES1 EXTRARULES2 ...]

Options:
  -h, --help            show this help message and exit
  -g RULEFILE, --genrules=RULEFILE
                        generate a rulefile named RULEFILE
  -a, --append          append to the end of an existing rulefile after
                        loading it
  -n, --noplugins       do not load rulefiles via plugins

rosbag check determines whether or not a bag file is playable in the current system.

To check whether a bag can be played:

$ rosbag check foo.bag

If a bag is currently unplayable and non-migratable, it may be necessary to generate rules to bring the bag up to date. See Migrating Messages for the preferred approaches to doing this.

Fix

Usage: rosbag fix INBAG OUTBAG [EXTRARULES1 EXTRARULES2 ...]

Options:
  -h, --help       show this help message and exit
  -n, --noplugins  do not load rulefiles via plugins

The rosbag fix tool actually repairs a bag using registered rules.

To repair a bag for which rules exist to fix messages

$ rosbag fix in.bag out.bag

Like with checkbag.py, locally defined rules, such as those created with rosbag check -g, can also be passed in as optional arguments:

$ rosbag fix in.bag out.bag myrules.bmr

Filter

Usage: rosbag filter INBAG OUTBAG EXPRESSION

EXPRESSION can be any Python-legal expression.

The following variables are available:
 * topic: name of topic
 * m: message
 * t: time of message (t.secs, t.nsecs)


Options:
  -h, --help            show this help message and exit
  --print=PRINT-EXPRESSION
                        Python expression to print for verbose debugging. Uses
                        same variables as filter-expression

rosbag filter is a command-line tool for converting bag files using Python expressions. The Python expression can access any of the Python builtins plus:

• topic: the topic of the message

• m: the message

• t: time of message. The time is represented as a rospy Time object (t.secs, t.nsecs)

Example usage:

rosbag filter chatter.bag rebag.bag "'1' in m.data"

In order to test the filter pattern that you pass in, you can also pass in a print expression. For example:

rosbag filter --print "m.data" chatter.bag rebag.bag "'1' in m.data"

Example output:

NO MATCH hello world 68
NO MATCH hello world 69
NO MATCH hello world 70
MATCH hello world 71
NO MATCH hello world 72
NO MATCH hello world 73

Compress

Usage: rosbag compress [options] BAGFILE1 [BAGFILE2 ...]

Compress one or more bag files.

Options:
  -h, --help   show this help message and exit
  -f, --force  force overwriting of backup file if it exists
  -q, --quiet  suppress noncritical messages

rosbag compress (ROS 1.1+) is a command-line tool for compressing bag files. A backup of each bag file is made before the bag is compressed.

Decompress

Usage: rosbag decompress [options] BAGFILE1 [BAGFILE2 ...]

Decompress one or more bag files.

Options:
  -h, --help   show this help message and exit
  -f, --force  force overwriting of backup file if it exists
  -q, --quiet  suppress noncritical messages

rosbag decompress (ROS 1.1+) is a command-line tool for decompressing bag files. A backup of each bag file is made before the bag is decompressed.

Reindex

Usage: rosbag reindex [options] BAGFILE1 [BAGFILE2 ...]

Reindexes one or more bag files.

Options:
  -h, --help   show this help message and exit
  -f, --force  force overwriting of backup file if it exists
  -q, --quiet  suppress noncritical messages

rosbag reindex (ROS 1.1+) is a command-line tool for repairing broken bag files. If a bag was not closed cleanly for any reason, then the index information may be corrupted. Use this tool to reread the message data and rebuild the index.

Mapping to old tools

rosrecord

rosrecord has become rosbag record. Changes of note:

• Attribute	rosrecord	rosbag record
  Filename (with date suffix)	-f	-o
  Filename	-F	-O
  Internal buffer	-m	-b or --buffsize
  Message limiting	-c	-l or --limit

rosplay

rosplay has become rosbag play. Changes of note:

• Attribute	rosplay	rosbag play
  Check bag	-c	N/A: Use rosbag info
  Queue	-q	--queue
  Clock	-b	--clock and --hz
  Delay (after advertise)	-s	-d
  Start offset	-t	-s or --start
  Immediate playback	-a	-i
  No display	-n	-q

rosrebag

rosrebag has become rosbag filter. The syntax has not changed.

rosbagmigration checkbag.py

rosbagmigration checkbag.py has become rosbag check. The syntax has not changed.

rosbagmigration fixbag.py

rosbagmigration fixbag.py has become rosbag fix. The syntax has not changed.

C++ API

There is not yet a C++ API as part of rosbag. If you need to read or write a bag from within a C++ program, look at the rosrecord C++ programmatic API.

Python API

There is not yet a python API as part of rosbag. If you need to read or write a bag from within a python program, look at the rosrecord python programmatic API.