Add new ros2 bag Kilted features + updates
#5771
Conversation
- These changes are meant to reflect the deprecation of positional topic arguments in favor of using --topics
- The bag directories are correctly explained in 3.1, but in subsequent sections it falls back to referring to the recordings as files. Adjust wording to explain that a bag directory is made - Change commands to capture the .mcap file inside the bag directory
- Add action and service info for ros2 bag info - Add playback controls and playback progress for ros2 bag play
- To make this progression logical, add an extra section where a recording is split into multiple bag files with -d arg in a bag directory called subset_separate - Later, use these separate files when explaining how to play all bag files from a single recording (just call ros2 bag play on the bag directory), as well as how to play multiple select files (using new arg -i!)
chen-harrison
changed the title
ros2 bag Kilted Features + Updatesros2 bag Kilted features + updates
There was a problem hiding this comment.
overall lgtm with a few minor comments.
@christophebedard @MichaelOrlov either of you can review this?
| @@ -163,32 +163,58 @@ This directory will contain a ``metadata.yaml`` along with the bag file in the r | |||
| 3.2 Record multiple topics | |||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |||
|
|
|||
| You can also record multiple topics, as well as change the name of the file ``ros2 bag`` saves to. | |||
| You can also record multiple topics, as well as change the name of the bag directory ``ros2 bag`` saves to. | |||
There was a problem hiding this comment.
the previous file is not actually wrong, it saves the bag file with the specified name as well as bag directory. how about the following?
| You can also record multiple topics, as well as change the name of the bag directory ``ros2 bag`` saves to. | |
| You can also record multiple topics, as well as change the name of the destination ``ros2 bag`` saves to. |
There was a problem hiding this comment.
I think what matters here is the directory. The files themselves are just a component of the bag; their name doesn't really matter. So I personally think we should keep "bag directory"
There was a problem hiding this comment.
I see that the help documentation for ros2 bag play says "destination", and maybe that helps clarify that it can also be a path? Would "bag directory path" accomplish that?
Also, since I'm still relatively new as a ROS contributor, I'm not really sure who to listen to as final say 😅
| The ``-o`` option allows you to choose a unique name for your bag directory. | ||
| The following string, in this case ``subset``, is the bag directory name. |
There was a problem hiding this comment.
| The ``-o`` option allows you to choose a unique name for your bag directory. | |
| The following string, in this case ``subset``, is the bag directory name. | |
| The ``-o`` option allows you to choose the destination for your bag directory and bag file name. | |
| The following string, in this case ``subset``, is the bag directory name and bag file prefix name. |
There was a problem hiding this comment.
Same comment as above: https://github.com/ros2/ros2_documentation/pull/5771/files#r2211670982
There was a problem hiding this comment.
At the end of section 3.1 when it says
This directory will contain a
metadata.yamlalong with the bag file in the recorded format.
We could replace it with
This directory will contain a bag file of the same name, with an index suffix "_0". It also contains a
metadata.yamlfile.
This would establish early on that the files use the name of the bag directory.
...rials/Beginner-CLI-Tools/Recording-And-Playing-Back-Data/Recording-And-Playing-Back-Data.rst
Outdated
Show resolved
Hide resolved
- Use keyboard syntax where appropriate
| Running this command on the ``subset/subset_0.mcap`` bag file will return a list of information on the file: | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| $ ros2 bag info subset | ||
| Files: subset.mcap | ||
| $ ros2 bag info subset/subset_0.mcap | ||
| Files: subset_0.mcap |
There was a problem hiding this comment.
I think we should keep subset here for simplicity.
| Then make sure your turtlesim window is visible so you can see the bag file in action. | ||
|
|
||
| Enter the command: | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| $ ros2 bag play subset | ||
| [INFO] [rosbag2_storage]: Opened database 'subset'. | ||
| $ ros2 bag play subset/subset_0.mcap |
There was a problem hiding this comment.
Similar to my other comment, I think we should just keep subset here. The user just wants to "play the bag" and not really "play the bag file"
| 5.1 Play a single bag file | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
There was a problem hiding this comment.
| 5.1 Play a single bag file | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 5.1 Play a single bag | |
| ~~~~~~~~~~~~~~~~~~~~~ |
| 5.2 Play multiple bag files | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
There was a problem hiding this comment.
| 5.2 Play multiple bag files | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 5.2 Play multiple bags | |
| ~~~~~~~~~~~~~~~~~~~~~~ |
| If you want to play multiple bag files that are all a part of the same recording, | ||
| simply call ``ros2 bag play`` on the bag directory, instead of a file: | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| $ ros2 bag play subset_separate | ||
|
|
||
| This will play all the files inside of the ``subset_separate`` recording consecutively. | ||
|
|
||
| If you want to play a specific selection of files, that can be done by calling ``-i <bag_file_name>`` | ||
| for each file. | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| $ ros2 bag play -i subset_separate/subset_separate_0.mcap -i subset_separate/subset_separate_2.mcap | ||
|
|
||
| This will play the first and third bag files in ``subset_separate``, skipping the second. | ||
| They will play with the same relative time as when recorded, meaning there will be a 5 second pause | ||
| in between, where the ``subset_separate_1.mcap`` would have played if not omitted. |
There was a problem hiding this comment.
I think this should be reframed to not mention "the bag files inside the same recording." It should be about "playing multiple bags."
Your explanation here about "They will play with the same relative time as when recorded, meaning there will be a 5 second pause" is correct, but I don't think this is the goal of this feature.
The feature is about playing multiple bags that contain different topics recorded at the same time. This is intended for cases where a lot of data needs to be recorded at the same time, so multiple recorders run at the same time: each one records a subset of the topics. Individual .mcap files part of the same bag don't overlap in time (they're sequential), so they're not really separate bags.
This section should also mention how messages from separate bags are ordered when replayed. This is controlled by the --message-order option. By default, messages are ordered based on when they were received by the recorder node (which isn't quite the same as when they were recorded):
$ ros2 bag play --help
...
--message-order {received,sent}
The reference to use for bag message chronological ordering. Choices: reception timestamp, publication timestamp. Default: reception timestamp. If messages are
significantly disordered (within a single bag or across multiple bags), replayed messages may not be correctly ordered. A possible solution could be to increase
the read_ahead_queue_size value to buffer (and order) more messages.
...So I think it should be something like this:
| If you want to play multiple bag files that are all a part of the same recording, | |
| simply call ``ros2 bag play`` on the bag directory, instead of a file: | |
| .. code-block:: console | |
| $ ros2 bag play subset_separate | |
| This will play all the files inside of the ``subset_separate`` recording consecutively. | |
| If you want to play a specific selection of files, that can be done by calling ``-i <bag_file_name>`` | |
| for each file. | |
| .. code-block:: console | |
| $ ros2 bag play -i subset_separate/subset_separate_0.mcap -i subset_separate/subset_separate_2.mcap | |
| This will play the first and third bag files in ``subset_separate``, skipping the second. | |
| They will play with the same relative time as when recorded, meaning there will be a 5 second pause | |
| in between, where the ``subset_separate_1.mcap`` would have played if not omitted. | |
| Multiple bags may be recorded at the same time with different topics, for example to distribute the recording workload over multiple recorder processes. | |
| To play multiple bags at the same time, simply call ``ros2 bag play`` and provide bags with ``-i``: | |
| .. code-block:: console | |
| $ ros2 bag play -i subset -i subset_separate | |
| By default, this will play messages from both bags based on when they were originally received by the recorder. | |
| The chronological ordering of messages can be changed with ``--message-order``. |
There was a problem hiding this comment.
I see, that makes a lot more sense - I didn't fully understand the original motivations behind the implementation. I originally added the instructions for the subset_separate recording to generate multiple bags, which we'd then be able to use for this example.
Given that the best way to demonstrate its use case is two bags recorded simultaneously with different topics, should that subset_separate example change? Is it not "beginner enough" to start ros2 bag record -o vel --topics /turtle1/cmd_vel and ros2 bag record -o pose --topics /turtle1/pose at the same time? Or is it more helpful to learn how to split up bag files, and less so to see the bags playing simultaneously?
Description
ros2 bag playprogress bar-iargument to play multiple bags-iexplanation--topicstoros2 bag recordcommands to reflect the deprecation of positional topic arguments-oargument, if provided), and pathing to .mcap files now reflects thatros2 bag recordandros2 bag play, so as not to confuse the reader when their output differsFixes #5550