zhangyiss/dji_kmz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

update readme

Browse Source
This commit is contained in:
张壹
2026-07-09 17:21:03 +08:00
parent 895991ba98
commit 143ff39327
1 changed files with 368 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

392
README.md
View File

@@ -1,20 +1,84 @@
# DJI KMZ Generator
将Google Earth的KML文件或普通坐标文件转换为DJI航线文件(.kmz)
将 Google Earth 的 KML 文件或普通坐标文本文件转换为 DJI Pilot 2 可识别的航线文件（`.kmz`），遵循 DJI WPML（Waypoint Markup Language）协议标准。
## 目录
- [工作原理](#工作原理)
- [功能特性](#功能特性)
- [依赖项](#依赖项)
- [构建说明](#构建说明)
- [使用方法](#使用方法)
- [配置文件详解](#配置文件详解)
- [全局配置](#1-全局配置)
- [任务配置 `[missionConfig]`](#2-任务配置-missionconfig)
- [航线配置 `[wayline]`](#3-航线配置-wayline)
- [航点配置 `[wayline.waylineCoordinateSysParam]`](#4-坐标系参数-waylinewaylinecoordinatesysparam)
- [航向参数 `[wayline.globalWaypointHeadingParam]`](#5-全局航向参数-waylineglobalwaypointheadingparam)
- [航点配置 `[placemark]`](#6-航点配置-placemark)
- [输入文件格式](#输入文件格式)
- [KML 文件（Google Earth）](#kml-文件推荐)
- [纯文本坐标文件](#纯文本坐标文件)
- [输出文件结构](#输出文件结构)
- [无人机型号支持列表](#无人机型号支持列表)
- [常见问题](#常见问题)
- [许可证](#许可证)
- [作者](#作者)
---
## 工作原理
```
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
│ config.toml │───▶│ │ │ │
│ (航线参数) │ │ dji_kmz │────▶ output.kmz │
├─────────────┤ │ (C++17) │ │ (DJI Pilot 2 │
│ points.kml │───▶│ │ │ 航线文件) │
│ 或 points.txt │ │ │ │ │
└─────────────┘ └──────────────┘ └─────────────────┘
```
程序执行流程：
1. 读取 TOML 格式的配置文件（[`example/config.toml`](example/config.toml)），解析无人机型号、飞行参数、航点文件路径等
2. 读取航点坐标文件：
- **KML 文件**：解析 Google Earth 导出的路径（`<LineString>`）或多边形（`<Polygon>`）坐标（参见 [`src/simple_kml.hpp`](src/simple_kml.hpp)）
- **文本文件**：按行解析经度、纬度、高度
3. 生成符合 **DJI WPML 1.0.5** 规范的 `template.kml`（参见 [`src/dji_kmz.cpp:374-423`](src/dji_kmz.cpp:374)）
4. 将 `template.kml` 压缩为 `.kmz` 格式（[`src/dji_kmz.cpp:427`](src/dji_kmz.cpp:427)）
---
## 功能特性
- 支持Google Earth导出的KML文件
- 支持自定义坐标文本文件
- 生成符合DJI Pilot规范的航线文件
- 通过TOML配置文件定义航线参数
- ✅ 支持 Google Earth 导出的 KML 文件（`<LineString>` 路径和 `<Polygon>` 多边形）
- ✅ 支持自定义纯文本坐标文件
- ✅ 支持 12 种大疆无人机型号（Matrice 系列、Mavic 3 系列等）
- ✅ 支持多种飞行模式配置（航点、二维航测、三维航测、带状航测）
- ✅ 支持多种高度模式（相对起飞点、EGM96 海拔、地面高度、实时地形跟随）
- ✅ 支持多种航向模式（跟随航线、手动控制、固定角度、平滑过渡、朝向 POI）
- ✅ 支持多种失联动作（继续执行、返航、降落、悬停）
- ✅ 通过 TOML 配置文件定义所有航线参数，无需手动编辑 XML
- ✅ 支持手动指定每个航点的独立高度、速度、航向和转弯参数
---
## 依赖项
- C++17编译器
- [toml11](https://github.com/ToruNiina/toml11) (已包含v4.3.0版本)
- CMake (3.11或更高版本)
| 依赖 | 版本要求 | 说明 |
|------|---------|------|
| 编译器 | C++17 | 支持 C++17 标准的编译器（GCC ≥ 7, Clang ≥ 5, Apple Clang ≥ 10） |
| [toml11](https://github.com/ToruNiina/toml11) | v4.3.0 | TOML 解析库（已包含在 `src/toml11/` 中） |
| CMake | ≥ 3.11 | 构建系统生成工具 |
| zip | — | 系统命令行压缩工具（macOS/Linux 默认包含） |
---
## 构建说明
### 从源码构建
```bash
# 克隆仓库
git clone https://github.com/your-repo/dji_kmz.git
@@ -31,28 +95,308 @@ cmake ..
make
```
编译完成后，可执行文件 `dji_kmz` 会生成在 `build/` 目录下。
---
## 使用方法
```
dji_kmz [-h] <config.toml>
```bash
# 查看帮助
dji_kmz -h
# 生成航线文件
dji_kmz <config.toml>
```
### 配置文件示例
见 `example/config.toml` 文件
### 快速开始
### 坐标文件格式
- KML文件: Google Earth导出的标准格式（仅支持路径）
- 文本文件: 每行包含经度、纬度、高度(空格或逗号分隔)。若高度为负则使用全局高度值。
示例:
```
120.123456,30.654321,50.0
120.124567,30.653210,45.5
```
```bash
# 使用示例配置生成航线文件
dji_kmz example/config.toml
```
该命令会读取 [`example/config.toml`](example/config.toml) 中的配置，将 [`example/ZJGFP01.kml`](example/ZJGFP01.kml) 中的航点转换为航线文件，输出到 `example/ZJGFP01_OUT.kmz`。
生成的 `.kmz` 文件可直接导入 **DJI Pilot 2** App 使用。
---
## 配置文件详解
配置文件使用 [TOML](https://toml.io/) 格式。以下是一个完整配置示例及每个字段的详细说明：
```toml
# ============================================
# DJI KMZ Generator 配置文件
# ============================================
# ---------- 1. 全局配置 ----------
author = "zhangyi" # 作者名称，会写入 KMZ 文件元数据
kmzFile = "output.kmz" # 输出文件名。若不含 .kmz 后缀则自动添加
# ---------- 2. 任务配置 ----------
[missionConfig]
droneType = "Matrice 350 RTK" # 无人机型号（详见下方无人机型号支持列表）
flyToWaylineMode = "safely" # 飞向首航点模式
# - "safely" : 安全飞行（先爬升到安全高度再飞向首航点）
# - "pointToPoint": 直线飞向首航点
finishAction = "goHome" # 任务结束动作
# - "goHome" : 自动返航
# - "noAction" : 无动作（悬停）
# - "autoLand" : 自动降落
# - "gotoFirstWaypoint" : 飞回首个航点
exitOnRCLost = "goContinue" # 遥控器信号丢失时的行为
# - "goContinue" : 继续执行任务
# - "executeLostAction" : 执行失联动作（由 executeRCLostAction 定义）
executeRCLostAction = "goBack" # 失联后的具体动作（仅 exitOnRCLost=executeLostAction 时生效）
# - "goBack" : 返航
# - "landing": 降落
# - "hover" : 悬停等待
takeOffSecurityHeight = 50.0 # 起飞安全高度（米），无人机起飞后先爬升到此高度
globalTransitionalSpeed = 10.0 # 过渡速度（米/秒），航段间的飞行速度
globalRTHHeight = 50.0 # 返航高度（米），返航时飞行的高度
# ---------- 3. 航线配置 ----------
[wayline]
templateType = "waypoint" # 航线模板类型
# - "waypoint" : 航点航线（自由规划航点）
# - "mapping2d" : 二维航测（正射影像）
# - "mapping3d" : 三维航测（倾斜摄影）
# - "mappingStrip": 带状航测（带状区域）
templateId = 0 # 模板 ID，同一任务中多个航线的标识符
autoFlightSpeed = 8.0 # 自动飞行速度（米/秒）
globalHeight = 30.0 # 全局飞行高度（米），当航点高度为负值时使用此值
caliFlightEnable = "no" # 是否启用标定飞行
# - "yes": 启用（用于测绘精度验证）
# - "no" : 禁用
gimbalPitchMode = "manual" # 云台俯仰控制模式
# - "manual" : 手动控制
# - "usePointSetting": 使用航点设置
globalWaypointTurnMode = "coordinateTurn" # 航点转弯模式
# - "coordinateTurn" : 协调转弯（提前转弯）
# - "toPointAndStopWithDiscontinuityCurvature" : 飞到航点停止（不连续曲率）
# - "toPointAndStopWithContinuityCurvature" : 飞到航点停止（连续曲率）
# - "toPointAndPassWithContinuityCurvature" : 飞到航点通过（连续曲率）
globalUseStraightLine = "yes" # 是否使用直线航线
# - "yes": 航点间直线飞行
# - "no" : 航点间曲线飞行
# ---------- 4. 坐标系参数 ----------
[wayline.waylineCoordinateSysParam]
coordinateMode = "WGS84" # 坐标模式（目前仅支持 WGS84）
heightMode = "relativeToStartPoint" # 高度模式
# - "EGM96" : EGM96 大地水准面海拔高度
# - "relativeToStartPoint": 相对起飞点高度
# - "aboveGroundLevel" : 相对地面高度
# - "realTimeFollowSurface": 实时地形跟随
positioningType = "GPS" # 定位类型
# - "GPS" : GPS 定位
# - "RTKBaseStation": RTK 基站定位
# - "QianXun" : 千寻位置
# - "Custom" : 自定义网络 RTK
# ---------- 5. 全局航向参数 ----------
[wayline.globalWaypointHeadingParam]
waypointHeadingMode = "followWayline" # 航向模式
# - "followWayline" : 跟随航线方向
# - "manually" : 手动控制
# - "fixed" : 固定航向角
# - "smoothTransition" : 平滑过渡
# - "towardPOI" : 朝向兴趣点
waypointHeadingAngle = 0.0 # 航向角（度），仅 fixed 模式生效
# 0°=正北，90°=正东，顺时针方向
waypointPoiPoint = [0.0, 0.0, 0.0] # POI 点坐标 [经度, 纬度, 高度]
# 仅 towardPOI 模式生效
waypointHeadingPoiIndex = 0 # POI 对应的航点索引
# ---------- 6. 航点配置 ----------
[placemark]
PointFile = "example/ZJGFP01.kml" # 航点坐标文件路径（支持 KML 或纯文本）
useGlobalHeight = "yes" # 是否使用全局高度
# - "yes": 所有航点使用 globalHeight
# - "no" : 使用文件中各航点单独指定的高度
useGlobalSpeed = "yes" # 是否使用全局速度
# - "yes": 所有航点使用 autoFlightSpeed
# - "no" : 使用文件中各航点单独指定的速度
useGlobalHeadingParam = "yes" # 是否使用全局航向参数
# - "yes": 所有航点使用全局航向设置
# - "no" : 各航点单独指定航向
useGlobalTurnParam = "yes" # 是否使用全局转弯参数
# - "yes": 所有航点使用全局转弯设置
# - "no" : 各航点单独指定转弯模式
```
---
## 输入文件格式
### KML 文件（推荐）
由 Google Earth Pro 导出的标准 KML 文件，支持以下两种几何类型：
**路径（LineString）** — 适用于航线规划：
- 在 Google Earth 中使用"路径"工具绘制航线
- 保存为 KML 文件
- 示例：[`example/ZJGFP01.kml`](example/ZJGFP01.kml)
**多边形（Polygon）** — 适用于区域测绘（开发中）：
- 在 Google Earth 中使用"多边形"工具绘制测区
- 保存为 KML 文件
- 示例：[`example/ZJG_WEST_Poly.kml`](example/ZJG_WEST_Poly.kml)
### 纯文本坐标文件
每行包含一个航点的经度、纬度、高度，使用空格或逗号分隔。
```
120.071320, 30.302966, 50.0
120.072224, 30.301360, -1 # 高度为负值时使用全局高度(globalHeight)
120.072158, 30.301230, 45.5
```
> **高度说明**：若高度值为负数（如 `-1`），则该航点将使用配置中的 `globalHeight` 作为飞行高度；若为非负数，则使用文件中指定的高度。
---
## 输出文件结构
生成的 `.kmz` 文件是一个 ZIP 压缩包，内部结构如下：
```
output.kmz
└── wpmz/
└── template.kml # DJI WPML 格式的航线文件
```
### template.kml 结构（DJI WPML 1.0.5）
```xml
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"
xmlns:wpml="http://www.dji.com/wpmz/1.0.5">
<Document>
<!-- 作者信息 -->
<wpml:author>作者名称</wpml:author>
<!-- 任务配置 -->
<wpml:missionConfig>
<wpml:flyToWaylineMode>safely</wpml:flyToWaylineMode>
<wpml:finishAction>goHome</wpml:finishAction>
<wpml:exitOnRCLost>goContinue</wpml:exitOnRCLost>
<wpml:takeOffSecurityHeight>50.0</wpml:takeOffSecurityHeight>
<wpml:globalTransitionalSpeed>10.0</wpml:globalTransitionalSpeed>
<wpml:globalRTHHeight>50.0</wpml:globalRTHHeight>
<wpml:droneInfo>
<wpml:droneEnumValue>89</wpml:droneEnumValue>
<wpml:droneSubEnumValue>0</wpml:droneSubEnumValue>
</wpml:droneInfo>
</wpml:missionConfig>
<!-- 航线模板 -->
<Folder>
<wpml:templateType>waypoint</wpml:templateType>
<wpml:templateId>0</wpml:templateId>
<!-- 坐标系参数 -->
<wpml:waylineCoordinateSysParam>
<wpml:coordinateMode>WGS84</wpml:coordinateMode>
<wpml:heightMode>relativeToStartPoint</wpml:heightMode>
<wpml:positioningType>GPS</wpml:positioningType>
</wpml:waylineCoordinateSysParam>
<!-- 飞行参数 -->
<wpml:autoFlightSpeed>8.0</wpml:autoFlightSpeed>
<wpml:globalHeight>30.0</wpml:globalHeight>
<wpml:caliFlightEnable>0</wpml:caliFlightEnable>
<wpml:gimbalPitchMode>manual</wpml:gimbalPitchMode>
<!-- 航向参数 -->
<wpml:globalWaypointHeadingParam>
<wpml:waypointHeadingMode>followWayline</wpml:waypointHeadingMode>
<wpml:waypointHeadingAngle>0.0</wpml:waypointHeadingAngle>
<wpml:waypointPoiPoint>0.0,0.0,0.0</wpml:waypointPoiPoint>
<wpml:waypointHeadingPoiIndex>0</wpml:waypointHeadingPoiIndex>
</wpml:globalWaypointHeadingParam>
<!-- 转弯参数 -->
<wpml:globalWaypointTurnMode>coordinateTurn</wpml:globalWaypointTurnMode>
<wpml:globalUseStraightLine>1</wpml:globalUseStraightLine>
<!-- 航点列表 -->
<Placemark>
<Point>
<coordinates>经度,纬度</coordinates>
</Point>
<wpml:index>0</wpml:index>
<wpml:ellipsoidHeight>30</wpml:ellipsoidHeight>
<wpml:height>30</wpml:height>
<wpml:useGlobalHeight>1</wpml:useGlobalHeight>
<wpml:useGlobalSpeed>1</wpml:useGlobalSpeed>
<wpml:useGlobalHeadingParam>1</wpml:useGlobalHeadingParam>
<wpml:useGlobalTurnParam>1</wpml:useGlobalTurnParam>
<wpml:isRisky>0</wpml:isRisky>
</Placemark>
<!-- 更多航点... -->
</Folder>
</Document>
</kml>
```
---
## 无人机型号支持列表
| 无人机型号 | `droneType` 配置值 | 枚举值 |
|-----------|-------------------|--------|
| Matrice 350 RTK | `Matrice 350 RTK` | 89 |
| Matrice 300 RTK | `Matrice 300 RTK` | 60 |
| Matrice 30 | `Matrice 30` | 67 |
| Matrice 30T | `Matrice 30T` | 67 |
| Mavic 3E | `Mavic 3E` | 77 |
| Mavic 3T | `Mavic 3T` | 77 |
| Matrice 3D | `Matrice 3D` | 91 |
| Matrice 3TD | `Matrice 3TD` | 91 |
| Matrice 4D | `Matrice 4D` | 100 |
| Matrice 4TD | `Matrice 4TD` | 100 |
| Matrice 4E | `Matrice 4E` | 99 |
| Matrice 4T | `Matrice 4T` | 99 |
---
## 常见问题
### Q: 生成的 KMZ 文件如何导入 DJI Pilot 2？
将 `.kmz` 文件传输至 DJI 遥控器（可通过 USB、SD 卡或云端同步），然后在 DJI Pilot 2 App 中点击"航线导入"选择该文件即可。
### Q: 如何自定义每个航点的高度？
在坐标文本文件中，为每个航点指定独立高度值。若某航点的高度值为负数（如 `-1`），则该航点使用配置中的 `globalHeight`。同时需将 `useGlobalHeight` 设为 `"no"`。
### Q: 支持哪些 Google Earth 导出的几何类型？
当前支持 `<LineString>`（路径）和 `<Polygon>`（多边形）两种类型。`<Point>`（点标记）暂不支持。
### Q: 如何规划区域测绘航线？
使用 `templateType = "mapping2d"`（二维航测）或 `templateType = "mapping3d"`（三维航测），无人机将自动在测区内生成蛇形扫描航线。
### Q: 编译时提示找不到 toml11？
toml11 已包含在源码中（`src/toml11/`），无需额外安装。若仍有问题，请检查 `CMakeLists.txt` 中 `aux_source_directory(src SRC)` 是否正确包含了所有源文件。
---
## 许可证
MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
MIT 许可证 — 详见 [LICENSE](LICENSE) 文件。
## 作者
张壹
浙江大学地球科学学院
邮箱: yizhang-geo@zju.edu.cn
**张壹** — 浙江大学地球科学学院
邮箱：yizhang-geo@zju.edu.cn
---
> **参考文档**：[DJI WPML 协议 — 上云 API 文档](https://developer.dji.com/doc/cloud-api-tutorial/cn/api-reference/dji-wpml/overview.html)