Skip to content

Requirements

Use this page to check that your machine and your recording fit MVIS before you install it. The install itself is on Installation.

  • Operating system: Linux or macOS, on x86-64 or arm64.
  • Windows: tentative. MVIS has run there, but GTSAM publishes no Windows wheels on PyPI, so the install steps aren’t written up yet.
  • Python: 3.11 or 3.12.
  • Not supported: Python 3.13. GTSAM publishes no wheels below Python 3.11, and NumPy 1.x, which GTSAM needs, has no Python 3.13 wheel.
  • Nothing to compile: every dependency installs from a pip wheel.

pip installs these with MVIS. The bounds are the ones in pyproject.toml.

PackageVersionUsed for
GTSAM≥ 4.2, < 4.3Factor-graph solver, with SO(3)/SE(3) rotations and poses as native types
NumPy≥ 1.20, < 2Arrays. GTSAM 4.2 is built for NumPy 1.x; NumPy 2 crashes it
OpenCV (opencv-python)≥ 4.5, < 4.12Board detection and initial poses. OpenCV 4.12 and later need NumPy 2
SciPy≥ 1.7Numerics
PyYAML≥ 6.0Config and result files
Matplotlib, Plotly≥ 3.5, ≥ 5.0Figures in the HTML reports
tqdm≥ 4.60Progress bars

Board detectors and bag readers are optional extras. They are listed on Installation.

Detection reads one image at a time, so memory does not grow with the size of the recording. Set source_type per camera:

source_typeInputExtra needed
imagesA folder of images, sorted by filename (.jpg .jpeg .png .bmp .tiff .tif)—
timestamped_imagesA folder of images plus a CSV of filename,timestamp—
eurocEuRoC / ASL folder, as in TUM-VI, EuRoC MAV and Monado SLAM—
rosbag_topicROS1 bag, several cameras from one file. sensor_msgs/Image, or CompressedImage in PNG or JPEGros1
ros2bagROS2 bag: the folder with its metadata.yaml, or one .db3 or .mcap file. Same image types as ROS1ros1
  • No ROS install: the ros1 extra installs rosbags, a pure-Python reader for ROS1 and ROS2 bags.
  • Camera–IMU runs read a ROS1 bag, a ROS2 bag or a EuRoC mav0 folder (input.format: ros1 | ros2 | euroc).
  • mvis apply-calib and mvis roundtrip read and write ROS1 bags only.
  • JPEG images are lossy and can shift corners. MVIS warns once per topic.
  • Video files are not read. Extract the frames to a folder first.

Set board_type and the fields for your board:

Boardboard_typeRequired fieldsExtra needed
AprilGridapriltagrows, cols, tag_size (m), tag_spacing (ratio), tag_familyapriltag
Chessboardchessboardrows, cols (inner corners), square_size (m)—
ArUcoarucorows, cols, marker_size, marker_separation, aruco_dictaruco

A Kalibr AprilGrid target YAML loads in Python with mvis.detection.apriltag_board.AprilTagBoard.from_kalibr_yaml; in a config, copy its values into board:. Set up the board covers printing and measuring it.

  • The board in view: in every camera, filling the image from centre to corners, near and far, at many tilts.
  • Overlap between cameras: for camera extrinsics, cameras must see the board at the same time in part of the recording.
  • Motion for the IMU: rotation about all three axes and acceleration along all three. Without it, the IMU intrinsics, lever arm and time offset stay weakly pinned (Degeneracy).
  • Timestamps: every image and IMU sample needs a timestamp. MVIS solves the offsets between clocks; it cannot recover missing stamps.

Record the dataset gives the motion pattern step by step. The mvis inspect command reports what a recording holds before you solve.