Requirements
Use this page to check that your machine and your recording fit MVIS before you install it. The install itself is on Installation.
System
Section titled “System”- 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.
Python dependencies
Section titled “Python dependencies”pip installs these with MVIS. The bounds are the ones in pyproject.toml.
| Package | Version | Used for |
|---|---|---|
| GTSAM | ≥ 4.2, < 4.3 | Factor-graph solver, with SO(3)/SE(3) rotations and poses as native types |
| NumPy | ≥ 1.20, < 2 | Arrays. GTSAM 4.2 is built for NumPy 1.x; NumPy 2 crashes it |
OpenCV (opencv-python) | ≥ 4.5, < 4.12 | Board detection and initial poses. OpenCV 4.12 and later need NumPy 2 |
| SciPy | ≥ 1.7 | Numerics |
| PyYAML | ≥ 6.0 | Config and result files |
| Matplotlib, Plotly | ≥ 3.5, ≥ 5.0 | Figures in the HTML reports |
| tqdm | ≥ 4.60 | Progress bars |
Board detectors and bag readers are optional extras. They are listed on Installation.
Input formats
Section titled “Input formats”Detection reads one image at a time, so memory does not grow with the size of
the recording. Set source_type per camera:
source_type | Input | Extra needed |
|---|---|---|
images | A folder of images, sorted by filename (.jpg .jpeg .png .bmp .tiff .tif) | — |
timestamped_images | A folder of images plus a CSV of filename,timestamp | — |
euroc | EuRoC / ASL folder, as in TUM-VI, EuRoC MAV and Monado SLAM | — |
rosbag_topic | ROS1 bag, several cameras from one file. sensor_msgs/Image, or CompressedImage in PNG or JPEG | ros1 |
ros2bag | ROS2 bag: the folder with its metadata.yaml, or one .db3 or .mcap file. Same image types as ROS1 | ros1 |
- No ROS install: the
ros1extra installsrosbags, a pure-Python reader for ROS1 and ROS2 bags. - Camera–IMU runs read a ROS1 bag, a ROS2 bag or a EuRoC
mav0folder (input.format: ros1 | ros2 | euroc). mvis apply-calibandmvis roundtripread 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.
Calibration boards
Section titled “Calibration boards”Set board_type and the fields for your board:
| Board | board_type | Required fields | Extra needed |
|---|---|---|---|
| AprilGrid | apriltag | rows, cols, tag_size (m), tag_spacing (ratio), tag_family | apriltag |
| Chessboard | chessboard | rows, cols (inner corners), square_size (m) | — |
| ArUco | aruco | rows, cols, marker_size, marker_separation, aruco_dict | aruco |
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.
What the recording needs
Section titled “What the recording needs”- 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.