104 lines
5.2 KiB
Markdown
104 lines
5.2 KiB
Markdown
# 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 下载数据并处理。
|
||
1. **Ingest:** 下载 SRTM GeoTIFF。
|
||
2. **Process:** 重投影 (EPSG:4326 -> EPSG:3857) -> 拼接 (Merge) -> 编码 (RGBify)。
|
||
3. **Tile:** 切片生成 Z10-Z14 瓦片金字塔。
|
||
4. **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)
|
||
|
||
```text
|
||
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
|
||
```
|