vistone/geoclaw

# geoclaw — Google Earth 3D 瓦片数据工具集 [](https://go.dev/) [](LICENSE) **geoclaw** 是一个 Google Earth 协议逆向工程的 Go 实现，提供从 Google Earth 服务器获取、解析、转换和渲染 3D 瓦片数据的完整工具链。支持将 Google Earth 的私有地形和影像格式转换为标准的 3D Tiles（GLB）格式，可用于 CesiumJS 等 Web 3D 地图框架。 ## 项目架构 geoclaw/ ├── cmd/ # 可执行程序入口 ├── config/ # 应用配置 ├── core/ # 核心业务逻辑 │ ├── gelib/ # Google Earth 协议库 │ ├── geomath/ # 地理数学工具 │ ├── httplib/ # HTTP 客户端 │ └── rocktree/ # 3D 模型解码库 ├── crawler/ # 瓦片数据爬虫 ├── handler/ # HTTP API 处理器 ├── middleware/ # HTTP 中间件 ├── pkg/ # 公共工具包 ├── client/ # C++ 3D 渲染客户端 ├── libge/ # C++ Windows DLL（早期实现） ├── dbroot/ # Google Earth 数据库根数据 └── test/ # 测试数据 ## 目录功能总览 ### cmd/ — 命令行入口 三个可执行程序入口： | 程序 | 说明 | |------|------| | `cmd/server` | HTTP 服务端 — 提供 Google Earth 瓦片数据的实时代理、REST API 和 3D Tiles 桥接 | | `cmd/crawler_flatfile` | 离线瓦片爬虫 — 从 Google Earth flatfile 服务爬取地形和影像，生成 GLB + tileset.json | | `cmd/tileset_gen` | tileset.json 生成器 — 从已有的 GLB 文件生成 3D Tiles 标准 tileset.json | ### config/ — 应用配置 从环境变量加载配置（`PORT`、`APP_ENV`），提供 `Config` 结构体和 `Load()` 函数。 ### core/ — 核心业务逻辑 | 子目录 | 说明 | |--------|------| | **gelib** | Google Earth 协议核心库 — 认证（GeAuth）、数据库根（GeDbRoot）、四叉树（QuadtreeSet）、地形解码（DecodeTerrain）、加密解密（GeCrypted）、GLB 生成（WriteNamedTexturedGLB） | | **geomath** | 地理数学工具 — Web Mercator 投影转换（GeoToTile/TileToGeo）、四叉树路径编码（QuadTreePath）、八叉树编号（TreeNumbering）、瓦片边界计算（QtNodeBounds） | | **httplib** | HTTP 客户端 — 支持代理配置、浏览器指纹（User-Agent 伪装）、Cookie 管理、gzip 解压、GET/POST 请求 | | **rocktree** | 3D 模型解码库 — 节点元数据（Node）、批量元数据（BulkMetadata）、CRN/DXT1 纹理解压缩、纹理格式转换（DXT1→RGB→PNG）、JSON 序列化 | ### crawler/ — 瓦片数据爬虫 封装 Google Earth `rt/` REST API 的 HTTP 客户端： | 文件 | 说明 | |------|------| | `client.go` | HTTP 客户端 — FetchPlanetoidMetadata、FetchBulkMetadata、FetchNodeData、URL pb= 参数编码 | | `geo.go` | 地理坐标转换（委托 core/geomath） | | `node_manager.go` | 线程安全的节点缓存管理器（sync.RWMutex） | | `request.go` | Protobuf 请求构建器（Builder 模式） | ### handler/ — HTTP API 处理器 | 路由 | 说明 | |------|------| | `GET /` | 首页（Hello, World!） | | `GET /tiles/` | 3D Tiles 动态桥接 — 实时从 Google Earth 获取并转换 | | `GET /api/planetoid` | 星球元数据 JSON API | | `GET /api/bulk` | 批量元数据 JSON API | | `GET /api/nodedata` | 节点数据 JSON API | | `GET /api/v2/bulk` | 批量元数据 V2 API（按类型分类返回） | ### middleware/ — HTTP 中间件 | 中间件 | 说明 | |--------|------| | `chain.go` | 中间件链模式 | | `cors.go` | CORS 跨域支持（Allow-Origin: *） | | `logger.go` | 请求日志（唯一 ID + 处理时长） | | `recovery.go` | Panic 恢复（返回 500） | ### pkg/ — 公共工具包 | 子目录 | 说明 | |--------|------| | `logger` | 分级日志（Debug/Info/Warn/Error） | | `response` | 标准 JSON API 响应封装（{code, message, data}） | ### client/ — C++ 3D 渲染客户端 基于 SDL2 + OpenGL 的 3D 地球渲染客户端，支持原生桌面和 WebAssembly（Emscripten）两种运行方式。包含完整的 Google Earth 协议解码器、HTTP 数据获取、视锥体裁剪、LOD 选择和 GPU 渲染管线。 ### libge/ — C++ Windows DLL 项目的早期 C++ 原型实现，提供 Google Earth 数据访问的 Windows DLL 封装。功能已被 Go 版本替代。 ### dbroot/ — Google Earth 数据库根数据 包含 Google Earth 的 dbRoot 数据文件（`earth1036.dat` + `earth1036.key`），用于协议初始化和数据解密。 ### test/ — 测试数据 包含多个测试数据集（喜马拉雅、珠穆朗玛峰等区域），用于验证地形解码、GLB 生成和 tileset 构建的正确性。 ## 数据流 Google Earth Server │ ├─── rt/ REST API ──── crawler/client ──── handler/api ──── HTTP JSON API │ │ │ └─── handler/tileset ──── 3D Tiles (tileset.json + GLB) │ └─── flatfile ──── cmd/crawler_flatfile ──── GLB 文件 + tileset.json │ └─── cmd/tileset_gen ──── tileset.json（从已有 GLB） ### 核心工作流 1. **认证** → `gelib.GeAuth()` 获取 Session ID 2. **初始化** → `gelib.GeDbRoot()` 获取数据库根配置和加密密钥 3. **元数据** → `crawler.FetchPlanetoidMetadata()` / `FetchBulkMetadata()` 获取节点树 4. **数据获取** → `crawler.FetchNodeData()` 或 flatfile 下载地形+影像 5. **解密** → `gelib.GeCrypted.JieBao()` 解密 Google Earth 加密数据 6. **解码** → `gelib.DecodeTerrain()` 解码地形网格 7. **纹理** → `core/rocktree` 解码 CRN/DXT1 纹理 → RGB 8. **输出** → `WriteNamedTexturedGLB()` 生成标准 GLB 文件 9. **组织** → 构建 3D Tiles tileset.json（含 LOD、边界盒、子 tileset 分割） ## 快速开始 ### 前置要求 - Go 1.26+ - 可选：SDL2、Eigen3（C++ 客户端） ### 启动服务 # 启动 HTTP 服务 go run ./cmd/server # 访问 API curl http://localhost:8080/api/planetoid curl "http://localhost:8080/api/bulk?path=020" curl "http://localhost:8080/api/nodedata?path=020&epoch=12345" ### 离线爬取 # 爬取喜马拉雅区域地形数据 go run ./cmd/crawler_flatfile -key 020121132332 -max-level 6 -out ./tiles # 从已有 GLB 生成 tileset.json go run ./cmd/tileset_gen -dir ./tiles -out tileset.json ### 3D Tiles 桥接 启动服务后，在 CesiumJS 中加载： const tileset = await Cesium.Cesium3DTileset.fromUrl( 'http://localhost:8080/tiles/tileset.json' ); ## 开发规范 详见 [DEVELOPMENT.md](./DEVELOPMENT.md)，包含： - Go Workspace 多模块管理 - 编码规范（命名、文件组织、错误处理） - 测试规范（表驱动测试、覆盖率、竞态检测） - Git 提交规范（Conventional Commits） - 分支策略 - 代码质量门禁 ## 技术栈 | 技术 | 用途 | |------|------| | Go 1.26 | 主要开发语言 | | Protocol Buffers | Google Earth 数据序列化 | | 3D Tiles 1.1 | 3D 瓦片标准格式 | | GLB (glTF Binary) | 3D 模型格式 | | Web Mercator | 瓦片投影坐标系 | | CRN / DXT1 | Google Earth 纹理压缩格式 | | C++ / SDL2 / OpenGL | 原生 3D 渲染客户端 | | Emscripten / WebAssembly | 浏览器端 3D 渲染 |

标签：3D Tiles, AI工具, CesiumJS, Go, Google Earth, Ruby工具, 云资产清单, 地理信息系统, 客户端加密, 数据爬虫, 日志审计, 逆向工程