Premap & Relocalization¶

Relocalization lets a Go2 navigate on a previously built map instead of only on what it sees right now. At runtime, RelocalizationModule aligns live LiDAR to a saved premap and publishes a world → map transform, so the costmap and planner operate on the live scan and premap together.

Note: Requires dimOS v0.0.13 or newer for PGO loop closure and dimos map export.

This guide takes four steps:

1. Record a walk-through with unitree-go2-memory
2. Build the premap with dimos map global {DB_NAME} --export
3. Test relocalization in replay, no robot needed
4. Deploy on the live Go2

Throughout this guide, {DB_NAME} is the stem of your recording, for example recording_go2 for recording_go2.db. For map_file, pass the same stem and dimOS appends .pc2.lcm automatically.

1. Record a run¶

Drive the Go2 through the space you want as your premap. Close loops when you can because PGO uses revisits to correct drift.

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

If ROBOT_IP is set in the environment or .env, you can omit --robot-ip:

dimos run unitree-go2-memory

This writes recording_go2.db to the repo root (DIMOS_PROJECT_ROOT) and records lidar, odom, and color_image plus the live TF tree. dimos --record run unitree-go2 records the same streams (and every other one) to recordings/<run-id>/memory.db instead; see Recording. The recorder stamps lidar frames with the latest odom pose so dimos map global can reconstruct poses later- see Go2Memory.

Quick validation (optional)¶

Before building a premap, inspect the recording:

dimos mem summary recording_go2
dimos map replay recording_go2 --duration 60

summary prints stream names and time ranges. replay opens Rerun so you can confirm lidar and odometry look sane.

2. Build the premap¶

Export a loop-closed global map as .pc2.lcm:

dimos map global recording_go2 --export

{DB_NAME} accepts a bare stem, ./path/to/file.db, or an absolute path. Bare names resolve in this order:

1. Current working directory
2. DIMOS_PROJECT_ROOT
3. data/ via LFS (get_data)

Examples:

dimos map global recording_go2 --export --no-gui
dimos map global ./recordings/office_walk.db --export
dimos map global data/go2_hongkong_office.db --export

Sample log:

running PGO twopass map...
  Pass 1: 908 frames, 1 keyframes
exporting PGO twopass map to .../recording_go2.pc2.lcm...
wrote .../recording_go2.pc2.lcm

Open the companion {DB_NAME}.rrd in Rerun to verify loop closure before deploying to hardware.

3. Relocalize in replay¶

Test alignment without the robot. unitree-go2-relocalization is unitree-go2 plus RelocalizationModule:

dimos --replay --replay-db recording_go2 run unitree-go2-relocalization \
  --map-file=recording_go2

map_file resolves {DB_NAME}.pc2.lcm with the same search order as above (cwd, then project root, then data/).

Reading the logs¶

Relocalization module started: map_file='recording_go2'  loaded_map.frame_id='map'
relocalize skipped: n_pts=37770 < MIN_LOCAL_POINTS=50000
relocalize rejected: fitness=0.433 < threshold=0.45 time_cost=8.1s n_pts=57385
relocalize: fitness=0.657 time_cost=3.0s n_pts=64703 reloc_t=[-0.007, -0.01, -0.102] TF 'world' -> 'map' published_t=[0.007, 0.009, 0.102]

relocalize skipped means the live submap is still warming up- fewer than MIN_LOCAL_POINTS points accumulated. relocalize rejected means a candidate alignment was found but its fitness was below the threshold, so no transform is published. Once relocalize: lines appear at info level, the world → map TF is live.

You can replay a different .db from the same physical space against the same premap to test generalization.

Rerun visualization¶

Watch alignment in Rerun, which is enabled by default on Go2 blueprints:

• Merged map shows the premap transformed into world plus the live scan, column-carved together.
• Toggle the merged map entity off to compare the live scan alone against the merged costmap.

4. Relocalize on a live robot¶

Run the replay test first. On hardware, use the same blueprint and map_file:

dimos --robot-ip {YOUR_ROBOT_IP} run unitree-go2-relocalization \
  --map-file=recording_go2

Before sending navigation goals, walk through this checklist:

1. Place the Go2 in a region that overlaps the premap on the same floor with recognizable geometry.
2. Wait for relocalize: info lines. Skipped and rejected lines are normal for the first 30 to 60 seconds.
3. Confirm stable world → map TF in Rerun before sending navigation goals.
4. Click to navigate or use agent skills such as navigate_with_text on the aligned costmap.

How it works¶

The unitree-go2-relocalization blueprint is the standard Go2 navigation stack plus RelocalizationModule:

from dimos.core.coordination.blueprints import autoconnect
from dimos.core.introspection.svg import to_svg
from dimos.mapping.relocalization.module import RelocalizationModule
from dimos.robot.unitree.go2.blueprints.smart.unitree_go2 import unitree_go2

unitree_go2_relocalization = autoconnect(
    unitree_go2,
    RelocalizationModule.blueprint(),
).global_config(n_workers=11)

to_svg(unitree_go2_relocalization, "assets/go2_reloc_blueprint.svg")

Note that CostMapper builds the costmap from the merged map only while RelocalizationModule has a good alignment; until then it falls back to the live map alone.

File formats¶

Configuration reference¶

CLI overrides use dynamically generated kebab-case flags such as --map-file=…. If a shorthand is ambiguous, qualify it with the module key, for example --relocalizationmodule.map-file=….

Constants are not overridable via CLI today:

To accept all candidates for visualization only (not for production nav):

dimos run unitree-go2-relocalization \
  --map-file=recording_go2 \
  --fitness-threshold=0.0

Troubleshooting¶

Related docs¶

For hardware setup, simulation, and the full blueprint list, see the Go2 platform guide. The v0.0.13 release notes summarize the PGO, dimos map, and relocalization work this guide builds on.