Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HKUST-Aerial-Robotics/Vins-Fusion/llms.txt

Use this file to discover all available pages before exploring further.

Accurate camera intrinsics are one of the largest sources of error in visual-inertial odometry. A badly calibrated camera introduces systematic reprojection errors that the back-end optimizer cannot compensate for, leading to scale drift in monocular mode or inconsistent stereo baselines in stereo mode. VINS-Fusion ships a calibration binary — built from camodocal — that accepts a folder of checkerboard images and produces a camera YAML file you can reference directly in your main config.

​
Supported camera models

VINS-Fusion supports three projection models. Choose the one that best matches your lens geometry. Pinhole (PINHOLE) is the standard rectilinear projection model. It is suitable for any camera with a field of view up to roughly 120°. The model stores four distortion coefficients (k1, k2, p1, p2) and four projection parameters (fx, fy, cx, cy). MEI (MEI) is the unified central catadioptric / omnidirectional model developed by Mei and Rives. It adds a mirror parameter xi on top of the standard radial-tangential distortion model, and uses gamma1, gamma2, u0, v0 as projection parameters. This is the model used for EuRoC — the EuRoC cameras are standard rectilinear lenses, but the MEI model fits them well because of its extra flexibility. Equidistant (EQUIDISTANT) implements the fisheye equidistant projection. Use this for cameras with fields of view exceeding 150° (e.g., GoPro, event cameras with fisheye optics).

​
Preparing calibration data

Print or display a checkerboard pattern and record a ROS bag or image sequence while moving the camera slowly in front of it. Aim for:
  • At least 30–50 images covering the full image plane including corners.
  • Varied distances and tilt angles relative to the board.
  • No motion blur — move slowly and pause briefly before capturing each frame.
Extract frames to a directory named calibrationdata (the tool’s default expected name): 
# Extract frames from a ROS bag at 2 Hz into ~/calibrationdata/
mkdir -p ~/calibrationdata
rosrun image_view extract_images _sec_per_frame:=0.5 image:=/cam0/image_raw \
  _filename_format:="$HOME/calibrationdata/frame%04d.png"
The EuRoC checkerboard used during the official calibration has 12×8 inner corners and 80 mm squares. Adapt -w, -h, and -s to your specific board.

​
Running the calibration tool

After building the camera_models package, the calibration binary is available as: 
rosrun camera_models Calibrations \
  -w 12 -h 8 -s 80 \
  -i calibrationdata \
  --camera-model pinhole
FlagMeaning
-wNumber of inner corners along the board width
-hNumber of inner corners along the board height
-sPhysical size of one square in millimetres
-iPath to the directory containing calibration images
--camera-modelProjection model: pinhole, mei, or equidistant
The tool iterates over all images in the input directory, detects the checkerboard, and runs a non-linear bundle adjustment. Progress is printed to stdout. On completion it writes a YAML file named after the camera model (e.g., camera_pinhole.yaml) in the current working directory.
Run the calibration tool from the same directory where you want the output YAML to land, then copy or rename the file to match the cam0_calib value in your main config.

​
Camera YAML file format

​
Pinhole model

The pinhole model uses standard radial-tangential (Brown-Conrady) distortion. The fx and fy fields are the focal lengths in pixels; cx and cy are the principal point in pixels. 
%YAML:1.0
---
model_type: PINHOLE
camera_name: camera
image_width: 752
image_height: 480
distortion_parameters:
   k1: -2.9545645106987750e-01
   k2:  8.6623215640186171e-02
   p1:  2.0132892276082517e-06
   p2:  1.3924531371276508e-05
projection_parameters:
   fx: 4.6115862106007575e+02
   fy: 4.5975286598073296e+02
   cx: 3.6265929181685937e+02
   cy: 2.4852105668448124e+02
This is cam0_pinhole.yaml from the EuRoC config directory.

​
MEI model

The MEI model adds a mirror_parameters block with a single xi coefficient that controls how much the image departs from the pinhole geometry. Projection parameters are named gamma1, gamma2 (focal lengths) and u0, v0 (principal point). 
%YAML:1.0
---
model_type: MEI
camera_name: camera
image_width: 752
image_height: 480
mirror_parameters:
   xi: 3.6313355285286337e+00
distortion_parameters:
   k1:  1.1757726639872075e+00
   k2:  1.5491281051140213e+01
   p1: -8.1237172954550494e-04
   p2:  6.7297684030310243e-04
projection_parameters:
   gamma1: 2.1387619122017772e+03
   gamma2: 2.1315886210259278e+03
   u0:     3.6119856633263799e+02
   v0:     2.4827644773395667e+02
This is cam0_mei.yaml from the EuRoC config directory, the model used by the default EuRoC configs shipped with VINS-Fusion. The second camera (cam1_mei.yaml) has different values because the two EuRoC cameras are physically distinct lenses: 
%YAML:1.0
---
model_type: MEI
camera_name: camera
image_width: 752
image_height: 480
mirror_parameters:
   xi: 8.1261505894146113e-01
distortion_parameters:
   k1: -3.4247886078397966e-01
   k2:  1.7108792755973357e-01
   p1: -6.6653144364906686e-04
   p2:  7.2311255846767091e-04
projection_parameters:
   gamma1: 8.3406249735437791e+02
   gamma2: 8.3140606765916948e+02
   u0:     3.7432007355249738e+02
   v0:     2.5422391621480082e+02

​
Referencing the calibration file in the main config

After calibrating, place the output YAML in the same directory as your main VINS-Fusion config file and set cam0_calib (and cam1_calib for stereo) to the filename — not an absolute path: 
cam0_calib: "cam0_pinhole.yaml"
cam1_calib: "cam1_pinhole.yaml"
image_width: 752
image_height: 480
VINS-Fusion resolves calibration files relative to the directory that contains the main config YAML. The image_width and image_height fields in the main config must match the image_width and image_height in the camera YAML — they control the feature tracker’s image bounds.
If image_width or image_height in the main config do not match the values in the camera YAML, feature detections near the image boundary may be accepted or rejected incorrectly, reducing tracking quality.

​
Verifying calibration quality

After calibration, the tool reports the reprojection RMS error in pixels. Target values depend on the model and lens:
Camera typeAcceptable RMS reprojection error
Pinhole (rectilinear lens)< 0.5 px
MEI (standard lens)< 0.8 px
Equidistant (fisheye)< 1.0 px
Errors above these thresholds usually indicate insufficient image coverage, a poorly printed checkerboard, or the wrong model for the lens type. Recalibrate with more images covering the corners and edges of the frame.

Build docs developers (and LLMs) love

Get started for freeTalk to us