{"id":13528508,"url":"https://github.com/ov2slam/ov2slam","last_synced_at":"2025-04-01T13:32:55.853Z","repository":{"id":37733625,"uuid":"304378444","full_name":"ov2slam/ov2slam","owner":"ov2slam","description":"OV²SLAM is a Fully Online and Versatile Visual SLAM for Real-Time Applications","archived":false,"fork":false,"pushed_at":"2024-04-08T14:03:37.000Z","size":9866,"stargazers_count":593,"open_issues_count":13,"forks_count":129,"subscribers_count":20,"default_branch":"main","last_synced_at":"2024-11-02T14:36:42.441Z","etag":null,"topics":["bundle-adjustment","localization","opencv","ov2slam","real-time","slam","versatile","visison","visual-slam"],"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/ov2slam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"support_files/ov2slam_readme.gif","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-15T16:00:18.000Z","updated_at":"2024-10-30T08:45:06.000Z","dependencies_parsed_at":"2024-11-02T14:41:54.020Z","dependency_job_id":null,"html_url":"https://github.com/ov2slam/ov2slam","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ov2slam%2Fov2slam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ov2slam%2Fov2slam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ov2slam%2Fov2slam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ov2slam%2Fov2slam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ov2slam","download_url":"https://codeload.github.com/ov2slam/ov2slam/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246647753,"owners_count":20811377,"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","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":["bundle-adjustment","localization","opencv","ov2slam","real-time","slam","versatile","visison","visual-slam"],"created_at":"2024-08-01T07:00:20.388Z","updated_at":"2025-04-01T13:32:55.847Z","avatar_url":"https://github.com/ov2slam.png","language":"C++","funding_links":[],"categories":["2. Visual SLAM","\u003ca name=\"cpp\"\u003e\u003c/a\u003eC++"],"sub_categories":["2.3 Stereo"],"readme":"# OV²SLAM\n## A Fully Online and Versatile Visual SLAM for Real-Time Applications\n\n**Paper**: [[arXiv]](https://arxiv.org/pdf/2102.04060.pdf)\n\n**Videos**: [[video #1]](https://www.youtube.com/watch?v=N4LFD4WKHyg), [[video #2]](https://www.youtube.com/watch?v=N5O0-0339fU), [[video #3]](https://www.youtube.com/watch?v=zNevDT12cKI), [[video #4]](https://www.youtube.com/watch?v=xhLZGDdb0FU), [[video #5]](https://www.youtube.com/watch?v=ITE1yYA5B78), [[video #6]](https://www.youtube.com/watch?v=9D66qpzBvi4)\n\n**Authors:** Maxime Ferrera, Alexandre Eudes, Julien Moras, Martial Sanfourche, Guy Le Besnerais \n(maxime.ferrera@gmail.com / first.last@onera.fr).\n\n---\n\n**April 2024 update**: A ROS2 branch of OV2SLAM is now available [here](https://github.com/ov2slam/ov2slam/tree/ros2) thanks to [@MatPiech](https://github.com/MatPiech)\n\n---\n\n\u003cimg src=\"support_files/ov2slam_readme.gif\" width = 512 height = 288 /\u003e\n\n**OV²SLAM** is a fully real-time **Visual SLAM** algorithm for **Stereo** and **Monocular** cameras.  A complete SLAM pipeline\nis implemented with a carefully designed multi-threaded architecture allowing to perform Tracking, Mapping, Bundle Adjustment and Loop Closing in real-time.\nThe Tracking is based on an undirect Lucas-Kanade optical-flow formulation and provides camera poses estimations at the camera's frame-rate.\nThe Mapping works at the keyframes' rate and ensures continuous localization by populating the sparse 3D map and minimize drift through a local map tracking step.\nBundle Adjustment is applied with an anchored inverse depth formulation, reducing the parametrization of 3D map points to 1 parameter instead of 3.\nLoop Closing is performed through an **Online Bag of Words** method thanks to [iBoW-LCD](https://github.com/emiliofidalgo/ibow-lcd).  In opposition to classical\noffline BoW methods, no pre-trained vocabulary tree is required.  Instead, the vocabulary tree is computed online from the descriptors extracted in the incoming video\nstream, making it always suited to the currently explored environment.\n\n## Related Paper:\n\nIf you use OV²SLAM in your work, please cite it as:\n\n\n```\n@article{fer2021ov2slam,\n      title={{OV$^{2}$SLAM} : A Fully Online and Versatile Visual {SLAM} for Real-Time Applications},\n      author={Ferrera, Maxime and Eudes, Alexandre and Moras, Julien and Sanfourche, Martial and {Le Besnerais}, Guy.},\n      journal={IEEE Robotics and Automation Letters},\n      year={2021}\n     }\n```\n\n## License\n\nOV²SLAM is released under the [GPLv3 license](https://www.gnu.org/licenses/gpl-3.0.txt). For a closed-source version of OV²SLAM for commercial purposes, please contact [ONERA](https://www.onera.fr/en/contact-us) (https://www.onera.fr/en/contact-us) or the authors. \n\nCopyright (C) 2020 [ONERA](https://www.onera.fr/en)\n\n## 1. Prerequisites\n\nThe library has been tested with **Ubuntu 16.04 and 18.04**, **ROS Kinetic and Melodic** and **OpenCV 3**.  It should also work with **ROS Noetic and OpenCV 4** but this configuration has not been fully tested.\n\n### 1.0 C++11 or Higher\n\nOV²SLAM makes use of C++11 features and should thus be compiled with a C++11 or higher flag.\n\n### 1.1 ROS\n\nROS is used for reading the video images through bag files and for visualization purpose in Rviz.\n\n[ROS Installation](http://wiki.ros.org/ROS/Installation)\n\nMake sure that the pcl_ros package is installed :\n\n```\n    sudo apt install ros-distro-pcl-ros\n```\n\nor even\n\n```\n    rosdep install ov2slam\n```\n\n\n\n### 1.2 Eigen3\n\n[Eigen3](http://eigen.tuxfamily.org/index.php?title=Main_Page) is used throughout OV²SLAM.  It should work with version \u003e= 3.3.0, lower versions have not been tested.\n\n\n### 1.3 OpenCV\n\nOpenCV 3 has been used for the development of OV²SLAM, OpenCV 4 might be supported as well but it has not been tested.\n(Optional) The use of BRIEF descriptor requires that **opencv_contrib** was installed.  If it is not the case, ORB will be used instead without scale and rotation invariance properties (which should be the exact equivalent of BRIEF).\n\n**WATCH OUT** By default the CMakeLists.txt file assumes that opencv_contrib is installed, __set the OPENCV_CONTRIB flag to OFF\nin CMakeLists.txt if it is not the case__.\n\n### 1.4 iBoW-LCD\n\nA modified version of [iBoW-LCD](https://github.com/emiliofidalgo/ibow-lcd) is included in the Thirdparty folder.  It has been turned into a shared lib and\nis not a catkin package anymore.  Same goes for [OBIndex2](https://github.com/emiliofidalgo/obindex2), the required dependency for iBoW-LCD.\nCheck the lcdetector.h and lcdetector.cc files to see the modifications w.r.t. to the original code.\n\n### 1.5 Sophus\n\n[Sophus](https://github.com/strasdat/Sophus) is used for _*SE(3), SO(3)*_ elements representation.  For convenience, a copy of Sophus has been included in the Thirdparty folder.\n\n### 1.6 Ceres Solver\n\n[Ceres](https://github.com/ceres-solver/ceres-solver) is used for optimization related operations such as PnP, Bundle Adjustment or PoseGraph Optimization.\nFor convenience, a copy of Ceres has been included in the Thirdparty folder.\nNote that [Ceres dependencies](http://ceres-solver.org/installation.html) are still required.\n\n### 1.6 (Optional) OpenGV\n\n[OpenGV](https://github.com/laurentkneip/opengv) can be used for Multi-View-Geometry (MVG) operations.  The results reported in the paper were obtained using OpenGV.\nFor convenience, if OpenGV is not installed, MVG operations' alternatives are proposed with OpenCV functions.  \n**Note** that the performances might be lower without OpenGV.\n\n\n## 2. Installation\n\n### 2.0 Clone\n\nClone the git repository in your catkin workspace:\n\n```\n    cd ~/catkin_ws/src/\n    git clone https://github.com/ov2slam/ov2slam.git\n```\n\n### 2.1 Build Thirdparty libs\n\nFor convenience we provide a script to build the Thirdparty libs:\n\n```\n    cd ~/catkin_ws/src/ov2slam\n    chmod +x build_thirdparty.sh\n    ./build_thirdparty.sh\n```\n\n**WATCH OUT** By default, the script builds obindex2, ibow-lcd, sophus and ceres.  If you want to use your own version of Sophus or Ceres \nyou can comment the related lines in the script.  Yet, about Ceres, as OV²SLAM is by default compiled with the \"-march=native\" flag, the \nCeres lib linked to OV²SLAM must be compiled with this flag as well, which is not the default case (at least since Ceres 2.0).  The _*build_thirdparty.sh*_ script ensures that Ceres builds with the \"-march=native\" flag.\n\nIf you are not interested in the Loop Closing feature of OV²SLAM, you can also comment the lines related to obindex2 and ibow-lcd.\n\n**(Optional)** Install OpenGV:\n\n```\n    cd your_path/\n    git clone https://github.com/laurentkneip/opengv\n    cd opengv\n    mkdir build\n    cd build/\n    cmake ..\n    sudo make -j4 install\n```\n\n\n### 2.2 Build OV²SLAM\n\nBuild OV²SLAM package with your favorite catkin tool:\n\n```\n    cd ~/catkin_ws/src/ov2slam\n    catkin build --this\n    source ~/catkin_ws/devel/setup.bash\n```\n\nOR\n\n```\n    cd ~/catkin_ws/\n    catkin_make --pkg ov2slam\n    source ~/catkin_ws/devel/setup.bash\n```\n\n## 3. Usage\n\nRun OV²SLAM using:\n\n```\n    rosrun ov2slam ov2slam_node parameter_file.yaml\n```\n\nVisualize OV²SLAM outputs in Rviz by loading the provided configuration file: ov2slam_visualization.rviz. \n\n## 4. Miscellaneous\n\n### Supported Cameras Model\n\nBoth the Pinhole Rad-tan and Fisheye camera's models are supported.  The models are OpenCV-based.\nIf you use [Kalibr](https://github.com/ethz-asl/kalibr) for camera calibration, the equivalencies are: \n\n- OpenCV \"Pinhole\" -\u003e Kalibr \"Pinhole Radtan\" \n- OpenCV \"Fisheye\" -\u003e Kalibr \"Pinhole Equidistant\"\n\n### Extrinsic Calibration\n\nThe stereo extrinsic parameters in the parameter files are expected to represent the transformation from the camera frame to the body frame (**T_body_cam \\ X_body = T_body_cam * X_cam**).\nTherefore, if **T_body_camleft** is set as the Identity transformation, for the right camera we have: **T_body_camright** = **T_camleft_camright**.\nIn Kalibr, the inverse transformation is provided (i.e. **T_cam_body**).  Yet, Kalibr also provide the extrinsic transformation of each camera w.r.t. to the previous one with the field **T_cn_cnm1**.  This transformation can be directly used in OV²SLAM by setting **T_body_camleft** = **T_cn_cnm1** and **T_body_camright** = **I_4x4**.\n\n### Parameters File Description\n\nThree directories are proposed within the parameter_files folder: _*accurate*_, _*average*_ and _*fast*_.  They all store the parameter files to be used with KITTI, EuRoC and TartanAir.\n\n* The _*accurate*_ folder provides the parameters as used in the paper for the full method (i.e. OV²SLAM w. LC).  \n\n* The _*fast*_ folder provides the parameters as used in the paper for the Fast version of OV²SLAM.\n\n* The _*average*_ folder is provided for convenience as an in-between mode.\n\n\u003cdetails\u003e\n  \u003csummary\u003e \u003cstrong\u003eParameters details:\u003c/strong\u003e \u003c/summary\u003e\n    \n    * debug: display debugging information or not\n    * log_timings: log and display main functions timings or not\n\n    * mono: set to 1 if you are in mono config\n    * stereo: set to 1 if you are in stereo config\n\n    * force_realtime: set to 1 if you want to enforce real-time processing (i.e. only process last received image, even if it leads to dropping not yet processed images)\n\n    * slam_mode: must be set to 1\n\n    * buse_loop_closer: set to 1 if you want to use LC\n\n    * bdo_stereo_rect: set to 1 if you want to apply stereo rectification (and use epipolar lines for stereo matching)\n    * alpha: to be set between 0 and 1, 0: rectified images contain only valid pixel / 1: rectified images contain all original pixels (see OpenCV doc for more details)\n\n    * bdo_undist: set to 1 if you want to process undistorted images (the alpha parameter will be used in this case too)\n\n    * finit_parallax: amount of parallax expected for creating new keyframes (should be set between 15. and 40.)\n\n    * use_shi_tomasi: set to 1 to use OpenCV GFTT keypoints detector \n    * use_fast: set to 1 to use OpenCV FAST keypoints detector\n    * use_brief: set to 1 to extract BRIEF descriptors from detected keypoints (must be set to 1 for apply local map matching, see below)\n    * use_singlescale_detector: set to 1 to use our keypoints detector based on OpenCV cornerMinEigenVal function\n\n    * nmaxdist: size of image cells for extracting keypoints (the bigger the less keypoints you will have)\n\n    * nfast_th: FAST detector threshold (the lower the more sensitive the detector is)\n    * dmaxquality: GFTT and cornerMinEigenVal detector threshold (the lower the more sensitive the detector is)\n\n    * use_clahe: set to 1 to apply CLAHE on processed images\n    * fclahe_val: strength of the CLAHE effect\n\n    * do_klt: must be set to 1\n    * klt_use_prior: if set to 1, keypoints which are observation of 3D Map Points will be initialized with a constant velocity motion model to get a prior before applying KLT tracking\n    * btrack_keyframetoframe: if set to 1, KLT will be applied between previous keyframe and current frame instead of previous frame and current frame (setting it to 0 usually leads to better accuracy)\n    * nklt_win_size: size of the pixels patch to be used in the KLT tracking\n    * nklt_pyr_lvl: number of pyramid levels to be used with KLT in addition the full resolution image (i.e. if set to 1, two levels will be used: half-resolution, full-resolution)\n\n    * nmax_iter: max number of iterations for KLT optimization\n    * fmax_px_precision: maximum precision seeked with KLT (i.e. solution is not varying more than this parameter)\n\n    * fmax_fbklt_dist: maximum allowed error in the backward KLT tracking\n    * nklt_err: maximum allowed error between KLT tracks\n\n    * bdo_track_localmap: set to 1 to use local map tracking using computed descriptors at each keyframe\n\n    * fmax_desc_dist: distance ratio w.r.t. descriptor size for considering a good match (to be set between 0 and 1)\n    * fmax_proj_pxdist: maximum distance in pixels between a map point projection and a keypoint to consider it as a matching candidate\n\n    * doepipolar: set to 1 to apply 2D-2D epipolar based filtering\n    * dop3p : set to 1 to use a P3P-RANSAC pose estimation\n    * bdo_random: set to 1 to randomize RANSAC\n    * nransac_iter: maximum number of RANSAC iterations allowed\n    * fransac_err: maximum error in pixels for RANSAC\n\n    * fmax_reproj_err: maximum reprojection error in pixels when triangulating new map points\n    * buse_inv_depth: set to 1 to use an anchored inverse depth parametrization in BundleAdjustment, set to 0 to use XYZ parametrization\n\n    * robust_mono_th: threshold to be used for the robust Huber cost function in BundleAdjustment\n\n    * use_sparse_schur: set to 1 to use sparse schur (recommanded) (see Ceres doc)\n    * use_dogleg: set to 1 to apply Dogleg optimization (see Ceres doc)\n    * use_subspace_dogleg: set to 1 to apply subspace Dogleg optimization (see Ceres doc)\n    * use_nonmonotic_step: set to 1 to allow nonmonotic steps in optimization (see Ceres doc)\n\n    * apply_l2_after_robust: set to 1 to re-optimize without the Huber function after removal of detected outliers in BundleAdjustment\n\n    * nmin_covscore: minimum covisibility score w.r.t. to current keyframe for adding a keyframe as a state to optimize in BundleAdjustment\n\n    * fkf_filtering_ratio: ratio of co-observed 3D map points by 4 other keyframes to consider a keyframe as redundant and remove it from the map\n\n    * do_full_ba: if set to 1, a final full BundleAdjustment will be applied once the sequence has been entirely processed\n\u003c/details\u003e\n\n\n### Note on \"-march=native\"\n\nIf you experience issues when running OV²SLAM (segfault exceptions, ...), it might be related to the \"-march=native\" flag.\nBy default, OpenGV and OV²SLAM come with this flag enabled but Ceres does not.  Making sure that all of them are built with or \nwithout this flag might solve your problem.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fov2slam%2Fov2slam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fov2slam%2Fov2slam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fov2slam%2Fov2slam/lists"}