# turfjs-cesium-three

**Repository Path**: YAY-404/turfjs-vue3-demo

## Basic Information

- **Project Name**: turfjs-cesium-three
- **Description**: 面向前端开发工程师（尤其是GIS相关方向），以Vue3技术栈为载体，结合Turfjs的核心地理空间分析能力，打造“理论+实战+可复用代码”的系列教程
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://blog.csdn.net/m0_72065108/article/details/155226062
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-11-27
- **Last Updated**: 2026-01-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Turf.js + Vue 3 + Cesium.js + Three.js Demo

一个基于 Vue 3 + Vite 的地理空间演示项目，集成 Turf.js 进行几何构建与空间计算，并用 Leaflet、Cesium.js 与 Three.js 在二维地图与三维场景中渲染结果，并配合 ECharts 进行数据可视化。界面使用 Element Plus 实现友好的表单与布局。

## 功能概览

本项目包含以下核心 GIS 功能模块：

1.  **地理要素编辑器 (GeoFeatureEditor)**

    -   点/线/面要素的创建与编辑
    -   GeoJSON 与 WKT 格式互转
    -   基础属性计算：长度、面积、包围盒（BBox）、质心
    -   要素集合管理与可视化

2.  **路线长度分析 (RouteLengthAnalyzer)**

    -   多点路线距离统计
    -   支持单位切换（千米/英里）
    -   实时计算路线总长度

3.  **地理围栏生成 (GeoFenceGenerator)**

    -   基于点/线/面的缓冲区（Buffer）生成
    -   支持自定义缓冲半径与单位
    -   原始要素与缓冲区的叠加展示

4.  **空间关系校验 (SpatialRelationValidator)**

    -   **点在面内判断**：判断坐标点是否在指定区域内
    -   **路径相交分析**：判断路径是否穿越区域或在区域内
    -   **邻近要素查询**：查找距离目标点最近的 POI（如最近骑手）

5.  **地理数据处理 (GeoDataProcessor)**

    -   **裁剪 (Crop)**：基于 BBox 区域裁剪线/面要素
    -   **合并 (Union)**：多面要素合并为单一要素
    -   **简化 (Simplify)**：抽稀坐标点，降低数据复杂度（支持精度控制）

6.  **坐标转换与投影 (CoordinateTransform)**

    -   **多坐标系互转**：支持 WGS84（GPS）、GCJ02（高德/腾讯）、BD09（百度）三种常见坐标系的互相转换
    -   **批量处理**：基于 Turf.js 遍历 GeoJSON，实现数据的批量坐标系变换
    -   **应用场景**：解决 WebGIS 开发中不同地图源导致的坐标偏移问题

7.  **三维地理围栏展示 (ThreeDGeoFence)**

    -   使用 Turf.js 生成的缓冲区结果在 Cesium 三维地球上实时渲染
    -   支持滑块动态调整半径、相机飞行定位到目标区域
    -   适用于城市/园区范围展示、空间管控可视化

8.  **辅助工具**

    -   两点距离计算器 (TurfDistanceCalculator)

9.  **空间数据可视化 (SpaceAnalysisCharts)**

    -   区域面积对比柱状图（基于 Turf.js 面积计算）
    -   路线长度统计柱状图（基于 Turf.js 线长度计算）
    -   简易栅格热力图（随机点集聚合展示）

10. **空间数据三维建模 (TurfThreeModeler)**

    -   基于面要素（GeoJSON 坐标）生成可挤出的三维地形
    -   顶面按空间距离着色：支持「质心距离」与「路径距离」两种模式
    -   基于线要素生成三维管道路径（Catmull-Rom 曲线拟合）
    -   提供高度、半径等参数控制，支持交互式清空与重建

## 大数据要素分析（BigDataFeatureAnalyzer）

-   组件位置：`src/components/BigDataFeatureAnalyzer.vue`
-   Worker 脚本：`src/workers/big-data-worker.js`
-   功能概述：
    -   生成海量随机坐标点数据（默认 10 万级）
    -   使用 Web Worker 分片执行空间包含分析（`pointsWithinPolygon`）
    -   进度与命中统计实时上报，避免阻塞主线程
    -   地图采样预览（以比例控制渲染负载）
-   参数说明：
    -   `pointsCount`：数据量（1000 ～ 300000）
    -   `chunkSize`：分片大小（1000 ～ 50000），影响 Worker 每次处理的数量
    -   `sampleRatio`：地图采样比例（0.001 ～ 1），控制预览点渲染数量
-   操作流程：
    -   点击「生成数据」生成随机点集并按比例预览到地图
    -   点击「开始分析」启动 Worker 分片处理，观察进度与命中数
    -   支持「中止分析」「清空」恢复初始状态
    -   可编辑目标区域坐标（GeoJSON 外环）并应用到地图
-   性能优化要点：
    -   使用 `requestAnimationFrame` 批次绘制采样点，避免一次性渲染过多
    -   主线程仅进行 UI 状态更新，计算逻辑在 Worker 内执行
    -   分片大小根据数据规模调优，兼顾 IPC 开销与计算吞吐
-   常见问题：
    -   采样渲染卡顿：降低 `sampleRatio` 或提高地图层批次阈值
    -   分片过小导致通信频繁：适当增大 `chunkSize`
    -   Worker 初始化异常：确认构建工具支持模块 Worker（Vite 默认支持）

## 综合实战：基于 Turfjs 的智慧园区空间管理系统

-   页面入口：`/park`（默认路由跳转）
-   组件位置：`src/components/ParkSpaceManagement.vue`
-   核心内容：
    -   需求分析与架构设计（路由视图、Pinia 状态、API 适配层）
    -   核心功能实现：区域管理、路径规划（基于步行网络最短路）、资源定位（最近邻）
    -   系统部署与优化：路由懒加载、GET 请求缓存、超时与重试、Cesium Token 管理
-   技术要点：
    -   Vue3 路由管理（`src/router/index.js`）
    -   Pinia 状态管理（`src/stores/park.js`）
    -   Turf.js 多 API 协同（buffer/centroid/distance 等）
    -   Cesium 集成（三维场景中渲染 Polygon/Polyline/Point/Label）

## 技术栈

-   **Vue 3 + Vite**
-   **Element Plus**（UI 组件库）
-   **Turf.js**（地理空间分析核心库）
-   **Leaflet**（轻量级 Web 地图渲染）
-   **Cesium + vite-plugin-cesium**（三维地球渲染与打包集成）
-   **Three.js**（WebGL 三维渲染）
-   **coordtransform**（坐标转换算法库）
-   **Less**（样式预处理）

## 环境要求

-   Node.js 18+（建议使用最新稳定版）
-   推荐包管理器：pnpm（也可使用 npm）
-   操作系统：Windows/macOS/Linux 均可

## 快速开始

### 安装依赖

```bash
npm install
# 或 pnpm install
```

### 启动项目

```bash
npm run dev
```

启动后访问本地地址（通常为 `http://localhost:5173/`）。

### 构建与预览

```bash
npm run build
npm run preview
```

预览默认在 `http://localhost:4173/`（Vite Preview）。

## 环境变量

本项目使用 Vite，环境变量需以 `VITE_` 前缀暴露到客户端。为避免在代码中硬编码敏感信息（如 Cesium Ion Token），请按以下步骤配置：

1. 在项目根目录创建 `.env.local`（已通过 `.gitignore` 的 `*.local` 规则忽略，不会提交到 Git）
2. 写入以下变量（将占位符替换为你的实际 Token）：

```bash
VITE_CESIUM_ION_TOKEN=REPLACE_WITH_YOUR_ION_TOKEN
```

3. 运行开发或预览构建时，组件会读取该变量（示例位置：ThreeDGeoFence）：

```js
const ION_TOKEN = import.meta.env.VITE_CESIUM_ION_TOKEN;
if (ION_TOKEN) {
    Cesium.Ion.defaultAccessToken = ION_TOKEN;
}
```

可选：根据环境拆分到 `.env.development` / `.env.production`，但请确保私密 Token 不被提交仓库，生产环境建议通过部署平台的环境变量注入。

### 后端接口 Base URL（可选）

-   通过 `VITE_API_BASE` 配置后端服务地址，默认值为 `/api`
-   新建或编辑 `.env.local`，例如：

```bash
VITE_API_BASE=https://your-api.example.com
```

接口约定（示例）：

-   `GET /areas`、`POST /areas`、`PUT /areas/:id`、`DELETE /areas/:id`
-   `GET /walkways`（步行网络 FeatureCollection）
-   `GET /resources`、`PUT /resources/:id`

## 目录结构

-   `src/App.vue`：应用主入口（路由视图），默认跳转到 `/park`
-   `src/router/index.js`：路由配置（含园区系统入口）
-   `src/stores/park.js`：园区状态（区域/资源/步行网络/最短路规划）
-   `src/api/client.js`：后端接口适配层（超时/重试/GET 缓存）
-   `src/components/`
    -   `GeoFeatureEditor.vue`：地理要素编辑与格式转换
    -   `RouteLengthAnalyzer.vue`：路线长度计算
    -   `GeoFenceGenerator.vue`：地理围栏与缓冲区分析
    -   `SpatialRelationValidator.vue`：空间关系校验（包含/相交/邻近）
    -   `GeoDataProcessor.vue`：地理数据处理（裁剪/合并/简化）
    -   `CoordinateTransform.vue`：坐标转换与投影工具
    -   `TurfDistanceCalculator.vue`：基础两点测距工具
    -   `SpaceAnalysisCharts.vue`：空间数据可视化
    -   `ThreeDGeoFence.vue`：三维地球上展示缓冲区与定位交互
    -   `TurfThreeModeler.vue`：三维建模演示（Turf.js + Three.js）
    -   `BigDataFeatureAnalyzer.vue`：大数据特征分析（点/线/面数量统计）
    -   `ParkSpaceManagement.vue`：综合实战（园区空间管理系统）

> 应用默认通过路由跳转到 `/park`，其他演示模块仍可保留并按需接入到路由或独立页面。

## 参考资料

-   **CSDN 博客专栏**：[Turfjs 示例教程专栏计划（Vue3+实战导向）](https://blog.csdn.net/m0_72065108/article/details/155226062)
    -   该项目配套的详细教程与设计思路解析。

## 组件对应文章索引

-   GeoFeatureEditor：已发布（地理要素编辑与格式转换）→ [链接](https://blog.csdn.net/m0_72065108/article/details/155314287)
-   RouteLengthAnalyzer：已发布（路线长度计算）→ [链接](https://blog.csdn.net/m0_72065108/article/details/155496998)
-   GeoFenceGenerator：已发布（地理围栏与缓冲区分析）→ [链接](https://blog.csdn.net/m0_72065108/article/details/155565382)
-   SpatialRelationValidator：已发布（空间关系校验（包含/相交/邻近））→ [链接](https://blog.csdn.net/m0_72065108/article/details/156271870)
-   GeoDataProcessor：已发布（地理数据处理（裁剪/合并/简化））→ [链接](https://blog.csdn.net/m0_72065108/article/details/156273531)
-   CoordinateTransform：已发布（坐标转换与投影工具）→ [链接](https://blog.csdn.net/m0_72065108/article/details/156308048)
-   TurfDistanceCalculator：已发布（基础两点测距工具）→ [链接](https://blog.csdn.net/m0_72065108/article/details/155308485)
-   ThreeDGeoFence：已发布（三维地球上展示缓冲区与定位交互）→ [链接](https://blog.csdn.net/m0_72065108/article/details/156385426)
-   SpaceAnalysisCharts：已发布（空间数据可视化）→ [链接](https://blog.csdn.net/m0_72065108/article/details/156386252)
-   TurfThreeModeler：待补充（三维建模演示（Turf.js + Three.js））
-   BigDataFeatureAnalyzer：待补充（大数据特征分析（点/线/面数量统计））
-   ParkSpaceManagement：待补充（综合实战（园区空间管理系统））

## 许可证

本项目采用 Apache-2.0 许可证，详见 `LICENSE`。