Updated example and README

README.md

@@ -1,10 +1,37 @@
 # aero-vloc
-aero-vloc is a tool for UAVs localization using different VPR systems and feature matchers.
-VPR systems AnyLoc, CosPlace, EigenPlaces, MixVPR, NetVLAD are now supported as well as LightGlue and SuperGlue keypoint matchers.
+[![Lint&Tests](https://github.com/prime-slam/aero-vloc/actions/workflows/ci.yml/badge.svg)](https://github.com/prime-slam/aero-vloc/actions/workflows/ci.yml)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-## Weights
-Weights for MixVPR, NetVLAD and SuperGlue as well as cluster centers for AnyLoc can be downloaded [here](https://drive.google.com/file/d/1JJWjbaY59XNICiXfQYdwoTYC6pIbzc_4/view?usp=sharing).
-All other necessary files for CosPlace, EigenPlaces and SuperPoint will be downloaded automatically via TorchHub.
+This is the official repository for the paper "Visual place recognition for aerial imagery: A survey".
 
-## Usage
-Please check `example.ipynb` for an example of downloading the satellite map, localizing and using the Recall metric.
+<img src="teaser.png">
+
+## Summary
+This paper introduces a methodology tailored for evaluating VPR techniques specifically
+in the domain of aerial imagery, providing a comprehensive assessment of various methods and their performance. However, we
+not only compare various VPR methods, but also demonstrate the importance of selecting appropriate zoom and overlap levels
+when constructing map tiles to achieve maximum efficiency of VPR algorithms in the case of aerial imagery.
+
+Our benchmark tool supports AnyLoc, CosPlace, EigenPlaces, MixVPR, NetVLAD, SALAD and SelaVPR VPR systems
+as well as LightGlue, SelaVPR and SuperGlue re-ranking techniques.
+
+## Getting started
+The tool has been tested on Python 3.10 with versions of the libraries from `requirements.txt`. 
+We recommend using the same parameters for creating a virtual environment.
+
+Please check `example.ipynb` for an example of downloading the satellite map, localizing of aerial imagery and using the Recall metric.
+Weights for MixVPR, NetVLAD, SuperGlue and SelaVPR as well as cluster centers for AnyLoc can be downloaded [here](https://drive.google.com/file/d/1D10Ulavy9VNXZb-0GTCngbheLyfIkrf-/view?usp=sharing).
+To use SelaVPR you will also have to download the pre-trained DINOv2 model [here](https://dl.fbaipublicfiles.com/dinov2/dinov2_vitl14/dinov2_vitl14_pretrain.pth).
+All other necessary files for CosPlace, EigenPlaces, LightGlue and SALAD will be downloaded automatically via TorchHub.
+
+## Datasets
+We used the [VPAir](https://github.com/AerVisLoc/vpair) datasets (from the [Anyloc repo](https://github.com/AnyLoc/AnyLoc?tab=readme-ov-file#included-datasets)) 
+as well as [ALTO](https://github.com/MetaSLAM/ALTO) and [MARS-LVIG](https://mars.hku.hk/dataset.html) for our experiments.
+
+However, you can use any dataset as a query sequence, please check `aero-vloc/primitives/uav_seq.py` for the test data format.
+
+## Citation
+If this repository aids your research, please consider starring it ⭐️ and citing the paper:
+```
+SOON!
+```

example.ipynb

@@ -26,7 +26,7 @@
    "source": [
     "map_downloader = avl.MapDownloader(north_west_lat=46.066412, north_west_lon=38.121383, \n",
     "                                   south_east_lat=45.999099, south_east_lon=38.250987,\n",
-    "                                   zoom=17, overlap_level=0.25, api_key=\"YOUR API KEY HERE\", \n",
+    "                                   zoom=17, api_key=\"YOUR API KEY HERE\", \n",
     "                                   folder_to_save=Path('test_map'))\n",
     "map_downloader.download_map()"
    ]
@@ -35,7 +35,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Specify paths to satellite map and UAV queries"
+    "Specify paths to satellite map and aerial queries.\n",
+    "You can also specify arbitrary zoom level and overlap level between frames."
    ]
   },
   {
@@ -54,7 +55,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Create a VPR system as well as a key point matcher. EigenPlaces and SuperGlue are used in the example"
+    "Create a VPR system as well as a re-ranking method. EigenPlaces and SuperGlue are used in the example"
    ]
   },
   {
@@ -76,7 +77,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The Recall metric can now be evaluated"
+    "Now you can run provided metrics"
    ]
   },
   {
@@ -85,7 +86,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "recall_value, _ = avl.reference_recall(drone_images, localization_pipeline, k_closest=50, threshold=100)\n",
+    "recall_value = avl.reference_recall(drone_images, localization_pipeline, k_closest=50, threshold=100)\n",
     "print(recall_value)"
    ]
   }