Using the CLI¶
We already have covered how to use Ouster CLI for recording data from live sensors and to read from data files (see Load sensor source). In this section, we will demonstrate how to write the data that was read into various file formats using the CLI.
The snippets below read environment variables such as SENSOR_HOSTNAME and
SAMPLE_DATA_OSF_PATH. Override them before running the commands, or export
them inline on the shell.
Recording Sensor Data to Supported File Formats¶
To capture frames from a live sensor into a supported file format, ouster-cli can be used with the save command.
ouster-cli source {SENSOR_HOSTNAME} save {OSF_OUTPUT_FILENAME}.pcap
The CLI’s source … save pipeline works with any input the source command can open — PCAP, OSF, BAG, MCAP, or a live sensor.
The dispatcher looks at the file extension, and forwards execution to the matching handler.
To capture frames directly into OSF, use the save command with an .osf filename. Use --overwrite optionally to overwrite existing files with the same name.
ouster-cli source {SENSOR_HOSTNAME} save --overwrite {OSF_OUTPUT_FILENAME}.osf
Use --dir to specify an output directory. The {VALID_INPUT_SOURCE} must be set to a live sensor hostname/ IP address or a valid PCAP/ OSF/ BAG/ MCAP file path.
ouster-cli source {VALID_INPUT_SOURCE} save --dir {CSV_OUTPUT_DIR} ".csv"
ouster-cli source {VALID_INPUT_SOURCE} save --dir {PNG_OUTPUT_DIR} ".png"
These commands run until interrupted (CTRL+C). Use --split to rotate output files at a size
threshold.
Recording Packet data to PCAP/BAG files¶
When one needs to save raw packets from the source, we can use save_raw command. This supports saving into PCAP/BAG files.
To record data from a udp port (7502 by default) to a pcap file in the current directory and write the metadata to a json file with the same name, simply use:
ouster-cli source {SENSOR_HOSTNAME} save_raw --duration 5 {PCAP_OUTPUT_FILENAME}.pcap
Similarly, specify .bag to capture raw packets into a ROS bag:
ouster-cli source {SENSOR_HOSTNAME} save_raw --duration 5 {BAG_OUTPUT_FILENAME}.bag
The extension you pass determines the output format; using .pcap preserves the raw UDP packets. A matching
metadata JSON file is written alongside the PCAP.
The save_raw command also accepts --duration to stop automatically after the
requested number of seconds.
Consult ouster-cli source <SOURCE> save --help for the full option set.
Note
ouster-cli does not currently expose an option to drop specific channel fields when saving
to OSF. Use the SDK examples in Using the API if you need to thin the field set.
Replaying Data as a Live Sensor (BETA)¶
sensor_replay can replay a PCAP/OSF/BAG/MCAP stream as if it were a live sensor. Point
ouster-cli at a dataset and specify the destination hostname (or interface) for the emulated
sensor packets.
ouster-cli source {REPLAY_SOURCE} sensor_replay --http-port 8080
You can view the sensor webpage at http://127.0.0.1:8080 .
Note
This is a BETA feature.
This emulator implements a limited subset of the device capabilities and does not fully model the actual sensor behavior.
The emulator allows the change of the following list of configuration options (All other settings are read-only):
UDP Destination Address (udp_dest)
UDP Lidar Port (lidar_port)
UDP IMU Port (imu_port)
Operating Mode (operating_mode)
Important: Applications developed and tested using this emulator should be validated on actual Ouster hardware to ensure correct functionality and performance.
This BETA feature requires Docker when using --dockerize. See help for supported transports and options.
ouster-cli source {SAMPLE_DATA_OSF_PATH} sensor_replay --help