Multi-session join (graph_slam_multisession_join)¶
Joins several runs (sessions) of one site into one pose graph. It needs no prior on how the sessions relate: place recognition finds the transform between their odometry frames. It refuses to join when the evidence does not hold over the whole map. A wrong cross-session join breaks the whole map, so when the matches are in doubt the tool leaves the sessions apart.

Status: offline tool, development stage (SOTA v7 Phase 3). The method, its evaluation on
GrandTour and its limits are in bench_report/REPORT.md chapter 38 and
bench_report/data/grandtour/multisession_2026-10-29/plan.txt.
Build¶
Built in every build of graph_based_slam: it uses the small_gicp copy vendored in
graph_based_slam/third_party/small_gicp (the same one as registration_method: SMALL_GICP).
In the product¶
lidarslam-map merge --place-recognition (scripts/map_join.py) runs this tool on outputs recorded
with --editable: it replays each run's backend, joins the sessions, and hands each joined
session's transform to the merge's own alignment and overlap gates. A refused session stops the
merge with the reason (docs/golden-path-cli.md, merge).
Inputs¶
For every session:
- its backend input bag: the frontend's odometry (
/rko_lio/odometry) and deskewed scans (/rko_lio/frame) as recorded byscripts/record_backend_input.sh; - the output directory of
graph_slam_offline_runneron that bag (trajectory_raw.tum,loop_edges.csv).
The first session is the reference frame. All sessions must come from the same rig: one LiDAR extrinsic is given for all of them.
graph_slam_multisession_join --ros-args \
--params-file lidarslam/param/lidarslam_mid360_rko_graph_walking.yaml \
-p "session_bag_paths:=['/data/run1/backend_input','/data/run2/backend_input']" \
-p "session_backend_dirs:=['/out/run1','/out/run2']" \
-p extrinsic_lidar2base_quat_xyzw_xyz:=[0,0,0,1,0,0,0] \
-p output_dir:=/out/joined
The pose graph settings (adjacent and loop edge information, robust kernel) are read under the runner's parameter names, so the params file of the single-session runs can be reused.
Joining a new run to a stored map¶
A session's self-similarity (method step 6) depends only on the session and the settings. With
multisession_cache_dir, the tool stores each session's result in that directory under the session's
fingerprint (self_similarity_<fingerprint>.yaml). Later runs use the stored result instead of a new
self-join. The fingerprint covers the keyframes (ids, frames, maps) and every setting of the check
except the number of threads. A changed session or setting therefore gets a new check, never a stale
result.
# once, when the map is made: check its self-similarity (one session is enough with the precheck)
graph_slam_multisession_join --ros-args --params-file <params> \
-p "session_bag_paths:=['/data/map/backend_input']" -p "session_backend_dirs:=['/out/map']" \
-p multisession_cache_dir:=/out/self_similarity -p multisession_precheck_self_similarity:=true \
-p output_dir:=/out/map_check
# each new run: only the new run's self-similarity is checked
graph_slam_multisession_join --ros-args --params-file <params> \
-p "session_bag_paths:=['/data/map/backend_input','/data/run7/backend_input']" \
-p "session_backend_dirs:=['/out/map','/out/run7']" \
-p multisession_cache_dir:=/out/self_similarity -p output_dir:=/out/map_run7
join_report.yaml ends with a self_similarity block. For each session it gives the fingerprint and
how the result was known: stored, checked (in this run, and then stored) or none (not needed).
Measured on the Construction pair (report 38.7). The outputs are byte-identical to computing the check in the join.
| Run | Time |
|---|---|
| Preparing the map (con-1) | 380 s |
| New run (con-2) joined to the stored map | 573 s (821 s without stored results) |
| Both stored | 75 s (73 s for a join that does not pass) |
A new run's self-join does not depend on the map either. Running the precheck when the run is processed takes it out of the join.
multisession_num_threads (4) sets how many candidates are registered at once. Each registration
runs on one thread, so the outputs are the same for any number of threads (byte-identical on 4 and
1 threads, report 38.6).
GNSS gate (a candidate, off by default)¶
With multisession_gnss_gate: true, sessions that carry RTK GNSS are joined by comparing each set's
transform with GNSS around its places, instead of the whole-map check (report 56.3).
- GNSS input. NavSatFix messages (
multisession_gnss_topic,/gnss/fix) are read from each session's bag. An editable run of a bag with GNSS keeps it inbackend_input/. A session recorded without GNSS can take a GNSS-only bag throughmultisession_gnss_bag_paths. - Fixes kept. Fixes with status >= 0 and a horizontal standard deviation of at most 0.3 m are
kept. Each is paired with the odometry pose nearest in time (within 0.05 s), moved by the antenna
offset
multisession_gnss_antenna_xyz. - The comparison. At each place of a set, the GNSS pairs within 30 m of the place (at least 50 per session) are fitted in yaw and translation, with outliers trimmed. The set's transform is compared with that local GNSS transform: the position difference at the place, and the heading difference.
- The decision. When a set has at least 5 such places, GNSS decides. The first set whose median
position and heading differences are at most 1.0 m and 2 deg (
ambiguity_m,ambiguity_deg) joins. The ambiguity and self-similarity refusals are not applied. Without GNSS the join is decided as before. join_report.yamlgives each set'sgnsscomparison and whether GNSS decided.
It has met its readings only on the data its comparison was developed on: RTK-SLAM Stadtgarten 1 + 2 and Construction 1 + 2 (reports 56.1 to 56.4). It is not the default until it is confirmed on RTK GNSS data not seen before.
Method¶
- The runner's submaps are the keyframes. A keyframe's map is the scans within
multisession_keyframe_window_s(1.0 s) of its stamp. The map is put in a gravity-aligned frame at the keyframe (its position and yaw), cropped to 40 m and thinned to 0.2 m. - Scan Context (the existing
ScanContextclass; 30 m, the map raised 2 m) proposes up to three keyframes of the reference session for each keyframe of the other. A candidate is kept if its distance is at most 0.4. - small_gicp GICP aligns each candidate from the Scan Context yaw (correspondence distance 2.0, 1.0, then 0.5 m). A match is kept if at least 60 % of its points land within 0.3 m.
- Every match implies one session transform. The largest set of matches that agree with one another (0.3 m at both matches' places, 1 deg) is found exactly (maximum clique). It must include 3 places at least 5 m apart.
- Whole-map check: the session's keyframes are put into the reference session with the set's transform. At least 5 of them must land within 3 m of a reference keyframe, and at most 10 % of those may have less than half of their points within 0.3 m of the reference maps there. Otherwise the next largest set is tried, up to 3 sets. A site's repeated structure (columns at a fixed spacing along a hall) makes wrong matches that agree with each other. This check is what rejects them.
- Two refusals guard against places that repeat themselves:
- Ambiguity. Every set that meets the spread criterion is checked, up to 3. If two of them pass with transforms that differ (1.0 m RMS over the session's keyframes, or 2 deg), there is no join. A symmetric room fits turned by 180 deg as well as it fits as it is.
- Self-similarity. After a set passes, each session is joined to itself by the same method, with the
matches near the identity left out (10 Scan Context candidates per keyframe; the 10 keyframes on either
side are skipped). If either session joins itself, there is no join. Its place repeats itself, so a join to
it cannot be told apart from a wrong one. In the self-join, a candidate is not refined after the first stage
if less than 0.48 of its points lie within 1.0 m of the other keyframe's (
self_gate_fraction). It could not be accepted anyway. Each session is checked once per run, however many sessions it is joined to. A join that passes still takes about ten times as long as one that does not: 821 s against 73 s on the Construction pair (report 38.6). - With more than two sessions, each session is joined to the map: the sessions joined before
it, their keyframes placed in the first session's frame (
multisession_join_to: map, the default;firstjoins every session to the first one only). The whole-map check runs over that map. Every session in the map was checked for self-similarity when it joined, so only the new session is checked. Sessions that do not join are tried again after the map has grown, until it stops growing. After each join, while sessions are left to join, the graph so far is optimized and the map places its keyframes at their optimized submap poses (multisession_reoptimize_map, default on; report 38.9). - The joined sessions form one graph: each session's odometry chain (no adjacent edge across a
session start,
SubmapNode::session_start), its own loop edges, and one inter-session edge per joined place, to the map keyframe's own session. It is optimized with the first submap fixed.
Outputs (output_dir)¶
join_report.yaml: per session, joined or not, candidates, accepted matches, every set tried with its whole-map check, and the transform to the reference session.map_joinsgives each session's tries, the pass it joined in, and the map's sessions at its last try.self_similaritygives each session's fingerprint and how its self-similarity was known.inter_session_edges.csv: the inter-session edges (the session, the map keyframe's sessionmap_session, both submaps, the relative pose).trajectory_session<i>.tum: each joined session's optimized submap poses in the reference session's frame. Densify them onto the frontend trajectory withscripts/densify_corrected_trajectory.py.
Measured (GrandTour development missions, two sites)¶
| Pair | Join error | Joint map: B's ATE with A's alignment vs B alone |
|---|---|---|
| con-1 + con-2 (both orders) | 11.5 / 12.5 mm | +2.0 / -0.1 mm |
| arc-5 + arc-6 (both orders) | 11.3 / 29.1 mm | +4.9 / +4.1 mm |
| different sites (2 pairs) | not joined | |
| the true matches removed (4 runs) | not joined |
Safety on more sites (report 38.5): 16 sessions were each split in two (debug_split_gap_s).
They come from GrandTour, MapsHD rooms, a corridor and garages, exp04 and Oxford. Every right match
was removed (debug_exclude_transform), so any join would be wrong.
- Without the two refusals, a symmetric room joined 20.7 m off: the room turned by 180 deg.
- With them there was no wrong join in any run.
- Two right joins were lost: one was ambiguous, the other had a self-similar half.
Joining to the map (report 38.8): there is no three-run set with a shared reference, so 18 sessions were each cut into three parts. Each part was joined as a session, and the truth is the identity.
- Joining to the map joins 10 parts. Joining to the first part only joins 8.
- Two parts join only with the map, on a second try, once the third part is in the map (Oxford, pil-2).
- There was no wrong join in 72 runs, with or without the right matches.
- A part joined through the map inherits the placement error of the map's sessions: Oxford's transform was 0.13 m off the loop-closed reference. The joint optimization brings it to 0.035 m. With the map optimized after each join, the transform is 0.064 m off. The final map does not change.
Oxford Spires (report 38.10; LiDAR and IMU only):
- New College: 04 joins 03 at 87 matched places, and 01 joins both at 123. The routes overlap a lot: 43 % of 03's route, 82 % of 04's and all of 01's lie within 5 m of another run's. New College 02 is not joined (22 of 474 candidates accepted, too few for a set).
- Christ Church: 04 joins 02 at 114 matched places (68 % of 02's route and 50 % of 04's lie within 5 m of the other's). 05 and 06 are refused because each joins itself. 03, a long hall that also fits turned round, is refused as ambiguous.
- Keble College: 02 and 03 join 05, but only walk round a quad that 05 also covers.
The GIF above shows New College. It is made with bench_report/scripts/p3_multisession_glow_gif.py; the steps are
in README media.
Limits:
- When only one session sees a symmetry (two identical rooms, each walked by a different session), neither rule can refuse the join. No data with such a pair and a known truth has been tested.
- The whole-map thresholds come from the Construction pair. On two outdoor MID-360 walks of one park (RTK-SLAM Stadtgarten 1 + 2, report 52), they refuse right sets: 10.2 % and 18.8 % of places had less than half their points overlapping. The refused sets were 0.28 m and 0.38 m from the surveyed truth (report 53).
- Lowering the place bar by each session's own map consistency over its revisits (reports 54, 55) joined Stadtgarten at the right transforms, but on MapsHD calibration-room 2, split in two, a half with few revisits (consistency 0.35) lowered the bar to 0.2, and the half turned by 180 deg joined 18.8 m off. The rule was removed.
- The whole-map check refuses sets far off, not slightly off: at the Construction pair it passes the right transform moved by 1 m, by 2 m along one axis or turned by 2 deg, and refuses it moved by 4 m or turned by 5 deg and more (report 55). The transform's accuracy comes from the matches' agreement (0.3 m).
- GNSS is not used. On Stadtgarten, RTK GNSS gave the relative transform within 0.48 m and 0.56 m of
the truth (report 53), and a trimmed 4-DoF fit on the overlap within 0.46 and 0.48 m. A gate that
accepts a set agreeing with that transform (report 56) joined Stadtgarten and refused every
transform 2 m or 2 deg off, but on Stadtgarten 1 split in two the halves' GNSS transform was 1.19 m
off, so the gate refused a right set: a rigid fit of GNSS to one session's odometry inherits the
session's drift (fit residuals 0.4-1.1 m). It was not built. Fitting GNSS only within 30 m of each
place (report 56.1) put the truth within 0.28-0.38 m (median) in all three cases and refused every
transform 2 m or 2 deg off, but its whole-map floor (25 % below) refused the split's right set; it
was not built either. Without the floor, on RTK-SLAM Construction 1 + 2 (report 56.2) it accepted
every right set, including two that the whole-map check refuses, but also the right transform
turned by 5 deg: the median disagreement of the places does not bound a rotation about their
middle. Neither variant is built. Comparing each place's heading as well (median at most 2 deg,
report 56.3) met every reading on Stadtgarten and Construction, but those data were seen when the
heading was added; it is built as a candidate, off by default (above), and needs a confirmation on
data not seen before it can become the default. An editable run of a bag with a
NavSatFix topic keeps it in
backend_input/(record_backend_input.sh --gnss-topic), so the sessions have their GNSS. - A join adds a session to the map; it does not update the map. A place that changed between sessions keeps both versions.
debug_exclude_transform, debug_split_gap_s, debug_split_parts and debug_check_transforms are test hooks
only. debug_check_transforms (two sessions; 12 values per transform, a 3x4 matrix row by row) writes the whole-map
check of session 1 at each transform to debug_checks.yaml and stops without joining.