CLI
Use this page to look up every mvis subcommand and its flags.
MVIS installs one command, mvis, with ten subcommands.
- Flags choose what to run and where the output goes.
- The YAML config says how to calibrate. Its keys are on Configuration.
mvis --help # list the subcommandsmvis --version # print the MVIS versionmvis cam-imu --help # flags of one subcommand| Subcommand | What it does |
|---|---|
run | Calibrate from any config; the config’s mode: picks camera-only or camera–IMU |
cam | Camera-only calibration |
cam-imu | Joint camera–IMU calibration |
calibrate | Older camera-only path for flat configs |
apply-calib | Apply a camera–IMU calibration to a raw ROS1 bag and write a corrected bag |
roundtrip | Calibrate, apply, recalibrate and report PASS or FAIL |
check | Check the installation and lint a config before a solve |
inspect | Summarise a recording: format, streams, rates, overlap |
verdict | Grade a finished result GREEN, YELLOW or RED |
datasets | List, download and verify the benchmark datasets |
A typical session
Section titled “A typical session”mvis inspect recording.bag # can MVIS read it, and which modes?mvis check -c config.yaml # is the config valid, are the extras installed?mvis run -c config.yaml # calibratemvis verdict result.json # grade the resultExit codes
Section titled “Exit codes”| Subcommand | 0 | 1 | 2 |
|---|---|---|---|
check, inspect | pass | warn | fail |
verdict | GREEN | YELLOW | RED |
roundtrip | PASS | FAIL | invalid config or arguments |
datasets | every file OK | a file is missing or fails its check | invalid arguments |
cam, run (mode: cam) | solved | the solve failed | invalid arguments |
cam and cam-imu exit 3 when the stored result does not match the files they wrote.
That is an internal consistency check; please report it as a bug.
cam-imu prints its summary JSON whether or not the solve succeeded.
Read ok in that JSON, or grade it with verdict.
Calibrate from one config file.
The top-level mode: key picks the pipeline:
mode: cam(the default whenmode:is absent): runscam.mode: cam-imu: runscam-imuand prints its summary JSON.
mvis run -c config.yaml| Flag | Default | Meaning |
|---|---|---|
-c, --config | required | Run config YAML |
Camera-only calibration: intrinsics, distortion, extrinsics between cameras, camera–camera time offsets and rolling-shutter readout. It reads both config shapes, the flat one and the sectioned one (see Camera-only config).
mvis cam -c t265/cam.yamlmvis cam -c t265/cam.yaml -o results/run # writes results/run/t265_cam_calib.yaml| Flag | Default | Meaning |
|---|---|---|
-c, --config | required | Camera-only config YAML |
-o, --output | <output_file folder>/ablation | Run folder for the report, log and detection cache. By default a folder named ablation next to output_file |
The run folder is cleared before the solve, except its caches.
MVIS clears only a folder it created; it refuses any other folder that already exists.
The run folder holds <name>_calib.yaml, <name>_full.yaml, <name>.html,
<name>.log and detections.mvisdb.
<name> is <config folder>_<config file name>.
The result is also written to the config’s output_file.
See Result formats.
cam-imu
Section titled “cam-imu”Joint camera–IMU calibration. It estimates:
- Extrinsics:
T_CtoI, the pose of each camera in the base IMU frame. The base IMU is the first entry ofinput.imu_topics. - Time offset
td: between each camera clock and the base IMU clock. - Rolling-shutter readout: when
estimate.camera.tris on. - Camera intrinsics: when
estimate.camera.intrinsicsis on. - IMU intrinsics: gyro and accelerometer scale and misalignment (
Dw,Da), optionalTg. - Biases: gyro and accelerometer.
t_ga: the base IMU’s gyro-to-accelerometer time offset (why).- Auxiliary IMUs: extrinsics, time offset and intrinsics of every further IMU.
mvis cam-imu -c cam_imu.yamlmvis cam-imu -c cam_imu.yaml --bag other_recording.bag| Flag | Default | Meaning |
|---|---|---|
-c, --config | required | Camera–IMU config YAML |
--bag | from config | Use this ROS1 bag instead of the config’s input. Sets input.format: ros1 and input.path to the bag |
With input.bags the config calibrates many recordings in one call.
Each one gets its own bag<NN>/cam_imu.json next to output.path.
The command prints a JSON summary of the run.
See Camera–IMU calibration.
calibrate
Section titled “calibrate”The older camera-only path. It reads the flat config shape only and does not
write the run folder, report or capture database that mvis cam writes.
Use cam or run for new work.
mvis calibrate -c config.yaml| Flag | Default | Meaning |
|---|---|---|
-c, --config | required | Flat camera-only config YAML |
apply-calib
Section titled “apply-calib”Apply a saved camera–IMU calibration to a raw ROS1 bag.
It writes a corrected bag and a provenance file, <output bag>.recalib.yaml, that
records the calibration, the topic mapping and which corrections ran.
By default it applies every correction:
- IMU intrinsics: applies the inverse IMU model (
Dw,Da,Tg) to every IMU. - Bias: subtracts the calibrated static gyro and accelerometer bias.
t_ga: re-samples the accelerometer att + t_ga, whent_gawas calibrated.td: re-stamps every camera and auxiliary IMU message onto the base IMU clock, using the header stamp.
mvis apply-calib -c recalib.yamlmvis apply-calib --calib cam_imu_calib.yaml --in raw.bag --out corrected.bagmvis apply-calib --calib cam_imu_calib.yaml --in raw.bag --no-td --keep-bias| Flag | Default | Meaning |
|---|---|---|
-c, --config | — | Config YAML with calib, input, output and the switches below. Flags override it |
--calib | config calib | Calibration to apply: the _calib.yaml that mvis cam-imu writes |
--in | config input | Raw input ROS1 bag |
--out | <input>.corrected.bag | Output bag. An existing bag is not overwritten |
--map | derived | YAML {base_imu_topic, mapping: {topic: sensor}}. Rarely needed: the calibration stores each sensor’s topic |
--keep-bias | off | Keep the static IMU biases (config remove_bias: false) |
--no-imu-intrinsics | off | Skip the inverse IMU model; remove only the bias (config imu_intrinsics: false) |
--no-t-ga | off | Skip the accelerometer t_ga re-sampling (config t_ga: false) |
--no-td | off | Keep the original header and record stamps (config td: false) |
--undistort | off | Also undistort mono8 images (config undistort: true) |
--strict | off | Stop with an error instead of passing data through (config strict: true). See below |
--strict rejects:
- mapped topics that are missing or empty
- messages of the wrong type
- images it cannot undistort
- duplicate IMU stamps on a topic that gets the
t_gacorrection - corrected IMU values that are not finite
The bag is streamed, so memory does not grow with its size. Rolling-shutter rows are not unwarped; only the frame stamp moves. More in Round-trip validation, section “Export a corrected dataset”.
roundtrip
Section titled “roundtrip”End-to-end check of a camera–IMU calibration on a ROS1 bag:
- Calibrate the bag.
- Apply the calibration to the same bag.
- Calibrate the corrected bag.
- Compare the two results and report PASS or FAIL.
On the corrected bag, IMU intrinsics must move to identity and biases to zero,
while extrinsics and the stereo baseline must stay the same.
A remaining td is reported as a warning only.
mvis roundtrip -c cam_imu.yaml| Flag | Default | Meaning |
|---|---|---|
-c, --config | required | Camera–IMU config YAML for a ROS1 bag |
--out | results/roundtrip/<name> | Output folder: forward/cam_imu.json, recal/cam_imu.json, report.txt (readable), report.json |
--bag | from config | Round-trip this ROS1 bag instead of the config’s input |
--keep-corrected | off | Keep the corrected bag; it is deleted by default |
--keep-bias | off | Pass --keep-bias to apply-calib |
It exits 1 on FAIL, so it works as a CI gate.
What PASS means: Round-trip validation.
Check the installation and lint a config before a solve.
The solver accepts configs leniently and only logs unknown keys; check is strict.
Each finding has a stable id and a status pass, warn or fail.
mvis check # check the installationmvis check --env --smoke # also run a short synthetic camera solvemvis check -c config.yaml # lint a configmvis check -c config.yaml --env --json| Flag | Default | Meaning |
|---|---|---|
-c, --config | — | Run config YAML to lint |
--env | on when no -c | Check the installation; with -c, also the optional extras that config needs (AprilGrid, ArUco, ROS bags) |
--smoke | off | Also run a short synthetic camera solve. Implies --env |
--json | off | Print JSON {status, findings} |
--out | — | Also write the JSON findings to this file |
inspect
Section titled “inspect”Summarise a recording before you calibrate it. It reads only metadata and a short sample of each stream. It reports:
- the container format and which modes can read it (
cam,cam-imu) - camera streams: rate, resolution, encoding
- IMU streams: rate, unit sanity, stamp order
- the time overlap of cameras and IMUs
mvis inspect recording.bagmvis inspect dataset/mav0 --json| Argument | Default | Meaning |
|---|---|---|
path | required | ROS1 bag, ROS2 bag folder (or one .db3 / .mcap file), EuRoC mav0 folder or image folder |
--json | off | Machine-readable output |
--out | — | Also write the JSON report to this file |
ROS1 bags, ROS2 bags and EuRoC folders can feed both modes; image folders feed camera-only.
apply-calib and roundtrip need a ROS1 bag.
verdict
Section titled “verdict”Grade a finished result.
Each check has a stable id, the measured value, its threshold and a status.
The grade is RED if any check fails, YELLOW if any warns, GREEN otherwise.
The checks cover:
- reprojection error: median, P95, RMS
- physical plausibility: focal aspect ratio, principal point, finite distortion
- data: corner observations per camera
- camera–IMU solves: solver status, iterations,
td, IMU fit, IMU scale - with
-c: lever arm and stereo baseline against the config’sreference:block
mvis verdict results/run/t265_cam_calib.yamlmvis verdict cam_imu.json -c cam_imu.yaml --independent-check roundtrip| Argument | Default | Meaning |
|---|---|---|
result | required | Camera-only result YAML or camera–IMU summary JSON |
-c, --config | — | Camera–IMU config whose reference: block is compared |
--independent-check | none | Independent check you already ran: none, roundtrip, holdout, repeatability, cross-tool. Recorded in the verdict |
--json | off | Print JSON |
--out | — | Also write the JSON verdict to this file |
verdict never takes a solver’s ok: true as proof of a good fit; see Evaluation & metrics.
datasets
Section titled “datasets”The catalog of benchmark datasets on Hugging Face
(calibench-vi/datasets).
Files go to $MVIS_DATASETS, by default a Datasets folder in your home directory.
The shipped example configs refer to them as ${MVIS_DATASETS}/....
The VI-Rig sets are gated: accept the terms on the Hub page, then set
HF_TOKEN to a read token (or run hf auth login, after pip install huggingface_hub) before you download.
See Datasets.
mvis datasets listmvis datasets list --dataset mvis_4imus_3camsmvis datasets download --select mvis_4imus_3cams/april_01 # about 7 GBmvis datasets download --selection smokemvis datasets verify --dataset mvis_4imus_3camsmvis_4imus_3cams is the catalog key of VI-Rig 4 IMUs + 3 cams.
| Action | What it does |
|---|---|
list | Print each dataset with its licence, and each sequence with its size and URL |
download | Download and checksum the chosen sequences |
verify | Check the local files’ sizes and checksums |
convert | Convert a third-party dataset from its native format to ROS1 bags |
export-recipes | Write stand-alone conversion scripts for datasets that cannot be re-hosted |
upload | Maintainers only: push converted bags to the Hub |
| Flag | Default | Meaning |
|---|---|---|
--dataset | all | One dataset key, for example mvis_4imus_3cams |
--select | — | DATASET or DATASET/SEQUENCE; repeat it to pick several |
--selection | — | A built-in selection (smoke: one sequence from each of eight datasets, VI-Rig april_01 first) or a JSON file {dataset: [sequences]} |
--suite | all | Only the sequences of one test suite: camera-only or camera-imu |
--allow-unverified | off | download: also fetch files the catalog has no checksum for |
--mcap | off | convert: also write a ROS2 MCAP copy of each bag |
--out | recipes | export-recipes: output folder |
--dry-run | off | upload: print the plan only |
Environment variables
Section titled “Environment variables”| Variable | Default | Meaning |
|---|---|---|
MVIS_DATASETS | Datasets in your home directory | Where mvis datasets puts files; ${MVIS_DATASETS} in configs expands to it |
MVIS_BLAS_THREADS | 1 | BLAS threads for the process. 0 keeps the library default. An exported OPENBLAS_NUM_THREADS, OMP_NUM_THREADS or MKL_NUM_THREADS is never overridden |
MVIS_EIGEN_CACHE_CPU | lowest allowed CPU | CPU whose cache sizes the linear algebra uses, so a solve does not depend on which core it starts on. off reads them wherever the first product runs |
The mvis command uses one BLAS thread because the solvers run many small matrix
products in Python. Extra threads only spin, and results can change with the thread count.
import mvis as a library leaves these settings alone.
Scripts in the repository
Section titled “Scripts in the repository”These ship in the source repository, not as subcommands:
| Script | What it does |
|---|---|
scripts/setup_env.sh | One-step conda setup; see Installation |
scripts/test.sh <tier> | Run the tests by tier: unit, solver, integration or full; extra arguments go to pytest |
scripts/visualize_result.py <run_dir> | Post-hoc Rerun 3D viewer for a result directory (--no-spawn to attach to a running viewer) |
scripts/run_calibration.py | Multi-camera ablation: calibrate with each camera as the reference |
scripts/recalib_batch.py | Apply one calibration across every *.bag in a directory (--calib, --in-dir, --out-dir) |
python -m mvis.analysis.regenerate_html [root] | Rebuild HTML reports from saved YAML + detection cache |
The maintainers’ regression runner and its baselines are not part of the public repository; Regression testing describes that workflow.
More detail in Evaluation & metrics.