FAQ & troubleshooting
Use this page when MVIS does not install, a run fails, or a result looks wrong. Each entry gives the short answer first, then the reason.
Install
Section titled “Install”Which platforms and Python versions work?
Section titled “Which platforms and Python versions work?”Answer: Linux or macOS (x86-64 or arm64), Python 3.11 or 3.12.
- No Windows: GTSAM, the optimisation library MVIS builds on, publishes no Windows wheels.
- No Python 3.13: MVIS needs NumPy 1.x (see below), and NumPy 1.x has no 3.13 wheel.
- No Python 3.10 or older: GTSAM publishes wheels for 3.11 and newer only.
How do I install it?
Section titled “How do I install it?”Answer: from source, until pymvis is on PyPI.
git clone https://github.com/openmvis/openmvis && cd openmvispython -m venv .venv && source .venv/bin/activatepip install -e ".[apriltag,aruco,ros1]"mvis check --env --smoke # checks the environment and runs a small solveWith the v0.1.0 release on PyPI, pip install "pymvis[apriltag,aruco,ros1]"
will install the same. The package is pymvis; the import and the command are mvis. Full
steps: Installation.
Which extras do I need?
Section titled “Which extras do I need?”Answer: only the ones for your board and your input.
apriltag: AprilGrid boards (the grid of square AprilTag markers).aruco: ArUco boards. It installsopencv-contrib-python; install it in a fresh environment, because it andopencv-pythonboth providecv2.ros1: ROS1 and ROS2 bags, through the pure-Pythonrosbagsreader.viz: the optional Rerun 3D viewer.mcap: converting MCAP episodes with H.265 video (it installs PyAV). ROS2 bags stored as.mcapneed onlyros1.
Chessboards, image folders and EuRoC folders need no extra.
Do I need ROS to read a bag?
Section titled “Do I need ROS to read a bag?”Answer: no, for ROS1 or ROS2 bags. The ros1 extra installs rosbags, a
pure-Python reader, so you need no ROS installation or catkin workspace.
-
ROS2 bags: give the bag folder with its
metadata.yaml, or one.db3or.mcapfile. -
ROS1 only:
mvis apply-calibandmvis roundtripwork on ROS1 bags only. -
Image topics:
sensor_msgs/Image, andsensor_msgs/CompressedImagein PNG or JPEG. -
JPEG: lossy, so it can shift corners. MVIS warns once per topic.
-
Rejected:
compressedDepthand video codecs stop the run with an error.
Can I calibrate from a video file?
Section titled “Can I calibrate from a video file?”Answer: not directly. Extract the frames into an image folder first.
The inputs are image folders, timestamped image folders, ROS1 bags, ROS2 bags and EuRoC / ASL folders.
Segfault when MVIS builds a pose
Section titled “Segfault when MVIS builds a pose”Answer: you have NumPy 2. Install NumPy 1.x.
pip install "numpy<2"GTSAM 4.2 from pip is built against the NumPy 1.x ABI. With NumPy 2,
constructing a gtsam.Pose3 crashes instead of raising an error. pymvis pins
numpy<2, so this only happens when something else upgrades NumPy later. The
same pin keeps OpenCV below 4.12, whose wheels need NumPy 2.
Does it work on macOS?
Section titled “Does it work on macOS?”Answer: yes. We test on Apple silicon (arm64) with Python 3.11. Intel Macs are not tested.
Choosing settings
Section titled “Choosing settings”Which camera model should I use?
Section titled “Which camera model should I use?”Answer: pick by the lens.
- Ordinary (non-fisheye) lens:
radtan, the pinhole model with radial-tangential distortion. - Fisheye:
kb4, the Kannala-Brandt model.fisheyeandkannala_brandtmeankb4. It stays valid past 90° from the optical axis. equidistant: the same polynomial, but it stops at 90°. It gives the same pixels askb4when every corner is under 90°. MVIS warns you to switch tokb4when a fit has corners past 90°.- Others:
fov,double_sphere,eucm,ucmandomni_radtan(experimental) are there to match a downstream system that expects them.
Why kb4 is the fisheye default: Fisheye model (kb4). The
equations: Camera model.
Which IMU convention should I use?
Section titled “Which IMU convention should I use?”Answer: the one your downstream estimator reads. The default is calyx.
The convention sets how the IMU intrinsics are written down, not how well they
fit. We calibrated TUM-VI (4 raw recordings) and Monado MIC (8 recordings) with
each of the three. The reprojection error, lever arm, baseline, td and the
corrected readings agreed across conventions; only the way the matrices are
laid out differs.
kalibr: lower-triangular scale and misalignment matricesDw(gyro) andDa(accel), plus a free gyro-to-IMU rotation.rpng: upper-triangularDwandDa, plus a free accel-to-IMU rotation.calyx: a full 3×3Dwand an upper-triangularDa, with no separate rotation. The gyro rotation is recovered fromDwafter the solve.
All three can add Tg, the gyro’s sensitivity to linear acceleration. Set the
convention with estimate.imu.model or solve.imu_intrinsics_model. How to
correct raw readings with each one: IMU model.
Which sign does td have?
Section titled “Which sign does td have?”Answer: td is the camera–IMU time offset. An image stamped
sees the IMU pose at .
- Kalibr:
timeshift_cam_imuuses the same sign (), so compare the two values as they are. - Basalt: the same sign as well.
- Aux IMUs: their
tdis relative to the base IMU, with the same sign as Kalibr’s per-IMUtime_offset.
What is t_ga, and why is it on by default?
Section titled “What is t_ga, and why is it on by default?”Answer: t_ga is the time offset between an IMU’s gyroscope and its
accelerometer. MVIS estimates it in every camera–IMU run
(solve.estimate_t_ga: true).
- Meaning: the accelerometer sample stamped was taken at ; the gyroscope defines the IMU clock.
- Why it matters: some drivers merge a slower accelerometer into the gyro
stream by interpolation. The Intel T265 is one: its 62.5 Hz accelerometer is
resampled to 200 Hz. Without
t_ga, that delay goes intotd. - Correcting it:
mvis apply-calibshifts the accelerometer channel byt_ga;--no-t-gaturns that step off.
Kalibr and Basalt have no t_ga. That is why the MVIS td can differ from
theirs on the same recording. See Why calibrate t_ga.
Should I estimate the board shape?
Section titled “Should I estimate the board shape?”Answer: yes, unless you know the board is flat. Set
estimate.board_points: true.
A printed board is never flat. Held flat in the solve, a bent board pulls the
focal length and, in camera–IMU runs, the gyro scale and the lever arm. With
board_points on, MVIS estimates a height per corner along the board normal,
with a 3 mm prior. It is off by default; our VI-Rig runs turn it on. See
Why calibrate the board shape.
Running
Section titled “Running”Few or no detections
Section titled “Few or no detections”Answer: check the board settings against the board you printed.
- AprilGrid:
rowsandcolscount tags; checktag_size(metres),tag_spacing(gap over tag size) andtag_family. - Chessboard:
rowsandcolscount inner corners; checksquare_size. - ArUco: check
marker_size,marker_separationandaruco_dict.
Then run mvis inspect <dataset path> for a summary of what MVIS sees in the
recording, and mvis check -c config.yaml to lint the config. MVIS detects at
several scales, so far and near boards both work. It cannot fix a wrong tag
family. Board set-up: Set up the board.
Every translation is off by the same factor
Section titled “Every translation is off by the same factor”Answer: the board size in the config does not match the print. Measure a tag
(or square) with calipers and set tag_size or square_size in metres.
Quality gating drops most of my frames
Section titled “Quality gating drops most of my frames”Answer: the recording is too sparse. Get closer to the board, keep more of it in view, or move more slowly.
Quality gating removes frames and corners that would be poorly constrained:
- Per frame: at least 6 tags.
- Per corner: at least 5 views across all cameras, and at least 3 in each camera.
- Shared frames: a reference frame needs at least 20 % of the tags across the cameras.
Initialisation fails on a wide fisheye
Section titled “Initialisation fails on a wide fisheye”Answer: use kb4.
- Why: with
equidistant, corners past 90° can make the first estimate unusable. - What MVIS does: it checks the first estimate of each camera. If the principal point falls outside the image or the distortion is extreme, it logs a warning naming the camera and restarts from a plain guess (focal length half the longer image side, principal point at the centre).
- If the warning appears: switch the camera to
kb4and run again.
A wide-field stereo fit diverged
Section titled “A wide-field stereo fit diverged”Answer: fit each camera alone, then use those intrinsics in the stereo or camera–IMU solve.
On TUM-VI, stereo camera-only fits with double_sphere, eucm or fov can
drift into a wrong solution, where the focal length trades against the model’s
shape parameter. Single-camera fits stay stable. The two-step recipe is in
examples/configs/tumvi_cam_imu/.
It is slow
Section titled “It is slow”Answer: check these, in order.
- BLAS threads: the
mviscommand pins the numerical library (BLAS) to one thread, because the solve works on small matrices and extra threads only spin. If you importmvisfrom your own Python, setOPENBLAS_NUM_THREADS=1,OMP_NUM_THREADS=1andMKL_NUM_THREADS=1before NumPy loads.MVIS_BLAS_THREADS=<n>changes the CLI’s choice. Details:doc/blas_threads.md. - Detection cache: set
input.cache_dir. Re-runs on the same recording then skip detection, and a camera-only and a camera–IMU run share it. - Frame rate in the solve:
factor_hzsets how many frames per second enter the camera factors. Lower it to cut the solve time. - Corner subsampling: camera-only runs already keep two diagonal corners per
tag (
two_anti). Do not drop to one corner (top_left): it shifts the principal point by up to about 0.8 px. - Window: by default (
input.window_mode: motion), a camera–IMU run solves the 80 s segment with the most IMU motion. Lowerinput.segment_lengthto cut the time, or setwindow_mode: manualwitht0andwindow(seconds) to choose the span yourself. Recordings shorter thansegment_lengthare used whole.
Results did not change after I changed detection settings
Section titled “Results did not change after I changed detection settings”Answer: clear the detection cache. The cache is keyed on the recording, the
image topic and the board, so other detection changes reuse the old detections.
Delete the cache_dir folder and run again.
Results that look wrong
Section titled “Results that look wrong”Reprojection error is low but the extrinsics look off
Section titled “Reprojection error is low but the extrinsics look off”Answer: check that the motion constrained them. Read the motion-excitation
grade in the HTML report, and for camera–IMU runs on a ROS1 bag also run
mvis roundtrip.
A low reprojection error means the solution explains its own observations. A parameter the motion never constrained stays near its starting value without raising the error. See Degeneracy.
The round trip fails
Section titled “The round trip fails”Answer: treat it as a real finding. (mvis roundtrip works on ROS1 bags
only.) Common causes:
- Wrong camera model: on a fisheye, use
kb4. - An interpolated accelerometer: keep
estimate_t_gaon, or setgyro_only: truefor that auxiliary IMU. - Too little motion: record again with rotation about every axis and changes of speed.
td or the lever arm look wrong on a fast-moving rig
Section titled “td or the lever arm look wrong on a fast-moving rig”Answer: keep state_hz at its default, 30 Hz.
state_hz is how many pose states per second the camera–IMU solve places along
the trajectory. Below 30 Hz, reprojection, lever arm and td get worse on fast
motion. Slow, gentle recordings barely notice.
One IMU’s accelerometer is unreliable
Section titled “One IMU’s accelerometer is unreliable”Answer: set gyro_only: true for that IMU under input.imus.
MVIS then calibrates that IMU from its gyroscope alone: rotation, td, gyro
scale (Dw) and gyro bias. Its lever arm, Da and Tg stay fixed. This works
for auxiliary IMUs only; the base IMU needs its accelerometer for gravity and
metric scale.
IMU intrinsics come back at their starting values
Section titled “IMU intrinsics come back at their starting values”Answer: the motion did not constrain them.
- Scale and misalignment: need rotation and acceleration on every axis.
Tg: needs rotation and strong linear acceleration at the same time.
See Degeneracy.
Results differ from Kalibr’s
Section titled “Results differ from Kalibr’s”Answer: check these, in order.
- IMU convention:
kalibr,rpngandcalyxwrite different matrices for the same device. Compare like with like. - Transform direction and sensor numbering: MVIS stores
T_cam_imulike Kalibr; check which camera and IMU each value belongs to. t_ga: Kalibr has none, sotdcan differ on IMUs with a gyro–accel offset.- Board shape: Kalibr holds the board flat. With
estimate.board_points: true, MVIS does not, and that alone moves the focal length on a bent board.
mvis.io.kalibr reads and writes Kalibr camchains, which is the reliable way to
compare. Our side-by-side results are on the Leaderboard.
Results differ between recordings of the same rig
Section titled “Results differ between recordings of the same rig”Answer: the parameters that differ were not well constrained by the motion in some recordings.
Calibrate every recording from one config with input.bags (see
Camera–IMU calibration) and compare the
spread. Without ground truth, the spread across recordings is the most honest
accuracy measure.
Still stuck
Section titled “Still stuck”Open an issue on github.com/openmvis/openmvis. Include:
- Your config YAML
- The full log
- The output of
mvis --version - Your OS, CPU and Python version
- A link to the data, if you can share it
Report security problems privately to contact@openmvis.com, not in an issue.