PyVINS-Mono is a Python implementation of the VINS-Mono algorithm, leveraging GTSAM for robust back-end optimization. This project aims to provide an easy-to-use, modular, and extensible visual-inertial SLAM (VIO) framework tailored for the Python ecosystem.
| ROS Rviz View | Open3D View |
|---|---|
 |
 |
| MH_01_easy evo trajectory | MH_01_easy evo accuracy |
|---|---|
 |
 |
This project is built upon the GTSAM 4.3a framework. The logic and implementation details draw inspiration and reference from the following established open-source projects:
This project strictly requires GTSAM 4.3a0 or GTSAM 4.3a1.
⚠️ Important Warning: Do not install GTSAM via the standardpip install gtsamcommand. The pip version is typically 4.2, which lacks specific features required by this project.
We highly recommend using Conda to manage your Python environment and dependencies.
Installing GTSAM 4.3a: You must compile GTSAM 4.3a0 or 4.3a1 from source or install a compatible binary.
- Source Compilation Tutorial: GTSAM 4.3a
(This might be change after other dataset is tested)
Before running the system, ensure your dataset is organized with the specific directory structure shown below.
For the EuRoC dataset, this project supports the standard raw format. You do not need to reorganize the files but just simply extract the downloaded dataset.
Required Directory Structure:
EuRoC_Dataset_Root/ # e.g., MH_01_easy
└── mav0/
├── cam0/ # Left camera data
├── cam1/ # Right camera data
├── imu0/ # IMU measurements
├── leica0/ # Ground truth (Leica)
└── state_groundtruth_estimate0/
- Tested Sequences: This project has been currently tested and verified on sequences below:
MH_01_EasyMH_02_EasyMH_03_MediumMH_04_DifficultMH_05_DifficultV1_01_EasyV1_02_MediumV2_01_EasyV2_02_MediumV2_03_Difficult
The project supports synced and unsynced KITTI formats. Ensure your dataset root contains the image and OXTS folders directly.
⚠️ Important Warning: Due to the complexity of the kitti dataset, running this project on KITTI is currently difficult. We have only successfully tested and verified one sequence.
Required Directory Structure:
KITTI_Dataset_Root/ # e.g., 2011_09_26_drive_0005_extract
├── image_00/ # Grayscale Left
├── image_01/ # Grayscale Right
├── image_02/ # Color Left
├── image_03/ # Color Right
└── oxts/ # GPS/IMU Data
- Tested Sequences: This project has been currently tested and verified on sequences below:
2011_09_30_drive_0027_sync
Modify the configuration file (located in config/) to set the path to your target dataset.
Open your terminal(with gtsam environment), navigate to the project root, and execute:
python3 main.py --config config/euroc/euroc_MH01-03.yamlThis project supports comprehensive debug logging functionality, including log outputs from both the frontend and backend of the VIO system. The debug module (utils/debug.py) provides flexible logging capabilities that allow you to:
- Monitor VIO System Performance: Track frontend feature tracking metrics and backend optimization states
- Custom Data Output: Define custom CSV log files with user-specified column names for any variables you want to monitor
- Trajectory Logging: Export trajectory data in TUM format for evaluation and visualization
The debug logs are saved as CSV files in the output/log/ directory, which can be easily visualized using tools like PlotJuggler.
Frontend Debug Example (using PlotJuggler):
 |
Backend Debug Example (using PlotJuggler):
 |
For more details on how to use the debug functionality, please refer to the utils/debug.py source code.
We are actively working on improving PyVINS-Mono
- Fix IMU gyroscope bias drift
- Add ROS interface
- Add more dataset tests