{"id":20837430,"url":"https://github.com/rpng/ov_maplab","last_synced_at":"2025-06-25T18:34:16.384Z","repository":{"id":67476498,"uuid":"203633634","full_name":"rpng/ov_maplab","owner":"rpng","description":"Interface for OpenVINS with the maplab project","archived":false,"fork":false,"pushed_at":"2023-08-26T07:33:54.000Z","size":5062,"stargazers_count":87,"open_issues_count":0,"forks_count":17,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-05-08T20:41:35.936Z","etag":null,"topics":["cooperative-localization","ekf-localization","maplab","msckf","open-vins","slam","visual-inertial-mapping"],"latest_commit_sha":null,"homepage":"https://docs.openvins.com/","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}},"created_at":"2019-08-21T17:33:39.000Z","updated_at":"2025-04-15T09:30:22.000Z","dependencies_parsed_at":"2023-08-31T14:45:13.105Z","dependency_job_id":null,"html_url":"https://github.com/rpng/ov_maplab","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rpng/ov_maplab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpng%2Fov_maplab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpng%2Fov_maplab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpng%2Fov_maplab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpng%2Fov_maplab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rpng","download_url":"https://codeload.github.com/rpng/ov_maplab/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rpng%2Fov_maplab/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261931200,"owners_count":23232034,"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":["cooperative-localization","ekf-localization","maplab","msckf","open-vins","slam","visual-inertial-mapping"],"created_at":"2024-11-18T01:07:31.136Z","updated_at":"2025-06-25T18:34:16.316Z","avatar_url":"https://github.com/rpng.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenVINS Maplab Interface\n\n[![ROS 1 Workflow](https://github.com/rpng/ov_maplab/actions/workflows/build_ros1.yml/badge.svg)](https://github.com/rpng/ov_maplab/actions/workflows/build_ros1.yml)\n\nHere we have our interface wrapper for exporting visual-inertial runs from [OpenVINS](https://github.com/rpng/open_vins) into the ViMap structure taken by [maplab](https://github.com/ethz-asl/maplab). The state estimates and raw images are appended to the ViMap as OpenVINS runs through a dataset. After completion of the dataset, we re-extract features and triangulate them due to the incompatibilities of the two frontends. Maplab requires BRISK or FREAK descriptors, while OpenVINS works with KLT or ORB feature tracking. In the future we will try to only extract descriptors on tracked features from OpenVINS, but for now we just re-detect for simplicity. We have tested this on the [EurocMav](https://docs.openvins.com/gs-datasets.html#gs-data-euroc) and [TUM-VI](https://docs.openvins.com/gs-datasets.html#gs-data-tumvi) datasets and have had good success with merging the different runs and optimizing the resulting graph. To ensure that we are able to compile maplab, we provide a [docker image](Dockerfile) for Ubuntu 20.04 which has all dependencies required.\n\n## Dependencies\n\n* OpenVINS (v2.7 release) - https://docs.openvins.com/gs-installing.html\n* maplab (v2.0, 20.04 release) - https://github.com/ethz-asl/maplab/wiki/Installation-Ubuntu\n* Docker - https://docs.docker.com/get-docker/\n\n## Installation Guide\n\nClone and setup workspace:\n```bash\n# setup our workspace and clone\nmkdir -p catkin_ws_maplab/src/\ncd catkin_ws_maplab/src/\ngit clone https://github.com/rpng/ov_maplab.git\ngit clone https://github.com/rpng/open_vins.git\ngit clone https://github.com/ethz-asl/maplab.git --recursive\n# switch open_vins to last tested commit (might build with newer)\ncd open_vins/\ngit checkout 4534a2f32d4763bdc8c95121b3292c7423e12aca\ncd ..\n# switch maplab to last tested commit (might build with newer)\ncd maplab/\ngit checkout 0b4868efeb292851d71f98d31a1e6bb40ebb244b\ngit submodule update --init --recursive\ncd ..\n```\n\nBuild the docker image:\n```bash\ncd ov_maplab/\ndocker build -t ov_maplab -f Dockerfile_ros1_20_04 .\nnano ~/.bashrc\nxhost + \u0026\u003e /dev/null\nexport DOCKER_CATKINWS=/home/username/workspace/catkin_ws_maplab\nexport DOCKER_DATASETS=/home/username/datasets\nalias ov_docker=\"docker run -it --net=host --gpus all \\\n    --env=\\\"NVIDIA_DRIVER_CAPABILITIES=all\\\" --env=\\\"DISPLAY\\\" \\\n    --env=\\\"QT_X11_NO_MITSHM=1\\\" --volume=\\\"/tmp/.X11-unix:/tmp/.X11-unix:rw\\\" \\\n    --mount type=bind,source=$DOCKER_CATKINWS,target=/catkin_ws \\\n    --mount type=bind,source=$DOCKER_DATASETS,target=/datasets $1\"\nsource ~/.bashrc\ncd ..\n```\n\nBuild maplab, OpenVINS, and ov_maplab in the container:\n```bash\nov_docker ov_maplab bash\ncd catkin_ws/\ncatkin init\ncatkin config --merge-devel\ncatkin config --extend /opt/ros/noetic\ncatkin config --cmake-args -DCMAKE_BUILD_TYPE=Release\ncatkin build maplab ov_maplab -j4\ncatkin build ov_maplab -j4 --no-deps # after first build\nsource devel/setup.bash\n```\n\n\n\n## Processing Map Example\n\nLoad into docker bash shell and run OpenVINS:\n```bash\nov_docker ov_maplab bash\ncd catkin_ws/\nsource devel/setup.bash\n# run OpenVINS on a dataset\nroslaunch ov_maplab serial.launch config:=euroc_mav dataset:=V1_02_medium\n```\n\nLoad and process the generated map:\n```bash\n# load into the main console\nrosrun maplab_console maplab_console\n# load all our maps and join them (they should each be a mission)\nload_all --maps_folder /datasets/euroc_mav/maplab/\njoin_all_maps --target_map_key mergedmap\nset_mission_baseframe_to_known\n# Display all the loaded missions\nmap_stats\n# (optional) Retriangulate landmarks and remove bad ones\nretriangulate_landmarks\nremove_bad_landmarks\n# Visualize all missions with different colors\nspatially_distribute_missions\nv --vis_color_by_mission\n# anchor all frames to the first mission\nanchor_all_missions\nprint_baseframes\n# Loop close the map.\nloopclosure_all_missions\n# Pose graph relaxation\nrelax\n# (optional) Key-frame the map (needed to reduce memory requirements)\nkeyframe_heuristic\n# Visualize all missions with different colors\nv --vis_color_by_mission\n# Bundle adjustment.\noptimize_visual_inertial --ba_num_iterations=50 --ba_visualize_every_n_iterations=1\n# Save the final map (overwrite the old map if there is one)\nsave --overwrite --map_folder \u003cyour_new_merged_map_folder_path\u003e\n```\n\n## Leveraging Maplab as Groundtruth\n\nA use case is if one wishes to use maplab optimized and loop-closed trajectory as groundtruth for evaluation on datasets which do not have an external pose system (i.e. no vicon available). For example of the V1\\_01\\_easy eurocmav dataset before optimization the RMSE was 0.680 degrees and 0.055 meters. After performing loop closure and optimizing the RMSE was 0.576 degrees and 0.021 meters as compared to the published groundtruth. Here are a few example commands which we use to process a run on the eurocmav dataset and then optimize it to be used as a groundtruth.\n\n\nLoad into docker bash shell and run OpenVINS:\n```bash\n# load into docker bash\nov_docker ov_maplab bash\ncd catkin_ws/\nsource devel/setup.bash\n# run openvins and export the map\nroslaunch ov_maplab serial.launch config:=euroc_mav dataset:=V1_02_medium\n```\n\n\nProcess and export an optimized map:\n```bash\n# load the map into maplab\nrosrun maplab_console maplab_console\nload --map_folder /datasets/euroc_mav/maplab/V1_02_medium/\n# optimize the map\nretriangulate_landmarks\nremove_bad_landmarks\nset_mission_baseframe_to_known\nloopclosure_all_missions\nrelax\nvisualize\noptimize_visual_inertial --ba_num_iterations=25 --ba_visualize_every_n_iterations=1\n# finally, we can export using our custom utility\n# this will get it into our space separated format needed for ov_eval\nexport_to_openvins --export_path /datasets/euroc_mav/maplab/\n```\n\n\n## Example Merges\n\nExample map merging of the V1_01_easy, V1_02_medium, and V1_03_difficult from the EurocMav datasets:\n![example eurocmav](docs/2019-08-21_14-13-32.png)\n\nExample map merging of the room1, room2, room3, and corridor1 from the TUM-VI datasets:\n![example tumvi](docs/2019-08-21_13-38-24.png)\n\nExample map merging of the aruco_hallway_02 and aruco_hallway_02 from the RPNG aruco datasets (before left and after right):\n\n\u003cimg src=\"docs/aruco_before.png\" width=\"49%\"/\u003e \u003cimg src=\"docs/aruco_after.png\" width=\"49%\"/\u003e \n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frpng%2Fov_maplab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frpng%2Fov_maplab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frpng%2Fov_maplab/lists"}