Warning

Warning: Unity Simulation is deprecated as of December 2023, and is no longer available.

Save sensor images to disk

Use the Image Message Saver component to subscribe to a topic and save messages of type ImageMsg as PNG files.

Add the Image Message Saver component

You can save images generated by your sensors as PNG files by performing the following:

  1. Select any GameObject in your scene.
  2. Select Add Component in the Inspector, and choose Image Message Saver.

  3. Set Topic to the topic the sensor is publishing to. The topic must be of type ImageMsg.

  4. Enter Play mode.

  5. Select Open next to Save Directory to open your file browser where the image has been saved.

Configure the save directory

Set the Save Directory to the path where you want to save the images. You can use the browse button (denoted by ...) to use a file dialog to find the desired path.

If you leave the path empty, the path defaults to Application.dataPath.

Configure the saving behavior

The Image Message Saver uses the File Name pattern you specify, replacing %n (if found) with a zero-padded four-digit index of the capture. The .png extension is added automatically.

By default, any existing file with the same name is overwritten. Disable Overwrite to skip to the next available file index.

Save images automatically

By default, Capture On Start is enabled, which instructs the Image Message Saver to start saving images automatically when the simulation starts.

Set Number Of Captures to specify the number of images you want to save. Set it to 0 to save images until the simulation stops.

You might want to skip the first few images generated by your sensors, for example, to have proper lighting effects computed by HDRP. Set Start Time to the simulation time when image capture should start.

Distributed Rendering considerations

If you are using Distributed Rendering to improve performance, you can configure Image Message Saver so that each render node saves images locally of the sensors it's rendering.

  • Add the Image Message Saver component on the same GameObject as the Distribution Affinity component used to specify on which render node the sensor runs.
  • Consider changing the File Name property to include the group ID. For example, set File Name to capture_rn2_%n if the distribution affinity group for the sensor is set to 2.

Limit the number of images saved

By default, all image messages received are saved to disk, up to the number you specify in Number Of Captures. If the sensor update rate is high, this might generate too much disk activity and slow down the simulation.

To limit the number of images saved per second, set Time Between Captures to the minimum number of seconds that must elapse before saving the next image.

Save images interactively

The Runtime Controls appear in the Inspector when you enter Play mode in the Editor. You can use Start and Stop to control image capture interactively.

You can use the Image Message Saver to save images from the Editor during Play mode:

  1. Disable Capture On Start.
  2. Set Start Time to 0.
  3. Enter Play mode.
  4. Use the visualization suite to determine when it's appropriate to save the image.
  5. Use Start in the Runtime Controls to save the image to PNG.

The Status indicates the current state of the Image Message Saver.

Status Description
Ready The image capture hasn't started yet.
In progress The Image Message Saver is waiting for more image messages to save.
Success The images have been saved successfully.
Stopped You manually stopped the last image capture before it had time to complete.
Timed out No message was received on the specified topic during the last image capture. Ensure Topic corresponds to the sensor's output image topic.
Exception An exception occurred during the last image capture. Check the console or the logs for more details.

Image Message Saver Inspector reference

Property Description
Topic The topic to save messages from. The topic's message type must be ImageMsg.
Number Of Captures The number of images to save. Set to 0 to save images indefinitely.
Start Time The delay in seconds to wait before acquiring the first message. Set to 0 to capture the first received message.
Time Between Captures The minimum time in seconds to wait between messages, skipping intermediate messages if necessary. Set to 0 to never skip messages. Has no effect when capturing only 1 image.
Save Directory The path used to save image files. If left empty, defaults to Application.dataPath.
File Name The file name pattern used for image files. Extension .png is added automatically. If found, %n is replaced by the image index. Can't be empty.
Overwrite Whether to overwrite destination image files if they exist. If File Name doesn't contain %n, this option is ignored and the file is always overwritten.
Capture On Start Whether to automatically start the capture when entering Play mode or when launching the executable.
Log To Console Whether to log information messages to the console.