Installation
Use this page to install MVIS and check that it works. Check Requirements first: Linux or macOS (Windows tentative), Python 3.11 or 3.12.
1. Install from source
Section titled “1. Install from source”MVIS 0.1.0 is not on PyPI yet. Install it from the code repository into a fresh virtual environment:
git clone https://github.com/openmvis/openmvis && cd openmvispython3.12 -m venv .venv && source .venv/bin/activate # or python3.11pip install -e ".[apriltag,aruco,ros1,dev]"-
Python 3.11 or 3.12: with Python 3.13 the install stops, because MVIS requires a version below 3.13.
-
-e: an editable install. Edits to the checkout take effect without a reinstall. -
Keep the checkout: the Quickstart runs example configs from it.
With conda
Section titled “With conda”The repository also ships a setup script. It creates a conda environment
named mvis with Python 3.11, installs MVIS with the apriltag, aruco,
ros1, viz and dev extras, adds ffmpeg for the simulator videos, runs
mvis check --env --smoke and then the unit tests:
bash scripts/setup_env.shconda activate mvisFrom PyPI, after the release
Section titled “From PyPI, after the release”With the v0.1.0 release on PyPI, the package installs without a clone:
Into any Python 3.11 or 3.12 environment:
pip install pymvis # core onlypip install "pymvis[apriltag,ros1]" # AprilGrid boards + ROS1/ROS2 bagsThe package is pymvis; the import and the command are mvis.
2. Pick the extras
Section titled “2. Pick the extras”The core install solves camera and camera–IMU calibrations and writes the reports. Extras add board detectors, bag readers and tools:
| Extra | Installs | Needed for |
|---|---|---|
apriltag | aprilgrid | AprilGrid boards |
aruco | opencv-contrib-python (< 4.12) | ArUco boards |
ros1 | rosbags (≥ 0.11.6) | ROS1 and ROS2 bags, read in pure Python with no ROS install |
mcap | mcap, mcap-protobuf-support, PyAV | Converting MCAP recordings |
viz | rerun-sdk | The Rerun 3D viewer (rerun_visualization: true) |
dev | pytest, pytest-cov, pytest-timeout | Running the test suite |
arucoand OpenCV:opencv-contrib-pythonandopencv-pythonboth providecv2, and the one installed last wins. Ifcv2misbehaves, install into a clean environment or uninstallopencv-pythonfirst.
3. Check the install
Section titled “3. Check the install”mvis check --env --smoke--env: checks Python, NumPy, GTSAM, OpenCV, each installed extra, and themviscommand. Each line reads PASS, WARN or FAIL.--smoke: also runs a short synthetic camera solve.- With a config:
mvis check --env -c config.yamlalso checks the extras that config needs.
mvis --help lists every subcommand. The CLI reference
documents each one.
Run your first calibration in the Quickstart.