# Netryx Astra V2: a three stage pipeline that puts a photograph on a map

> Netryx Astra V2 takes one image and returns GPS coordinates by retrieving street-view candidates with MegaLoc, confirming each with MASt3R dense matching, and resolving the ambiguity with spatial consensus over a 50 metre grid. It replaced a nine stage V1 pipeline with three, and it depends on a Hugging Face hosted index that anyone can contribute to.

**sparkyniner/Netryx-Astra-V2-Geolocation-Tool** — The world's most sophisticated street level image geolocation software

- Repository: https://github.com/sparkyniner/Netryx-Astra-V2-Geolocation-Tool
- Stars: 1,091 · Forks: 123
- Language: Python
- License: not declared
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/sparkyniner-netryx-astra-v2-geolocation-tool

## The problem it claims to solve, and the claim itself

Netryx Astra V2 is presented as state-of-the-art AI geolocation from a single image, and the README opens with the scenario that motivates it. You have a photograph. Maybe it is a screenshot from a video, maybe a cropped and blurry phone photo someone posted online, maybe it shows just a storefront, a stretch of road, or the corner of a building. You want to know exactly where it was taken.

The system answers that question by matching the image against a database of street-view panoramas, and the README says that within minutes it tells you the street, the city, and the coordinates, down to a few meters.

Two things are worth flagging about the framing before the engineering. The project description calls itself the world's most sophisticated street level image geolocation software, which is a marketing claim rather than a measured one, and the README is more measured, saying it finds the precise GPS coordinates and gives coordinates down to a few meters without claiming a benchmark for the whole pipeline.

The second thing is that this is a research-shaped project built on published models. The README carries badges for MegaLoc from CVPR 2025 and MASt3R from ECCV 2024, and the primary language is Python with a badge for Python 3.10 and above. The repository is not archived, the last push was on 2026-08-03, and there are no GitHub releases, so the project is distributed as a repository and a set of scripts rather than as a packaged tool. The licence field on the project is recorded as unknown even though the README badge reads MIT, which is a discrepancy worth resolving before you build on it.

The top level listing shows how the code is organised, and it is a flat set of scripts rather than a package. There is mast3r_utils.py, megaloc_model.py, megaloc_utils.py and mixvpr_utils.py, plus a models_mixvpr/ directory, netryx_hub.py for the index, test_super.py, setup.sh, setup.bat and run.bat. The presence of both MegaLoc and MixVPR files, and of a models_mixvpr directory, suggests the retrieval stage has more than one implementation behind it rather than a single hardcoded one.

## The three stage pipeline and what each stage asks

The README is emphatic that the pipeline is genuinely three stages and not an oversimplification, and it gives each stage a question.

```
Query Image
     │
     ▼
┌─────────────┐
│   MegaLoc   │  "Where in the city could this be?"
│  Retrieval  │  
└─────┬───────┘
      │  Top 500 candidates
      ▼
┌─────────────┐
│   MASt3R    │  "Is this actually the same place?"
│   Matching  │  
└─────┬───────┘
      │  Scored candidates
      ▼
┌─────────────┐
│   Spatial   │  "Which cluster of matches is most trustworthy?"
│  Consensus  │  
└─────┬───────┘
      │
      ▼
  📍 GPS Coordinates
```

Stage one is retrieval. Your query image gets converted into a compact descriptor, an 8448-dimensional vector capturing the visual essence of the scene, which is then PCA-reduced to 1024 dimensions and compared against every indexed location by dot-product similarity. The output is the top 500 candidate locations ranked by visual similarity.

There is a detail in that stage that is easy to miss and is the difference between working and not working. A descriptor is also extracted for a slightly zoomed-in center crop and for a horizontally flipped version of the query, and the results are merged. That handles the case where the query is at a different zoom level or facing the opposite direction from the indexed view, which is the normal case for a random internet photograph against a systematically captured panorama.

MegaLoc comes from Gabriele Berton's lab, the same group that made CosPlace and EigenPlaces, and the README says it is the latest in their line of work, trained on SF-XL, GSV-Cities, MSLS and landmark retrieval data simultaneously.

Stage two is confirmation, and it is where the heavy downloads happen. For each of those 500 candidates, the system downloads the corresponding street-view panorama, crops it at the indexed heading angle, and runs MASt3R to find dense pixel correspondences between the query and the crop.

Stage three is disambiguation, and it exists because of a specific failure. Picking the candidate with the highest match score is not enough, because false positives exist. Two identical chain restaurants 5km apart will both produce high MASt3R scores, and a row of Soviet-era apartment blocks all look the same. Spatial consensus divides the search area into roughly 50-meter grid cells and clusters all the good matches geographically, with each cell scored on the combined evidence from the matches in it and its neighbours. The README's illustration of the principle is that a single outlier with 200 inliers at the wrong location gets outscored by a cluster of 5 matches with 80 to 150 inliers each.

## Why dense matching beats keypoint matching on cropped images

The second stage is where the project claims its largest gain, and the argument is about what breaks when the input is bad.

Traditional matchers such as SuperPoint plus LightGlue extract maybe 500 to 2000 sparse keypoints and try to match them. If the query image only overlaps 20 percent with the database image, there might only be 50 co-visible keypoints, which is not enough for a reliable match. That is the specific failure mode for the use case the project targets, since a cropped or blurry phone photo overlaps only a fraction of the panorama it came from.

MASt3R works differently, and the README's description of the difference is precise. It treats matching as a 3D reconstruction problem, predicting dense point maps and local feature descriptors for every pixel. Even a small overlapping region produces hundreds of reliable correspondences, because it understands the 3D structure of the scene and not just 2D pixel patterns.

The performance claim is also specific. On the Map-free localization benchmark, with a single reference image and viewpoint changes up to 180 degrees, MASt3R beats previous methods by 30 percent, and the README is clear that this is not an incremental improvement.

That number is a benchmark result for the underlying model, not for this pipeline, and the distinction matters. The pipeline adds the retrieval stage and the consensus stage on top, and the consensus stage in particular exists to fix a class of error that the 30 percent figure does not measure. A method can be excellent at confirming that two images are the same place and still fail to pick the right one out of five lookalikes, and that is a different problem.

The comparison table in the README makes the V1 to V2 change concrete. Finding candidates went from CosPlace, a ResNet-50 producing 512-dimensional vectors, to MegaLoc, a DINOv2 ViT-B/14 producing 8448 dimensions reduced by PCA to 1024. Confirming matches went from DISK plus LightGlue plus RANSAC to MASt3R dense 3D matching. Handling edge cases went from LoFTR fallback, descriptor hopping, neighborhood expansion and Ultra Mode to spatial consensus, and the table's own summary of that row is that that is it.

The totals row is the headline. Total pipeline stages went from 9 or more to 3, and the README's argument for why that matters is not aesthetic: fewer stages means fewer places for things to go wrong, faster searches, and code that is actually maintainable. The partial image matching row says V1 was weak because sparse keypoints fail on small overlaps, and V2 is strong because MASt3R finds dense correspondences in tiny regions.

## The Community Hub, and the index as a shared artefact

The last row of the V1 to V2 comparison table is about sharing indexes, and it is the one that changes what the project is. Sharing indexes was not possible in V1, and in V2 it is possible through the Community Hub via Hugging Face plus offline .netryx bundles.

That is a significant design decision. The index of street-view panoramas is the expensive part of this system, and the alternative to every user building their own is a shared one. A Hugging Face dataset is the natural home for it, since that is where large binary artefacts with versioning already live, and the offline .netryx bundle is the escape hatch for anyone who needs the index on a machine with no network access or who wants to pin a specific version.

The file layout supports this reading. netryx_hub.py sits at the top level next to the model utilities, which is what you would expect if the hub is a distinct concern from the matching code, and the setup scripts in the repository root are what a user runs to fetch a model and configure a path to an index.

The index is also what determines the coverage of any answer. The pipeline retrieves candidates from the index, so a region that is not indexed cannot be geolocated no matter how good the models are. That is a property the README does not belabour, and it is the first thing to check for a given task, because a street-view index is a geographic artefact and the tool's usefulness for a particular query depends on whether that place is in it.

The requirements file shows the dependency shape, and it is a heavy one. numpy, Pillow, opencv-python, scikit-learn, aiohttp, tkintermapview, huggingface-hub, requests, safetensors, einops, timm and matplotlib. The presence of safetensors and huggingface-hub is the model distribution layer, einops and timm are the transformer plumbing that MegaLoc needs, and aiohttp and requests are for the panorama downloads in stage two, which is the stage that does the network work. tkintermapview is there for the map display, which tells you the tool renders an interactive map rather than only printing coordinates.

And the two lines at the end of that file are the ones to read carefully. MASt3R and Dust3r should be cloned separately alongside this repo, with the comment giving the git clone command for naver/mast3r. So the installation is not a pip install, it is a set of side-by-side clones, which matters for reproducibility and for anyone packaging the project.

## Conclusion

Netryx Astra V2 fits a researcher or a verification team that has an image with no location metadata and needs candidate coordinates rather than a guess, and who can run a GPU pipeline and host or fetch a street-view index. It is the wrong tool if you need a single offline lookup, since the index is a Hugging Face dataset and the matching stage downloads panoramas for every candidate, and it is the wrong tool if you need a definitive answer, since the spatial consensus stage explicitly exists because identical-looking places produce identical high scores. Before adopting, read the README section on the Community Hub to understand where the index comes from, and note that the licence field on the project is recorded as unknown, that there are no GitHub releases, and that the MASt3R and Dust3r repositories have to be cloned alongside the project rather than installed from a package index.

## FAQ

### How does Netryx Astra V2 geolocate a single image?

In three stages. MegaLoc retrieval turns the query into an 8448-dimensional descriptor reduced by PCA to 1024 and compares it against the index by dot-product similarity, giving the top 500 candidates. MASt3R then downloads and crops each candidate panorama and runs dense 3D matching. Spatial consensus clusters the good matches into roughly 50-meter cells and scores each cell, resolving lookalike locations.

### What changed between Netryx V1 and Astra V2?

The candidate retrieval moved from CosPlace, a ResNet-50 with 512-dimensional output, to MegaLoc, a DINOv2 ViT-B/14 with 8448 dimensions reduced to 1024. Match confirmation moved from DISK plus LightGlue plus RANSAC to MASt3R dense 3D matching, and the edge case handling moved from LoFTR fallback, descriptor hopping and neighborhood expansion to spatial consensus, taking the pipeline from nine or more stages to three.

### How do I install Netryx Astra V2?

The MASt3R and Dust3r repositories have to be cloned separately alongside the project rather than installed from a package index, and the requirements.txt lists the Python dependencies including numpy, opencv-python, timm, safetensors, huggingface-hub and aiohttp. The repository also ships setup.sh, setup.bat and run.bat for the setup and run steps.

### Why does Netryx Astra V2 need a spatial consensus stage?

Because false positives exist in the dense matching stage. Two identical chain restaurants 5km apart will both produce high MASt3R scores, and rows of identical apartment blocks look the same. The stage divides the search area into roughly 50-meter grid cells and clusters the good matches geographically so that a cluster of consistent matches beats a single high-scoring outlier.

## Sources

- [Issues](https://github.com/sparkyniner/Netryx-Astra-V2-Geolocation-Tool/issues)
- [README](https://github.com/sparkyniner/Netryx-Astra-V2-Geolocation-Tool/blob/main/README.md)
- [sparkyniner/Netryx-Astra-V2-Geolocation-Tool on GitHub](https://github.com/sparkyniner/Netryx-Astra-V2-Geolocation-Tool)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sparkyniner-netryx-astra-v2-geolocation-tool