Round-trip validation
Step 8 of the walkthrough. Here you check the calibration on real data, where there is no ground truth.
- You need: the camera–IMU config from step 4. It must read a ROS1 bag.
- You get: PASS or FAIL, with a check list.
- Check: read the check list (section 2). A FAIL is a finding, not a flaky test.
Why a round trip:
- Reprojection error (how far the detected corners land from where the calibration predicts them) tells you a calibration fits its own data. It does not tell you the calibration is right.
- A round trip does. We apply the calibration to the data it came from, then calibrate again. If the first answer was right, there is nothing left to find.
1. Run it
Section titled “1. Run it”mvis roundtrip -c virig_4imus_4cams_cam_imu.yamlOne command runs four steps:
- Calibrate (calibration A).
- Correct the bag with
mvis apply-calib. - Calibrate the corrected bag (calibration B).
- Compare A and B and report PASS or FAIL.
It exits non-zero on FAIL, so it can run in CI.
| Flag | Effect |
|---|---|
-c, --config | The camera–IMU config to check (ROS1 bag) |
--out | Output folder (default results/roundtrip/<config name>) |
--bag | Use this ROS1 bag instead of the config’s source |
--keep-corrected | Keep the corrected bag (deleted by default) |
--keep-bias | Do not remove the IMU biases in step 2 |
- Disk space: the corrected bag is written next to the raw bag and is about as large. After calibration A, MVIS checks the disk has room for it and stops if not.
- Detection cache: the corrected bag gets its own name, so its corners are detected afresh.
- Output:
report.txtandreport.jsonin the output folder, with the results of both calibrations inforward/andrecal/. - EuRoC input: convert the folder to a ROS1 bag first, then pass it with
--bag. For a catalog dataset usemvis datasets convert --dataset <key>; for anymav0folder callmvis.datasets.converters.euroc_folder_to_rosbag.convert_euroc_folder_to_rosbag(src, "out.bag").
2. What PASS means
Section titled “2. What PASS means”PASS needs two things. They pull in opposite directions, which is what makes the test useful.
- Collapse. On the corrected bag, every IMU’s
DwandDa(the gyroscope and accelerometer scale and misalignment matrices) must go to identity, and the biasesb_gandb_ato zero. Calibration A claimed to measure them; if it was right, the correction used them up. - Preserve. Each camera’s lever arm (its position in the base IMU frame) must not move, nor must the stereo baseline between the first two cameras. The correction changes timing and IMU scaling, not geometry. A lever that moves means calibration A traded geometry against something else.
The limits:
DwandDa: every diagonal entry within 1 % of 1.- Biases: below 0.02 (rad/s for the gyroscope, m/s² for the accelerometer).
- Lever arms and the stereo baseline: at most 2 mm of drift.
The timing terms are warnings, not failures: each camera’s td (time offset to the base IMU) and each
IMU’s t_ga (gyroscope-to-accelerometer offset). How much of them survives depends on how well the data
observes them. The aux IMUs’ td is not checked.
- In
report.txt: every timing row is markedwarn, whatever its value. It only means the row is a warning-only check. The value should be near 0; above 2 ms it is worth a look.
3. Limits on this rig
Section titled “3. Limits on this rig”- Rolling shutter is not tested.
apply-calibre-stamps each frame but does not unwarp its rows. So a round trip on the ELP pair does not check its readout. - Use other checks for the readout: Rolling-shutter calibration and the digital-twin check.
4. Results on the running example
Section titled “4. Results on the running example”The full rig: VI-Rig bag 01, all 4 cameras and all 4 IMUs, the step-4 config, run on 2026-11-10 with MVIS just before the 0.1.0 release. Result: PASS. All 16 IMU checks (4 per IMU) and all 5 geometry checks (4 levers, 1 baseline) pass.
IMUs: what calibration A measured collapses. A ran on the raw bag, B on the corrected bag. A right calibration leaves nothing for B to find.
| Check | Calibration | Xsens (base) | GX3-25 | GX3-35 | T265 IMU | Pass if |
|---|---|---|---|---|---|---|
Gyroscope scale Dw: worst axis off 1 | A | 0.23 % | 0.27 % | 0.14 % | 0.37 % | |
| B | 0.00 % | 0.00 % | 0.00 % | 0.00 % | < 1 % | |
Accelerometer scale Da: worst axis off 1 | A | 0.36 % | 0.46 % | 0.51 % | 2.05 % | |
| B | 0.01 % | 0.00 % | 0.00 % | 0.00 % | < 1 % | |
| Largest bias (m/s²) | A | 0.036 | 0.093 | 0.064 | 0.161 | |
| B | 0.002 | 0.0002 | 0.0003 | 0.002 | < 0.02 | |
t_ga (ms) | A | −0.82 | +0.10 | +0.01 | −6.74 | |
| B | +0.30 | 0.00 | 0.01 | 0.00 | warn-only, near 0 | |
td to base (ms) | A | — | −0.69 | −2.07 | −7.17 | |
| B | — | 0.00 | 0.00 | 0.00 | shown only |
The largest corrections A made, the T265 IMU’s 2 % accelerometer scale and its −6.74 ms t_ga, are fully
gone in B. The base Xsens keeps +0.30 ms of t_ga, well under 2 ms.
Full scale diagonals (x, y, z)
| IMU | Dw, A | Dw, B | Da, A | Da, B |
|---|---|---|---|---|
| Xsens (base) | 0.9981, 0.9977, 1.0009 | 1.0000, 1.0000, 1.0000 | 0.9999, 0.9964, 1.0013 | 0.9999, 1.0001, 1.0000 |
| GX3-25 | 0.9999, 0.9998, 1.0027 | 1.0000, 1.0000, 1.0000 | 0.9954, 1.0011, 1.0008 | 1.0000, 1.0000, 1.0000 |
| GX3-35 | 0.9990, 0.9986, 1.0009 | 1.0000, 1.0000, 1.0000 | 0.9949, 1.0004, 1.0006 | 1.0000, 1.0000, 1.0000 |
| T265 IMU | 0.9967, 1.0037, 1.0028 | 1.0000, 1.0000, 1.0000 | 1.0205, 1.0204, 1.0123 | 1.0000, 1.0000, 1.0000 |
Cameras: the geometry stays. apply-calib does not touch the lever arms, rotations and intrinsics that A
found, so B should find them again. Only the lever rows and the T265 baseline are graded; the other rows are
shown for reference.
| Check | Calibration | T265 left | T265 right | ELP-L | ELP-R | Pass if |
|---|---|---|---|---|---|---|
| Lever arm to base (mm) | A | 130.82 | 112.24 | 145.12 | 185.95 | |
| B | 130.90 | 112.33 | 145.16 | 185.98 | ||
| Lever change (mm) | A → B | 0.09 | 0.09 | 0.08 | 0.06 | ≤ 2 mm |
| Rotation change (mrad) | A → B | 0.08 | 0.11 | 0.12 | 0.11 | |
td (ms) | A | −5.41 | −7.47 | −123.25 | −123.30 | |
| B | 0.00 | 0.00 | 0.00 | 0.00 | warn-only, near 0 | |
| fx (px) | A | 286.54 | 286.51 | 426.90 | 423.58 | |
| B | 286.53 | 286.50 | 426.89 | 423.58 | ||
| fy (px) | A | 286.34 | 286.08 | 426.45 | 423.10 | |
| B | 286.33 | 286.08 | 426.45 | 423.11 |
| Stereo baseline | A | B | Pass if |
|---|---|---|---|
| T265 pair (cam0–cam1, graded) | 63.69 mm | 63.69 mm | moves ≤ 2 mm |
| ELP pair (shown only) | 59.39 mm | 59.40 mm |
- Geometry: every camera moves by under 0.1 mm and turns by under 0.13 mrad; fx and fy move by under 0.01 px. The reprojection error stays at 0.52 px RMS.
- Camera
td: it collapses with the IMU terms. It is a timing term that A measured andapply-calibremoved. - Not tested: the ELP readout, as
apply-calibdoes not unwarp rolling-shutter rows (section 3).
The check list as mvis roundtrip prints it: report.txt.
The report of calibration B, as MVIS wrote it except for local folder names:
Open full screen (HTML, 11.6 MB). The report of calibration A is the one in step 4.
Export a corrected dataset
Section titled “Export a corrected dataset”mvis apply-calib is the correction step inside the round trip. You can also run it on its own. It takes a
camera–IMU calibration and a raw ROS1 bag, and writes a new bag with the calibration applied:
- IMU intrinsics removed: scale, misalignment and g-sensitivity.
- Biases removed.
- One timeline for every stream.
Downstream tools then get corrected data and need to know nothing about the calibration.
Run apply-calib
Section titled “Run apply-calib”With flags:
mvis apply-calib --calib cam_imu_calib.yaml --in raw.bag --out corrected.bagOr from a config file:
mvis apply-calib -c recalib.yaml- Calibration:
mvis cam-imuwritescam_imu_calib.yamlnext tocam_imu.json. Pass that YAML to--calib. - Output: defaults to
<input>.corrected.bag. An existing bag is not overwritten. - Topics: the calibration records each sensor’s source topic, so MVIS finds which topic belongs to which
sensor. Use
--maponly to override that. - Example config:
examples/configs/recalib_example.yamlin the MVIS repo. It lists every config key.
What gets corrected
Section titled “What gets corrected”| Correction | Detail | Turn off with |
|---|---|---|
| IMU intrinsics | Dw, Da and Tg removed through the inverse IMU model | --no-imu-intrinsics |
| Static bias | The calibrated biases subtracted | --keep-bias |
| Time alignment | Every camera and aux IMU re-stamped onto the base IMU clock by its td | --no-td |
| Gyroscope-to-accelerometer offset | The accelerometer re-sampled at t + t_ga, when t_ga was calibrated | --no-t-ga |
| Undistortion | Images undistorted (mono8 images only) | on only with --undistort |
The terms:
Dw/Da: the scale and misalignment of the gyroscope and the accelerometer.Tg: the g-sensitivity, how linear acceleration leaks into the gyroscope.td: the time offset of a sensor to the base IMU.t_ga: the time offset between the gyroscope and the accelerometer.
More flags:
--strict: stop on missing or empty topics, wrong message types, duplicate IMU stamps and non-finite values, instead of passing them through.
Many recordings
Section titled “Many recordings”One calibration usually serves many recordings of a rig. To correct a whole folder of bags, run
scripts/recalib_batch.py --calib cam_imu_calib.yaml --in-dir raw/ --out-dir corrected/ from the
MVIS repo. It runs the same correction as apply-calib on every
*.bag in the folder.
The t_ga study starts from such a corrected bag: Why calibrate t_ga.
When it fails
Section titled “When it fails”A FAIL is a real finding. The usual causes:
- Wrong camera model. The intrinsics absorbed an error that comes back once the timing is corrected. Try another camera model.
- Wrong IMU convention. See IMU model.
- An interpolated accelerometer that corrupts
td, as on the T265. The fix isgyro_onlyon that IMU, or estimatingt_ga. A round trip alone does not catch this case: a tool with not_gaalso returns to about zero on its own corrected bag. Turnt_gaon and read it. See Why calibrate t_ga. - Not enough motion. The parameter was never observed, so correcting by it does nothing consistent.
You have finished the walkthrough. The corrected bag from apply-calib is also what the
Why calibrate pages test: start with Why calibrate the IMU.