Quickstart
Use this page to run a first calibration end to end on one of our recordings. You download one bag, solve one camera, then solve three cameras with four IMUs, and read the reports.
You need:
- MVIS installed from source, with the
apriltagandros1extras. Run every command below from the root of theopenmvischeckout. See Installation. - About 7 GB of free disk for the recording.
- A Hugging Face account. The VI-Rig data is gated: you accept its terms once on the Hub.
1. Get the recording
Section titled “1. Get the recording”We use the first recording of VI-Rig — 4 IMUs + 3 cameras, a rig we built for calibration research. It has a FLIR Blackfly camera, an Intel RealSense T265 fisheye pair and four IMUs, all recorded in front of a 6 × 6 AprilGrid.
-
Accept the terms on calibench-vi/datasets.
-
Give MVIS your token: set
HF_TOKENto a read token from your Hugging Face settings. Orpip install huggingface_huband runhf auth login; MVIS reads the token file it writes. -
Download recording
april_01:Terminal window mvis datasets list --dataset mvis_4imus_3camsmvis datasets download --select mvis_4imus_3cams/april_01
- Where it goes:
$MVIS_DATASETS/mvis_4imus_3cams/virig_4imus_3cams_april_01.bag.MVIS_DATASETSdefaults to~/Datasets. Configs refer to it as${MVIS_DATASETS}. - Checked: the download is verified against the checksum in the catalog.
- Licence: CC BY-NC 4.0, non-commercial; commercial licences on request. If you publish with it, cite the MVIS paper; see Contributors & citation.
mvis inspect <bag> prints the topics, rates and duration of a recording.
2. Calibrate one camera
Section titled “2. Calibrate one camera”Save this as quickstart/blackfly_cam.yaml inside the checkout:
mode: caminput: cameras: - camera_id: 0 name: Blackfly source_type: rosbag_topic source_path: ${MVIS_DATASETS}/mvis_4imus_3cams/virig_4imus_3cams_april_01.bag topic: /blackfly/image_raw distortion_model: radtan shutter_type: globalboard: board_type: apriltag rows: 6 cols: 6 tag_size: 0.088 # metres, measured on the printed board tag_spacing: 0.3 # gap between tags, as a fraction of tag_size tag_family: t36h11solve: max_iterations: 15 pixel_sigma: 1.0 huber_threshold: 1.345estimate: board_points: true # solve the board shape toooutput: path: results/quickstart/blackfly.yaml format: yamldistortion_model: radtan: the Blackfly has a standard lens. For a fisheye lens, usekb4. Camera model helps you choose.tag_size: sets the scale of every distance MVIS reports. On your own board, measure a printed tag; see Set up the board.estimate.board_points: our board is not flat, so we solve its shape. Why.
Check the config, then solve:
mvis check -c quickstart/blackfly_cam.yamlmvis cam -c quickstart/blackfly_cam.yaml -o results/quickstart/blackflyOn our Linux test machine this took about 7 minutes, mostly board detection.
The run folder results/quickstart/blackfly then holds:
| File | Use |
|---|---|
quickstart_blackfly_cam.html | The report, one self-contained file |
quickstart_blackfly_cam_calib.yaml | The calibration. Deploy this, or feed it to mvis cam-imu |
quickstart_blackfly_cam_full.yaml | The calibration plus board poses, to replay the run |
The file names are <config folder>_<config name>. MVIS also copies the
result to output.path.
3. Calibrate cameras and IMUs
Section titled “3. Calibrate cameras and IMUs”The repository ships a camera–IMU config for this recording. Run it as it is:
mvis cam-imu -c examples/configs/tga_mvis/tga_mti_01.yaml- Sensors: all three cameras and all four IMUs. The Xsens MTi-100
(
/imu/data) is the base IMU; the others are solved relative to it. - Camera starting point:
camera_input.pathreadsexamples/configs/tga_mvis/mvis_4imus_3cams_calib.yaml, the median of ten camera-only solves per camera on this dataset. The lenses are held fixed (estimate.camera.intrinsics: false). To use your own camera result, pointcamera_input.pathat its_calib.yaml. - Solved: camera–IMU extrinsics and time offsets, IMU-to-IMU extrinsics
and time offsets, the IMU intrinsics
DwandDain thecalyxconvention, the biases, and each IMU’s gyro–accel offsett_ga. - Window:
window_mode: motionpicks the 80 s with the most motion. - Time: about 13 minutes on our Linux test machine.
It writes next to output.path (results/tga_mvis/mti_01/):
| File | Use |
|---|---|
cam_imu.json | The full result |
cam_imu_calib.yaml | The calibration to deploy, or to pass to mvis apply-calib |
cam_imu_camchain-imucam.yaml | The same result as a Kalibr camchain |
cam_imu_report.html | The report |
4. Read the reports
Section titled “4. Read the reports”Open the HTML files in a browser.
- Camera report: expand Calibration Data Quality and read the motion-excitation assessment first, not the reprojection error. A fit can be tight while the recording never pinned a parameter down. Then check the error per frame and the corner heatmaps for a pattern.
- Camera–IMU report: start with the summary grades, then the 3D rig view:
each camera and IMU should sit where it sits on the real rig. Then read each
camera’s lever arm and
td, and each IMU’s intrinsics. - A grade for both:
mvis verdictreads a result and prints GREEN, YELLOW or RED with the reasons:
mvis verdict results/quickstart/blackfly.yamlmvis verdict results/tga_mvis/mti_01/cam_imu.jsonGREEN means every check passed; it does not mean the recording pinned every parameter. Round-trip validation is the stronger test.
The Examples page shows our run of this dataset, and its results page compares it with Kalibr and Basalt.
- Your own rig: follow the guides from Set up the board to Round-trip validation.
- With an agent: the MVIS repository ships a Claude Code skill,
mvis-calibrate, that walks a recording through seven gated stages (installation check, data qualification, sensor suite, parameters, configs, solve, verification, release) on top ofmvis inspect,mvis check,mvis run,mvis verdictandmvis roundtrip. Start Claude Code in a checkout, or copy its.claude/folder next to your data, and run/mvis-calibrate. See doc/agent.md. - Second reference dataset: TUM-VI, on Examples.
- Every config key: Configuration.