/
SLAM & Localization example using CLI

SLAM & Localization example using CLI

 

Prerequisites

  1. ouster_sdk 0.15.1

    pip install ouster-sdk

  2. Data capture (pcap, osf, bag) of environment/facility

Original data recorded at customer site. Do not share publicly. For internal purposes only

 

For information on optimizing data captures and general best practices, see article .

https://ouster.atlassian.net/wiki/pages/resumedraft.action?draftId=2163310595&draftShareId=753d3070-6f97-4830-b538-2d7c95d0c744

Mapping

  1. Review original capture and determine what can be modified to improve the subsequent SLAM map quality.

  2. Most common operations include:

    • Removal of frames with no movement

    • Eliminate nearby measurements that should not exist in the final map

      • (e.g. Removal of the vehicle)

ouster-cli source original_mapping_capture.pcap viz

File size:

original_mapping_capture.pcap: 4.47 GB

  1. Identify and remove frames (via slice) where the vehicle is not moving for long durations.

  2. Commonly found at start and stop of the recording.

    • Frames without vehicle movement

      • Beginning of capture: 0:280

      • End of capture: 2708:2804

2025-11-20_16-48-59.jpg

 

  1. Apply slice and view for correctness

ouster-cli source original_mapping_capture.pcap slice 280: slice :2708 viz

  1. Remove the vehicle (via clip)

  2. Start with clip RANGE in 1m increments until the vehicle is completely removed and review changes in the visualizer. In this example, 1m was not sufficient.

ouster-cli source original_mapping_capture.pcap clip RANGE 3m: viz
2025-11-20_17-17-34.jpg
clip not applied

 

2025-11-20_17-11-24.jpg
clip applied

 

  1. Review the slice and clip modifications for correctness

ouster-cli source original_mapping_capture.pcap slice 280: slice :2708 clip RANGE 3m: viz

  1. Save slice and clip modifications into a new osf file.

ouster-cli source original_mapping_capture.pcap slice 280: slice :2708 clip RANGE 3m: save modified_mapping_capture.osf

File sizes:

  • original_mapping_capture.pcap: 4.47 GB

  • modified_mapping_capture.osf: 1.48 GB

 

SLAM

Now utilize slam to create the map from the modified capture.

  1. Review slam in the visualizer

ouster-cli source modified_mapping_capture.osf slam --voxel-size 0.5 viz --accum-num 100 --accum-every-m 1 --map-ratio 0.005 -e stop
slam_modified_mapping_capture.gif

General recommendations for voxel-size based on the use case.

Outdoor: 1.4 - 2.2

Large indoor: 1.0 - 1.8

Small indoor: 0.4 - 0.8

 

  1. Save slam modifications into a new osf file.

  2. In this example, we can reduce the resultant file size significantly by slicing out every 5th frame from the modfied_mapping_capture.osf into a new osf. Thedownsampled_modified_mapping_capture.osf.

ouster-cli source modified_mapping_capture.osf slam --voxel-size 0.5 slice ::5 save downsampled_modified_mapping_capture.osf

The save command (when used after slam command) stores both the lidar data and the lidar movement trajectory into the result osf file.

File sizes:

  • original_mapping_capture.pcap: 4.47 GB

  • modified_mapping_capture.osf: 1.48 GB

  • downsampled_modified_mapping_capture.osf: 363 MB

The slam process will take time. Appx 6 minutes in my case (MacBook pro M1 13”). To reduce this time, increase the voxel-size parameter (e.g. 1.0-1.8).

MAP generation

1st_pass

  1. Save downsampled_modified_mapping_capture.osf as PLY/PCD/LAS

ouster-cli source downsampled_modified_mapping_capture.osf save first_pass_map.ply

The filename will automatically include a numerical suffix attached the end.

  • first_pass_map-000.ply

File Size: 76.4 MB

Crop and refine Map using Cloud-Compare

2nd_Pass

  1. Import first_pass_map-000.ply into CloudCompare, and select REFLECTIVITY as scalar field.

image-20251124-172910.png

  1. Highlight the PLY “Cloud” in the DB tree, then select the Cross Selection tool

image-20251124-173033.png

 

image-20251124-173102.png

 

  1. Use the RGB handles to rotate the cloud and crop unnecessary points. Export the changes as new Cloud entity in the DB Tree. Save as second_pass_map-000.ply

image-20251124-173240.png
image-20251124-173343.png

 

2025-11-20_18-06-58.jpg
Original: first_pass_map-000.ply

 

image-20251124-173654.png
Modified: second_pass_map-000.ply

File sizes:

  • original_mapping_capture.pcap: 4.47 GB

  • modified_mapping_capture.osf: 1.48 GB

  • downsampled_modified_mapping_capture.osf: 363 MB

  • second_pass_map-000.ply: 75 MB

 

Localization

Try out localization with the original capture (input source) and the new PLY map created

ouster-cli source original_mapping_capture.pcap localize second_pass_map-000.ply viz
localize_2d.gif

 

Change map view displayed in the viz from 2D (global-map-flatten) to 3D

ouster-cli source original_mapping_capture.pcap localize second_pass_map-000.ply viz --global-map-flatten FALSE
localize_3d.gif

The examples above work fine when the input source begins from the same place as the origin of the map, however, this is not always the case.

If the input source’s start position differs from the map origin, you must add the initial pose information in the command line. PX,PY,PZ represent the position and R,P,Y represent orientation in Euler angles (roll, pitch, yaw) specified in degrees.

ouster-cli source --initial-pose PX,PY,PZ,R,P,Y <SOURCE_URL> localize <map.ply> viz

 

[Optional] Compare slam and localization trajectories

--

pip install evo

 

  1. Extract the slam trajectory and save as csv file

ouster-cli source downsampled_modified_mapping_capture.osf save_trajectory --tum example_slam_traj.csv

 

  1. Extract the localization trajectory and save as csv file

ouster-cli source downsampled_modified_mapping_capture.osf localize second_pass_map-000.ply save_trajectory --tum example_localization_traj.csv

 

  1. Plot the slam and localization trajectories and compare the differences

    evo_traj tum --plot --plot_mode xy --project_to_plane xy --ref example_localization_traj.csv example_slam_traj.csv -p --t_max_diff 1.0
image-20251124-190521.png
2025-11-24_14-05-44.jpg
2025-11-24_14-05-52.jpg

 

2025-11-24_14-05-58.jpg

 

In the above example, both the slam and localization are computed using the same data capture. This is not very useful in practice, however, it is fine as a means to show the procedure.

 Related articles

https://ouster.atlassian.net/wiki/pages/resumedraft.action?draftId=2163310595&draftShareId=753d3070-6f97-4830-b538-2d7c95d0c744

Filter by label

There are no items with the selected labels at this time.