The only mode we currently support is LocalizeInMap. In this mode, we first localize against the map; if that succeeds, the current map is replaced by the loaded one. We do not support unlocalized loading (load now, localize later).

Users who call LocalizeInMap must provide:

Image(s)
Timestamp (timestamp_ns on the call, aligned with the images)
Prior 3D pose (guess_pose)

API

Pose Track(const Odometry::State& state, const Pose* gt_pose = nullptr);

 
void SaveMap(const std::string_view& folder_name,
             std::function<void(bool success)> callback) const;

using LocalizeStartCB = std::function<void()>;
using LocalizeFinishCB = std::function<void(const Result<Pose>& result)>;
 
void LocalizeInMap(const std::string_view& folder_name, int64_t timestamp_ns, const Pose& guess_pose,
                   const ImageSet& images, const LocalizationSettings& settings, LocalizeStartCB start_cb,
                   LocalizeFinishCB finish_cb);

QA

Loading of maps — what do we want to support, and how should it work?

Current functionality is minimal, solid, bug-free, and well-tested:

No external GlobalLocalizer (no GPS, no slam.SetPose).
No tracking-lost recovery support.
No user-provided tracking-lost detection.
Sensor fusion is limited to visual SBA only.

There is a single cuVSLAM system that runs until the first tracking loss. Users can save and load maps without interrupting real-time processing.

Scenarios

The user creates a cuVSLAM::Slam instance.
The user feeds images via Track. This is a low-latency, real-time path (e.g. ~100 fps) with all camera frames. The user receives a real-time SLAM pose; the background thread runs LC search and map building.
At some point the user calls SaveMap (possibly from another thread). The map is written to disk by the background path; Track is not blocked by that work.
At some point the user calls LocalizeInMap with image(s), timestamp, and prior. The background thread matches the images to the on-disk map. On success it drops the current map and replaces it with the loaded one. After that, the next Track returns a pose in the new map.

Camera moves during startup, then a map load is requested — what behavior do we support?

During the load, the user keeps calling Track for every frame and keeps receiving a pose. After the map is applied, the next Track returns the real robot pose in the loaded map.

Example: car at 80 km/h, cuVSLAM starts, then 3 minutes / ~4 km later a map load is requested — what is expected?

The user supplies a localization image + timestamp + prior for the “current” moment (e.g. timestamp = 3 min). Even if loading takes time (e.g. 10 s), poses over that interval are reconciled to the localized pose at that timestamp. History before that timestamp is dropped.

Ten minutes later another map load — what is expected?

Same pattern: timestamp = 13 min (for example), current image and prior. As in step 3, previous history is replaced when localization succeeds.

What if the map has nothing around the location?

LocalizeInMap fails (finish_cb with failure); cuVSLAM keeps the current map.

What if the map is wrong (e.g. from a different session)?

There is no automatic repair. If the user needs a full reset (for example, tracking was lost a minute ago), they must reinitialize cuVSLAM.

What if the map is huge and load takes minutes?

After the load, odometry since the localization timestamp is applied at the localized pose. cuVSLAM has retention_time—history older than that window cannot be used; localization with too-old timestamps fails.

In “connected to database” setups, loading is often a quick reconnect and the map is ready immediately.

Load map under the hood

I'm a Robot: load_map_mermaid.md.

Load map under the hood

**Slam::Track()**

Accumulate odometry between keyframes.
Append new keyframe to the end of the tail.

**Slam::BackgroundThread::ProcessMessage**

Update state in the past if localize or find-FC runs.
Recalculate poses from the updated segment to the latest.

Use cases

The user calls localize with a timestamp ≥ the last pose in the tail. Odometry inputs with older timestamps are ignored until a newer timestamp arrives.
The user calls localize with a timestamp outside the retention window. Localization returns failure.
The user calls localize with a fresh timestamp before the last pose in the tail. The localized pose is injected at the correct place in the tail (same idea as FindLC).