Skip to content

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.
Terminal window
mvis --help # list the subcommands
mvis --version # print the MVIS version
mvis cam-imu --help # flags of one subcommand
SubcommandWhat it does
runCalibrate from any config; the config’s mode: picks camera-only or camera–IMU
camCamera-only calibration
cam-imuJoint camera–IMU calibration
calibrateOlder camera-only path for flat configs
apply-calibApply a camera–IMU calibration to a raw ROS1 bag and write a corrected bag
roundtripCalibrate, apply, recalibrate and report PASS or FAIL
checkCheck the installation and lint a config before a solve
inspectSummarise a recording: format, streams, rates, overlap
verdictGrade a finished result GREEN, YELLOW or RED
datasetsList, download and verify the benchmark datasets
Terminal window
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 # calibrate
mvis verdict result.json # grade the result
Subcommand012
check, inspectpasswarnfail
verdictGREENYELLOWRED
roundtripPASSFAILinvalid config or arguments
datasetsevery file OKa file is missing or fails its checkinvalid arguments
cam, run (mode: cam)solvedthe solve failedinvalid 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 when mode: is absent): runs cam.
  • mode: cam-imu: runs cam-imu and prints its summary JSON.
Terminal window
mvis run -c config.yaml
FlagDefaultMeaning
-c, --configrequiredRun 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).

Terminal window
mvis cam -c t265/cam.yaml
mvis cam -c t265/cam.yaml -o results/run # writes results/run/t265_cam_calib.yaml
FlagDefaultMeaning
-c, --configrequiredCamera-only config YAML
-o, --output<output_file folder>/ablationRun 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.

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 of input.imu_topics.
  • Time offset td: between each camera clock and the base IMU clock.
  • Rolling-shutter readout: when estimate.camera.tr is on.
  • Camera intrinsics: when estimate.camera.intrinsics is on.
  • IMU intrinsics: gyro and accelerometer scale and misalignment (Dw, Da), optional Tg.
  • 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.
Terminal window
mvis cam-imu -c cam_imu.yaml
mvis cam-imu -c cam_imu.yaml --bag other_recording.bag
FlagDefaultMeaning
-c, --configrequiredCamera–IMU config YAML
--bagfrom configUse 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.

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.

Terminal window
mvis calibrate -c config.yaml
FlagDefaultMeaning
-c, --configrequiredFlat camera-only config YAML

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:

  1. IMU intrinsics: applies the inverse IMU model (Dw, Da, Tg) to every IMU.
  2. Bias: subtracts the calibrated static gyro and accelerometer bias.
  3. t_ga: re-samples the accelerometer at t + t_ga, when t_ga was calibrated.
  4. td: re-stamps every camera and auxiliary IMU message onto the base IMU clock, using the header stamp.
Terminal window
mvis apply-calib -c recalib.yaml
mvis apply-calib --calib cam_imu_calib.yaml --in raw.bag --out corrected.bag
mvis apply-calib --calib cam_imu_calib.yaml --in raw.bag --no-td --keep-bias
FlagDefaultMeaning
-c, --config—Config YAML with calib, input, output and the switches below. Flags override it
--calibconfig calibCalibration to apply: the _calib.yaml that mvis cam-imu writes
--inconfig inputRaw input ROS1 bag
--out<input>.corrected.bagOutput bag. An existing bag is not overwritten
--mapderivedYAML {base_imu_topic, mapping: {topic: sensor}}. Rarely needed: the calibration stores each sensor’s topic
--keep-biasoffKeep the static IMU biases (config remove_bias: false)
--no-imu-intrinsicsoffSkip the inverse IMU model; remove only the bias (config imu_intrinsics: false)
--no-t-gaoffSkip the accelerometer t_ga re-sampling (config t_ga: false)
--no-tdoffKeep the original header and record stamps (config td: false)
--undistortoffAlso undistort mono8 images (config undistort: true)
--strictoffStop 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_ga correction
  • 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”.

End-to-end check of a camera–IMU calibration on a ROS1 bag:

  1. Calibrate the bag.
  2. Apply the calibration to the same bag.
  3. Calibrate the corrected bag.
  4. 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.

Terminal window
mvis roundtrip -c cam_imu.yaml
FlagDefaultMeaning
-c, --configrequiredCamera–IMU config YAML for a ROS1 bag
--outresults/roundtrip/<name>Output folder: forward/cam_imu.json, recal/cam_imu.json, report.txt (readable), report.json
--bagfrom configRound-trip this ROS1 bag instead of the config’s input
--keep-correctedoffKeep the corrected bag; it is deleted by default
--keep-biasoffPass --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.

Terminal window
mvis check # check the installation
mvis check --env --smoke # also run a short synthetic camera solve
mvis check -c config.yaml # lint a config
mvis check -c config.yaml --env --json
FlagDefaultMeaning
-c, --config—Run config YAML to lint
--envon when no -cCheck the installation; with -c, also the optional extras that config needs (AprilGrid, ArUco, ROS bags)
--smokeoffAlso run a short synthetic camera solve. Implies --env
--jsonoffPrint JSON {status, findings}
--out—Also write the JSON findings to this file

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
Terminal window
mvis inspect recording.bag
mvis inspect dataset/mav0 --json
ArgumentDefaultMeaning
pathrequiredROS1 bag, ROS2 bag folder (or one .db3 / .mcap file), EuRoC mav0 folder or image folder
--jsonoffMachine-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.

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’s reference: block
Terminal window
mvis verdict results/run/t265_cam_calib.yaml
mvis verdict cam_imu.json -c cam_imu.yaml --independent-check roundtrip
ArgumentDefaultMeaning
resultrequiredCamera-only result YAML or camera–IMU summary JSON
-c, --config—Camera–IMU config whose reference: block is compared
--independent-checknoneIndependent check you already ran: none, roundtrip, holdout, repeatability, cross-tool. Recorded in the verdict
--jsonoffPrint 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.

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.

Terminal window
mvis datasets list
mvis datasets list --dataset mvis_4imus_3cams
mvis datasets download --select mvis_4imus_3cams/april_01 # about 7 GB
mvis datasets download --selection smoke
mvis datasets verify --dataset mvis_4imus_3cams

mvis_4imus_3cams is the catalog key of VI-Rig 4 IMUs + 3 cams.

ActionWhat it does
listPrint each dataset with its licence, and each sequence with its size and URL
downloadDownload and checksum the chosen sequences
verifyCheck the local files’ sizes and checksums
convertConvert a third-party dataset from its native format to ROS1 bags
export-recipesWrite stand-alone conversion scripts for datasets that cannot be re-hosted
uploadMaintainers only: push converted bags to the Hub
FlagDefaultMeaning
--datasetallOne 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]}
--suiteallOnly the sequences of one test suite: camera-only or camera-imu
--allow-unverifiedoffdownload: also fetch files the catalog has no checksum for
--mcapoffconvert: also write a ROS2 MCAP copy of each bag
--outrecipesexport-recipes: output folder
--dry-runoffupload: print the plan only
VariableDefaultMeaning
MVIS_DATASETSDatasets in your home directoryWhere mvis datasets puts files; ${MVIS_DATASETS} in configs expands to it
MVIS_BLAS_THREADS1BLAS 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_CPUlowest allowed CPUCPU 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.

These ship in the source repository, not as subcommands:

ScriptWhat it does
scripts/setup_env.shOne-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.pyMulti-camera ablation: calibrate with each camera as the reference
scripts/recalib_batch.pyApply 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.