NETRYX

Open-Source Street-Level Geolocation Engine

Upload any street photo. Get precise GPS coordinates.
Sub-50m accuracy. No landmarks needed. Runs entirely on your hardware.

Demos · How It Works · Getting Started · Usage · FAQ

---

THIS VERSION IS OLD, USE THIS INSTEAD

NEW REPO

What is Netryx?

Netryx is a local-first geolocation tool that identifies the exact GPS coordinates of any street-level photograph. Unlike reverse image search (which matches against uploaded web images), Netryx matches against systematically crawled street-view panoramas — meaning it works on any random street corner with zero internet presence.

The core pipeline combines three state-of-the-art computer vision models:

• CosPlace for global visual place recognition (retrieval)
• ALIKED/DISK for local feature extraction (keypoints)
• LightGlue for deep feature matching (verification)

Google Lens searches the internet. Netryx searches the physical world.

---

Demos

Use Case	Link
Missile strike geolocation — Qatar (Feb 2026)	Watch on YouTube
Conflict monitoring — Paris protests	Watch on YouTube
Blind geolocation from a random photo — Paris	Watch on YouTube
Technical deep-dive: how the pipeline works	Watch on YouTube

---

How It Works

Netryx uses a three-stage pipeline that progressively narrows from millions of candidates to a single precise match. Netryx is simply a tool, it is source agnostic and can process images from any provider such as mapilliary or kartaview or any other provider

Stage 1 — Global Retrieval (CosPlace)

Every street-view panorama in the index has been pre-processed into a 512-dimensional "fingerprint" using CosPlace, a visual place recognition model trained on millions of geo-tagged images.

When you upload a query photo:

1. The system extracts a CosPlace descriptor from your image
2. It also extracts a descriptor from a horizontally-flipped version (catches reversed perspectives)
3. Both descriptors are compared against every entry in the index using cosine similarity
4. A radius filter (haversine distance) narrows candidates to your specified search area
5. The top 500–1000 most visually similar panorama views are returned as candidates

This stage runs in under 1 second regardless of index size — it's a single matrix multiplication.

Stage 2 — Local Geometric Verification (ALIKED/DISK + LightGlue)

CosPlace finds places that look similar. Stage 2 proves they're the same place using geometric verification.

For each candidate:

1. The original panorama is downloaded from Google Street View (8 tiles, stitched)
2. A rectilinear crop is extracted at the indexed heading angle
3. Multi-FOV crops are generated at three fields of view (70°, 90°, 110°) to handle zoom mismatches between the query photo and the indexed view
4. ALIKED (on CUDA) or DISK (on MPS/CPU) extracts local keypoints and descriptors
5. LightGlue performs deep feature matching between query and candidate keypoints
6. RANSAC filters matches to keep only geometrically consistent correspondences (rejects false matches)
7. The candidate with the most verified inliers is the best match

This stage processes 300–500 candidates in 2–5 minutes depending on your hardware.

Stage 3 — Refinement

The initial match is good but not always optimal. Refinement improves it:

• Heading refinement: For the top 15 candidates, the system tests ±45° heading offsets at 15° steps across 3 FOVs. This catches cases where the indexed heading doesn't exactly match the query's viewing direction.
• Spatial consensus: Matches are clustered into 50m cells. If multiple candidates cluster in one area, that cluster is preferred over a single high-inlier outlier — reducing false positives.
• Confidence scoring: The system evaluates geographic clustering of top matches and uniqueness ratio (how much better the best match is vs. the runner-up at a different location).

Ultra Mode (Optional)

For difficult images (night, blur, low texture), Ultra Mode adds:

• LoFTR: A detector-free dense matcher that finds correspondences without relying on keypoint detection. Handles blur and low-contrast scenes where ALIKED/DISK struggle.
• Descriptor hopping: If the initial match is weak (<50 inliers), the system extracts a CosPlace descriptor from the matched panorama (which is clean/high-quality) and re-searches the index. This often finds the exact right panorama that the degraded query missed.
• Neighborhood expansion: Searches all panoramas within 100m of the best match. The correct location is often one street node away from the CosPlace top match.

---

Architecture

Query Image
    │
    ├── CosPlace descriptor extraction (512-dim fingerprint)
    ├── Flipped descriptor extraction
    │
    ▼
Index Search (cosine similarity, radius-filtered)
    │
    ├── Top 500 candidates ranked by visual similarity
    │
    ▼
Download Panoramas → Crop at 3 FOVs → Extract ALIKED/DISK keypoints
    │
    ├── LightGlue matching against query keypoints
    ├── RANSAC geometric verification
    │
    ▼
Heading Refinement (±45°, 3 FOVs, top 15 candidates)
    │
    ├── Spatial consensus clustering
    ├── Confidence scoring
    │
    ▼
📍 GPS Coordinates + Confidence Score

---

Getting Started

Requirements

Component	Minimum	Recommended
OS	macOS / Linux / Windows	macOS (M1+) or Linux with NVIDIA GPU
GPU VRAM	4GB	8GB+
RAM	8GB	16GB+
Storage	10GB	50GB+ (depends on indexed area size)
Internet	Required for indexing and searching	Broadband recommended
Python	3.9+	3.10+

GPU support:

• Mac: MPS (Metal Performance Shaders) — M1/M2/M3/M4
• NVIDIA: CUDA — any GPU with 4GB+ VRAM
• CPU: Works but significantly slower

Installation

# Clone the repository
git clone https://github.com/sparkyniner/Netryx-OpenSource-Next-Gen-Street-Level-Geolocation.git

cd .\Netryx-OpenSource-Next-Gen-Street-Level-Geolocation\

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install LightGlue explicitly (required for matching)
pip install git+https://github.com/cvg/LightGlue.git

# Optional: Install kornia for Ultra Mode (LoFTR)
pip install kornia

Note: lightglue is imported by the app as a Python module, but it is installed from the GitHub repository above.

Gemini API Key (Optional — for AI Coarse mode) [Not recommended for use, manual does the job]

If you want to use the AI-assisted blind geolocation feature:

1. Get a free API key from Google AI Studio
2. Set it as an environment variable:

export GEMINI_API_KEY="your_key_here"

---

Usage

Launch the GUI

python test_super.py

macOS users: If the GUI appears blank, upgrade tkinter: brew install [email protected] (or your Python version). The system Python's bundled tkinter has known rendering issues on recent macOS versions.

Step 1: Create an Index