{"id":20837434,"url":"https://github.com/rpng/ov_plane","last_synced_at":"2025-09-21T18:07:14.611Z","repository":{"id":150651142,"uuid":"623152262","full_name":"rpng/ov_plane","owner":"rpng","description":"A monocular plane-aided visual-inertial odometry","archived":false,"fork":false,"pushed_at":"2024-05-20T20:48:58.000Z","size":8601,"stargazers_count":220,"open_issues_count":4,"forks_count":30,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-05-20T15:05:31.656Z","etag":null,"topics":["ekf-localization","msckf","open-vins","planar-regularities","plane","robotics","sensor-calibration","slam","vio","visual-inertial-odometry"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rpng.png","metadata":{"files":{"readme":"ReadMe.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-03T19:57:54.000Z","updated_at":"2025-05-20T06:02:48.000Z","dependencies_parsed_at":"2025-01-15T23:16:14.915Z","dependency_job_id":"e76ff78a-06a6-42cf-b049-65fe3998d51a","html_url":"https://github.com/rpng/ov_plane","commit_stats":{"total_commits":11,"total_committers":2,"mean_commits":5.5,"dds":0.09090909090909094,"last_synced_commit":"51b3d96b43fed9fa9cb49b88a89e2ed0d79f5e01"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/rpng/ov_plane","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpng%2Fov_plane","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpng%2Fov_plane/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpng%2Fov_plane/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpng%2Fov_plane/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rpng","download_url":"https://codeload.github.com/rpng/ov_plane/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpng%2Fov_plane/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276281346,"owners_count":25615609,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-21T02:00:07.055Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ekf-localization","msckf","open-vins","planar-regularities","plane","robotics","sensor-calibration","slam","vio","visual-inertial-odometry"],"created_at":"2024-11-18T01:07:32.198Z","updated_at":"2025-09-21T18:07:14.589Z","avatar_url":"https://github.com/rpng.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Monocular Visual-Inertial Odometry with Planar Regularities \n\n\n[![](data/resources/readme.png)](https://www.youtube.com/watch?v=bec7LbYaOS8)\n\n[![ROS 1 Workflow](https://github.com/rpng/ov_plane/actions/workflows/build_ros1.yml/badge.svg)](https://github.com/rpng/ov_plane/actions/workflows/build_ros1.yml)\n\nThis is a real-time monocular visual-inertial odometry (VIO) system leverage environmental **planes** within a multi-state constraint Kalman filter (MSCKF) framework.\nAt the core of our method is an efficient robust monocular-based plane detection algorithm which does not require additional sensing modalities such as a stereo, depth camera or neural network.\nThe project is built on top of [OpenVINS](https://github.com/rpng/open_vins) and thus shares similar tooling and architecture.\nThis plane detection and tracking algorithm enables real-time regularization of point features to environmental planes which are either maintained in the state vector as long-lived planes, or marginalized for efficiency.\nPlanar regularities are applied to both in-state SLAM and out-of-state MSCKF point features, enabling long-term point-to-plane loop-closures due to the large spacial volume of planes.\n\n* Github project page - https://github.com/rpng/ov_plane\n* Demonstration video - https://www.youtube.com/watch?v=bec7LbYaOS8\n* Publication reference: https://chuchuchen.net/downloads/papers/Chen2023ICRA.pdf\n\n\n\n## Installation and Building\n\nYou will need to ensure you have installed OpenCV 3 or 4, Eigen3, Ceres Solver, and a valid ROS 1 installation.\nPlease additionally refer to the OpenVINS [Installation Guide](https://docs.openvins.com/gs-installing.html) as dependencies are shared with it.\nFor Ubuntu linux-based system the system dependencies are (in addition to [ROS 1](https://docs.openvins.com/gs-installing.html#gs-install-ros-1)):\n\n```bash\nsudo apt-get install libeigen3-dev libboost-all-dev libceres-dev\n```\n\nWe now setup a catkin workspace with both OpenVINS and the ov_plane project.\nSpecifically, we can clone both projects:\n\n```bash\nmkdir -p ~/workspace/catkin_ws_plane/src/\ncd ~/workspace/catkin_ws_plane/src/\ngit clone https://github.com/rpng/open_vins/\ngit clone https://github.com/rpng/ov_plane/ \ncd open_vins/\ngit checkout 74a63cf758f595cc280f2165e5a6576e7ef8521d # last tested OpenVINS commit\ncd ~/workspace/catkin_ws_plane/\ncatkin build\nsource devel/setup.bash \n```\n\n\n## Running - Simulation\n\nWe extended the OpenVINS simulator to simulated environmental planes which contain environmental features.\nA certain number of points are simulated as being planar and \"free\" non-planar per frame.\nThis simulator leverages a C++ implementation of our [lips](https://github.com/rpng/lips) simulator.\n\n```bash\nroslaunch ov_plane simulation.launch\n```\n\nTo generate simulation results, one inspect the [results/run_simulation.sh](results/run_simulation.sh) script to reproduce the results of the paper.\nTo evaluate the results relative to the groundtruth please refer to [ov_eval](https://docs.openvins.com/namespaceov__eval.html) of OpenVINS.\nThe code has changed since publication to upgrade to the newest OpenVINS, but the results should still be representative.\n\n\n## Running - Real-World Datasets\n\nWe support both the [The EuRoC MAV Dataset](https://projects.asl.ethz.ch/datasets/doku.php?id=kmavvisualinertialdatasets) and our released [RPNG AR Table Dataset](https://github.com/rpng/ar_table_dataset) datasets.\nTo run on either real-world dataset, use one of the following commands:\n\n```bash\nroslaunch ov_plane serial.launch config:=euroc_mav dataset:=V1_01_easy bag:=\u003cpath_to_bag\u003e\nroslaunch ov_plane serial.launch config:=rpng_plane dataset:=table_01  bag:=\u003cpath_to_bag\u003e\n```\n\nUsers can reproduce the results presented in our publication with the scripts provided in the [results/](results/) folder.\nWe additionally provide the script used to compute the evaluation, which are simple calls to [ov_eval](https://docs.openvins.com/namespaceov__eval.html) of OpenVINS.\nThe groundtruth \"truths\" files can be found in [ov_data](https://github.com/rpng/open_vins/tree/master/ov_data).\nPlease note the project has been updated since the time of publication and thus will cause slight variations in performance relative to the paper\n\n```bash\n./src/ov_plane/results/run_ros_eth.sh        # Euroc MAV\n./src/ov_plane/results/run_ros_rpng_plane.sh # RPNG Indoor AR Table\n./src/ov_plane/results/run_ros_tracking.sh   # Tracking statistics\n```\n\n\n\n## Acknowledgements\n\nThis project additionally leveraged the following wonderful libraries.\n- [CDT](https://github.com/artem-ogre/CDT) - For generating Delaunay triangulations\n- [ikd-tree](https://github.com/hku-mars/ikd-Tree) - For KNN searching without requiring ICP\n- [tinyrender](https://github.com/ssloy/tinyrenderer) - For loading models for the AR demo\n\n\n\n## Credit / Licensing\n\nThis code was written by the [Robot Perception and Navigation Group (RPNG)](https://sites.udel.edu/robot/) at the\nUniversity of Delaware. If you have any issues with the code please open an issue on our github page with relevant\nimplementation details and references. For researchers that have leveraged or compared to this work, please cite the\nfollowing:\n\n\n```bibtex\n@Conference{Chen2023ICRA,\n  Title      = {Monocular Visual-Inertial Odometry with Planar Regularities},\n  Author     = {Chuchu Chen and Patrick Geneva and Yuxiang Peng and Woosik Lee and Guoquan Huang},\n  Booktitle  = {Proc. of the IEEE International Conference on Robotics and Automation},\n  Year       = {2023},\n  Address    = {London, UK},\n  Url        = {\\url{https://github.com/rpng/ov_plane}}\n}\n```\n\n```bibtex\n@Conference{Geneva2020ICRA,\n  Title      = {{OpenVINS}: A Research Platform for Visual-Inertial Estimation},\n  Author     = {Patrick Geneva and Kevin Eckenhoff and Woosik Lee and Yulin Yang and Guoquan Huang},\n  Booktitle  = {Proc. of the IEEE International Conference on Robotics and Automation},\n  Year       = {2020},\n  Address    = {Paris, France},\n  Url        = {\\url{https://github.com/rpng/open_vins}}\n}\n```\n\nThe codebase and documentation is licensed under the [GNU General Public License v3 (GPL-3)](https://www.gnu.org/licenses/gpl-3.0.txt).\nYou must preserve the copyright and license notices in your derivative work and make available the complete source code with modifications under the same license ([see this](https://choosealicense.com/licenses/gpl-3.0/); this is not legal advice).\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frpng%2Fov_plane","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frpng%2Fov_plane","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frpng%2Fov_plane/lists"}