---
title: VPR Interactive GPS Analysis
emoji: 🌍
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
hf_repo_paths:
  - repo_id: medwa126/gardensgp
    repo_type: dataset
    local_dir: data/gardensgp
---

# 📘 VPR Interactive GPS Analysis Demo  
*A Gradio + Plotly dashboard for analysing Visual Place Recognition (VPR) experiment outputs*

---

## 🧭 Overview

This repository contains an **interactive demo** for exploring and analysing the output of Visual Place Recognition (VPR) experiments. It provides:

- GPS-aligned **trajectory visualisation**
- Per-query **correct/incorrect prediction markers**
- Full **TP / FP / FN / TN introspection** overlays
- Side-by-side **query, predicted, and ground-truth image comparisons**
- Interactive **navigation**, **hover tooltips**, and **method switching**

It is designed for VPR researchers who want a rich, visual debugging tool to inspect failure cases, spatial error patterns, and introspective reliability outputs.

**This is just a demonstration of what is possible on HuggingFace and is not being maintained**

---

## 🌐 Key Features

### ✔️ **Interactive GPS Accuracy Heatmap**
- Visualises query trajectory and database path in metres  
- Colours indicate correctness (green/red)  
- Marker shapes show introspection class (TP, FP, FN, TN)

### ✔️ **Rich hover information**
Hovering over any prediction shows:
- Query index  
- Predicted and GT indices  
- Error in metres  
- Correct/incorrect classification  
- TPR category  

### ✔️ **Image Comparison Panel**
- Displays:
  - **Query image**
  - **Ground truth match**
  - **Model’s predicted match**
- Shows correctness, distance error, and introspection metadata

### ✔️ **Navigation Controls**
- Jump to any query index  
- Click previous/next to iterate sequentially  
- All interactions update the viewer dynamically

### ✔️ **HuggingFace Dataset Integration**
Uses `huggingface_hub.snapshot_download` to automatically load datasets required for VPR experiments.

---

## 🗂 Directory Structure

```
project/
│
├── data/gardensgp/           # Downloaded dataset from HuggingFace Hub
├── experiment_output/        # Your VPR pipeline’s output JSON + images
│
├── plot_interactive_loader.py
└── interactive_app.py        # This demo script
```

---

## 🔧 How It Works

### 1. **Dataset Loading**
The HuggingFace dataset is downloaded locally using an authentication token.

### 2. **Experiment Output Parsing**
The script expects a folder containing:
- VPR predictions  
- GPS coordinates  
- Error metrics  
- Paths to image files  
- Optional introspection labels  

These are parsed into a unified format for visualisation.

### 3. **GPS Conversion**
Lat/lon coordinates are converted into **metres** using the Haversine formula, enabling consistent 2D rendering.

### 4. **Plotly Visualisation**
The GPS plot includes:
- Query path  
- Database trajectory  
- Per-prediction markers  
- Legend entries for correctness and introspection  

### 5. **Gradio Frontend**
A user-friendly panel lets you:
- Select a method  
- Explore predictions on a map  
- Inspect image matches  
- Navigate across query indices  

---

## 🎨 Legend

| Symbol | Meaning | Style |
|--------|---------|--------|
| 🟢 Green circle | Correct prediction | Below tolerance |
| 🔺 Blue triangle | False Positive | Wrong match |
| ❌ Red X | False Negative | Model missed correct match |
| ⬛ Grey square | True Negative | Correct rejection |
| ⚫ Black circle | Not assigned | N/A |

Background elements:
- 🔵 Blue dots = database reference path  
- 🔴 Red dots = query traversal path  

---

## 🚀 Running the Demo

### **1. Install dependencies**
```
pip install -r requirements.txt
```

### **2. Set your HuggingFace token**
```
export HF_TOKEN="your_token_here"
```

### **3. Launch the dashboard**
```
python interactive_app.py
```

### **4. Open the app at**
```
http://localhost:7860
```

## 🧑‍💻 Authors
Margaux Edwards
Queensland University of Technology Centre of Robotics