README.md

---
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: Generative Visual Geolocation with PLONK
---

# 🗺️ 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
```python
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
```bash
curl -X POST \
  -F "[email protected]" \
  "https://kylanoconnor-plonk-geolocation.hf.space/api/predict"
```

### JavaScript/Node.js
```javascript
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)
```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

```json
{
  "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](https://arxiv.org/abs/2412.06781)

**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:
```bash
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*