GeoFinder

GeoFinder is an image geolocation prototype using a Vision Transformer + FAISS similarity search.

Organized Project Structure

GeoFinder/
├── src/geofinder/            # Core Python package
│   ├── custom_vit.py
│   ├── extractor.py
│   ├── indexer.py
│   ├── search.py
│   ├── heatmap.py
│   └── train.py
├── scripts/                  # CLI entrypoints
│   ├── extractor.py
│   ├── indexer.py
│   ├── search.py
│   ├── heatmap.py
│   └── train.py
├── data/
│   ├── index/                # FAISS index + metadata
│   │   ├── vectors.faiss
│   │   └── metadata.json
│   └── samples/              # Sample/query images
├── models/weights/           # Trained model weights
├── outputs/                  # Generated outputs (maps, etc.)
├── dataset/                  # Input dataset for indexing/training
├── Dockerfile
├── docker-compose.yml
└── requirements.txt

Setup

1. Create and activate a virtual environment (recommended).
2. Install dependencies:

pip install -r requirements.txt

Or using Make:

make install

Quick Start (Makefile)

make index
make search
make heatmap

Useful overrides:

make search QUERY_IMAGE=data/samples/query_image.jpg TOP_K=10
make train DATASET=dataset EPOCHS=10 BATCH_SIZE=8

Commands

1) Extract embedding from one image

python3 scripts/extractor.py data/samples/sample_image.jpg

Optional (pretrained backbone):

python3 scripts/extractor.py data/samples/sample_image.jpg --pretrained

2) Build FAISS index from dataset

python3 scripts/indexer.py --dataset dataset

Optional output locations:

python3 scripts/indexer.py --dataset dataset --out-index data/index/vectors.faiss --out-meta data/index/metadata.json

3) Run similarity search

python3 scripts/search.py data/samples/query_image.jpg --top_k 5

4) Generate geolocation heatmap

python3 scripts/heatmap.py data/samples/query_image.jpg --top_k 50 --output-map outputs/output_map.html

5) Train custom ViT

python3 scripts/train.py --dataset dataset --epochs 5 --batch_size 4 --save_path models/weights/custom_vit_weights.pth

Docker

Build and run:

docker compose up --build

The container default command runs:

python3 scripts/extractor.py

Notes

• The scripts now use organized default paths under data/, models/weights/, and outputs/.
• If an image has no GPS EXIF metadata, indexing falls back to random coordinates.
• data/index/ and outputs/ are created automatically when needed.
• Use make clean to remove generated FAISS index, map output, and trained weight artifacts.