Relocalization

Creating a Map

Main steps:

1. dimos run unitree-go2-memory to create a .db file
2. Auto-clean the .db file into a usable map
3. Load the map back (replay)
4. Load the map into the Go2 (live)

1. Record a run

dimos --robot-ip {YOUR_ROBOT_IP} run unitree-go2-memory

If DIMOS_ROBOT_IP is set in your environment (or .env), you can drop the --robot-ip flag:

dimos run unitree-go2-memory

This writes recording_go2.db to the repo root. Run the next command from the repo root so the bare-name lookup finds this file. In the next steps {DB_NAME} refers to the stem of your recording - recording_go2 if you kept the default.

2. Auto-clean the .db, convert into a Map

To create the map file (.pc2.lcm):

# default name from step 1:
dimos map global recording_go2 --export

# renamed:
dimos map global {DB_NAME} --export

--export implies --pgo (runs pose graph optimization) and writes ./{DB_NAME}.pc2.lcm to the current working directory. Add --no-gui to skip the rerun viewer for headless runs.

{DB_NAME} can be a file name (with or without extension), or a relative / absolute path.

When a bare file name is given, the tool searches in:

1. current working directory
2. data/ (where LFS files live)

Examples:

dimos map global go2_hongkong_office --export
dimos map global ./go2_hongkong_office.db --export
dimos map global data/go2_hongkong_office.db --export
dimos map global /abs/path/to/scan.db --export

Sample log:

running PGO twopass map...
  Pass 1: 908 frames, 1 keyframes
12:54:32.025[inf][dimos/mapping/voxels.py       ] VoxelGrid using device: CPU:0
exporting PGO twopass map to /Users/dimos/Desktop/dimos-reloc/recording_go2.pc2.lcm...
wrote /Users/dimos/Desktop/dimos-reloc/recording_go2.pc2.lcm

3. Relocalize against replay

Replay a recording and have the relocalization module localize against the premap. Use the unitree-go2-relocalization blueprint — it’s the standard unitree-go2 stack plus RelocalizationModule:

dimos --replay --replay-db {DB_NAME} run unitree-go2-relocalization \
  -o relocalizationmodule.map_file={DB_NAME}

{DB_NAME} is resolved the same way as in section 2: cwd first, then data/.

Sample log:

12:58:51.469[inf][imos/mapping/relocalization.py] Relocalization module started: map_file='recording_go2'  loaded_map.frame_id='map'  placeholder TF 'world' -> 'map'  z_offset=20.0
12:58:56.528[war][imos/mapping/relocalization.py] relocalize skipped: n_pts=14198 < MIN_LOCAL_POINTS=20000
12:59:04.777[war][imos/mapping/relocalization.py] relocalize rejected: fitness=0.466 < threshold=0.6 time_cost=5.3s n_pts=20231
12:59:14.880[war][imos/mapping/relocalization.py] relocalize rejected: fitness=0.433 < threshold=0.6 time_cost=8.1s n_pts=37770
12:59:19.877[inf][imos/mapping/relocalization.py] relocalize: fitness=0.657 time_cost=3.0s n_pts=57385 reloc_t=[-0.007, -0.01, -0.102] TF 'world' -> 'map' published_t=[0.007, 0.009, 0.102]
12:59:27.410[inf][imos/mapping/relocalization.py] relocalize: fitness=0.684 time_cost=5.5s n_pts=64703 reloc_t=[0.001, -0.018, -0.171] TF 'world' -> 'map' published_t=[-0.004, 0.015, 0.171]
12:59:34.213[inf][imos/mapping/relocalization.py] relocalize: fitness=0.681 time_cost=4.8s n_pts=76752 reloc_t=[0.002, -0.003, -0.06] TF 'world' -> 'map' published_t=[-0.002, 0.003, 0.06]

relocalize skipped means the live submap is still warming up (fewer than MIN_LOCAL_POINTS points). relocalize rejected means a candidate was found but its fitness was below the configured threshold (default 0.6). If you want to see every candidate accepted regardless of quality, disable the gate:

-o relocalizationmodule.fitness_threshold=0.0

You can watch the alignment in Rerun. The merged map is published on its own entity — to compare the merged costmap (live scan + premap) against the live scan alone, click the eye icon next to the merged map entity to toggle it off.

With the merged map hidden you see the partial pointcloud from the scanning replay plus the full costmap from the merged current scan + premap.

You can also replay a different recording taken in the same physical space against the same premap.

4. Relocalize on a live robot

Same flags as the replay test, but point at the live robot instead of a recorded .db:

dimos --robot-ip {YOUR_ROBOT_IP} run unitree-go2-relocalization \
  -o relocalizationmodule.map_file={DB_NAME}