medwa126/vpr-interactive-demo

📘 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

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