Skip to content

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.
A Raw bag images + IMU as recorded 1 · Calibrate mvis cam-imu Calibration A Dw, Da, biases, td,t_ga, extrinsics 2 · Correct mvis apply-calib:A applied to the raw bag Corrected bag a perfect sensor,if A was right 3 · Recalibrate same config, new bag Calibration B what is left to find 4 · Compare B with a perfect sensorand with A Collapse: what A measured is gone • Dw, Da within 1 % of identity• biases below 0.02• td, base t_ga near 0 (warn > 2 ms) Preserve: what A did not touch stays • lever arms move ≤ 2 mm• stereo baseline moves ≤ 2 mm PASS = both hold A Raw bag images + IMU as recorded 1 · Calibrate mvis cam-imu Calibration A Dw, Da, biases, td,t_ga, extrinsics 2 · Correct mvis apply-calib:A applied to the raw bag Corrected bag a perfect sensor,if A was right 3 · Recalibrate same config, new bag Calibration B what is left to find 4 · Compare B with a perfect sensorand with A Collapse: what A measured is gone • Dw, Da within 1 % of identity• biases below 0.02• td, base t_ga near 0 (warn > 2 ms) Preserve: what A did not touch stays • lever arms move ≤ 2 mm• stereo baseline moves ≤ 2 mm PASS = both hold
Why both checks: a solver that hides an IMU error inside the geometry can still collapse the IMU terms, but then a lever arm or the baseline moves. A solver that measured nothing keeps the geometry, but nothing collapses. Only a right calibration passes both, with no ground truth needed.
shell
mvis roundtrip -c virig_4imus_4cams_cam_imu.yaml

One command runs four steps:

  1. Calibrate (calibration A).
  2. Correct the bag with mvis apply-calib.
  3. Calibrate the corrected bag (calibration B).
  4. Compare A and B and report PASS or FAIL.

It exits non-zero on FAIL, so it can run in CI.

FlagEffect
-c, --configThe camera–IMU config to check (ROS1 bag)
--outOutput folder (default results/roundtrip/<config name>)
--bagUse this ROS1 bag instead of the config’s source
--keep-correctedKeep the corrected bag (deleted by default)
--keep-biasDo 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.txt and report.json in the output folder, with the results of both calibrations in forward/ and recal/.
  • EuRoC input: convert the folder to a ROS1 bag first, then pass it with --bag. For a catalog dataset use mvis datasets convert --dataset <key>; for any mav0 folder call mvis.datasets.converters.euroc_folder_to_rosbag.convert_euroc_folder_to_rosbag(src, "out.bag").

PASS needs two things. They pull in opposite directions, which is what makes the test useful.

  • Collapse. On the corrected bag, every IMU’s Dw and Da (the gyroscope and accelerometer scale and misalignment matrices) must go to identity, and the biases b_g and b_a to 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:

  • Dw and Da: 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 marked warn, 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.
  • Rolling shutter is not tested. apply-calib re-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.

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.

CheckCalibrationXsens (base)GX3-25GX3-35T265 IMUPass if
Gyroscope scale Dw: worst axis off 1A0.23 %0.27 %0.14 %0.37 %
B0.00 %0.00 %0.00 %0.00 %< 1 %
Accelerometer scale Da: worst axis off 1A0.36 %0.46 %0.51 %2.05 %
B0.01 %0.00 %0.00 %0.00 %< 1 %
Largest bias (m/s²)A0.0360.0930.0640.161
B0.0020.00020.00030.002< 0.02
t_ga (ms)A−0.82+0.10+0.01−6.74
B+0.300.000.010.00warn-only, near 0
td to base (ms)A—−0.69−2.07−7.17
B—0.000.000.00shown 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)
IMUDw, ADw, BDa, ADa, B
Xsens (base)0.9981, 0.9977, 1.00091.0000, 1.0000, 1.00000.9999, 0.9964, 1.00130.9999, 1.0001, 1.0000
GX3-250.9999, 0.9998, 1.00271.0000, 1.0000, 1.00000.9954, 1.0011, 1.00081.0000, 1.0000, 1.0000
GX3-350.9990, 0.9986, 1.00091.0000, 1.0000, 1.00000.9949, 1.0004, 1.00061.0000, 1.0000, 1.0000
T265 IMU0.9967, 1.0037, 1.00281.0000, 1.0000, 1.00001.0205, 1.0204, 1.01231.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.

CheckCalibrationT265 leftT265 rightELP-LELP-RPass if
Lever arm to base (mm)A130.82112.24145.12185.95
B130.90112.33145.16185.98
Lever change (mm)A → B0.090.090.080.06≤ 2 mm
Rotation change (mrad)A → B0.080.110.120.11
td (ms)A−5.41−7.47−123.25−123.30
B0.000.000.000.00warn-only, near 0
fx (px)A286.54286.51426.90423.58
B286.53286.50426.89423.58
fy (px)A286.34286.08426.45423.10
B286.33286.08426.45423.11
Stereo baselineABPass if
T265 pair (cam0–cam1, graded)63.69 mm63.69 mmmoves ≤ 2 mm
ELP pair (shown only)59.39 mm59.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 and apply-calib removed.
  • Not tested: the ELP readout, as apply-calib does 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.

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.

With flags:

shell
mvis apply-calib --calib cam_imu_calib.yaml --in raw.bag --out corrected.bag

Or from a config file:

shell
mvis apply-calib -c recalib.yaml
  • Calibration: mvis cam-imu writes cam_imu_calib.yaml next to cam_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 --map only to override that.
  • Example config: examples/configs/recalib_example.yaml in the MVIS repo. It lists every config key.
CorrectionDetailTurn off with
IMU intrinsicsDw, Da and Tg removed through the inverse IMU model--no-imu-intrinsics
Static biasThe calibrated biases subtracted--keep-bias
Time alignmentEvery camera and aux IMU re-stamped onto the base IMU clock by its td--no-td
Gyroscope-to-accelerometer offsetThe accelerometer re-sampled at t + t_ga, when t_ga was calibrated--no-t-ga
UndistortionImages 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.

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.

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 is gyro_only on that IMU, or estimating t_ga. A round trip alone does not catch this case: a tool with no t_ga also returns to about zero on its own corrected bag. Turn t_ga on 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.