Recording and Playing Back Logs

Overview

In Choreonoid, simulation results can be recorded for every single step (frame) of the physics computation, and the recorded results can be played back at the resolution of a single step at any time.

There are roughly two recording methods:

1. Recording in memory

The standard recording function of the simulator items. The behavior of each body model is recorded into a “body motion item”. The recorded results can be used directly for playback and analysis, and can also be saved to files individually as needed.

2. Recording to an external file (world log file)

A function that incrementally records the log to an external file during the simulation using a “world log file item”. Even if the simulation crashes in the middle, the log up to that point remains, and the log can be played back even after closing and restarting the project.

This page explains these recording functions and how to play back the recorded results.

Recording in Memory

Recording Mode

Recording in memory is configured with the “Recording” property of the simulator item. The mode is selected from the following:

• full

Records the results of the entire period from the start to the end of the simulation.

• tail

Records a certain period before the end of the simulation. Older portions beyond that period are discarded. The period is set with the “Time length” property.

• off

No recording is performed. Simulation results can only be checked during simulation execution. Even in this case, simulation results are continuously reflected in the models, so you can observe the progress of the simulation. However, you will not be able to play back or analyze the results later.

Recording simulation results requires memory space. As the number of simulated objects increases or the simulation time lengthens, memory usage increases accordingly. If the memory used for recording simulation results exceeds the available capacity, Choreonoid may crash during the simulation, so caution is needed.

The “tail” mode is provided to avoid such situations. This mode keeps memory usage within a certain range by discarding temporally old portions when the specified time length is exceeded. If you set a time length considering the system memory capacity, the system won’t crash due to memory shortage even during long simulations. In consideration of this safety, the default mode is “tail”.

On the other hand, with the “full” mode, you can play back and analyze the results for the entire period from the start of the simulation. Use this mode when the memory required for recording is not a problem.

Note

If you want to record the entire period of a long simulation, you can also use the world log file described later on this page to record the results by continuously writing them out to a file. In this case, even if the memory capacity is not sufficient, it is OK as long as there is enough free space in the file system.

Recorded Contents

Recording is performed for every single step of the physics computation. That is, the frame rate of the recorded data is the same as the frame rate corresponding to the time step of the simulation. The following contents are recorded in each frame:

• Link positions

The position and orientation of each link. When the “All link position recording” property is false, only the position and orientation of the root link are recorded, and the positions of the other links are reproduced by forward kinematics computation from the joint displacements during playback.

• Joint displacements

The displacement (joint angle or translation) of each joint.

• Device states

The states of the devices such as sensors and lights. They are recorded when the “Device state output” property is enabled (see the next section).

In addition, when the “Record collision data” property is enabled, the collision data between objects detected during the simulation is also recorded. This is recorded as an item named “(simulator item name)-collisions” placed as a child item of the world item, and can be used for displaying the collision positions during playback.

For these properties, see also Properties Common to Simulator Items.

Recording Device States

The fundamental elements recorded as simulation results are the motion trajectory data (link positions and joint displacements) necessary for playing back the physical motions of the models. In addition to these, when the “Device state output” property is set to true (the default), changes in the device states are also recorded. This makes it possible to play back changes in sensor states and operations such as turning devices on and off. However, this increases the memory required for recording and the processing overhead accordingly, so switch it as needed.

Body Motion Items

When recording is enabled, a “body motion item” (BodyMotionItem) is created as the recording destination for each body model in the virtual world when the simulation is started. This item is named “(simulator item name)-(body name)” and is placed as a child item of the corresponding body item (when controller items are used, it is placed under the controller item).

For example, when you run a simulation with the project created in Creating a Simulation Project, the item tree becomes as follows.

[ ] - World
[/]   + box1
[ ]     + AISTSimulator-box1
[/]   + Floor
[ ]   + AISTSimulator

Here, “AISTSimulator-box1” is the body motion item that records the behavior of the box1 model. The time-series data of the link positions, joint displacements, and device states described above are stored in this item.

When you run the simulation again with the same simulator item, the recording overwrites the existing body motion item. Note that this item is treated as a temporary item and is not saved with the project. If you want to keep the recorded results, save them to a file as described next.

Saving Body Motion Items to Files

Body motion items can be saved to files individually. With the target item selected, execute “File” - “Save Selected Items As” from the main menu and select “Body Motion” as the file format to save. The file becomes a text file in the standard body motion file format (extension .seq). The details of this format are explained in Standard Body Motion File Format.

Saved files can be loaded with “File” - “Load” - “Body Motion” from the main menu. If you place the loaded item as a child item of the target body item, it can be played back in the same way as when it was recorded.

Note

What is saved to the file is the link positions and joint displacements (and additional trajectory data); the device states are not saved to the file.

How to Play Back

Playback of recorded results is performed with the following steps:

1. Select the target item on the item tree view (or turn on its check)

2. Operate the time bar

Pressing the play button of the time bar plays the animation, and operating the time slider or the time input displays the state at any time. Since the recording is made for every single step, you can also check the states frame by frame with the slider operations. See Time Axis Operations for the details of the time bar operations.

There are the following choices for the item to select as the playback target:

• Selecting a simulator item

The simulator item itself knows where the logs of the simulation results are recorded. Therefore, when you select a simulator item and play back, all the motions of all the bodies (and the collision data) included in that simulation are played back together. This is the easiest way to play back the whole simulation.

• Selecting body motion items individually

When you select a body motion item and play back, the playback is applied to its parent body item. In this case, only the body corresponding to the selected item is the target of the playback. Use this method when you want to check the motion of a specific model only, or when playing back a body motion loaded from a file.

Note that the display of an ongoing simulation is also realized by this playback function in the form of “playing back the data being recorded”. See Displaying Ongoing Simulations for details.

World Log File

Apart from recording in memory, using a “world log file item” (WorldLogFileItem), the log can be incrementally (sequentially) recorded to an external file during the simulation. This method has the following advantages:

• Even if the simulation crashes in the middle, the motions up to that point are saved in the file and can be played back

• The log is retained even after closing and restarting the project

• The recording period is not limited by the memory capacity (recording is possible up to the free space of the file system)

How to Record

Create a world log file item with “File” - “New” - “WorldLogFileItem” from the main menu, and place it as a child item of the world item (or the simulator item). Then set the path of the log file to record to with the “Log file” property. The file name is arbitrary, but adding an extension such as “.log” makes it easier to recognize.

When you start a simulation in this state, the link positions, joint displacements, and device states of each frame are written out to the log file sequentially in parallel with the progress of the simulation. No special ending operation is required.

The following properties are available in the world log file item.

Property	Default value	Meaning
Log file	—	The path of the log file to record to.
Actual log file	—	The path of the log file actually read and written (display only). When the time-stamp suffix is enabled, its contents are reflected.
Time-stamp suffix	false	When set to true, the date and time of the start of the recording is appended to the file name as a suffix. Use this when you want to keep the recording as a separate file for each simulation.
Recording frame rate	0	The recording frame rate to the log file [Hz]. When 0, all the frames of the simulation are recorded. When a value is specified, the recording is decimated to that rate, which can reduce the file size.
Live playback read interval (ms)	10	The time interval of reading the new data of the log file in the live playback (described later).
Live playback read timeout	0.0	The timeout period after which the addition of data is considered to have stopped in the live playback [s]. When 0, no timeout occurs.

How to Play Back

Playback of a world log file item is the same as the other logs; select (or check) the item and operate the time bar. The state at each time is read from the log file and applied to all the bodies in the virtual world.

Since the log file information is saved in the project, you can play back the log even after closing and restarting the project as long as the log file remains. However, when the recording was made with the “Time-stamp suffix” enabled, the actual log file name has the recording start time appended, so the log file is not loaded just by reloading the project. In this case, set the time-stamp suffix to false and then set the actual file name at the time of the recording to the “Log file” property. If you want to reliably keep and play back the recorded results, using the log playback archive described later is the most reliable way. It is also possible to load an existing log file with “File” - “Load” - “World Log” from the main menu and play it back (in this case, it must be placed under a world item with the same model configuration as when it was recorded).

By executing “Start Live Playback” in the context menu, you can also perform “live playback”, which plays back a log file that is currently being written while following it. With this, for example, you can observe the progress of a simulation running in another process on another Choreonoid via the log file. For the details including how to do this between different hosts, see Live Playback of a Simulation on a Remote Host.

Log Playback Archive

Playback with a world log file assumes that the same models as when it was recorded are loaded. Therefore, if the model files are modified or moved later, it may become impossible to play back the same result as when it was recorded.

To prepare for this, executing “Save project as log playback archive” in the context menu of the world log file item saves a project dedicated to the log playback as an archive. The archive is saved as a single zip file (log playback archive pack), and all the model files at the time of the simulation and the log file are copied and stored in it, together with the project file for the playback. The model files are copied as the original files, and the files referenced by the models such as mesh files and texture images are all included with the original directory structure kept (for the models in the ROS package format such as URDF, the package.xml files for identifying the packages are also included so that the “package://” references are resolved even in an environment without ROS). Note that since the archive is dedicated to playback, the items related only to the execution of simulation (such as controller items and simulator items) are removed from the saved project (items that declare that they also function during log playback are retained). With this, no matter what happens to the original model files afterwards, you can play back the same result in the future just by opening the archived project. Since the archive can be handed over as a single file, this is a useful function when you want to save and share simulation results as deliverables.

A zip-format archive can be opened by directly specifying the zip file with “File” - “Open Project” from the main menu and setting the file type to “Project pack files (*.zip)”. It is also possible to load a zip file by specifying it as a command line argument when launching Choreonoid. In either case, the contents are extracted into the same directory as the zip file, and the playback project contained in it is loaded. When a directory with the same name as the extraction destination already exists, the loading from the dialog shows a confirmation of whether to overwrite it, and the loading from the command line results in an error and the file is not loaded. If you want to check the files in the archive directly, you can refer to this extracted directory (extracting the zip file manually gives the same result).

When the project loaded from a zip file is closed (when another project is loaded or Choreonoid is terminated), the extracted directory is cleaned up. If the contents of the extracted directory have not changed since the extraction, the directory is automatically removed without any confirmation because all the contents are retained in the zip file. If the files in the directory have been modified or added, a dialog asking whether to keep or remove the directory is shown. With this, you can use zip-format archives without leaving the extracted files behind. Note that if a directory with the same name as the extraction destination existed before the extraction, it is not the target of the removal because it may contain files not related to the pack.

It is also possible to save the archive with a confirmation even when the log file has not been recorded yet (or is empty). In this case, an empty log file is included in the archive. This is for such a usage that the archive is distributed in advance and the log is filled later, for example, by the log file transfer described in Live Playback of a Simulation on a Remote Host.

Note that in saving the archive, the configuration of the current project is temporarily modified to construct the archive contents, and after the archive is saved, the project is restored by reloading its project file. Since the simulation results recorded in memory are lost by this reloading, a dialog confirming this is shown first when the archive saving is executed. In addition, since the project file is necessary for the restoration, a dialog prompting you to save the project is shown first if the project has never been saved. If the project has its project file but has unsaved modifications, you can choose whether to save the modifications before proceeding. Even if you proceed without saving, the archive reflects the current contents of the project, but the project restored after saving the archive becomes the state at the time of the last save.

Handling of Vision Data

When using the vision sensor simulation explained in Vision Sensor Simulation, note the following points regarding the recording of the simulated camera images, range data, and so on (vision data):

• Whether to record the vision data is switched with the “Record vision data” property of the GL vision simulator item (false by default). When this is enabled, the vision data is also recorded in the in-memory log as part of the device states, and the sensor images etc. can be checked during playback.

• The state parameters of the sensors, such as on/off, are handled separately from the vision data. They are subject to log recording and playback as normal device states like the other devices.

• However, since the vision data is huge in size, saving it to external files (the body motion files and the world log files) is currently not supported. Recording and playing back the vision data is possible only with the in-memory log.

Summary of Recorded Contents

The following table summarizes the contents recorded and saved by each recording method.

Recorded contents	In-memory recording	Body motion file	World log file
Link positions	○	○	○
Joint displacements	○	○	○
Device states	○	×	○
Vision data	○ (config required)	×	×
Collision data	○ (config required)	×	×