README.md

metadata

title: PLONK Geolocation
emoji: 🗺️
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
license: mit
short_description: Around the World in 80 Timesteps - Generative Visual Geolocation

🗺️ PLONK: Around the World in 80 Timesteps

A generative approach to global visual geolocation using diffusion models. Upload an image and PLONK will predict where it was taken!

🚀 Features

• High-Quality Predictions: Uses 32 samples with CFG=2.0 for robust geolocation
• Uncertainty Estimation: Provides confidence radius (±km) for each prediction
• REST API: Full programmatic access with JSON responses
• Multiple Input Methods: File upload, webcam, clipboard, or base64 encoding
• CORS Enabled: Ready for web integration

📡 API Usage

REST API Endpoints

Main Prediction:

POST https://kylanoconnor-plonk-geolocation.hf.space/api/predict

JSON Response:

POST https://kylanoconnor-plonk-geolocation.hf.space/api/predict_json

Python Example

import requests

# Upload image file
response = requests.post(
    "https://kylanoconnor-plonk-geolocation.hf.space/api/predict",
    files={"file": open("image.jpg", "rb")}
)
result = response.json()
print(f"Location: {result['data']['latitude']}, {result['data']['longitude']}")
print(f"Uncertainty: ±{result['data']['uncertainty_km']} km")

cURL Example

curl -X POST \
  -F "[email protected]" \
  "https://kylanoconnor-plonk-geolocation.hf.space/api/predict"

JavaScript/Node.js

const formData = new FormData();
formData.append('data', imageFile);

const response = await fetch(
    'https://kylanoconnor-plonk-geolocation.hf.space/api/predict',
    {
        method: 'POST',
        body: formData
    }
);

const result = await response.json();
console.log('Location:', result.data);

Gradio Client (Python)

from gradio_client import Client

client = Client("kylanoconnor/plonk-geolocation")
result = client.predict("path/to/image.jpg", api_name="/predict")
print(result)

🎯 Model Configuration

• Model: nicolas-dufour/PLONK_YFCC
• Dataset: YFCC-100M
• Samples: 32 (for uncertainty estimation)
• Guidance Scale: 2.0
• Timesteps: 32
• Uncertainty: Statistical analysis across predictions

📊 Response Format

{
  "status": "success",
  "mode": "production", 
  "predicted_location": {
    "latitude": 40.756123,
    "longitude": -73.984567
  },
  "confidence": "high",
  "samples": 32,
  "uncertainty_km": 12.3,
  "note": "Real PLONK prediction using 32 samples"
}

📚 About

Paper: Around the World in 80 Timesteps: A Generative Approach to Global Visual Geolocation

Authors: Nicolas Dufour, David Picard, Vicky Kalogeiton, Loic Landrieu

Original Code: https://github.com/nicolas-dufour/plonk

This Space provides both a user-friendly web interface and robust API access for global visual geolocation using the PLONK model. The model uses 32 samples per prediction to provide uncertainty estimation and more reliable results.

🔧 Development

To run locally:

pip install -r requirements_hf_spaces.txt
python app.py

The app will be available at http://localhost:7860 with API documentation at /docs.

---

Built with ❤️ using Gradio and Hugging Face Spaces