# dji_way_line

**Repository Path**: volara/dji_way_line

## Basic Information

- **Project Name**: dji_way_line
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 11
- **Forks**: 5
- **Created**: 2025-12-25
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DJI 航线生成器 (DJI Waypoint KMZ Generator)

一个基于 Vue 3 + CesiumJS 的 DJI 无人机航线规划工具，支持生成符合 WPML 1.0.6 标准的 KMZ 航线文件，可直接导入大疆司空 2 (DJI FlightHub 2) 和 Matrice 系列无人机。

![License](https://img.shields.io/badge/license-GPL--3.0-blue.svg)
![Vue](https://img.shields.io/badge/Vue-3.5-brightgreen.svg)
![Cesium](https://img.shields.io/badge/Cesium-1.135-blue.svg)

[English](./README_EN.md) | [简体中文](./README.md)

� **仓库地址**：[GitHub](https://github.com/hecongyuan/dji_way_line) | [Gitee](https://gitee.com/hecongyuan/dji_way_line)

## ⭐ Star 历史

[![Star History Chart](https://api.star-history.com/svg?repos=hecongyuan/dji_way_line&type=Date)](https://star-history.com/#hecongyuan/dji_way_line&Date)

## 🎨 界面预览

### 主界面
![主界面](doc/images/main_interface.png)
- 左侧：航线库面板，显示已创建的航线列表
- 右侧：3D 地图视图（基于高德地图+Cesium）
- 底部：坐标信息和系统状态显示
- 右上角：地图控制工具栏

### 创建航线
![创建航线](doc/images/create_mission.png)
- 当前支持航线类型：巡逻航线、面状航线（更多类型开发中）
- 选择飞行器型号（Matrice 3/4 系列）
- 选择挂载设备（Matrice 4E/4T）
- 自定义航线名称

### 航线编辑
![航线编辑](doc/images/route_editor.png)
- 实时显示航线统计（距离、时长、面积）
- 任务配置面板（飞行参数、高度模式）
- 地图上可视化航线路径和航点
- 一键生成/导入 KMZ 文件


## 📅 开发计划 (Roadmap)

- ✅ **巡逻航线生成、跟司空2兼容**
- ✅ **m4t 真机测试**：在实际环境中验证 Matrice 4T 的飞行和 摄影功能。

> 💼 **如需商业版，请联系作者**（微信：`hecongyuan2026`）
> 
> ![商业版航点航线截图](doc/images/9B3EA1D0BE249C3D52B4FF9B09E604BE.png)

## ✨ 核心功能

### 🗺️ 航线规划
- **可视化地图编辑**：基于高德地图 + CesiumJS 的 3D 地图界面
- **当前支持航线类型**：
  - **巡逻航线**：在地图上添加航点，支持循环或单程巡逻任务
  - **面状航线**：绘制区域自动生成 S 形扫描路径，支持 AI 目标识别
  - 更多航线类型（航点、带状、斜面、几何体等）正在开发中
- **实时预览**：航线路径实时显示，支持闭合航线和单程航线
- **坐标系转换**：自动转换 GCJ-02（高德）和 WGS84（GPS）坐标系

### 🤖 面状航线 AI 扫描 (Matrice 4T)
- **智能扫描路径生成**：自动生成 S 形扫描路径
- **目标识别配置**：支持人、车、船三种目标类型
- **参数可调**：
  - 扫描间距（5-200m）
  - 航线方向（0-359°）
  - 边界内缩（0-50m）
  - 云台俯仰角（-90° ~ 30°）
- **重叠率设置**：航向重叠 80%，旁向重叠 70%

### 📐 高度模式
- **海拔高度 (WGS84)**：绝对海拔高度，基于 WGS84 椭球
- **相对起飞点高度**：相对于起飞点的高度
- **相对地形高度 (实时仿地)**：实时跟随地形起伏，保持相对地面高度恒定

### 🎯 任务配置
- **飞行参数**：速度、高度、起飞安全高度
- **失控动作**：返航、悬停、降落、继续执行
- **完成动作**：返航、降落、悬停、返回首航点
- **爬升模式**：垂直爬升、倾斜爬升

### 📦 KMZ 导入导出
- **导出 KMZ**：生成符合 WPML 1.0.6 标准的 KMZ 文件
- **导入 KMZ**：解析现有 KMZ 文件，恢复航线和配置
- **兼容性**：完全兼容大疆司空 2 和 Matrice 系列无人机

## 🚀 快速开始

### 环境要求
- Node.js >= 20.x
- pnpm >= 10.x (推荐) 或 npm

### 安装依赖
```bash
# 使用 pnpm (推荐)
pnpm install

# 或使用 npm
npm install
```

### 开发运行
```bash
# 启动开发服务器
pnpm dev

# 或
npm run dev
```

访问 `http://localhost:5173` 即可使用。

### 生产构建
```bash
# 构建生产版本
pnpm build

# 或
npm run build
```

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

## 📖 使用指南

### 1. 绘制航线

#### 巡逻航线
1. 选择“巡逻航线”类型
2. 在地图上点击添加巡逻航点
3. 设置航点参数（速度、高度、云台角度）
4. 支持循环巡逻和单程巡逻

#### 面状航线（AI 扫描）
1. 选择“面状航线”类型
2. 在地图上绘制扫描区域（至少 3 个点）
3. 系统自动生成 S 形扫描路径
4. 调整扫描参数（间距、方向、边距）
5. 选择 AI 识别目标（人、车、船） - 仅 Matrice 4T 支持

### 2. 配置参数

#### 基础参数
- **飞行速度**：1-15 m/s，推荐 10 m/s
- **飞行高度**：20-500 m，推荐 60 m
- **起飞安全高度**：10-200 m，推荐 20 m

#### 高度模式选择
- **海拔高度**：适用于地形平坦区域
- **相对起飞点**：适用于起飞点和目标区域高度相近的场景
- **实时仿地**：适用于山地、丘陵等地形起伏较大的区域

### 3. 生成 KMZ

1. 点击 **生成 KMZ** 按钮
2. 文件自动下载（`mission.kmz`）
3. 导入大疆司空 2 或无人机遥控器

### 4. 导入 KMZ

1. 点击 **导入 KMZ** 按钮
2. 选择已有的 KMZ 文件
3. 系统自动解析并恢复航线和配置

## 🛠️ 技术栈

### 前端框架
- **Vue 3.5**：渐进式 JavaScript 框架
- **Vite 5.4**：下一代前端构建工具

### 地图引擎
- **CesiumJS 1.135**：3D 地球和地图引擎
- **Vue-Cesium 3.2**：CesiumJS 的 Vue 3 封装
- **高德地图**：底图服务（GCJ-02 坐标系）

### 核心库
- **JSZip 3.10**：KMZ 文件压缩/解压
- **UUID**：生成唯一标识符（自定义实现）

## 📁 项目结构

```
way_line/
├── src/
│   ├── components/
│   │   └── WaypointGenerator/
│   │       ├── index.vue              # 主组件
│   │       ├── MapViewer.vue          # 地图视图
│   │       ├── ControlPanel.vue       # 控制面板
│   │       ├── MissionConfig.vue      # 任务配置
│   │       └── WaypointList.vue       # 航点列表
│   ├── utils/
│   │   ├── kmzGenerator.js            # KMZ 生成器
│   │   ├── kmzParser.js               # KMZ 解析器
│   │   ├── routePlanner.js            # 路径规划算法
│   │   ├── coordTransform.js          # 坐标转换 (GCJ-02 ↔ WGS84)
│   │   └── geoUtils.js                # 地理计算工具
│   ├── App.vue                        # 应用根组件
│   └── main.js                        # 应用入口
├── public/                            # 静态资源
├── package.json                       # 项目配置
├── vite.config.js                     # Vite 配置
└── README.md                          # 项目文档
```

## 🔧 核心算法

### 坐标转换
项目实现了 GCJ-02（火星坐标系）和 WGS84（GPS 坐标系）之间的相互转换：

- **存储**：使用 GCJ-02 坐标（与高德地图一致）
- **显示**：直接使用 GCJ-02 坐标（无偏移）
- **导出**：转换为 WGS84 坐标（大疆标准）

这确保了：
- ✅ 前端点击位置和显示位置完全一致
- ✅ 导入大疆后位置准确无偏移

### S 形扫描路径生成
基于多边形区域自动生成 S 形扫描路径：

1. **坐标投影**：将经纬度转换为平面坐标（米）
2. **多边形收缩**：根据边距参数向内收缩
3. **坐标旋转**：根据方向角旋转坐标系
4. **扫描线生成**：在旋转后的坐标系中生成水平扫描线
5. **交点计算**：计算扫描线与多边形的交点
6. **路径优化**：S 形连接，减少转弯次数
7. **反向旋转**：转换回原坐标系
8. **坐标还原**：转换回经纬度

### 距离和时间计算
使用 **Haversine 公式**计算航点间的大圆距离：

```javascript
const R = 6371000; // 地球半径（米）
const φ1 = lat1 * π / 180;
const φ2 = lat2 * π / 180;
const Δφ = (lat2 - lat1) * π / 180;
const Δλ = (lng2 - lng1) * π / 180;

const a = sin²(Δφ/2) + cos(φ1) · cos(φ2) · sin²(Δλ/2);
const c = 2 · atan2(√a, √(1−a));
const d = R · c;
```


## 📝 KMZ 文件结构

生成的 KMZ 文件符合 DJI WPML 1.0.6 标准：

```
mission.kmz
└── wpmz/
    ├── template.kml       # 模板定义（区域、参数）
    └── waylines.wpml      # 航线定义（航点、动作）
```

### template.kml
- 任务配置（速度、高度模式、失控动作等）
- 区域定义（多边形坐标）
- AI 巡逻参数（方向、边距、重叠率、目标类型）
- 云台和相机参数

### waylines.wpml
- 航点列表（坐标、高度、速度）
- 航点动作（云台角度、拍照、录像）
- AI 目标检测动作
- 航线统计（距离、时间）

## ⚠️ 注意事项

### 坐标系统
- 前端地图使用 **GCJ-02**（高德地图）
- 导出 KMZ 使用 **WGS84**（GPS 标准）
- 系统自动处理转换，无需手动操作

### 高度设置
- **海拔高度**：需要知道区域的实际海拔
- **相对起飞点**：适用于大部分场景
- **实时仿地**：需要无人机支持实时测距传感器

### AI 巡逻
- 仅支持 **Matrice 4T** 及以上型号
- 需要在大疆司空 2 中启用 AI 功能
- 扫描间距建议 10-50m，根据目标大小调整

### 文件兼容性
- 生成的 KMZ 文件符合 **WPML 1.0.6** 标准
- 兼容大疆司空 2 和 Matrice 系列无人机
- 建议在导入前备份原有航线

## 🐛 常见问题

### Q: 导入大疆后位置偏移？
A: 已通过坐标转换解决。如果仍有偏移，请检查：
- 地图底图是否为高德地图
- 是否在中国境内（坐标转换仅在中国有效）

### Q: AI 巡逻航线显示为虚线？
A: 虚线表示模板，实线表示确定航线。已添加 `distance` 和 `duration` 参数，应显示为实线。

### Q: 扫描路径方向不对？
A: 调整 **航线方向角度**：
- 0° = 南北向（垂直）
- 90° = 东西向（水平）

### Q: 生成的航线点数太多？
A: 减小扫描间距或增大重叠率会增加航点数。建议：
- 扫描间距：20-50m
- 重叠率：保持默认 80%/70%

## 📄 许可证

本项目采用 **GPL-3.0 许可证** (GNU General Public License v3.0)。

### 主要条款

- ✅ **商业使用**：允许商业使用
- ✅ **修改**：允许修改源代码
- ✅ **分发**：允许分发原始或修改后的版本
- ✅ **专利授权**：提供明确的专利授权
- ✅ **私人使用**：允许私人使用和修改

### 限制条件

- ⚠️ **相同许可证**：修改后的衍生作品必须使用相同的 GPL-3.0 许可证
- ⚠️ **开源要求**：分发时必须提供完整的源代码
- ⚠️ **版权声明**：必须保留原作者的版权声明和许可证信息
- ⚠️ **状态变更说明**：修改文件时必须注明修改内容

### 为什么选择 GPL-3.0？

1. **保护开源生态**：确保衍生作品也保持开源，防止闭源商用
2. **专利保护**：GPL-3.0 提供了明确的专利授权，保护用户免受专利诉讼
3. **促进共享**：鼓励开发者共享改进，共同推动项目发展
4. **DRM 限制**：禁止使用 DRM（数字版权管理）限制用户权利

详细许可证内容请查看 [LICENSE](./LICENSE) 文件。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📧 联系方式

- **作者微信**：`hecongyuan2026`
- **Email**：`h285121973@gmail.com`
- **问题反馈**：通过 GitHub Issues 提交

**扫码加作者微信进入社群，备注 `dji_way_line`**

<img src="doc/images/wechat_qr.jpg" width="200" alt="微信二维码">

## 👥 社区交流群

欢迎加入 DJI 航线生成器社区交流群，与其他开发者和用户交流使用经验、分享航线规划技巧、获取最新功能更新！

<img src="doc/images/sq.jpg" width="300" alt="社区交流群二维码">