API review

Proposer: Jeremy Leibs

Present at review:

• List reviewers

Proposed command-line APIs

rosbag 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
  -p PREFIX, --prefix=PREFIX
                        append PREFIX to beginning of bag name (name will
                        always end with date stamp)
  -n NAME, --name=NAME  record to bag with namename NAME.bag
  -z, --gzip            compress the message with gzip
  -j, --bzip            compress the message with bzip2
  -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 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 outgoign queue of size SIZE (defaults to 0)
  --frequency=HZ        publish the log time at a frequency of HZ (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 TIME, --start=TIME
                        start TIME seconds into the bag files

rosbag info

Usage: rosbag info BAGFILE

Summarize the contents of a bag file.

Options:
  -h, --help  show this help message and exit

Returns bag information in YAML format:

bag: 2009-12-16-10-49-50.bag
version: 1.2
start_time: 1260989391943123000
end_time: 1260989403343135999
length: 11400012999
topics:
  - name: /bar
    count: 58
    datatype: std_msgs/String
    md5sum: 992ce8a1687cec8c8bd883ec73ca41d1

rosbag 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 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.

Proposed programmatic APIs

C++

   1 namespace rosbag
   2 {
   3   //! Base class for rosbag exceptions
   4   class RosbagException : public std::runtime_error;
   5 
   6   //! Exception thrown if trying to add or read from an unopened
   7   //  recorder/player
   8   class BagNotOpenException : public RosbagException;
   9 
  10   //! Exception thrown when assorted IO problems
  11   class BagIOException : public RosbagException;
  12 
  13   //! Exception thrown if an invalid MsgPos (such as from another bag)
  14   //  is passed to seek
  15   class InvalidMsgPosException : public RosbagException;
  16 
  17   //! Exception thrown if trying to instantiate a MsgInstance as the
  18   //  wrong time
  19   class InstantiateException : public RosbagException;
  20 
  21 
  22   //! Class for recording to a bagfile
  23   class Recorder
  24   {
  25      //! Constructor
  26     Recorder();
  27     
  28     //! Destructor
  29     ~Recorder();
  30     
  31     //! Open a bagfile by name 
  32     bool open(const std::string &file_name);
  33     
  34     //! Close bagfile 
  35     /*!
  36      *  Make sure bagfile is written out to disc, index is appended,
  37      *  file descriptor is closed, etc..
  38      */
  39     void close();
  40     
  41     //! Add a message to the bag file
  42     /*!
  43      * \param topic_name  The topic name
  44      * \param time        Timestamp of the message
  45      * \param msg         A pointer to the message to be added.
  46      *
  47      * Can throw BagNotOpenException or BagIOException
  48      */
  49     void add(const std::string& topic_name, 
  50              ros::Time time,
  51              ros::Message::ConstPtr msg);
  52   };
  53 
  54   //! Class representing the location of a message in a bagfile
  55   class MsgPos
  56   {
  57     const ros::Time time;
  58 
  59   private:
  60     // Not part of user interface, but used to do seek on file
  61     uint64_t pos; 
  62   };
  63 
  64   //! Typedef for index: map of topic_name -> list of MsgPos
  65   typedef std::map<std::string, std::vector<MsgPos> > Index;
  66 
  67   
  68   class MsgInstance
  69   {
  70     const std::string topic;
  71     const std::string datatype;
  72     const std::string md5sum;
  73     const ros::Time time;
  74     
  75     bool valid() const;
  76     boost::shared_ptr<M> instantiate() const;
  77   };
  78 
  79 
  80   //! Class for playing from a bagfile
  81   class Player
  82   {
  83     //! Constructor
  84     Player();
  85     
  86     //! Destructor
  87     ~Player();
  88     
  89     //! Open a bagfile by name 
  90     bool open(const std::string &file_name);
  91     
  92     //! Close bagfile 
  93     void close();
  94     
  95     //! Return the bagfile index.
  96     /*!
  97      * The bagfile index is a map of topics which point to vectors of
  98      * MsgPos classes a MsgPos instance can be used as an argument to
  99      * seek.
 100      */
 101     Index getIndex();
 102 
 103     //! Seek to a specific location in a bagfile 
 104     void seek(const MsgPos& pos);
 105 
 106     //! Return next message from player
 107     MsgInstance next();
 108   };
 109 }

Example Usage

   1 //Example usage:
   2 int main()
   3 {
   4   rosbag::Recorder recorder;
   5   rosbag::Player player;
   6 
   7   if (!recorder.open('out.bag'))
   8     ROS_FATAL("Could not open bag for writing.");
   9   if (!player.open('in.bag'))
  10     ROS_FATAL("Could not open bag for reading.");
  11 
  12   MsgInstance inst;
  13 
  14   while ((inst = player.next()).valid())
  15   {
  16     if (inst.datatype == "std_msgs/String")
  17     {
  18       // Is there a slicker way of doing this with a change to topic tools?
  19       my_msgs::MyType::Ptr msg = inst.msg->instantiate<my_msgs::MyType>();
  20       
  21       // Do something with msg here...
  22 
  23       // Add it into our recorder
  24       recorder.add(inst.topic, inst.time, msg);
  25     }
  26   }
  27 
  28   player.close();
  29   recorder.close();
  30 }

Python API

The python API will mirror the ROS API with subtle pythonic differences where appropriate. I will do those in a separate review once the C++ API is determined.

Question / concerns / comments

Enter your thoughts on the API and any questions / concerns you have here. Please sign your name. Anything you want to address in the API review should be marked down here before the start of the meeting.

Jeremy

• Would -o and -O (output) possibly make more sense than -p/-f for record file syntax?

• Should -f-equivalent append .bag/.gz for you or not? What should behavior of -f foo.bag be? What about -zf foo.bag. Or worse: -zf foo.bag.bz2.

• How hard should we work to avoid re-using options between different commands? For example -p to pause in rosplay but -p for prefix in rosrecord. Or -a is all in record but -a is append in check.

Meeting agenda

To be filled out by proposer based on comments gathered during API review period

Conclusion

Package status change mark change manifest)

• Action items that need to be taken.

• Major issues that need to be resolved