Skip to content

Python API

Use this page to find which MVIS module to import for each job. MVIS is a Python library: the mvis command is a thin layer over the functions below. The package is pymvis; you import it as mvis.

import mvis
print(mvis.__version__) # 0.1.0
ModuleContents
mvis.coreResult types (Observation, CameraParams, CalibrationResult), the config dataclasses, timing
mvis.cameraOne CameraModel class per camera model: projection, Jacobians and unprojection in one place
mvis.detectionBoards (chessboard, AprilGrid, ArUco), detectors, frame quality, corner subsampling
mvis.ioData sources, the streaming detection pipeline, image decoding, the camera–IMU loader, output writers, Kalibr and Basalt files
mvis.imuIMU intrinsic models (kalibr, rpng, calyx), resampling, Allan-variance analysis
mvis.calibrationFirst guess, factor graph, camera-only and camera–IMU pipelines, outlier rejection
mvis.simulationSynthetic camera–IMU data, digital twins, simulator examples
mvis.recalibapply-calib and roundtrip
mvis.datasetsThe dataset catalog behind mvis datasets
mvis.doctormvis check and mvis inspect
mvis.mvisdbThe capture database
mvis.analysisHTML reports, plots, the Rerun 3D view, motion analysis, verdict
mvis.cliThe mvis command

Terms:

  • Jacobian: the derivatives of a projection with respect to its inputs; the solver needs them.
  • Unprojection: the reverse of projection, from a pixel back to a viewing ray.
  • First guess: OpenCV’s pose-from-known-points solve (PnP) and a focal-length estimate, before the joint solve.
from mvis.core.config import CamRunConfig, CamImuRunConfig, CalibrationConfig
from mvis.core.config_validator import validate_config
cam_cfg = CamRunConfig.from_yaml("t265/cam.yaml") # camera-only, flat or sectioned
imu_cfg = CamImuRunConfig.from_yaml("cam_imu.yaml") # camera–IMU
problems = validate_config(CalibrationConfig.from_yaml("t265/cam.yaml")) # list of strings

The fields are those on Configuration. from_yaml expands ${MVIS_DATASETS} and ~, and warns on unknown keys.

FunctionDoes
mvis.calibration.cam_run.run_cam(config_path, output=None, *, result_file=None, ...)Camera-only run, as mvis cam; the other keyword arguments mirror its options. Returns 0 on success, 1 when the solve failed; raises SystemExit(3) on an internal consistency failure
mvis.cli.main.calibrate_cam_imu(config)Camera–IMU run from a CamImuRunConfig, as mvis cam-imu. Writes every output file and returns the summary dict (the cam_imu.json content)
mvis.cli.main.calibrate_cam_imu_batch(config, out_dir)One calibrate_cam_imu per entry of input.bags; returns {bag<NN>: summary}
mvis.calibration.pipeline_cam_imu.run_cam_imu_calibration_multi(cams, board_points, t_imu, w_m, a_m, *, aux_imus=None, config=None)The camera–IMU solve on arrays already in memory, without files. The simulator examples use it
from mvis.core.config import CamImuRunConfig
from mvis.cli.main import calibrate_cam_imu
summary = calibrate_cam_imu(CamImuRunConfig.from_yaml("cam_imu.yaml"))
print(summary["ok"], summary["cams"][0]["p_CinI_mm"], summary.get("t_ga_ms"))
FunctionDoes
mvis.analysis.verdict.assess(path, reference=None)Grade a result file, as mvis verdict. Returns a Verdict with grade and checks; .to_dict() for JSON
mvis.doctor.inspect.inspect(path)Summarise a recording, as mvis inspect. Returns a report with status, streams and findings
mvis.doctor.check_config.check_env(needs=None, smoke=False)Installation checks, as mvis check --env; a list of findings
mvis.doctor.check_config.check_config(path)Config lint, as mvis check -c; a list of findings

Each finding has a stable id, a subject, a status (pass, warn, fail) and a message.

FunctionDoes
mvis.recalib.load_rig_calib(path)Read a camera–IMU _calib.yaml for apply_calibration
mvis.recalib.sensor_map.resolve_mapping(rig, map_path, cfg)Topic-to-sensor mapping: a --map file, the config’s mapping:, or derived from the topics in the calibration
mvis.recalib.apply.apply_calibration(in_bag, out_bag, rig, mapping, base_imu_topic, *, remove_bias=True, undistort=False, imu_intrinsics=True, td=True, t_ga=True, strict=False)Write the corrected bag and its .recalib.yaml, as mvis apply-calib. Returns message counts and output paths
mvis.recalib.roundtrip.run_roundtrip(config_path, *, out=None, keep_corrected=False, keep_bias=False, bag_override=None)The whole round trip, as mvis roundtrip. Returns {ok, checks}
mvis.recalib.roundtrip.roundtrip_report(forward, recal)Compare two cam_imu.json dicts with the round-trip tolerances

mvis.io.kalibr is the one place for Kalibr files.

FunctionDoes
read_camchain(doc)A Kalibr camchain dict → per-camera intrinsics, distortion, resolution
read_camchain_imucam(doc)Also each camera’s T_cam_imu and the stereo T_cn_cnm1
write_camchain_imucam(result)A camera–IMU result → a camchain-imucam dict, ready for yaml.safe_dump
parse_results(path), camera_only(dir), camera_imu(dir)Read the output files of a finished Kalibr run

A camchain is Kalibr’s YAML file of camera parameters. T_cam_imu maps points from the IMU frame into the camera frame. T_cn_cnm1 maps points from the previous camera into this one.

Kalibr AprilGrid target files load with mvis.detection.apriltag_board.AprilTagBoard.from_kalibr_yaml(path). Any board: config block builds a board with mvis.detection.board_factory.create_board(BoardConfig).

import numpy as np
from mvis.camera import create_camera_model
from mvis.imu import create_imu_model, KalibrImu, RpngImu, CalyxImu
cam = create_camera_model("kb4", fx=286.7, fy=286.7, cx=415.0, cy=404.5,
distortion_coeffs=np.array([-0.005, 0.036, -0.035, 0.006]))
  • mvis.camera: PinholeRadtan, PinholeEquidistant, KannalaBrandt4, FOVModel, DoubleSphere, EUCM, UCM, OmniRadtan. Each projects, unprojects and gives Jacobians.
  • mvis.imu: the three IMU intrinsic models and their correction matrices (dw_matrix, da_matrix, tg_matrix). See IMU model.

Simulator examples: a real recorded motion with a full rig setup, ready to simulate.

from mvis.simulation.examples import available, load_example, simulate
from mvis.calibration.pipeline_cam_imu import run_cam_imu_calibration_multi
print(available()) # example names
ex = load_example("twin_gs")
data = simulate(ex, seed=0) # cams, t_imu, w_m, a_m, aux_imus
result = run_cam_imu_calibration_multi(data["cams"], ex.board_points_flat, data["t_imu"],
data["w_m"], data["a_m"],
aux_imus=data["aux_imus"] or None)

The installed package ships twin_gs. A source checkout also has the others under data/sim_examples/, led by virig_4imus_3cams. Their true values are real solves moved by a fixed, seeded perturbation, so no real device calibration ships.

Digital twins of whole recordings are in mvis.simulation.twin: capture(config_path, name) builds a twin from a config and its recording, Twin.load(path) reads a saved one, and solve(twin) simulates, runs the real solver and returns the errors against the truth. See Digital-twin check.

from mvis.datasets import DatasetCatalog
cat = DatasetCatalog.load()
ds = cat.get("mvis_4imus_3cams")
print(ds.license, [s.sequence for s in ds.sequences()])
from mvis.mvisdb.manager import DatabaseManager
db = DatabaseManager()
print(db.runs("results/run/detections.mvisdb")) # the runs stored in one capture
capture = db.load("results/run/detections.mvisdb", run_id=1) # an MVISDatabase with that run folded in

See Capture database.

from mvis.analysis.cam_imu_report import write_cam_imu_report
write_cam_imu_report(result, html_path="report.html", text_path="report.txt",
reference=ref, board=board)

board and reference are optional; without board the report has no board in the 3D scene. To rebuild a camera-only report from a finished run folder: python -m mvis.analysis.regenerate_html <run folder> --config <config>.

A report cannot disagree with the fit it describes: it computes residuals with the same code the solver minimised.

  • mvis.camera holds each model’s projection, Jacobian and unprojection together.
  • mvis.calibration.factors.camera_projection is shared by the solver and the HTML report.