Skip to content

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 apriltag and ros1 extras. Run every command below from the root of the openmvis checkout. 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.

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.

The VI-Rig: several cameras and IMUs on one rigid frame
  1. Accept the terms on calibench-vi/datasets.

  2. Give MVIS your token: set HF_TOKEN to a read token from your Hugging Face settings. Or pip install huggingface_hub and run hf auth login; MVIS reads the token file it writes.

  3. Download recording april_01:

    Terminal window
    mvis datasets list --dataset mvis_4imus_3cams
    mvis datasets download --select mvis_4imus_3cams/april_01
  • Where it goes: $MVIS_DATASETS/mvis_4imus_3cams/virig_4imus_3cams_april_01.bag. MVIS_DATASETS defaults 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.

Save this as quickstart/blackfly_cam.yaml inside the checkout:

quickstart/blackfly_cam.yaml
mode: cam
input:
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: global
board:
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: t36h11
solve:
max_iterations: 15
pixel_sigma: 1.0
huber_threshold: 1.345
estimate:
board_points: true # solve the board shape too
output:
path: results/quickstart/blackfly.yaml
format: yaml
  • distortion_model: radtan: the Blackfly has a standard lens. For a fisheye lens, use kb4. 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:

Terminal window
mvis check -c quickstart/blackfly_cam.yaml
mvis cam -c quickstart/blackfly_cam.yaml -o results/quickstart/blackfly

On our Linux test machine this took about 7 minutes, mostly board detection. The run folder results/quickstart/blackfly then holds:

FileUse
quickstart_blackfly_cam.htmlThe report, one self-contained file
quickstart_blackfly_cam_calib.yamlThe calibration. Deploy this, or feed it to mvis cam-imu
quickstart_blackfly_cam_full.yamlThe calibration plus board poses, to replay the run

The file names are <config folder>_<config name>. MVIS also copies the result to output.path.

The repository ships a camera–IMU config for this recording. Run it as it is:

Terminal window
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.path reads examples/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, point camera_input.path at its _calib.yaml.
  • Solved: camera–IMU extrinsics and time offsets, IMU-to-IMU extrinsics and time offsets, the IMU intrinsics Dw and Da in the calyx convention, the biases, and each IMU’s gyro–accel offset t_ga.
  • Window: window_mode: motion picks 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/):

FileUse
cam_imu.jsonThe full result
cam_imu_calib.yamlThe calibration to deploy, or to pass to mvis apply-calib
cam_imu_camchain-imucam.yamlThe same result as a Kalibr camchain
cam_imu_report.htmlThe report

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 verdict reads a result and prints GREEN, YELLOW or RED with the reasons:
Terminal window
mvis verdict results/quickstart/blackfly.yaml
mvis verdict results/tga_mvis/mti_01/cam_imu.json

GREEN 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 of mvis inspect, mvis check, mvis run, mvis verdict and mvis 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.