{"id":13738243,"url":"https://github.com/naver/fire","last_synced_at":"2025-04-14T23:25:13.962Z","repository":{"id":43037620,"uuid":"451693736","full_name":"naver/fire","owner":"naver","description":null,"archived":false,"fork":false,"pushed_at":"2022-07-06T08:12:31.000Z","size":21,"stargazers_count":136,"open_issues_count":5,"forks_count":8,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-28T11:21:22.119Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/naver.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}},"created_at":"2022-01-25T01:27:16.000Z","updated_at":"2025-02-11T12:03:31.000Z","dependencies_parsed_at":"2022-09-09T17:00:31.760Z","dependency_job_id":null,"html_url":"https://github.com/naver/fire","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/naver%2Ffire","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naver%2Ffire/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naver%2Ffire/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naver%2Ffire/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/naver","download_url":"https://codeload.github.com/naver/fire/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248976580,"owners_count":21192427,"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":[],"created_at":"2024-08-03T03:02:15.571Z","updated_at":"2025-04-14T23:25:13.945Z","avatar_url":"https://github.com/naver.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Learning Super-Features for Image Retrieval\r\n\r\n\r\nThis repository contains the code for running our FIRe model presented in our [ICLR'22 paper](https://openreview.net/pdf?id=wogsFPHwftY):\r\n\r\n```bibtex\r\n@inproceedings{superfeatures,\r\n  title={{Learning Super-Features for Image Retrieval}},\r\n  author={{Weinzaepfel, Philippe and Lucas, Thomas and Larlus, Diane and Kalantidis, Yannis}},\r\n  booktitle={{ICLR}},\r\n  year={2022}\r\n}\r\n```\r\n\r\n## License\r\n\r\nThe code is distributed under the CC BY-NC-SA 4.0 License. See [LICENSE](LICENSE) for more information.\r\nIt is based on code from [HOW](https://github.com/gtolias/how), [cirtorch](https://github.com/filipradenovic/cnnimageretrieval-pytorch/) and [ASMK](https://github.com/jenicek/asmk) that are released under their own license, the MIT license.\r\n\r\n## Preparation\r\n\r\nAfter cloning this repository, you must also have HOW, cirtorch and ASMK and have them in your PYTHONPATH.\r\n\r\n1. install [HOW](https://github.com/gtolias/how)\r\n```\r\ngit clone https://github.com/gtolias/how\r\nexport PYTHONPATH=${PYTHONPATH}:$(realpath how)\r\n```\r\n\r\n2. install [cirtorch](https://github.com/filipradenovic/cnnimageretrieval-pytorch/)\r\n```\r\nwget \"https://github.com/filipradenovic/cnnimageretrieval-pytorch/archive/v1.2.zip\"\r\nunzip v1.2.zip\r\nrm v1.2.zip\r\nexport PYTHONPATH=${PYTHONPATH}:$(realpath cnnimageretrieval-pytorch-1.2)\r\n```\r\n\r\n3. install [ASMK](https://github.com/jenicek/asmk)\r\n```\r\ngit clone https://github.com/jenicek/asmk.git\r\npip3 install pyaml numpy faiss-gpu\r\ncd asmk\r\npython3 setup.py build_ext --inplace\r\nrm -r build\r\ncd ..\r\nexport PYTHONPATH=${PYTHONPATH}:$(realpath asmk)\r\n```\r\n\r\n4. install dependencies by running:\r\n```\r\npip3 install -r how/requirements.txt\r\n```\r\n\r\n5. data/experiments folders\r\n\r\nAll data will be stored under a folder ``fire_data`` that will be created when running the code; similarly, results and models from all experiments will be stored under folder ``fire_experiments``\r\n\r\n## Evaluating our ICLR'22 FIRe model\r\n\r\nTo evaluate on ROxford/RParis our model trained on SfM-120k, simply run\r\n```\r\npython evaluate.py eval_fire.yml\r\n```\r\n\r\nWith the released model and the parameters found in ``eval_fire.yml``, we obtain 90.3 on the validation set, 82.6 and 62.2 on ROxford medium and hard respectively, 85.2 and 70.0 on RParis medium and hard respectively.\r\n\r\n\r\n## Training a FIRe model \r\n\r\nSimply run\r\n```\r\npython train.py train_fire.yml -e train_fire\r\n```\r\nAll training outputs will be saved to ``fire_experiments/train_fire``.\r\n\r\nTo evaluate the trained model that was saved in ``fire_experiments/train_fire``, simply run:\r\n```\r\npython evaluate.py eval_fire.yml -e train_fire -ml train_fire\r\n```\r\n\r\n## Pretrained models\r\n\r\nFor reproducibility, we provide the following model weights for the architecture we use in the paper (ResNet50 without the last block + LIT):\r\n* Model pre-trained on ImageNet-1K (with Cross-Entropy, the pre-trained model we use for training FIRe) [(link)](http://download.europe.naverlabs.com/ComputerVision/FIRe/pretraining/fire_imagenet.pth)\r\n* Model trained on SfM-120k trained with FIRe [(link)](http://download.europe.naverlabs.com/ComputerVision/FIRe/official/fire.pth)\r\n\r\nThey will be automatically downloaded when running the training / testing script.\r\n\r\n## Dockerfile\r\n\r\nFor convenience, we provide a dockerfile. You can build it with\r\n```bash\r\ndocker build --tag naver/fire .\r\n```\r\nIt does not contain the ``fire_data`` nor ``fire_experiments`` so these need to be stored outside.  \r\nIn ``evaluate.py``, the options ``--data-folder`` and ``--exp-folder`` can be used to overwrite these paths.\r\n\r\nexample:\r\n```bash\r\ndocker run --gpus all --rm -it --ipc=host --mount type=bind,source=/local/fire,target=/local/fire --entrypoint bash naver/fire\r\npython evaluate.py eval_fire.yml --data-folder /local/fire/fire_data --exp-folder /local/fire/fire_experiments\r\n```\r\n\r\n## kapture integration\r\n\r\nWith ``kapture_compute_pairs.py`` you can compute pairs from datasets that are provided in kapture format ([link to kapture github](https://github.com/naver/kapture)) using FIRe or HOW. These pairs can be used to, e.g., run the kapture visual localization pipeline ([link to kapture-localization github](https://github.com/naver/kapture-localization)).\r\n``--codebook-cache-path`` can be used to cache the codebook. It only needs to be computed once per model.  \r\n``--ivf-cache-path`` can be used to cache the ivf database. It needs to be computed once per model per dataset (mapping images).  \r\n``--model-load``, ``--data-folder`` can be used to overwrite ``demo_eval.net_path`` and ``demo_eval.fire_data``. Note that ``demo_eval.exp_folder`` and ``evaluation.local_descriptor.datasets`` are ignored.\r\n\r\nexample: extracting top50 FIRe pairs, and top50 HOW pairs for GangnamStation_B2\r\n```\r\ndocker run --gpus all --rm -it --ipc=host --mount type=bind,source=/local/fire,target=/local/fire --entrypoint bash naver/fire\r\n\r\n# prepare dataset\r\nmkdir /local/fire/kapture_datasets\r\ncd /local/fire/kapture_datasets\r\nkapture_download_dataset.py update\r\nkapture_download_dataset.py install  \"GangnamStation_B2*\"\r\n# read license terms and type y [enter] to agree\r\ncd GangnamStation/B2/release\r\nkapture_merge.py -v info \\\r\n                 -i test validation \\\r\n                 -o query_all \\\r\n                 --image_transfer link_relative\r\n\r\n# extract FIRe pairs\r\ncd /opt/src/fire\r\n# map -\u003e map pairs\r\npython3 kapture_compute_pairs.py -v debug \\\r\n    --parameters eval_fire.yml \\\r\n    --model fire \\\r\n    --data-folder /local/fire/fire_data \\\r\n    --codebook-cache-path /local/fire/fire_codebook \\\r\n    --ivf-cache-path /local/fire/kapture_datasets/GangnamStation/B2/release/fire_ivf \\\r\n    --map /local/fire/kapture_datasets/GangnamStation/B2/release/mapping/ \\\r\n    -o /local/fire/kapture_datasets/GangnamStation/B2/release/pairsfile/mapping/fire_top50.txt \\\r\n    --topk 50\r\n# query -\u003e map pairs\r\npython3 kapture_compute_pairs.py -v debug \\\r\n    --parameters eval_fire.yml \\\r\n    --model fire \\\r\n    --data-folder /local/fire/fire_data \\\r\n    --codebook-cache-path /local/fire/fire_codebook \\\r\n    --ivf-cache-path /local/fire/kapture_datasets/GangnamStation/B2/release/fire_ivf \\\r\n    --map /local/fire/kapture_datasets/GangnamStation/B2/release/mapping/ \\\r\n    --query /local/fire/kapture_datasets/GangnamStation/B2/release/query_all \\\r\n    -o /local/fire/kapture_datasets/GangnamStation/B2/release/pairsfile/query/fire_top50.txt \\\r\n    --topk 50\r\n\r\n# extract HOW pairs\r\ncd /opt/src/fire\r\n# you can use the same data-folder as for fire\r\n# map -\u003e map pairs\r\npython3 kapture_compute_pairs.py -v debug \\\r\n    --parameters ../how/examples/params/eccv20/eval_how_r50-_1000.yml \\\r\n    --model how \\\r\n    --data-folder /local/fire/fire_data \\\r\n    --codebook-cache-path /local/fire/how_codebook \\\r\n    --ivf-cache-path /local/fire/kapture_datasets/GangnamStation/B2/release/how_ivf \\\r\n    --map /local/fire/kapture_datasets/GangnamStation/B2/release/mapping/ \\\r\n    -o /local/fire/kapture_datasets/GangnamStation/B2/release/pairsfile/mapping/how_top50.txt \\\r\n    --topk 50\r\n# query -\u003e map pairs\r\npython3 kapture_compute_pairs.py -v debug \\\r\n    --parameters ../how/examples/params/eccv20/eval_how_r50-_1000.yml --model fire \\\r\n    --data-folder /local/fire/fire_data \\\r\n    --codebook-cache-path /local/fire/how_codebook \\\r\n    --ivf-cache-path /local/fire/kapture_datasets/GangnamStation/B2/release/how_ivf \\\r\n    --map /local/fire/kapture_datasets/GangnamStation/B2/release/mapping/ \\\r\n    --query /local/fire/kapture_datasets/GangnamStation/B2/release/query_all \\\r\n    -o /local/fire/kapture_datasets/GangnamStation/B2/release/pairsfile/query/how_top50.txt \\\r\n    --topk 50\r\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaver%2Ffire","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnaver%2Ffire","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaver%2Ffire/lists"}