MapMap - 3D Earth Globe

一个基于 Three.js 和 React + TypeScript 的交互式 3D 地球应用，支持真实地图纹理和地理边界数据可视化。

特性

• ✨ 使用 React Three Fiber 构建的 3D 地球
• 🌍 真实地图纹理渲染
• 🗺️ SHP 文件支持 - 加载和渲染地理边界数据
• 📊 图层控制系统 - 动态显示/隐藏不同边界线
• 🖱️ 完整的鼠标交互支持
  • 左键拖动：旋转地球
  • 滚轮：缩放视图
• 🎨 现代化的 UI 设计
• 🌟 高质量地球纹理

技术栈

• React 18 - UI 框架
• TypeScript - 类型安全
• Vite - 快速构建工具
• Three.js - 3D 图形库
• @react-three/fiber - React 的 Three.js 渲染器
• @react-three/drei - Three.js 辅助组件库
• shpjs - Shapefile 解析库

快速开始

安装依赖

npm install

启动开发服务器

npm run dev

应用将在 http://localhost:5173 启动。

构建生产版本

npm run build

构建产物将输出到 dist 目录。

预览生产构建

npm run preview

项目结构

mapmap/
├── src/
│   ├── components/
│   │   ├── Globe.tsx           # 3D 地球组件（支持纹理贴图）
│   │   ├── BoundaryLayer.tsx   # 边界线图层组件
│   │   ├── LayerControl.tsx    # 图层控制面板
│   │   └── LayerControl.css    # 图层控制样式
│   ├── utils/
│   │   └── geoUtils.ts         # 地理数据工具函数
│   ├── types/
│   │   └── shpjs.d.ts          # shpjs 类型声明
│   ├── App.tsx                 # 主应用组件
│   ├── App.css                 # 应用样式
│   ├── main.tsx                # 应用入口
│   └── index.css               # 全局样式
├── public/
│   ├── earth_hq.jpg            # 高质量地球底图纹理
│   └── shapefiles/             # Shapefile 数据
├── 地图数据/                   # 原始地图数据
│   ├── 10m 争议/
│   ├── 10m 省州/
│   ├── 110m 国界/
│   └── tif1.png
├── index.html                  # HTML 模板
├── vite.config.ts              # Vite 配置
├── tsconfig.json               # TypeScript 配置
└── package.json                # 项目配置

已实现功能

• ✅ 加载和渲染高质量地球纹理
• ✅ 解析和渲染 SHP 文件边界数据（使用 ArrayBuffer 方式）
• ✅ 多图层管理系统
• ✅ 交互式图层控制面板
• ✅ 经纬度坐标到球面 3D 坐标转换
• ✅ 优化的纹理映射（避免极点撕裂）

未来计划

• 📍 添加更多图层（省州边界、争议地区等）
• 🎯 添加数据可视化功能（热力图、标记点等）
• 🔍 地点搜索和定位功能
• 📊 数据统计和分析工具

开发说明

组件说明

• Globe.tsx: 核心地球组件，使用 TextureLoader 加载地图纹理
• BoundaryLayer.tsx: 边界线图层组件，解析 SHP 文件并渲染为 3D 线条
• LayerControl.tsx: 图层控制面板，管理多个图层的显示状态
• App.tsx: 主应用组件，设置 Canvas、相机、灯光和控制器
• geoUtils.ts: 地理数据工具，包含 SHP 加载和坐标转换函数

添加新的边界线图层

在 src/App.tsx 中添加新图层配置：

const [layers, setLayers] = useState<LayerConfig[]>([
  {
    id: 'countries',
    name: '国界 (110m)',
    shpPath: '/shapefiles/ne_110m_admin_0_countries.shp',
    color: '#FFD700',
    visible: true,
  },
  // 添加新图层
  {
    id: 'provinces',
    name: '省州边界',
    shpPath: '/shapefiles/ne_10m_admin_1_states_provinces.shp',
    color: '#00CED1',
    visible: false,
  },
])

自定义地球纹理

替换 public/earth_hq.jpg 文件，或在 Globe.tsx 中修改纹理路径：

const texture = useLoader(TextureLoader, '/your-texture.jpg')

获取更高质量的地球纹理，请参考 TEXTURE_GUIDE.md。

License

MIT