Skip to content

Configuration

Use this page to look up any key in an MVIS config file. One YAML file describes the board, the inputs and the solve. There are two config types:

  • Camera-only (mode: cam): calibrates the cameras alone.
  • Camera–IMU (mode: cam-imu): adds one or more IMUs (inertial measurement units: gyroscope and accelerometer) to a camera rig.

mvis run reads mode: to pick the pipeline; mvis cam and mvis cam-imu ignore it. For the commands, see the CLI reference.

  • Paths: ${VAR} expands to the environment variable and a leading ~ to your home folder. ${MVIS_DATASETS} defaults to a Datasets folder in your home directory.
  • Units: lengths in metres, times in seconds, angles in radians, unless a key says otherwise.
  • Unknown keys: logged as a warning and ignored.
  • Aliases: target_hz is read as factor_hz; sigma_px and pixel_sigma are read as each other; pin_tr: true is read as estimate_readout: false.
  • Camera models: radtan, equidistant, kb4, fov, double_sphere, eucm, ucm, omni_radtan (experimental). fisheye and kannala_brandt mean kb4 (why). See Camera model.

The calibration target. Both config types use the same block.

KeyDefaultForMeaning
board_typechessboardallapriltag (AprilGrid), chessboard or aruco
rows, cols9, 6allTag rows and columns; inner corners for a chessboard
tag_size0.02apriltagTag edge length (m)
tag_spacing0.005apriltagGap between tags. Below 1 it is a fraction of tag_size (Kalibr’s convention); 1 or more is metres
tag_familyt36h11apriltagAprilTag family
square_size0.025chessboardSquare edge length (m)
marker_size0.02arucoMarker edge length (m)
marker_separation0.005arucoGap between markers (m)
aruco_dictDICT_6X6_250arucoOpenCV dictionary name
heights_filenonecamera–IMUStart values for the board shape: one height per corner. The <output>_board_shape.yaml of an earlier camera–IMU run is a valid file. Camera-only runs do not read it

board.detection holds expert settings for the multi-scale AprilTag detector. The defaults suit most boards; leave it out unless detection misses tags.

The estimate: block says what is solved and what is held fixed. Both config types read it. It wins over the older low-level keys it maps to (the parser warns when both are set). Leave a key out to keep the default.

estimate:
camera: # every camera; a camera entry can override with its own estimate:
intrinsics: true # focal length and principal point
distortion: true # distortion coefficients
tr: false # rolling-shutter readout
td: true # time offset
extrinsics: true # camera pose in the rig
imu: # every IMU (camera–IMU only)
intrinsics: dw_da # how much IMU intrinsics to solve
model: calyx # which IMU model: kalibr | rpng | calyx
extrinsics: true # auxiliary IMU pose in the base IMU frame
td: true # auxiliary IMU time offset to the base IMU
board_points: false # board shape: one height per corner
KeyDefaultCamera-onlyCamera–IMU
camera.intrinsicstrueSolve the intrinsicsRefine the prior intrinsics; false pins them to camera_input.path
camera.distortiontrueNot read: the solver always estimates distortionFollows camera.intrinsics
camera.trfalseNot read: set shutter_type: rolling on the cameraSolve the readout of rolling-shutter cameras
camera.tdcamera-only false, camera–IMU trueCamera–camera time offsets (unsynchronised cameras)Camera to base-IMU time offset
camera.extrinsicstrueNot read: always estimatedSolve T_CtoI
imu.intrinsicsdw_da—pinned, dw_da (scale and misalignment), dw_da_r (plus the gyro-to-accelerometer rotation), full (plus Tg); true = full, false = pinned
imu.modelcalyx—kalibr, rpng or calyx: a convention, see IMU model
imu.extrinsicstrue—Solve each auxiliary IMU’s pose in the base IMU frame
imu.tdtrue—Solve each auxiliary IMU’s time offset
board_pointsfalseSolve one height per board cornerSame; one board only

A false on a camera–IMU key adds a very tight prior that holds the value at its start. Board heights carry a weak 3 mm prior (solve.board_height_sigma on camera–IMU). Their mean and the two tilts are held at zero, so the board pose keeps the plane.

Two shapes are accepted. They mean the same thing.

Flat shapeSectioned shape
cameras:input.cameras:
—input.cache_dir:
optimizer:solve:
output_file:output.path:
output_format:output.format:

board:, estimate:, report: and the top-level keys are the same in both. mvis calibrate reads only the flat shape.

One entry per camera, under cameras: or input.cameras:.

KeyDefaultMeaning
camera_id0Camera index; reference_camera refers to it
nameemptyLabel in reports
source_typeimagesimages, timestamped_images, rosbag_topic (ROS1 bag), ros2bag or euroc
source_pathemptyImage folder, ROS1 bag file, ROS2 bag folder (or one .db3 / .mcap file) or EuRoC camera folder. For timestamped_images: image_dir,timestamps.csv
topicemptyImage topic; required for bag sources
distortion_modelradtanCamera model; models may differ between cameras of one rig
shutter_typeautoglobal, rolling or auto (treated as global). rolling estimates the readout
factor_hzsolve.factor_hzFrames per second used in the solve
initial_intrinsicsnoneStart values [fx, fy, cx, cy], instead of the automatic first guess
initial_distortionnoneStart values for the distortion coefficients
estimatenonePer-camera override of estimate.camera

Bag topics can be sensor_msgs/Image or PNG or JPEG sensor_msgs/CompressedImage. JPEG is lossy and can move corners, so MVIS warns once per topic. There is no video input: extract frames to an image folder first.

KeyDefaultMeaning
max_iterations200Levenberg–Marquardt (LM) iterations of the joint solve
max_init_frames100Frames used for the first guess; 0 = no cap
init_frame_selectionuniformuniform (spaced in time) or diverse (spread over position, size and tilt)
factor_hz5.0Frame rate for cameras without their own factor_hz
pixel_sigma1.0Corner noise (px)
huber_threshold1.345Huber robust-loss threshold
optimize_intrinsicstrueOlder form of estimate.camera.intrinsics
pnp_methoditerativeFirst-guess pose solver: iterative or ippe (planar)
lm_lambda_lower, lm_lambda_upper0, 100LM damping bounds

Four nested groups hold expert settings. Their defaults suit most rigs:

  • frame_quality: detection gates, for example min_tags_per_frame: 6, min_corner_views: 5, max_pnp_reprojection_px: 10.
  • trajectory_alignment: first guess of extrinsics and time offsets, for example max_expected_dt_s: 0.5.
  • outlier_rejection: the second pass, for example enabled: true, threshold_px: 2.0, percentile: 99.
  • guardrail: when to fall back to the first pass, for example p95_regression_factor: 1.5.
KeyDefaultMeaning
modecamcam or cam-imu; read by mvis run
reference_camera0Camera the extrinsics are expressed in
corner_subsampletwo_antiCorners kept per AprilGrid tag. See below
optimize_time_offsetfalseSolve camera–camera time offsets; for unsynchronised cameras
rerun_outlierstrueRun a second pass without outliers; it falls back to the first pass if the second one goes wrong
rerun_visualizationfalseOpen the Rerun 3D viewer (needs the viz extra)
output_filecalibration_result.yamlResult path (flat shape)
output_formatyamlyaml or json (flat shape)
report.thumbnail_max_dim320Size of detection thumbnails in the report (px)

corner_subsample values:

  • two_anti (camera-only default): two diagonal corners per tag. Faster than all, and in our runs on VI-Rig and TUM-VI (MVIS 0.1.0) the principal point stayed within about 0.1 px of it.
  • two_diag: the other diagonal pair.
  • all (camera–IMU default): every corner.
  • top_left, top_right, bottom_left, bottom_right (or tl, tr, bl, br): one corner per tag. Fastest, but in the same runs it moved cx and cy by up to about 0.8 px, and reprojection error does not show it.

With few tags it falls back to all. The first guess always uses every corner. The sectioned shape also accepts solve.corner_subsample; the top-level key wins.

The three cameras of the VI-Rig 4 IMUs + 3 cams set.

virig_3cams_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
factor_hz: 15.0
- camera_id: 1
name: T265-1
source_type: rosbag_topic
source_path: ${MVIS_DATASETS}/mvis_4imus_3cams/virig_4imus_3cams_april_01.bag
topic: /t265/fisheye1/image_raw
distortion_model: kb4
shutter_type: global
factor_hz: 15.0
- camera_id: 2
name: T265-2
source_type: rosbag_topic
source_path: ${MVIS_DATASETS}/mvis_4imus_3cams/virig_4imus_3cams_april_01.bag
topic: /t265/fisheye2/image_raw
distortion_model: kb4
shutter_type: global
factor_hz: 15.0
board: {board_type: apriltag, rows: 6, cols: 6, tag_size: 0.088, tag_spacing: 0.3, tag_family: t36h11}
solve:
max_iterations: 15 # enough for this board; default 200
output:
path: results/virig_3cams/calibration.yaml
reference_camera: 0
optimize_time_offset: true
estimate:
board_points: true

Top-level sections: input, board, camera_input, solve, estimate, output and the optional reference. Camera–IMU calibration is two steps:

  1. Calibrate the cameras (camera-only config).
  2. Give that result to camera_input.path and solve with the IMUs.
KeyDefaultMeaning
formatros1ros1 (ROS1 bag), ros2 (ROS2 bag folder, or one .db3 / .mcap file) or euroc (EuRoC / ASL mav0 folder)
pathemptyROS1 bag file, ROS2 bag folder or .db3 / .mcap file, or mav0 folder
bagsemptySeveral recordings: each is calibrated into its own bag<NN>/cam_imu.json next to output.path. Each inherits format
cam_topicsfrom camera_input.pathImage topics, in camera order. Empty = the topics stored in the camera calibration
imu_topics["/imu0"]IMU topics. The first is the base IMU; the rest are auxiliary IMUs
imusemptyPer-IMU options, in imu_topics order. {gyro_only: true} calibrates an auxiliary IMU from its gyroscope alone; not allowed on the base IMU
window_modemotionmotion picks the segment_length seconds with the most IMU motion; manual uses t0 and window
segment_length80.0Window length in motion mode (s). A shorter recording falls back to manual
t03.0Window start in manual mode (s from the start)
window0.0Window length in manual mode (s); 0 = to the end
min_obs4Fewest board corners for a frame to be kept
cache_dirnoneFolder for the detection cache (capture database); none = no cache

ROS1, ROS2 and EuRoC all feed camera–IMU runs. apply-calib and roundtrip read ROS1 bags only.

KeyDefaultMeaning
pathemptyCamera calibration: a _calib.yaml from mvis cam, or a Kalibr camchain
free_intrinsicstrueRefine the camera intrinsics with the IMU. Older form of estimate.camera.intrinsics
estimate_readoutfalseSolve the rolling-shutter readout. Older form of estimate.camera.tr
rolling_mode0Which row the frame stamp refers to: 0 top, 1 middle, 2 bottom
camerasemptyPer-camera overrides, in camera order. See below

camera_input.cameras[i] accepts free_intrinsics, estimate_readout, rolling_mode, factor_hz (vision factors per second for that camera) and vision_pose (imu or interp). For cameras whose stamps are not on the sensor clock, retime_sensor_clock: true solves a per-frame capture offset first, and retime_map reuses the <output>_sensor_clock.json of an earlier run.

Three terms first:

  • td: the camera–IMU time offset.
  • t_ga: the time offset between the gyroscope and accelerometer of one IMU (why).
  • State: the IMU pose, velocity and biases at one instant; states are placed at state_hz.
KeyDefaultMeaning
state_hz30.0Rate of the states (Hz); 0 = one per base-camera frame
factor_hz10.0Vision factors (frames used) per second per camera
max_iterations50LM iterations
sigma_px1.0Corner noise (px)
huber_px2.0Huber threshold (px); 0 turns the robust loss off
corner_subsampleallCorners kept per tag; values as in camera-only
vision_poseimuHow a frame’s pose is found between two states: imu propagates the IMU samples to the capture time; interp interpolates between the two states
imu_intrinsicsdw_daOlder form of estimate.imu.intrinsics
imu_intrinsics_modelcalyxOlder form of estimate.imu.model
estimate_t_gatrueSolve the base IMU’s t_ga
sigma_t_ga0.010Prior on t_ga (s)
estimate_readoutfalseSolve the rolling-shutter readout for every camera
board_height_sigma0.003Prior on each board-corner height (m), with estimate.board_points: true
sigma_td_prior0.0Prior that holds each camera’s td near its start (s); 0 = off
pnp_methoditerativeFirst-guess pose solver: iterative or ippe (planar)
rms_gate_px0.0Mark the result ok: false when the final reprojection RMS is above this; 0 = off
init_kwargs{}Options for the camera–IMU first guess, for example keyframe_hz (default 2.0) and scale_rel_tol (default 0.10)

IMU noise, as continuous-time densities:

KeyDefaultMeaning
sigma_g0.01Gyroscope noise (rad/s/√Hz)
sigma_bg0.001Gyroscope bias random walk (rad/s²/√Hz)
sigma_a0.02Accelerometer noise (m/s²/√Hz)
sigma_ba0.002Accelerometer bias random walk (m/s³/√Hz)

Set them from your IMU’s measured noise densities (for example an Allan-variance fit), inflated two to three times. The values in a Kalibr imu.yaml are not drop-in values for these keys.

Multi-IMU and expert keys:

KeyDefaultMeaning
aux_imu_stride3One auxiliary-IMU factor per this many base-IMU state intervals. A larger stride means fewer factors and a faster solve; the auxiliary levers move a little with it
aux_imu_factor_hz0.0Rate of auxiliary-IMU factors (Hz). Used only when aux_imu_stride is 0; with both 0, one factor per base interval
imu_min_rate_hz200.0An IMU slower than this is upsampled before integration; 0 = off
imu_upsample_methodcubiclinear or cubic
sigma_dw_da, sigma_tg, sigma_imu_R0.1, 0.05, 0.1Weak priors on the free IMU intrinsics
sigma_v0, sigma_bg0, sigma_ba00.5, 0.01, 0.1Priors on the first state’s velocity and biases
bound_intrinsicsfalseKeep free camera intrinsics in their valid range (for example double_sphere ξ in [−1, 1])
max_interp_dt0.3Frames between states further apart than this (s) are dropped
lm_lambda_lower, lm_lambda_upper0, 100LM damping bounds
KeyDefaultMeaning
pathcam_imu_calib.jsonSummary JSON. The other files are named after it
calib_yaml<path>_calib.yamlFull MVIS calibration, the input of apply-calib
kalibr_yaml<path>_camchain-imucam.yamlKalibr camchain-imucam export
report_html<path>_report.htmlHTML report
report_txtnoneText report

See Result formats.

Known values to compare against: CAD, factory or published numbers. The HTML report and mvis verdict -c read it. It is a consistency check, not ground truth.

KeyMeaning
labelName shown in the report, for example factory
lever_mmPer camera (cam0: or 0:): the camera position in the base IMU frame, [x, y, z] in mm
baseline_mmStereo baseline between cam0 and cam1 in mm: a length or a 3-vector

All three cameras and four IMUs of the VI-Rig 4 IMUs + 3 cams set, with the camera result of the example above as the prior.

virig_3cams_cam_imu.yaml
mode: cam-imu
input:
format: ros1
path: ${MVIS_DATASETS}/mvis_4imus_3cams/virig_4imus_3cams_april_01.bag
cam_topics:
- /blackfly/image_raw
- /t265/fisheye1/image_raw
- /t265/fisheye2/image_raw
imu_topics:
- /imu/data # base IMU
- /gx3_25/data # auxiliary IMUs
- /gx3_35/imu/data
- /t265/imu
window_mode: motion
segment_length: 80.0
cache_dir: results/virig_3cams/cache
board: {board_type: apriltag, rows: 6, cols: 6, tag_size: 0.088, tag_spacing: 0.3, tag_family: t36h11}
camera_input:
path: results/virig_3cams/calibration.yaml
cameras:
- {}
- factor_hz: 4.0
- factor_hz: 4.0
solve:
max_iterations: 40 # as in our VI-Rig runs; default 50
estimate:
board_points: true
camera: {intrinsics: true, tr: false, td: true, extrinsics: true}
imu: {intrinsics: dw_da, model: calyx, extrinsics: true, td: true}
output:
path: results/virig_3cams/cam_imu.json

More configs ship under examples/configs/ in the repository:

  • tga_mvis/: VI-Rig camera–IMU runs, one per base IMU
  • tumvi_cam_imu/: TUM-VI camera–IMU, one config per camera model (see its README)
  • example_cam_run.yaml, example_estimate.yaml: commented camera-only and camera–IMU templates
  • recalib_example.yaml: an apply-calib config