Usage

The 1.2 bag format is used by ROS releases from 0.5.0 to 1.0.x. The primary differences compared to 1.1 are that 1.2 organizes the message metadata in a more extensible manner, and stores the full text of each message definition, instead of just the type and md5sum. This information was added to improve bag longevity by allowing for tools that manipulate a bag after the message types stored within have been changed, moved, or deleted.

Format

Following the version line, records are written, one after the other:

#ROSRECORD V1.2
<record 1><record 2>....<record N>

Each record has the following format:

<header_len><header><data_len><data>

Name

Description

Format

Length

header_len

length, in bytes, of the header to follow

little-endian integer

4 bytes

header

metadata for the record

(see below)

header_len bytes

data_len

length, in bytes, of the data to follow

little-endian integer

4 bytes

data

record specific data

(see below)

data_len bytes

Header format

Each record header (the header field that precedes the data) contains a sequence of name=value fields, formatted as follows:

<field1_len><field1_name>=<field1_value><field2_len><field2_name>=<field2_value>...<fieldN_len><fieldN_name>=<fieldN_value>

Name

Description

Format

Length

fieldX_len

length, in bytes, of the name and value to follow

little-endian integer

4 bytes

fieldX_name

name of the field

character string

variable; terminated by '='

fieldX_value

value of the field

field-specific

variable

The total length of fieldX_name=fieldX_value, including the '=' character, is fieldX_len bytes. The total length of this header sequence (including the names, '=' characters, value lengths, and values) is header_len bytes.

Header fields may appear in any order. Field names can contain any printable ASCII character (0x20 - 0x7e), except = (0x3d). Field values can contain any data (including binary data with embedded nulls, newlines, etc.).

Every header is required to include the following field:

Name

Description

Format

Length

op

what kind of header this is (see below)

unsigned byte

1 byte

The op field is used to distinguish between different types of headers:

  • 0x01 : Message definition. Includes full text of message definition and is not followed by actual message data (the format is unchanged, so data_len is set to 0).

  • 0x02 : Message data. Does not include the full definition, and is followed by actual message data (which can be zero-length). In a well-formed bag file, the message definition for a given topic will appear exactly once, prior to any message data for that topic.

ROS 0.11 introduced two new header types:

  • 0x03 : Bag header (optional). Stores information about the entire file, such as the offset to the first index data record. It does not include any data.

  • 0x04 : Index data (optional). Stores a versioned index of messages in the bag file.

The following fields are guaranteed to appear in the message headers (op=0x01,0x02):

Name

Description

Format

Length

topic

topic on which the message arrived

character string

variable

md5

md5sum for the message type

character string

variable

type

message type

character string

variable

The following fields are guaranteed to appear in a message definition header (op=0x01):

Name

Description

Format

Length

def

full text of message definition

character string, produced by gendeps

variable

The following fields are guaranteed to appear in a message data header (op=0x02):

Name

Description

Format

Length

sec

time at which the message was received, integral seconds part

little-endian integer

4 bytes

nsec

time at which the message was received, integral nanoseconds part

little-endian integer

4 bytes

The data in these records is the serialized message data in the ROS serialization format.

The following field is guaranteed to appear in the bag header (op=0x03):

Name

Description

Format

Length

index_pos

offset of first index data record

little-endian long integer

8 bytes

The bag header record is padded out by filling data with ASCII space characters (0x20) so that additional information can be added after the bag file is recorded. Currently, this padding is such that the total record is 4096 bytes long.

The following field is guaranteed to appear in an index data header (op=0x04):

Name

Description

Format

Length

ver

index data version

little-endian integer

4 bytes

Index Data

Version 0 of the bag index stores one index data record per topic.

The following fields are guaranteed to appear in these headers:

Name

Description

Format

Length

topic

topic on which the messages arrived

character string

variable

type

message type

character string

variable

count

number of messages on topic in the bag file

little-endian integer

4 bytes

The data in each of these records consists of count repeating occurrences of timestamps and offsets:

Name

Description

Format

Length

sec

time at which the message was received, integral seconds part

little-endian integer

4 bytes

nsec

time at which the message was received, integral nanoseconds part

little-endian integer

4 bytes

pos

message record offset

little-endian long integer

8 bytes

The total data_len is count * 16 bytes.

The first pos entry points to the message definition record if the earliest message for type in this bag file occurs on this topic. Otherwise, the first pos entry points to a message data record.

Wiki: Bags/Format/1.2 (last edited 2010-04-19 23:28:07 by TimField)