{"id":18792479,"url":"https://github.com/prbonn/vpr_relocalization","last_synced_at":"2025-04-13T14:31:18.118Z","repository":{"id":83737696,"uuid":"109698048","full_name":"PRBonn/vpr_relocalization","owner":"PRBonn","description":"The framework for visual place recognition in changing enviroments. Matches two sequence of images of arbitrary trajectory overlap.","archived":false,"fork":false,"pushed_at":"2022-09-24T15:06:29.000Z","size":3872,"stargazers_count":102,"open_issues_count":1,"forks_count":32,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-03-21T13:56:36.634Z","etag":null,"topics":["graph-based-matching","outdoor-localization","relocalization","visual-place-recognition"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PRBonn.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":null,"governance":null}},"created_at":"2017-11-06T13:20:47.000Z","updated_at":"2024-02-27T08:31:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"95f67046-e6bf-4a98-b80f-df32df4e0c5c","html_url":"https://github.com/PRBonn/vpr_relocalization","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/PRBonn%2Fvpr_relocalization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRBonn%2Fvpr_relocalization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRBonn%2Fvpr_relocalization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRBonn%2Fvpr_relocalization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PRBonn","download_url":"https://codeload.github.com/PRBonn/vpr_relocalization/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223589759,"owners_count":17170034,"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":["graph-based-matching","outdoor-localization","relocalization","visual-place-recognition"],"created_at":"2024-11-07T21:20:05.583Z","updated_at":"2024-11-07T21:20:06.614Z","avatar_url":"https://github.com/PRBonn.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Visual place recognition using image sequences with Relocalization\n\nThis project is **not maintained**. Please consider a newer version [image_sequence_localizer](https://github.com/ovysotska/image_sequence_localizer).\n\n## What does this code do?\nPerforms matching of two image sequences of arbitrary shaped trajectories, e.g. the query trajectory may deviate from reference one. This work is an extension of our work on image sequence matching under changing visual appearances. The previous approach was dealing well with trajectories that roughly follows the same route. You can find the code by following this link [online place recognition](https://github.com/Photogrammetry-Robotics-Bonn/online_place_recognition).\n\nIn this framework, the system is able to deal with trajectories of arbitrary shapes:\n\n* by performing relocalization step, whenever the robot is considered lost, e.g. the query trajectory deviates from the reference one.\n* by taking into account the information about the similar places within reference trajectory to ensure the multiple localization hypothesis.\n\n![image sequences from different routes and weather conditions](doc/pics/motiv.png)\n\nIn Figure the images from the blue trajectory are matched against the images of orange trajectory. Blue trajectory (query) follows partially the orange trajectory (reference) as well as deviating from it. These kinds of challenges in matching images sequences are targeted in this framework. (Trajectories are plotted over Google Maps for visualization purposes. The GPS coordinates are not used for place recognition.)\n\nFor more theoretical details, please refer to our paper [Relocalization under Substantial Appearance Changes using Hashing](http://www.ipb.uni-bonn.de/wp-content/papercite-data/pdf/vysotska2017irosws.pdf).\n\n\n## Installation guide\n\n### Prerequisites\n\n* Yaml-cpp (requires BOOST till now): `sudo apt-get install libyaml-cpp-dev libboost-all-dev`\n* OpenCV: `sudo apt-get install libopencv-dev`\n* Qt5: `sudo apt-get install qt5-default`\n* (optional) Doxygen (generate documentation): `sudo apt-get install doxygen`\n\n\n### Build\nThe code is tested on Ubuntu 16.04 and 18.04.\nTo build the project, run the following commands from the main directory:\n\n* `mkdir build`\n* `cd build`\n* `cmake ..`\n* `make -j4`\n\n\nAdditionally, you should be able to generate documentation as follows:\n\n* `cd doc`\n* `doxygen online_place_recognition.conf`\n\nTo access the documentation run `firefox html/index.html`.\n\nIf you want to build on Ubuntu 14.04, you may run into issues with yaml-cpp.\n\n\n## What do I need to run this code?\n\n* Precomputed image descriptors (features) or cost matrix\n* Configuration file\n* Precomputed hash table\n* (optional) Estimated similar places within the reference sequence\n\nFor the examples of how to run the code please see [**RUN EXAMPLES**](examples/readme.md).\n\n\n#### Feature based matching\nIn this mode, the program operates using **precomputed image descriptors**.\nTo run the matching procedure you need to provide the feature files. An example of how to run the code can be found [feature based matching example](apps/feature_based_matching). \n\nFor details on used feature descriptors please refer to [feature description](src/features/readme.md).\n\n**Note**: In this mode, individual features will be loaded and matched on demand. In order to be able to deal with dramatic visual changes, we typically operate with high-dimensional features and the matching procedure can take quite a long time--depending on the size and the complexity of the sequences.\n\n#### Cost matrix based matching\n\nFor this mode, we require the **cost matrix** between two sequences to be given/precomputed. To compute the matching matrix, please see the following [estimating of a cost matrix](apps/create_cost_matrix/).\n\nAn example on how to run the matching procedure in this mode can be found [cost matrix matching example](examples/).\n\n**Note**: This method may be used if you have rather small sequences (up to 1000 images). For bigger sequences, you may run into memory issues since the programs has to store quite a big matrix.\n\n\n## How to run this code on own dataset?\n\n### 1. Extract features\nIn our code, we provide  the way to use features from OverFeat and VGG-16.\n\nTo use overfeat: Go to [OverFeat Github](https://github.com/sermanet/OverFeat), follow the installation instructions and extract features using the binary as in the example:\n`bin/linux_64/overfeat -f -l samples/pliers.jpg`. Store the features from individual images in the separate files.\n\nTo use VGG-16 : Go to [Keras VGG](https://keras.io/applications/) and extract features with VGG16. Store the features from individual images in the separate files.\n\n### 2. Hash reference features \nHash the features of reference sequence. Use [hash app](apps/hash_features) for obtaining the '.txt' file with a hash table.\n\n### 3. (Optional) Estimate similar places within reference sequence\nTo improve the localization performance, you may include the notion about the similar places in the reference trajectory. Use [estimate similar places app](apps/estimate_similar_places).\n\n### 4. Adapt the config file\nChange the `config.yaml` file with your new input files.\n\nNow, **you ready to run** the code!\nTry [feature based matching](apps/feature_based_matching)! \n\n:grimacing: Didn't work? Leave an issue.\n\n## Adapting the code for custom features\n\nThis framework can be adapted to matching features of the different type --- your **own features**. To use the graph matching strategy with your **own features** see the following [description](src/features/readme.md).\n\n## Parameters\nThe code relies on couple of parameters. Take a look at [parameters desciption](src/tools/config_parser/parameters_readme.md) to get the best code experience.\n\n## Related publication\n\nPlease cite the related publication, if you use the code:\n\n```\n@inproceedings{vysotska2017irosws,\n\ttitle     = {Relocalization under Substantial Appearance Changes using Hashing},\n\tauthor    = {O. Vysotska and C. Stachniss},\n\tbooktitle = {9th Workshop on Planning, Perception and Navigation for Intelligent Vehicles at the IEEE } # IROS,\n\tyear      = {2017},\n}\n```\n\n## Troubleshooting\n\nIn case the code is not working for you or you experience some code related problems, please consider opening an issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprbonn%2Fvpr_relocalization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprbonn%2Fvpr_relocalization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprbonn%2Fvpr_relocalization/lists"}