Skip to main content
ORB-SLAM3 supports saving and loading maps (Atlas) to enable map reuse, localization-only mode, and multi-session SLAM. This guide covers the functionality, use cases, and implementation details.

​
Overview

Map persistence allows you to:
  • Reuse previously built maps: Load a map and localize without rebuilding
  • Multi-session SLAM: Continue mapping across multiple runs
  • Localization mode: Track camera pose in a known environment
  • Share maps: Transfer maps between systems or sessions
Map saving/loading is implemented through the Atlas system, which manages multiple maps and their relationships.

​
Configuration

Map loading and saving are configured in the YAML settings file: 
#--------------------------------------------------------------------------------------------
# System config
#--------------------------------------------------------------------------------------------

# Load a previous Atlas from file (optional)
System.LoadAtlasFromFile: "Session_MH01_MH02_MH03_Stereo60_Pseudo"

# Save current Atlas to file (optional)
System.SaveAtlasToFile: "Session_MH01_MH02_MH03_Stereo60_Pseudo"

​
Configuration Options

Specifies the filename to load a previously saved Atlas.
  • If the file doesn’t exist, ORB-SLAM3 creates a new Atlas from scratch
  • If the file exists, it loads all maps, keyframes, and map points
  • Comment out or remove this line to start with an empty Atlas
Example:
System.LoadAtlasFromFile: "my_office_map"
Specifies the filename to save the Atlas after shutdown.
  • The Atlas is saved when System::Shutdown() is called
  • If the file already exists, it will be overwritten
  • Comment out to disable saving
Example:
System.SaveAtlasToFile: "my_office_map"
Both parameters are optional. If commented out, no map loading or saving occurs.

​
API Methods

While direct SaveMap/LoadMap methods are marked as TODO in include/System.h:170-172, the functionality is implemented through the Atlas system.

​
System.h Interface

// From include/System.h
class System
{
public:
    // TODO: Save/Load functions
    // SaveMap(const string &filename);
    // LoadMap(const string &filename);
    
private:
    void SaveAtlas(int type);
    bool LoadAtlas(int type);
    
    string CalculateCheckSum(string filename, int type);
};
The SaveAtlas() and LoadAtlas() methods are called internally based on the YAML configuration.

​
File Format

ORB-SLAM3 supports two file formats: 
enum FileType {
    TEXT_FILE = 0,
    BINARY_FILE = 1,
};

​
Use Cases

​
1. Build and Save a Map

Create a map from a dataset and save it for future use:
1

Configure save path

Edit your YAML config:
# Comment out load (start fresh)
#System.LoadAtlasFromFile: "warehouse_map"

# Enable saving
System.SaveAtlasToFile: "warehouse_map"
2

Run ORB-SLAM3

./Examples/Stereo/stereo_euroc \
  Vocabulary/ORBvoc.txt \
  Examples/Stereo/EuRoC.yaml \
  /path/to/dataset \
  EuRoC_TimeStamps/MH01.txt
3

Wait for completion

The system will build the map as usual. After completion, it automatically saves the Atlas.
4

Verify saved map

ls -lh warehouse_map*
# Should see the saved Atlas file

​
2. Localization in a Known Map

Load a previously built map and localize only (no mapping):
1

Configure load path

# Load existing map
System.LoadAtlasFromFile: "warehouse_map"

# Optionally save updates
#System.SaveAtlasToFile: "warehouse_map_updated"
2

Activate localization mode

// In your code or modified example
SLAM.ActivateLocalizationMode();
3

Run ORB-SLAM3

The system loads the map and performs localization without creating new map points:
./Examples/Stereo/stereo_euroc \
  Vocabulary/ORBvoc.txt \
  Examples/Stereo/EuRoC_localization.yaml \
  /path/to/new_sequence \
  timestamps.txt
Localization mode is more efficient than full SLAM and useful for navigation in known environments.

​
3. Multi-Session SLAM

Continue mapping across multiple runs:
1

First session - Build initial map

# Start fresh
#System.LoadAtlasFromFile: "campus_map"
System.SaveAtlasToFile: "campus_map"
Run ORB-SLAM3 on first sequence.
2

Second session - Extend map

# Load previous map
System.LoadAtlasFromFile: "campus_map"
# Save extended map
System.SaveAtlasToFile: "campus_map_extended"
Run on a new sequence that overlaps with the first.
3

Subsequent sessions

Continue loading and saving to incrementally build a larger map:
System.LoadAtlasFromFile: "campus_map_extended"
System.SaveAtlasToFile: "campus_map_complete"

​
4. Map Sharing

Transfer maps between systems: 
# On system A: Save map
./stereo_euroc vocab.txt config_save.yaml dataset timestamps

# Copy map file to system B
scp warehouse_map user@systemB:/path/to/ORB_SLAM3/

# On system B: Load and use map
./stereo_euroc vocab.txt config_load.yaml new_dataset timestamps
Ensure both systems use:
  • Same ORB-SLAM3 version
  • Same vocabulary file
  • Compatible camera calibration (same camera or equivalent calibration)

​
Atlas Structure

The Atlas manages multiple maps and handles map merging: 
class Atlas
{
    std::vector<Map*> mvpMaps;  // All maps in the Atlas
    Map* mpCurrentMap;           // Active map
    
    // Map management
    void CreateNewMap();
    void SetCurrentMap(Map* pMap);
    
    // Serialization
    void PreSave();
    void Save(const string &filename);
    void Load(const string &filename);
};

​
Multi-Map SLAM

ORB-SLAM3’s Atlas can maintain multiple maps simultaneously:
  • Map creation: New map created when tracking is lost and cannot relocalize
  • Map switching: System switches between maps during relocalization
  • Map merging: Related maps can be merged through loop closure

​
Implementation Details

​
Saving Process

1

Shutdown called

When System::Shutdown() is called, the system:
  • Stops all threads (Tracking, LocalMapping, LoopClosing)
  • Waits for pending operations to complete
2

Prepare Atlas

Atlas::PreSave() prepares data structures:
  • Resolves all keyframe and map point references
  • Serializes covisibility graph
  • Prepares essential metadata
3

Serialize to disk

SaveAtlas(int type) writes to file:
  • Uses Boost serialization
  • Includes checksum for integrity verification
  • Saves all maps in the Atlas

​
Loading Process

1

System initialization

During System constructor, if LoadAtlasFromFile is specified:
2

Load Atlas

LoadAtlas(int type) reads from file:
  • Verifies checksum
  • Deserializes maps, keyframes, map points
  • Restores graph structure
3

Initialize tracking

Tracking thread starts with loaded map:
  • Can immediately attempt relocalization
  • No initialization phase needed if map valid

​
File Management

​
Map File Naming

By convention, use descriptive names: 
# Good examples
System.SaveAtlasToFile: "office_floor3_stereo_2024"
System.SaveAtlasToFile: "warehouse_section_A_rgbd"
System.SaveAtlasToFile: "campus_outdoor_mono_inertial"

# Include: location, sensor type, date/version

​
Storage Requirements

Map file sizes vary based on:
  • Scene size: Larger environments = larger maps
  • Mapping duration: Longer runs = more keyframes
  • ORB features: More features per frame = larger storage
Typical sizes:
  • Small indoor (2-5 min): 50-200 MB
  • Large indoor (10-20 min): 200-800 MB
  • Outdoor sequences: 500 MB - 2 GB+
Compress map files for long-term storage:
tar -czf warehouse_map.tar.gz warehouse_map

​
Backup Strategy

# After successful SLAM run, backup map
cp warehouse_map warehouse_map.backup

# Before risky operations (extending, merging)
cp campus_map campus_map_$(date +%Y%m%d)

# Regular backups
cp office_map office_map_v1  # Version control

​
Troubleshooting

Symptoms: Error message on startup, system starts with empty AtlasPossible causes:
  • Map file doesn’t exist at specified path
  • File corrupted or incomplete
  • Incompatible ORB-SLAM3 version
  • Checksum verification failed
Solutions:
# Verify file exists
ls -lh warehouse_map

# Check for error messages in terminal
# Try loading with absolute path
System.LoadAtlasFromFile: "/full/path/to/warehouse_map"

# If corrupted, restore from backup
cp warehouse_map.backup warehouse_map
Symptoms: Map loaded successfully, but tracking cannot initializePossible causes:
  • Camera in area not covered by loaded map
  • Different lighting conditions
  • Camera calibration changed
  • Vocabulary mismatch
Solutions:
  • Start in area where map was originally built
  • Ensure consistent lighting
  • Verify camera calibration matches map session
  • Move camera to help relocalization (show distinctive features)
  • Consider using ORB parameter tuning for challenging conditions
Symptoms: System continues creating new map points despite localization modeSolution: Ensure ActivateLocalizationMode() is called after System initialization:
ORB_SLAM3::System SLAM(vocab, settings, sensor_type, true);

// Activate localization mode
SLAM.ActivateLocalizationMode();

// Now process frames
To resume mapping:
SLAM.DeactivateLocalizationMode();
Symptoms: Map file grows to several GB, causing slow load timesCauses:
  • Very long mapping sessions
  • High feature count settings
  • Multiple maps in Atlas
Solutions:
  • Reduce ORBextractor.nFeatures for future sessions
  • Use keyframe culling (automatic in ORB-SLAM3)
  • Split into multiple smaller maps
  • Compress old maps for archival: 
    tar -czf old_maps.tar.gz map1 map2 map3
Symptoms: No map file created, or file incompleteCauses:
  • Insufficient disk space
  • No write permissions
  • System crashed before shutdown
Solutions:
# Check disk space
df -h .

# Check write permissions
touch test_write && rm test_write

# Ensure proper shutdown (call Shutdown() before exit)
# Always call System::Shutdown() to trigger save

​
Best Practices

Map Building

  • Use high-quality calibration
  • Ensure good visual coverage
  • Include loop closures for consistency
  • Verify map quality before saving
  • Backup important maps

Map Loading

  • Start in mapped area
  • Use same vocabulary file
  • Match camera calibration
  • Test relocalization before deployment
  • Monitor tracking status

Localization Mode

  • Load established, optimized map
  • Disable mapping for efficiency
  • Handle tracking loss gracefully
  • Provide relocalization assistance
  • Log pose estimates

Multi-Session

  • Maintain version history
  • Use descriptive filenames
  • Verify map merging
  • Test incrementally
  • Document map coverage

​
Future Development

The TODO comment in System.h suggests future public API methods: 
// Potential future API
void SaveMap(const string &filename);  // Save current map
void LoadMap(const string &filename);  // Load specific map
Currently, use the YAML configuration approach for map persistence.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us