Netryx Astra V2

Geolocalização AI de última geração a partir de uma única imagem.

The Idea • How It Works • Getting Started • Community Hub • Installation

Netryx Astra V2 em ação

The Idea

Você tem uma fotografia. Talvez seja uma captura de tela de um vídeo. Talvez seja uma foto de celular cortada e desfocada que alguém postou online. Talvez mostre apenas uma fachada de loja, um trecho de estrada ou a esquina de um prédio. Você quer saber exatamente onde foi tirada.

Netryx Astra V2 responde a essa pergunta.

É um sistema de geolocalização de código aberto que pega uma única imagem e encontra as coordenadas GPS precisas ao compará-la com um banco de dados de panoramas de street-view. Faça upload da sua foto e, em minutos, ela informa a rua, a cidade e as coordenadas — com precisão de alguns metros.

O que torna o V2 diferente do Netryx original (e de outras ferramentas disponíveis) é o pipeline de correspondência. Nós reconstruímos tudo do zero usando dois modelos que não existiam quando começamos este projeto:

MegaLoc (CVPR 2025) — o modelo de recuperação de imagens mais preciso para reconhecimento de locais, treinado em seis conjuntos de dados cobrindo ambientes internos, externos, diurnos, noturnos e variações sazonais. Ele encontra o bairro certo.
MASt3R (ECCV 2024) — um matcher denso com consciência 3D que entende a geometria das cenas, não apenas padrões de pixels. Ele confirma a localização exata, mesmo a partir de fotos parciais ou fortemente cortadas que quebrariam os matchers tradicionais.

O resultado é um pipeline de três etapas que é mais simples e mais preciso do que o sistema de nove estágios que substituiu.

O que Mudou do V1

O Netryx original usava CosPlace para recuperação e uma pilha de DISK + LightGlue + LoFTR + RANSAC + salto de descritor + expansão de vizinhança para verificação. Funcionava, mas era frágil — muitas heurísticas empilhadas umas sobre as outras, cada uma sendo uma solução alternativa para uma limitação do estágio anterior.

O V2 jogou tudo isso fora. Aqui está o que substituiu o quê:

A simplificação não é apenas estética. Menos estágios significa menos lugares para as coisas darem errado, pesquisas mais rápidas e um código que é realmente mantível.

How It Works

O pipeline tem três estágios. Isso não é uma simplificação exagerada — é genuinamente apenas três estágios.

Query Image
     │
     ▼
┌─────────────┐
│   MegaLoc   │  "Onde na cidade isso poderia estar?"
│  Retrieval  │  
└─────┬───────┘
      │  Top 500 candidates
      ▼
┌─────────────┐
│   MASt3R    │  "Isso é realmente o mesmo lugar?"
│   Matching  │  
└─────┬───────┘
      │  Scored candidates
      ▼
┌─────────────┐
│   Spatial   │  "Qual cluster de correspondências é mais confiável?"
│  Consensus  │  
└─────┬───────┘
      │
      ▼
  📍 GPS Coordinates

Estágio 1: Recuperação MegaLoc

Sua imagem de consulta é convertida em um descritor compacto — um vetor de 8448 dimensões que captura a essência visual da cena. Ele é reduzido por PCA para 1024 dimensões e então comparado com cada localização indexada por similaridade de produto escalar.

Também extraímos um descritor para um corte central ligeiramente ampliado e para uma versão espelhada horizontalmente da consulta, depois mesclamos os resultados. Isso lida com casos em que a consulta está em um nível de zoom diferente ou voltada para a direção oposta à vista indexada.

A saída são as 500 principais localizações candidatas do índice, classificadas por similaridade visual.

MegaLoc é do laboratório de Gabriele Berton (o mesmo grupo que fez CosPlace e EigenPlaces). É o mais recente de sua linha de trabalho, treinado simultaneamente em SF-XL, GSV-Cities, MSLS e dados de recuperação de marcos. Nenhum outro modelo de recuperação o supera consistentemente em todos os benchmarks — interno, externo, urbano, rural, diurno, noturno.

Estágio 2: Correspondência Densa MASt3R

Para cada um desses 500 candidatos, baixamos o panorama street-view correspondente, recortamos no ângulo de direção indexado e executamos o MASt3R para encontrar correspondências densas de pixels entre a consulta e o recorte.

É aqui que a mágica acontece para consultas difíceis. Matchers tradicionais como SuperPoint + LightGlue extraem talvez 500-2000 keypoints esparsos e tentam correspondê-los. Se sua imagem de consulta sobrepõe apenas 20% com a imagem do banco de dados, pode haver apenas 50 keypoints co-visíveis — não o suficiente para uma correspondência confiável.

MASt3R funciona de maneira completamente diferente. Ele trata a correspondência como um problema de reconstrução 3D, prevendo mapas de pontos densos e descritores de características locais para cada pixel. Mesmo uma pequena região sobreposta produz centenas de correspondências confiáveis, porque ele entende a estrutura 3D da cena, não apenas padrões de pixels 2D.

No benchmark de localização sem mapa (imagem de referência única, mudanças de ponto de vista de até 180°), o MASt3R supera métodos anteriores em 30%. Isso não é uma melhoria incremental — é um salto geracional.

Estágio 3: Consenso Espacial

Aqui está o problema de simplesmente escolher o candidato com a maior pontuação de correspondência: existem falsos positivos. Dois restaurantes de rede idênticos a 5 km de distância produzirão altas pontuações de MASt3R. Uma fileira de blocos de apartamentos da era soviética todos parecem iguais.

O consenso espacial resolve isso. Dividimos a área de busca em células de grid de aproximadamente 50 metros e agrupamos geograficamente todas as boas correspondências. Cada célula recebe uma pontuação baseada na evidência combinada de todas as correspondências nessa célula e nas células vizinhas.

Um único outlier com 200 inliers no local errado é superado por um cluster de 5 correspondências com 80-150 inliers cada no local correto. A melhor correspondência do cluster vencedor se torna a resposta final.

É por isso que a precisão se mantém mesmo em raios de busca maiores, onde há mais locais de aparência semelhante.

Exemplos

Podemos observar nesta imagem que não há absolutamente nada para se guiar, é apenas uma pequena parte recortada. O OSINT convencional falharia completamente aqui. No entanto, o Netryx Astra o geolocalizou até suas coordenadas exatas sem nenhum metadado ou pistas prévias, executando completamente localmente.

Uma pequena foto recortada de um edifício, isso foi o suficiente para encontrar sua localização em um raio de 1km em Moscou.

Getting Started

Community Hub

Esta é a parte que mais nos entusiasma.

Indexar uma cidade leva horas de computação. É desperdício para cada usuário indexar independentemente a mesma cidade. Então construímos um sistema de compartilhamento: uma pessoa indexa Moscou, envia o resultado, e todos os outros baixam em minutos.

Opção A: Baixar um índice existente e começar a pesquisar

A maneira mais rápida. Alguém já fez o trabalho de indexação — você apenas baixa o índice pré-construído.

Defina o modo como Search, clique em Run Search e selecione sua imagem de consulta. As coordenadas do mapa e o raio de busca são preenchidos automaticamente a partir dos metadados do índice. Este recurso só funciona se a comunidade contribuir e se apoiar mutuamente; se você indexar uma região, ficaremos muito gratos se fizer o upload.

Opção B: Construir seu próprio índice do zero

NOTA IMPORTANTE: se o aplicativo congelar devido à falta de memória do aplicativo durante o ajuste do PCA, use este comando no terminal: python3 -c "from test_super import build_compact_index; build_compact_index()"

Deseja indexar uma cidade ou área que ninguém fez ainda? O aplicativo cuida de tudo — baixar panoramas, extrair descritores, construir o índice de busca.

python test_super.py

Defina o modo como Create
Insira as coordenadas do centro (latitude, longitude) e raio em km
Clique em Create Index
Aguarde. Para um raio de 1km, espere cerca de 20-30 minutos. Para 5km, algumas horas. Para 10km, durante a noite.

O que está acontecendo nos bastidores: o aplicativo gera uma grade de pontos dentro do raio, encontra todos os locais de panorama disponíveis, baixa cada panorama como tiles e os combina, recorta cada panorama em vários ângulos de direção, extrai descritores MegaLoc para cada recorte, ajusta PCA em todos os descritores e constrói um índice de busca compacto.

Opção C: Importar um arquivo de índice de alguém

Recebeu um arquivo .netryx de um amigo, servidor Discord ou link de download? Basta clicar em 📥 Import Index no aplicativo, selecionar o arquivo e você está pronto para pesquisar. Sem necessidade de conta, sem necessidade de internet — é um fluxo de trabalho totalmente offline.

Como funciona

Os índices são hospedados no Hugging Face Hub como conjuntos de dados públicos. Qualquer um pode baixar sem conta. Contribuir (enviar) requer uma conta gratuita no Hugging Face.

Pela GUI: Clique no botão 🌐 Community Hub para navegar, pesquisar e baixar índices disponíveis. Clique em ⬆ Upload Current Index para compartilhar o seu.

O formato .netryx

Os pacotes de índice usam o formato .netryx — um arquivo ZIP contendo:

Descritores MegaLoc reduzidos por PCA (os vetores de busca reais)
Metadados de coordenadas (lat/lon/heading/panoid para cada entrada)
O modelo PCA ajustado (necessário para transformar descritores de consulta no momento da busca)
Um manifesto com informações de cobertura (centro, raio, número de entradas, criador, etc.)

Ao exportar, a filtragem geográfica acontece automaticamente. Se seu índice contém Moscou + Paris + Tóquio, mas você exporta "Moscou 1km", apenas as entradas de Moscou são incluídas. Você pode recortar regiões específicas de um índice maior sem nenhum trabalho manual.

Compartilhamento offline

Não quer usar o Hugging Face? Basta exportar e compartilhar o arquivo como quiser:

# Exportar
python netryx_hub.py export \
  --index-dir ./netryx_data/index \
  -o moscow_1km.netryx \
  --city moscow --radius 1 --lat 55.75 --lon 37.62

# Enviar o arquivo via Discord, email, Google Drive, etc.

# Outra pessoa importa
python netryx_hub.py import moscow_1km.netryx -o ./netryx_data/index

Installation

Configuração rápida (recomendada)

Mac / Linux:

git clone https://github.com/sparkyniner/Netryx-Astra-V2-Geolocation-Tool.git
cd netryx-astra-v2
chmod +x setup.sh && ./setup.sh
source venv/bin/activate
python3 test_super.py

Windows:

git clone https://github.com/sparkyniner/netryx-astra-v2.git
cd netryx-astra-v2

Em seguida, clique duas vezes em setup.bat para instalar tudo. Quando terminar, clique duas vezes em run.bat para iniciar.

É isso. O script de configuração cria um ambiente virtual, instala todas as dependências, clona o MASt3R junto ao repositório e baixa previamente os pesos do modelo. Nenhuma configuração manual necessária.

O que você precisa

Python 3.10+
macOS (Apple Silicon via MPS),
Linux (GPU NVIDIA via CUDA, GPU AMD via ROCM), ou
Windows (GPU NVIDIA via CUDA)
8GB+ de RAM para pesquisar (16GB+ recomendado para indexar grandes áreas)
~2GB de disco por índice de cidade

Os pesos do MASt3R são baixados automaticamente do Hugging Face na primeira execução.

Sua estrutura de pastas deve se parecer com esta:

some_folder/
├── netryx-astra-v2/       # Este repositório
│   ├── test_super.py
│   ├── megaloc_utils.py
│   ├── mast3r_utils.py
│   ├── netryx_hub.py
│   └── ...
└── mast3r/                # Clonado separadamente
    ├── mast3r/
    ├── dust3r/
    └── ...

mast3r_utils.py encontra e importa automaticamente o diretório mast3r/ adjacente em tempo de execução. Nenhuma configuração de caminho necessária.

Notas sobre Apple Silicon (MPS)

Tudo funciona no Apple Silicon pronto para uso. O código lida automaticamente com peculiaridades do MPS — fallback para CPU em operações não implementadas, monkey-patching de .view() → .reshape() para tensores não contíguos e limpeza de cache MPS durante execuções longas de indexação.

Se você tem um Mac M1/M2/M3/M4, ele usará aceleração GPU automaticamente. Nenhuma configuração necessária.

Notas sobre AMD Rocm

Você precisará instalar manualmente o rocm/pytorch para seu dispositivo específico no ambiente virtual após executar o script de instalação.

Use as builds TheRock do pytorch para seu dispositivo: https://github.com/ROCm/TheRock/blob/main/RELEASES.md#installing-pytorch-python-packages

Para instalar, por exemplo, para placas da série RX7xxx:

pip install --index-url https://rocm.nightlies.amd.com/v2/gfx110X-all/ torch torchaudio torchvision

NOTA: certifique-se de que o usuário faça parte do grupo render:

sudo usermod -aG render <userid>

e que o driver base esteja instalado: https://rocm.docs.amd.com/projects/install-on-linux/en/latest/install/quick-start.html#amd-gpu-driver-installation

Estrutura do Projeto

netryx-astra-v2/
├── test_super.py          # Aplicativo principal — GUI, pipeline, tudo
├── megaloc_utils.py       # Carregamento do modelo MegaLoc, extração de descritores, PCA
├── megaloc_model.py       # Arquitetura MegaLoc autocontida (fallback se torch.hub falhar)
├── mast3r_utils.py        # Carregamento e correspondência densa MASt3R
├── netryx_hub.py          # Community Hub — upload, download, export, import
├── README.md
├── LICENSE
└── requirements.txt

# Criado em tempo de execução (não commitado no git):
netryx_data/
├── megaloc_parts/         # Chunks brutos de descritores 8448-dim (criados durante a indexação)
└── index/                 # O índice de busca compacto
    ├── megaloc_descriptors.npy   # Descritores reduzidos por PCA
    ├── metadata.npz              # Coordenadas, headings, IDs de panoid
    ├── megaloc_pca.pkl           # Modelo PCA para transformação na consulta
    └── manifest.json             # Presente se baixado do Community Hub

# Dependência externa (clonada separadamente, NÃO dentro deste repositório):
../mast3r/                 # https://github.com/naver/mast3r

Configuração

Você pode ajustar estes parâmetros em test_super.py se necessário. Os padrões funcionam bem para a maioria dos casos de uso.

O principal que você pode querer ajustar é INDEX_TARGET_DIM — reduzir para 512 diminui o tamanho do índice pela metade com apenas ~2-3% de perda de precisão.

Limitações

Acreditamos em ser transparentes sobre o que esta ferramenta pode e não pode fazer.

Ela só encontra lugares que estão no índice. Se uma localização não foi indexada por você ou baixada da comunidade, ela não será encontrada. Nenhum modelo, por mais avançado que seja, pode corresponder a dados que não existem. O teto de precisão é definido pela cobertura, não pelos modelos.

Arquitetura repetitiva causa falsos positivos. Lojas de rede, conjuntos habitacionais suburbanos, fileiras de blocos de apartamentos idênticos — todos realmente parecem iguais ao nível da rua. O consenso espacial ajuda (um cluster de correspondências próximas supera um único outlier isolado), mas não é infalível, especialmente em grandes raios de busca (10km+) onde há mais candidatos de aparência semelhante. Este é um problema não resolvido na área, não uma limitação específica do Netryx.

Existem lacunas de cobertura em algumas áreas. Áreas rurais, países em desenvolvimento, bairros recém-construídos e espaços internos podem ter imagens de nível de rua limitadas ou ausentes para indexação.

Este não é um sistema em tempo real. Executar o MASt3R em 500 candidatos leva vários minutos em uma GPU de consumo. Isso é projetado para análise forense — jornalismo investigativo, documentação de direitos humanos, pesquisa OSINT, investigação de fraudes de seguros — não para navegação ou rastreamento ao vivo.

A indexação requer poder computacional significativo. O backbone DINOv2 do MegaLoc é ~5x mais pesado que o backbone CosPlace usado no V1. Indexar um raio de 1km leva ~20-30 minutos. Uma cidade inteira (10km+) é um trabalho durante a noite. É por isso que o Community Hub existe — para que este custo seja pago uma vez e compartilhado. Além disso, a correspondência com mais inliers não é necessariamente a correspondência correta; por isso, retorna vários resultados que você pode verificar por conta própria.

Citação

Se você usar Netryx Astra V2 em sua pesquisa ou trabalho, agradecemos uma citação:

@software{netryx_astra_v2,
  title={Netryx Astra V2: State-of-the-Art AI Geolocation},
  author={Sairaj Balaji},
  year={2026},
  url={https://github.com/yourusername/netryx-astra-v2}
}

Licença

Licença MIT. Consulte LICENSE para obter detalhes.

Os pesos do MegaLoc são licenciados sob MIT. MASt3R é licenciado sob Apache 2.0. DINOv2 é licenciado sob Apache 2.0. Índices compartilhados pela comunidade são CC-BY-4.0.

Construído por Sairaj Balaji

Também construiu o PrismX, apresentado no Fast Company · 404 Media · Deutsche Welle

Encontrar candidatos	CosPlace (ResNet-50, 512-dim)	MegaLoc (DINOv2 ViT-B/14, 8448-dim → PCA 1024)
Confirmar correspondências	DISK + LightGlue + RANSAC	Correspondência densa 3D MASt3R
Lidar com casos extremos	Fallback LoFTR, salto de descritor, expansão de vizinhança, Modo Ultra	Consenso espacial — só isso
Total de estágios do pipeline	9+	3
Correspondência de imagem parcial	Fraca — keypoints esparsos falham em pequenas sobreposições	Forte — MASt3R encontra correspondências densas em regiões minúsculas
Compartilhar índices	Não possível	Community Hub via Hugging Face + pacotes `.netryx` offline

`INDEX_TARGET_DIM`	1024	Dimensão de saída do PCA. 512 = índice menor, ligeiramente menos preciso. 1024 = bom equilíbrio.
`MAX_PANOID_WORKERS`	16	Quantos panoramas baixar em paralelo durante a indexação
`MAX_DOWNLOAD_WORKERS`	100	Conexões simultâneas de download de tiles (cada pano = 8 tiles)
`EARLY_EXIT_INLIER_THRESHOLD`	450	Se o MASt3R encontrar este número de correspondências densas, interrompa a busca cedo — é um acerto confiável
`MAST3R_STAGE2_TOP_N`	500	Quantos candidatos MegaLoc passar pelo MASt3R

Netryx-Astra-V2-Geolocation-Tool

Mais Populares