Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rpng/open_vins/llms.txt

Use this file to discover all available pages before exploring further.

OpenVINS is an open-source research platform for visual-inertial estimation, and contributions from the community are welcome. The project is licensed under GPL-3.0, which means all derivative works and contributions must be made available under the same license. Before submitting a pull request, familiarize yourself with the coding conventions, automated formatting tools, and CI pipeline described on this page.

​
Contribution Workflow

1

Fork and clone the repository

Fork the rpng/open_vins repository on GitHub, then clone your fork locally.
git clone https://github.com/<your-username>/open_vins.git
cd open_vins
2

Create a feature branch

Always work on a dedicated branch. Never commit directly to master.
git checkout -b feature/my-improvement
3

Make your changes

Write your code following the coding style conventions below. Ensure all public functions and classes include Doxygen doc comments. Update or add unit tests where appropriate.
4

Run the code formatter

Before committing, run run_format.sh from the repository root to apply clang-format across all packages. This is required — the CI pipeline will fail if formatting is inconsistent.
bash run_format.sh
The script applies clang-format with the project’s style file to all C/C++ source files across the four core packages:
# run_format.sh
# sudo apt install clang-format

find ov_core/  -regex '.*\.\(cpp\|hpp\|cu\|c\|h\)' -exec clang-format -style=file -i {} \;
find ov_eval/  -regex '.*\.\(cpp\|hpp\|cu\|c\|h\)' -exec clang-format -style=file -i {} \;
find ov_init/  -regex '.*\.\(cpp\|hpp\|cu\|c\|h\)' -exec clang-format -style=file -i {} \;
find ov_msckf/ -regex '.*\.\(cpp\|hpp\|cu\|c\|h\)' -exec clang-format -style=file -i {} \;
5

Open a pull request

Push your branch and open a pull request against the master branch of the upstream repository. Provide a clear description of what the change does and why. Link any relevant GitHub issues.
git push origin feature/my-improvement
Then open a PR at https://github.com/rpng/open_vins/compare.

​
Coding Style

The codebase uses snake_case throughout — for variable names, function names, and file names. Rotation matrices are the one exception and start with a capital letter. All functions must be documented both inline and in the header with Doxygen comments.

​
Naming Conventions

Orientation and position variables must carry their reference frames explicitly: 
Eigen::Matrix<double,3,3> R_ItoC; // SO(3) rotation from IMU to camera frame
Eigen::Matrix<double,4,1> q_ItoC; // JPL quaternion rotation from IMU to camera
Eigen::Vector3d p_IinC;           // 3D position of the IMU frame in the camera frame
Eigen::Vector3d p_FinG;           // position of feature F in the global frame G
Use the built-in print macros (PRINT_ALL, PRINT_DEBUG, PRINT_INFO, PRINT_WARNING, PRINT_ERROR) instead of raw printf or std::cout. The verbosity level is configurable at runtime:
MacroLevel
PRINT_ALLVerbose trace output
PRINT_DEBUGDebug-level information
PRINT_INFOGeneral operational information
PRINT_WARNINGNon-fatal warnings
PRINT_ERRORError conditions
PRINT_INFO("Initialized at time %.4f\n", startup_time);
PRINT_WARNING("Feature count below threshold: %d\n", count);
PRINT_ERROR(RED "Covariance not positive definite!\n" RESET);

​
General Formatting Principles

  • 4-space indentation (no tabs)
  • Prefer vertical and horizontal compression — more code on screen while remaining readable
  • Long lines are acceptable where readability benefits (e.g., Jacobian expressions)
  • Every header file must use an include guard

​
Building the Documentation

OpenVINS uses Doxygen for API documentation, post-processed by m.css for the rendered website.

​
Build the PDF Reference Manual

1

Install dependencies

sudo apt-get update
sudo apt-get install doxygen texlive-full
You may need Doxygen 1.9.4 or newer to avoid ghostscript errors. See this Stack Overflow answer for instructions on installing a newer version.
2

Generate LaTeX files

cd open_vins/
doxygen
3

Compile the PDF

cd doxgen_generated/latex/
make
# Output: refman.pdf

​
Build the Documentation Website

1

Clone m.css (outside the open_vins folder)

git clone https://github.com/mosra/m.css
2

Install Python 3.6 and dependencies

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.6 python3.6-distutils
curl https://bootstrap.pypa.io/pip/3.6/get-pip.py | sudo python3.6
sudo -H pip3.6 install jinja2 Pygments
sudo apt install texlive-base texlive-latex-extra texlive-fonts-extra texlive-fonts-recommended
3

Run the m.css documentation builder

cd m.css/documentation/
python3.6 doxygen.py ~/catkin_ws/src/open_vins/Doxyfile-mcss
If you run into Python path issues:
export PYTHONPATH=/usr/local/lib/python3.6/dist-packages/
4

Open the generated site

open ~/catkin_ws/src/open_vins/doxgen_generated/html/index.html

​
Adding a New Documentation Page

  1. Create docs/pagename.dox with the up-to-date license header.
  2. Add a @page definition and title.
  3. If top-level, list it in docs/00-page-order.dox.
  4. If a subpage, add it with @subpage in its parent page.
  5. Use @section and @subsection to structure the content.

​
CI/CD Pipeline

Every push to master and every pull request triggers three GitHub Actions workflows defined in .github/workflows/:
Builds and runs the simulation on Ubuntu 16.04, 18.04, and 20.04 using Docker images. Each job:
  • Builds using catkin build
  • Launches the simulation: roslaunch ov_msckf simulation.launch verbosity:=WARNING
All three Ubuntu variants must pass before a PR can be merged.
Builds on Ubuntu 18.04, 20.04, and 22.04 using Docker images and colcon build. The simulation step is executed on Ubuntu 20.04:
ros2 run ov_msckf run_simulation src/open_vins/config/rpng_sim/estimator_config.yaml
Verifies that the core library builds without any ROS dependency using plain CMake on Ubuntu Latest. Dependencies installed:
sudo apt-get install -y libeigen3-dev libopencv-dev libboost-all-dev libceres-dev
mkdir build && cd build
cmake ../ov_msckf/ && make
Run bash run_format.sh before pushing. Formatting failures are caught by CI and will block your PR from merging.

​
Reporting Issues

When opening a GitHub issue, include:
  • Platform: OS version, ROS distro (if applicable)
  • Reproduction steps: minimal launch file or dataset used
  • Expected vs. actual behavior: what you expected and what happened
  • Relevant logs: set verbosity:=DEBUG and paste the output
Open issues at https://github.com/rpng/open_vins/issues.

​
License Implications

OpenVINS is licensed under the GNU General Public License v3.0 (GPL-3.0). Contributing code means agreeing to distribute your contribution under the same license. Key requirements for derivative works:
All modifications and extensions that are distributed publicly must include the complete corresponding source code and must be licensed under GPL-3.0. You must preserve all existing copyright and license notices. This is not legal advice — consult the full license text and a legal professional if in doubt.
For research that uses or compares to OpenVINS, please cite the original paper: 
@Conference{Geneva2020ICRA,
  Title     = {{OpenVINS}: A Research Platform for Visual-Inertial Estimation},
  Author    = {Patrick Geneva and Kevin Eckenhoff and Woosik Lee and Yulin Yang and Guoquan Huang},
  Booktitle = {Proc. of the IEEE International Conference on Robotics and Automation},
  Year      = {2020},
  Address   = {Paris, France},
  Url       = {https://github.com/rpng/open_vins}
}

Build docs developers (and LLMs) love

Get started for freeTalk to us