Skip to content

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.

MVIS 0.1.0 is not on PyPI yet. Install it from the code repository into a fresh virtual environment:

Terminal window
git clone https://github.com/openmvis/openmvis && cd openmvis
python3.12 -m venv .venv && source .venv/bin/activate # or python3.11
pip 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.

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:

Terminal window
bash scripts/setup_env.sh
conda activate mvis

With the v0.1.0 release on PyPI, the package installs without a clone:

Into any Python 3.11 or 3.12 environment:

Terminal window
pip install pymvis # core only
pip install "pymvis[apriltag,ros1]" # AprilGrid boards + ROS1/ROS2 bags

The package is pymvis; the import and the command are mvis.

The core install solves camera and camera–IMU calibrations and writes the reports. Extras add board detectors, bag readers and tools:

ExtraInstallsNeeded for
apriltagaprilgridAprilGrid boards
arucoopencv-contrib-python (< 4.12)ArUco boards
ros1rosbags (≥ 0.11.6)ROS1 and ROS2 bags, read in pure Python with no ROS install
mcapmcap, mcap-protobuf-support, PyAVConverting MCAP recordings
vizrerun-sdkThe Rerun 3D viewer (rerun_visualization: true)
devpytest, pytest-cov, pytest-timeoutRunning the test suite
  • aruco and OpenCV: opencv-contrib-python and opencv-python both provide cv2, and the one installed last wins. If cv2 misbehaves, install into a clean environment or uninstall opencv-python first.
Terminal window
mvis check --env --smoke
  • --env: checks Python, NumPy, GTSAM, OpenCV, each installed extra, and the mvis command. Each line reads PASS, WARN or FAIL.
  • --smoke: also runs a short synthetic camera solve.
  • With a config: mvis check --env -c config.yaml also checks the extras that config needs.

mvis --help lists every subcommand. The CLI reference documents each one.

Run your first calibration in the Quickstart.