5.2 KiB

Raw Blame History

SUMMIT - 全球 14 座 8000 米级雪山 3D 可视化平台

1. 项目概述 (Project Overview)

本项目旨在构建一个完全免费、零商业依赖、高性能的 Web 3D 地球可视化平台，专注于展示全球 14 座 8000 米级雪山。项目采用 "硬核极客" 路线，核心理念是 Data Autonomy (数据自主)：直接从 NASA 获取原始地形数据，自行构建数据生产流水线，结合 PostgreSQL + Redis 多级缓存架构，提供极致的性能体验。前端使用开源的 MapLibre GL JS 结合 Three.js 进行高保真渲染。

2. 系统架构 (System Architecture)

系统采用经典的前后端分离架构，辅以离线数据处理流水线。

2.1 顶层设计

Frontend (Web): SPA 单页应用，负责 3D 地图交互、渲染与漫游控制。通过 Proxy (代理) 访问后端 API 和静态资源。
Backend (API): 提供 RESTful API，负责元数据查询、路线数据分发、用户系统等。同时作为一个静态文件服务器，托管地形瓦片。
Data Pipeline (Offline): 负责将 NASA 原始数据 (GeoTIFF) 处理为 Web 可用的地形瓦片 (Terrain-RGB)。
Database & Cache: PostgreSQL 存储核心结构化数据，Redis 提供热点数据高速缓存。

3. 技术栈 (Tech Stack)

3.1 前端 (Frontend)

Framework: React 18 + TypeScript + Vite
Map Engine: MapLibre GL JS (Mapbox 开源分支，负责地图瓦片调度与底图渲染)
3D Engine: Three.js (负责渲染攀登路线、营地、光效、粒子系统)
UI Library: TailwindCSS + Lucide Icons
State Management: Zustand / React Context

3.2 后端 (Backend)

Framework: Python 3.11+ (FastAPI)
Server: Uvicorn (ASGI)
ORM: SQLAlchemy (Async) / Tortoise ORM
Geo Processing: GDAL / Rasterio (用于后端动态分析地形)

3.3 数据存储与缓存 (Storage & Caching)

Primary DB: PostgreSQL 15+ (with PostGIS extension)
- 存储山峰元数据、GeoJSON 路线、用户数据。
Cache: Redis 7+
- Layer 1: API 响应缓存 (Response Cache)。
- Layer 2: 高频地理空间查询缓存 (Spatial Cache)。
- Layer 3: 瓦片元数据缓存 (如果自建瓦片服务)。

3.4 数据流水线 (Data Pipeline)

Source: NASA SRTM (30m DEM), Esri World Imagery.
Tools: GDAL (gdal_translate, gdalwarp), rio-rgbify, gdal2tiles.
Output: Mapbox Terrain-RGB compatible tiles (.png / .webp)，输出至 backend/upload。

4. 核心功能模块 (Core Modules)

4.1 数据生产流水线 (The Pipeline)

自动化脚本集，负责从 NASA 下载数据并处理。

Ingest: 下载 SRTM GeoTIFF。
Process: 重投影 (EPSG:4326 -> EPSG:3857) -> 拼接 (Merge) -> 编码 (RGBify)。
Tile: 切片生成 Z10-Z14 瓦片金字塔。
Export: 将产物存入 backend/upload/tiles。

4.2 3D 可视化引擎 (Visualization Engine)

地形渲染: 加载自定义 Terrain-RGB 瓦片，实现真实地形起伏。
混合渲染: MapLibre 负责底图与地形，Three.js 自定义图层负责覆盖物 (Routes, Camps)。
光照模拟: 基于太阳位置算法 (SunCalc) 的实时光照与阴影。

4.3 后端服务与缓存 (Backend & Cache)

Peaks API: 提供 14 座山峰的详细信息 (高度、位置、首登记录)。
- Cache Strategy: 永久缓存 (除非数据更正)，Redis Key: peak:{id}:info.
Routes API: 提供 GPX/GeoJSON 格式的攀登路线。
- Cache Strategy: LRU 缓存，Redis Key: route:{id}:geojson.
Elevation API: (可选) 后端直接查询 GeoTIFF 返回特定坐标高度。

5. 项目目录结构 (Directory Structure)

summit/
├── .github/                # CI/CD workflows
├── backend/                # FastAPI Application
│   ├── app/
│   │   ├── api/            # Routes
│   │   ├── core/           # Config, Database connection
│   │   ├── models/         # SQLAlchemy Models
│   │   └── services/       # Business Logic
│   ├── upload/             # [NEW] Static Resources Root
│   │   ├── tiles/          # Generated Terrain-RGB Tiles ({z}/{x}/{y}.png)
│   │   └── shapes/         # Route GeoJSONs / GPX files
│   └── tests/
├── data/                   # Data Processing Workspace (Offline)
│   ├── raw/                # NASA GeoTIFFs (Source)
│   └── scripts/            # Python/Shell processing scripts (GDAL)
├── frontend/               # React Application
│   ├── src/
│   │   ├── components/     # UI Components
│   │   ├── map/            # MapLibre & Three.js logic
│   │   └── store/          # State Management
│   ├── public/             # Static Assets (Favicon, etc.)
│   └── vite.config.ts      # Proxy Configuration
├── CONFIG.md               # [NEW] Configuration Guide (Env, DB, Redis)
├── DATABASE.md             # Database Design
├── PROJECT.md              # Project Documentation
└── ROADMAP.md              # Roadmap

5.2 KiB Raw Blame History Unescape Escape