sparkyniner/Netryx-OpenSource-Next-Gen-Street-Level-Geolocation
GitHub: sparkyniner/Netryx-OpenSource-Next-Gen-Street-Level-Geolocation
基于深度学习视觉模型的开源街景级地理定位工具，可从任意街景照片中精确识别 GPS 坐标。
Stars: 430 | Forks: 54
NETRYX
开源街景级地理定位引擎
上传任意街景照片。获取精确的 GPS 坐标。
精度小于 50 米。无需地标。完全在您的硬件上运行。
演示 · 工作原理 · 入门指南 · 使用方法 · 常见问题
## Netryx 是什么？
Netryx 是一款本地优先的地理定位工具，能够识别任意街景照片的精确 GPS 坐标。与反向图像搜索（匹配已上传的网络图像）不同，Netryx 匹配的是**系统化爬取的街景全景图**——这意味着它适用于任何零网络足迹的随机街角。
核心流水线结合了三个最先进的计算机视觉模型：
- **CosPlace**：用于全局视觉地点识别（检索）
- **ALIKED/DISK**：用于局部特征提取（关键点）
- **LightGlue**：用于深度特征匹配（验证）
## 演示
| 用例 | 链接 |
|----------|------|
| 导弹袭击地理定位 —— 卡塔尔（2026 年 2 月） | [在 YouTube 上观看](https://www.youtube.com/watch?v=Y_eC5VPypPU) |
| 冲突监控 —— 巴黎抗议活动 | [在 YouTube 上观看](https://www.youtube.com/watch?v=DV8vsoa5sLU) |
| 基于随机照片的盲地理定位 —— 巴黎 | [在 YouTube 上观看](https://www.youtube.com/watch?v=N5Cx7j6qA7I) |
| 技术深入探讨：流水线如何工作 | [在 YouTube 上观看](https://www.youtube.com/watch?v=KMbeABzG6IQ) |
## 工作原理
Netryx 使用三阶段流水线，逐步将范围从数百万候选缩小到单一精确匹配。Netryx 仅仅是一个工具，它来源无关，可以处理来自任何提供商（如 Mapilliary、Kartaview 或其他任何提供商）的图像。
### 第 1 阶段 —— 全局检索 (CosPlace)
索引中的每张街景全景图都使用 [CosPlace](https://github.com/gmberton/cosplace) 预处理成了 512 维的“指纹”，CosPlace 是一个在数百万张地理标记图像上训练的视觉地点识别模型。
当您上传查询照片时：
1. 系统从您的图像中提取 CosPlace 描述符
2. 它还从水平翻转的版本中提取描述符（捕捉反向视角）
3. 使用余弦相似度将两个描述符与索引中的每个条目进行比较
4. 半径过滤器（半正矢距离）将候选范围缩小到您指定的搜索区域
5. 返回前 500–1000 个视觉上最相似的全景视图作为候选
无论索引大小如何，此阶段运行时间**不到 1 秒**——这是单次矩阵乘法。
### 第 2 阶段 —— 局部几何验证 (ALIKED/DISK + LightGlue)
CosPlace 寻找*看起来相似*的地方。第 2 阶段使用几何验证证明它们是*同一个地方*。
对于每个候选：
1. 从 Google Street View 下载原始全景图（8 个切片，拼接而成）
2. 在索引的航向角处提取矩形裁剪
3. 生成三个视场角（70°、90°、110°）的**多 FOV 裁剪**，以处理查询照片与索引视图之间的缩放不匹配
4. [ALIKED](https://github.com/naver/alike)（在 CUDA 上）或 [DISK](https://github.com/cvlab-epfl/disk)（在 MPS/CPU 上）提取局部关键点和描述符
5. [LightGlue](https://github.com/cvg/LightGlue) 在查询和候选关键点之间执行深度特征匹配
6. **RANSAC** 过滤匹配，仅保留几何上一致的对应关系（拒绝错误匹配）
7. 拥有最多经验证内点的候选即为最佳匹配
根据您的硬件情况，此阶段处理 300–500 个候选需要 **2–5 分钟**。
### 第 3 阶段 —— 优化
初始匹配虽然不错，但并不总是最优的。优化改进了它：
- **航向优化**：对于前 15 个候选，系统在 3 个 FOV 下以 15° 为步长测试 ±45° 的航向偏移。这可以捕捉索引航向与查询视角方向不完全匹配的情况。
- **空间共识**：将匹配聚合到 50 米的单元格中。如果多个候选聚集在一个区域，则该簇优于单个高内点的异常值——从而减少误报。
- **置信度评分**：系统评估最佳匹配的地理聚类以及唯一性比率（最佳匹配与位于不同位置的亚军相比好多少）。
### 极限模式 (Ultra Mode) (可选)
对于困难图像（夜间、模糊、低纹理），极限模式增加了：
- **LoFTR**：一种无检测器的密集匹配器，无需依赖关键点检测即可找到对应关系。适用于 ALIKED/DISK 难以处理的模糊和低对比度场景。
- **描述符跳跃**：如果初始匹配较弱（<50 个内点），系统从*匹配的全景图*（干净/高质量）中提取 CosPlace 描述符并重新搜索索引。这通常能找到退化查询错过的确切正确全景图。
- **邻域扩展**：搜索最佳匹配 100 米范围内的所有全景图。正确位置通常距离 CosPlace 最佳匹配仅一个街道节点。
## 架构
```
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
```
## 入门指南
### 系统要求
| 组件 | 最低配置 | 推荐配置 |
|-----------|---------|-------------|
| 操作系统 | macOS / Linux / Windows | macOS (M1+) 或配备 NVIDIA GPU 的 Linux |
| GPU 显存 | 4GB | 8GB+ |
| 内存 | 8GB | 16GB+ |
| 存储空间 | 10GB | 50GB+（取决于索引区域大小） |
| 网络 | 索引和搜索需要 | 推荐宽带 |
| Python | 3.9+ | 3.10+ |
**GPU 支持：**
- **Mac**: MPS (Metal Performance Shaders) — M1/M2/M3/M4
- **NVIDIA**: CUDA — 任何拥有 4GB+ 显存的 GPU
- **CPU**: 可用但速度明显较慢
### 安装
```
# 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 (matching required)
pip install git+https://github.com/cvg/LightGlue.git
# Optional: Install kornia for Ultra Mode (LoFTR)
pip install kornia
```
### Gemini API Key (可选 — 用于 AI 粗略模式) [不推荐使用，手动即可完成任务]
如果您想使用 AI 辅助的盲地理定位功能：
1. 从 [Google AI Studio](https://aistudio.google.com) 获取免费的 API Key
2. 将其设置为环境变量：
```
export GEMINI_API_KEY="your_key_here"
```
## 使用方法
### 启动 GUI
```
python test_super.py
```
macOS 用户：如果 GUI 显示为空白，请升级 tkinter：brew install python-tk@3.11（或您的 Python 版本）。系统 Python 自带的 tkinter 在最近的 macOS 版本上存在已知的渲染问题。
### 第 1 步：创建索引
在搜索之前，您需要索引一个区域。这会爬取 Street View 全景图并提取 CosPlace 指纹。
1. 选择 **Create** 模式
2. 输入您想要索引区域的中心坐标（纬度，经度）
3. 设置搜索半径（测试从 0.5–1km 开始，生产环境从 5–10km 开始）
4. 设置网格分辨率（300 是一个不错的默认值 —— 越高 = 覆盖越密，请勿随意更改）
5. 点击 **Create Index**
**索引时间估算：**
| 半径 | 大约全景图数量 | 时间 (M2 Max) | 索引大小 |
|--------|-------------------|---------------|------------|
| 0.5 km | ~500 | 30 分钟 | ~60 MB |
| 1 km | ~2,000 | 1–2 小时 | ~250 MB |
| 5 km | ~30,000 | 8–12 小时 | ~3 GB |
| 10 km | ~100,000 | 24–48 小时 | ~7 GB |
索引是增量保存的——如果过程中断，下次运行时会从中断处继续。
### 第 2 步：搜索
1. 选择 **Search** 模式
2. 上传一张街景照片
3. 选择搜索方式：
- **Manual**：如果您大致知道照片的来源地，请输入坐标 + 半径
- **AI Coarse**：让 Gemini 分析视觉线索（标志、建筑、植被）来猜测区域 —— 无需先验知识
4. 点击 **Run Search**，然后点击 **Start Full Search**
5. 观察实时扫描可视化，系统会评估候选
6. 结果及置信度分数将显示在地图上
### 极限模式
对于困难图像，启用 **Ultra Mode** 复选框。这增加了 LoFTR 密集匹配、描述符跳跃和邻域扩展。速度明显较慢，但能捕捉标准流水线错过的匹配。
## 索引如何工作
所有 Embedding 都存储在单个统一索引中。当您搜索时，半径过滤器会自动将结果限制在您指定的区域内。这意味着：
- 您可以先索引巴黎，然后是特拉维夫，再到伦敦 —— 全部放入同一个索引
- 使用 center=Paris, radius=5km 搜索仅返回巴黎的结果
- 使用 center=London, radius=10km 搜索仅返回伦敦的结果
- 无需选择城市 —— 坐标 + 半径搞定一切
**数据流：**
```
Create Mode:
Grid points → Google Street View API → Panoramas → Crops → CosPlace → cosplace_parts/*.npz
Auto-build:
cosplace_parts/*.npz → cosplace_descriptors.npy + metadata.npz (searchable index)
Search Mode:
Query image → CosPlace → Index search (radius-filtered) → Download candidates → ALIKED/DISK + LightGlue → Result
```
## 项目结构
```
netryx/
├── test_super.py # Main application (GUI + indexing + search)
├── cosplace_utils.py # CosPlace model loading and descriptor extraction
├── build_index.py # Standalone high-performance index builder (for large datasets)
├── requirements.txt # Python dependencies
├── cosplace_parts/ # Raw embedding chunks (created during indexing)
├── index/ # Compiled searchable index
│ ├── cosplace_descriptors.npy # All 512-dim descriptors
│ └── metadata.npz # Coordinates, headings, panoid IDs
└── README.md
```
## 技术细节
### 使用的模型
| 模型 | 用途 | 论文 |
|-------|---------|-------|
| [CosPlace](https://github.com/gmberton/cosplace) | 视觉地点识别（全局描述符） | [CVPR 2022](https://arxiv.org/abs/2204.02287) |
| [ALIKED](https://github.com/naver/alike) | 局部特征提取（在 CUDA 上使用） | [IEEE TIP 2023](https://arxiv.org/abs/2304.03608) |
| [DISK](https://github.com/cvlab-epfl/disk) | 局部特征提取（在 MPS/CPU 上使用） | [NeurIPS 2020](https://arxiv.org/abs/2006.13566) |
| [LightGlue](https://github.com/cvg/LightGlue) | 深度特征匹配 | [ICCV 2023](https://arxiv.org/abs/2306.13643) |
| [LoFTR](https://github.com/zju3dv/LoFTR) | 无检测器密集匹配 (极限模式) | [CVPR 2021](https://arxiv.org/abs/2104.00680) |
### 平台特定行为
| 特性 | CUDA (NVIDIA) | MPS (Mac) | CPU |
|---------|--------------|-----------|-----|
| 特征提取器 | ALIKED (1024 kp) | DISK (768 kp) | DISK (768 kp) |
| LightGlue flash attention | 启用 | 禁用 | 禁用 |
| LoFTR (极限模式) | 全速 | 部分操作 CPU 回退 | 全 CPU |
| 索引速度 | 最快 | 良好 | 慢 |
## 常见问题
**搜索半径越大，准确度会下降吗？**
不会。CosPlace 在整个索引中按视觉相似度排名。无论您的索引覆盖 1km 还是 50km，最佳候选始终是视觉上最相似的。半径过滤器只是在排名前排除地理上无关的条目。
**搜索需要多长时间？**
在 Apple Silicon 上通常需要 2–5 分钟，在 NVIDIA GPU 上需要 1–3 分钟。瓶颈是从 Google 下载全景图切片（受网络限制），而不是匹配本身。
**我可以索引整个国家吗？**
不切实际。10km 半径会产生约 100K 张全景图和约 7GB 的索引。整个国家将需要 PB 级存储。索引特定的城市或感兴趣区域（5–20km）。
**我的搜索找到了 0 个候选。**
您的搜索坐标与任何索引区域不重叠。请先索引该区域，或者调整您的搜索中心/半径以与现有索引数据重叠。使用“Show Coverage Map”可视化已索引的内容。
**匹配略有偏差（偏差一个街区）。**
启用极限模式。邻域扩展搜索初始匹配 100 米范围内的所有全景图，通常能找到确切正确的街道节点。
**这对室内照片有效吗？**
无效。Netryx 仅匹配户外街景全景图。室内照片、航拍/卫星图像和特写物体照片不会产生有意义的结果。
**这需要花钱吗？**
Netryx 是免费且开源的。可选的 AI Coarse 功能需要 Gemini API Key（Google 提供免费层）。计算成本仅为您自己的硬件——无需云服务。
**有托管版本吗？**
有的。[netryx.live](https://netryx.live) 在云端运行完整流水线，因此您无需在本地进行任何设置。如果您想快速获得结果而不想构建自己的索引，这很有用。
## 不想搭建完整流水线？
[**netryx.live**](https://netryx.live) 在云端运行相同的引擎——上传照片，获取坐标。无需安装，无需索引，无需 GPU。
## 作者
**Saj Balaji** —— AI 研究员，PrismX 创造者。获得 Microsoft for Startups 和 ElevenLabs 的资助。被 Fast Company 和 Deutsche Welle 报道。
- [LinkedIn](https://www.linkedin.com/in/sairaj-balaji-7295b2246/)
## 许可证
MIT License。详见 [LICENSE](LICENSE)。
## 法律免责声明
Netryx 专为合法的 OSINT 研究、调查性新闻、人权监控、灾害响应和学术研究而设计。
**用户责任**：您需全权负责确保遵守适用法律，包括 Google Maps/Street View 服务条款和当地隐私法规。
**请勿用于**：跟踪、骚扰、未经授权的监视或任何侵犯个人隐私或安全的活动。
Netryx 的开发者对滥用行为不承担任何责任。
标签：ALIKED, CosPlace, DISK, ESC4, HTTP/HTTPS抓包, LightGlue, LSASS转储, OSINT, Python, Vectored Exception Handling, 二进制发布, 凭据扫描, 图像检索, 图像识别, 地理定位, 坐标定位, 定位引擎, 开源工具, 态势感知, 无后门, 无需API, 智能监控, 本地部署, 深度学习, 特征提取, 神经网络, 离线运行, 街景爬虫, 街景识别, 计算机视觉, 逆向工具, 隐私计算