GeoGuessr Screen Hint MVP

A local overlay assistant: press F1, capture the screen, run it through a local vision model, and show the top-5 likely countries in the upper-right corner.

Use this only for training, solo play, or your own experiments. In online competitive modes, this kind of assistant may violate GeoGuessr rules.

Stack

• Python 3.10-3.14
• PySide6 for a transparent always-on-top overlay
• pynput for the global F1 hotkey
• mss for fast screenshots
• PyTorch + Transformers
• CLIP zero-shot as the first ready-to-use local model

Installation

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

The first run downloads openai/clip-vit-large-patch14 into the local Hugging Face cache. After that, the model runs locally.

Run

.\.venv\Scripts\Activate.ps1
python -m geohint

While playing, press F1. The overlay will show the top-5 countries with percentages.

Environment Variables

$env:GEOHINT_MODEL="openai/clip-vit-large-patch14"
$env:GEOHINT_DEVICE="auto"
$env:GEOHINT_HOTKEY="f1"
python -m geohint

GEOHINT_DEVICE: auto, cuda, or cpu.

Future Improvements

• replace CLIP zero-shot with GeoCLIP or a custom model trained on a GeoGuessr-style dataset;
• add OCR for road signs and storefronts;
• crop out the GeoGuessr UI so the model sees only the panorama;
• add a multi-frame mode and average probabilities across several screenshots;
• add country priors based on language, road markings, license plates, and driving side.