NETRYX

Motor de Geolocalização de Nível de Rua Open-Source

Carregue qualquer foto de rua. Obtenha coordenadas GPS precisas.
Precisão abaixo de 50m. Sem necessidade de pontos de referência. Funciona inteiramente no seu hardware.

Demonstrações · Como Funciona · Primeiros Passos · Uso · FAQ

ESTA VERSÃO É ANTIGA, USE ESTA EM VEZ

NOVO REPOSITÓRIO

O que é o Netryx?

O Netryx é uma ferramenta de geolocalização local-first que identifica as coordenadas GPS exatas de qualquer fotografia de nível de rua. Ao contrário da pesquisa reversa de imagens (que corresponde a imagens da web carregadas), o Netryx corresponde a panoramas de street view sistematicamente rastreados — ou seja, funciona em qualquer esquina aleatória sem presença na internet.

O pipeline central combina três modelos de visão computacional de última geração:

• CosPlace para reconhecimento global de lugares visuais (recuperação)
• ALIKED/DISK para extração de características locais (pontos-chave)
• LightGlue para correspondência profunda de características (verificação)

O Google Lens pesquisa a internet. O Netryx pesquisa o mundo físico.

Demonstrações

Como Funciona

O Netryx usa um pipeline de três estágios que progressivamente reduz de milhões de candidatos a uma única correspondência precisa. O Netryx é simplesmente uma ferramenta, é agnóstico quanto à fonte e pode processar imagens de qualquer provedor, como Mapillary ou KartaView ou qualquer outro.

Estágio 1 — Recuperação Global (CosPlace)

Cada panorama de street view no índice foi pré-processado em uma "impressão digital" de 512 dimensões usando CosPlace, um modelo de reconhecimento de lugares visuais treinado em milhões de imagens geo-referenciadas.

Quando você carrega uma foto de consulta:

1. O sistema extrai um descritor CosPlace da sua imagem
2. Também extrai um descritor de uma versão espelhada horizontalmente (captura perspectivas invertidas)
3. Ambos os descritores são comparados com cada entrada no índice usando similaridade de cosseno
4. Um filtro de raio (distância haversiana) reduz os candidatos à sua área de pesquisa especificada
5. As 500–1000 vistas panorâmicas mais visualmente semelhantes são retornadas como candidatos

Este estágio é executado em menos de 1 segundo independentemente do tamanho do índice — é uma única multiplicação de matrizes.

Estágio 2 — Verificação Geométrica Local (ALIKED/DISK + LightGlue)

O CosPlace encontra lugares que parecem semelhantes. O Estágio 2 prova que são o mesmo lugar usando verificação geométrica.

Para cada candidato:

1. O panorama original é baixado do Google Street View (8 tiles, unidos)
2. Um recorte retilíneo é extraído no ângulo de orientação indexado
3. Recortes multi-FOV são gerados em três campos de visão (70°, 90°, 110°) para lidar com diferenças de zoom entre a foto de consulta e a vista indexada
4. ALIKED (no CUDA) ou DISK (no MPS/CPU) extrai pontos-chave e descritores locais
5. LightGlue realiza correspondência profunda de características entre os pontos-chave da consulta e do candidato
6. RANSAC filtra as correspondências para manter apenas correspondências geometricamente consistentes (rejeita falsas correspondências)
7. O candidato com mais inliers verificados é a melhor correspondência

Este estágio processa 300–500 candidatos em 2–5 minutos dependendo do seu hardware.

Estágio 3 — Refinamento

A correspondência inicial é boa, mas nem sempre ideal. O refinamento a melhora:

• Refinamento de orientação: Para os 15 principais candidatos, o sistema testa deslocamentos de orientação de ±45° em passos de 15° em 3 FOVs. Isso captura casos onde a orientação indexada não corresponde exatamente à direção de visualização da consulta.
• Consenso espacial: As correspondências são agrupadas em células de 50m. Se vários candidatos se agrupam em uma área, esse grupo é preferido em vez de um único outlier com muitos inliers — reduzindo falsos positivos.
• Pontuação de confiança: O sistema avalia o agrupamento geográfico das principais correspondências e a taxa de exclusividade (quanto melhor a melhor correspondência é em relação à segunda colocada em um local diferente).

Modo Ultra (Opcional)

Para imagens difíceis (noturnas, borradas, baixa textura), o Modo Ultra adiciona:

• LoFTR: Um correspondente denso sem detector que encontra correspondências sem depender da detecção de pontos-chave. Lida com cenas borradas e de baixo contraste onde ALIKED/DISK têm dificuldade.
• Salto de descritor: Se a correspondência inicial for fraca (<50 inliers), o sistema extrai um descritor CosPlace do panorama correspondido (que é limpo/de alta qualidade) e repesquisa o índice. Isso geralmente encontra o panorama exato e correto que a consulta degradada perdeu.
• Expansão de vizinhança: Pesquisa todos os panoramas num raio de 100m da melhor correspondência. O local correto geralmente está a um nó de rua de distância da melhor correspondência do CosPlace.

Arquitetura

Imagem de Consulta
    │
    ├── Extração de descritor CosPlace (impressão digital de 512 dimensões)
    ├── Extração de descritor espelhado
    │
    ▼
Pesquisa no Índice (similaridade de cosseno, filtrado por raio)
    │
    ├── Top 500 candidatos classificados por similaridade visual
    │
    ▼
Baixar Panoramas → Recortar em 3 FOVs → Extrair pontos-chave ALIKED/DISK
    │
    ├── Correspondência LightGlue contra pontos-chave da consulta
    ├── Verificação geométrica RANSAC
    │
    ▼
Refinamento de Orientação (±45°, 3 FOVs, top 15 candidatos)
    │
    ├── Agrupamento de consenso espacial
    ├── Pontuação de confiança
    │
    ▼
📍 Coordenadas GPS + Pontuação de Confiança

Primeiros Passos

Requisitos

Suporte a GPU:

• Mac: MPS (Metal Performance Shaders) — M1/M2/M3/M4
• NVIDIA: CUDA — qualquer GPU com 4GB+ de VRAM
• CPU: Funciona, mas significativamente mais lento

Instalação

# Clone o repositório
git clone https://github.com/sparkyniner/Netryx-OpenSource-Next-Gen-Street-Level-Geolocation.git

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

# Crie o ambiente virtual
python3 -m venv venv
source venv/bin/activate  # No Windows: venv\Scripts\activate

# Instale as dependências
pip install -r requirements.txt

# Instale o LightGlue explicitamente (necessário para correspondência)
pip install git+https://github.com/cvg/LightGlue.git

# Opcional: Instale o kornia para o Modo Ultra (LoFTR)
pip install kornia

Nota: lightglue é importado pelo aplicativo como um módulo Python, mas é instalado a partir do repositório GitHub acima.

Chave da API Gemini (Opcional — para modo AI Coarse) [Não recomendado para uso, o manual faz o trabalho]

Se quiser usar o recurso de geolocalização cega assistida por IA:

1. Obtenha uma chave de API gratuita do Google AI Studio
2. Defina-a como uma variável de ambiente:

export GEMINI_API_KEY="sua_chave_aqui"

Uso

Iniciar a GUI

python test_super.py

Usuários de macOS: Se a GUI aparecer em branco, atualize o tkinter: brew install [email protected] (ou sua versão do Python). O tkinter empacotado do Python do sistema tem problemas de renderização conhecidos em versões recentes do macOS.

Passo 1: Criar um Índice

Antes de pesquisar, você precisa indexar uma área. Isso rastreia panoramas do Street View e extrai impressões digitais CosPlace.

1. Selecione o modo Create (Criar)
2. Insira as coordenadas centrais (latitude, longitude) da área que deseja indexar
3. Defina o raio de busca (comece com 0.5–1km para teste, 5–10km para produção)
4. Defina a resolução da grade (300 é um bom padrão — maior = cobertura mais densa, por favor não mexa nisso)
5. Clique em Create Index (Criar Índice)

Estimativas de tempo de indexação:

O índice é salvo incrementalmente — se o processo for interrompido, ele retoma de onde parou na próxima execução.

Passo 2: Pesquisar

1. Selecione o modo Search (Pesquisar)
2. Carregue uma foto de nível de rua
3. Escolha o método de pesquisa:
   • Manual: Insira coordenadas + raio se você souber aproximadamente de onde a foto é
   • AI Coarse: Deixe o Gemini analisar pistas visuais (placas, arquitetura, vegetação) para adivinhar a região — sem necessidade de conhecimento prévio
4. Clique em Run Search (Executar Pesquisa), depois em Start Full Search (Iniciar Pesquisa Completa)
5. Observe a visualização de varredura em tempo real enquanto os candidatos são avaliados
6. O resultado aparece no mapa com a pontuação de confiança

Modo Ultra

Ative a caixa de seleção Ultra Mode para imagens difíceis. Isso adiciona correspondência densa LoFTR, salto de descritor e expansão de vizinhança. Significativamente mais lento, mas captura correspondências que o pipeline padrão perde.

Como o Índice Funciona

Todas as incorporações são armazenadas em um único índice unificado. Quando você pesquisa, o filtro de raio restringe automaticamente os resultados à área que você especificar. Isso significa:

• Você pode indexar Paris, depois Tel Aviv, depois Londres — todos no mesmo índice
• Pesquisar com centro=Paris, raio=5km retorna apenas resultados de Paris
• Pesquisar com centro=Londres, raio=10km retorna apenas resultados de Londres
• Nenhuma seleção de cidade necessária — coordenadas + raio cuidam de tudo

Fluxo de dados:

Modo Create:
  Pontos da grade → API do Google Street View → Panoramas → Recortes → CosPlace → cosplace_parts/*.npz

Auto-build:
  cosplace_parts/*.npz → cosplace_descriptors.npy + metadata.npz (índice pesquisável)

Modo Search:
  Imagem de consulta → CosPlace → Pesquisa no índice (filtrado por raio) → Baixar candidatos → ALIKED/DISK + LightGlue → Resultado

Estrutura do Projeto

netryx/
├── test_super.py          # Aplicação principal (GUI + indexação + pesquisa)
├── cosplace_utils.py      # Carregamento do modelo CosPlace e extração de descritores
├── build_index.py         # Construtor de índice independente de alto desempenho (para grandes conjuntos de dados)
├── requirements.txt       # Dependências Python
├── cosplace_parts/        # Pedaços de incorporação brutos (criados durante a indexação)
├── index/                 # Índice pesquisável compilado
│   ├── cosplace_descriptors.npy   # Todos os descritores de 512 dimensões
│   └── metadata.npz               # Coordenadas, orientações, IDs de panoid
└── README.md

Detalhes Técnicos

Modelos Utilizados

Comportamento Específico da Plataforma

FAQ

A precisão diminui com um raio de pesquisa maior?

Não. O CosPlace classifica por similaridade visual em todo o índice. Se o seu índice cobre 1km ou 50km, os principais candidatos são sempre os mais visualmente semelhantes. O filtro de raio simplesmente exclui entradas geograficamente irrelevantes antes da classificação.

Quanto tempo leva uma pesquisa?

Normalmente 2–5 minutos no Apple Silicon, 1–3 minutos na GPU NVIDIA. O gargalo é o download dos tiles do panorama do Google (limitado pela rede), não a correspondência em si.

Posso indexar um país inteiro?

Não é prático. Um raio de 10km produz ~100K panoramas e um índice de ~7GB. Um país inteiro exigiria petabytes. Indexe cidades ou regiões específicas de interesse (5–20km).

Minha pesquisa não encontrou nenhum candidato.

Suas coordenadas de pesquisa não se sobrepõem a nenhuma área indexada. Indexe a área primeiro ou ajuste o centro/raio da pesquisa para sobrepor os dados indexados existentes. Use "Show Coverage Map" (Mostrar Mapa de Cobertura) para visualizar o que foi indexado.

A correspondência está ligeiramente errada (a um quarteirão de distância).

Ative o Modo Ultra. A expansão de vizinhança pesquisa todos os panoramas num raio de 100m da correspondência inicial, muitas vezes encontrando o nó de rua exato e correto.

Isso funciona com fotos internas?

Não. O Netryx corresponde apenas a panoramas de street view externos. Fotos internas, imagens aéreas/satélite e fotos de objetos em close não produzirão resultados significativos.

Isso custa dinheiro?

O Netryx é gratuito e de código aberto. O recurso opcional AI Coarse requer uma chave de API Gemini (nível gratuito disponível no Google). Os custos de computação são do seu próprio hardware — nenhum serviço em nuvem necessário.

Existe uma versão hospedada?

Sim. netryx.live executa o pipeline completo na nuvem, para que você não precise configurar nada localmente. Útil se você quiser resultados rápidos sem construir seu próprio índice. Mas é cerca de 30% menos preciso que a versão de código aberto devido a restrições de computação.

Não quer configurar o pipeline completo?

netryx.live executa o mesmo motor na nuvem — carregue uma foto, obtenha coordenadas. Sem instalação, sem indexação, sem GPU necessária. Mas é cerca de 30% menos preciso que a versão de código aberto devido a restrições de computação.

Construído Por

Sairaj Balaji — Pesquisador de IA e criador do PrismX. Bolsas da Microsoft for Startups e ElevenLabs. Destacado na Fast Company e Deutsche Welle.

• LinkedIn

Licença

Licença MIT. Veja LICENSE para detalhes.

Aviso Legal

O Netryx foi projetado para pesquisa OSINT legítima, jornalismo investigativo, monitoramento de direitos humanos, resposta a desastres e pesquisa acadêmica.

Responsabilidade do usuário: Você é o único responsável por garantir a conformidade com as leis aplicáveis, incluindo os Termos de Serviço do Google Maps/Street View e regulamentações locais de privacidade.

Não use para: Perseguição, assédio, vigilância não autorizada ou qualquer atividade que viole a privacidade ou segurança de indivíduos.

Os desenvolvedores do Netryx se isentam de toda responsabilidade por uso indevido.