# DJI KMZ Generator

将 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 文件（`<LineString>` 路径和 `<Polygon>` 多边形）
- ✅ 支持自定义纯文本坐标文件
- ✅ 支持 12 种大疆无人机型号（Matrice 系列、Mavic 3 系列等）
- ✅ 支持多种飞行模式配置（航点、二维航测、三维航测、带状航测）
- ✅ 支持多种高度模式（相对起飞点、EGM96 海拔、地面高度、实时地形跟随）
- ✅ 支持多种航向模式（跟随航线、手动控制、固定角度、平滑过渡、朝向 POI）
- ✅ 支持多种失联动作（继续执行、返航、降落、悬停）
- ✅ 通过 TOML 配置文件定义所有航线参数，无需手动编辑 XML
- ✅ 支持手动指定每个航点的独立高度、速度、航向和转弯参数

---

## 依赖项

| 依赖 | 版本要求 | 说明 |
|------|---------|------|
| 编译器 | 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
cd dji_kmz

# 创建构建目录
mkdir build
cd build

# 生成构建系统
cmake ..

# 编译项目
make
```

编译完成后，可执行文件 `dji_kmz` 会生成在 `build/` 目录下。

---

## 使用方法

```bash
# 查看帮助
dji_kmz -h

# 生成航线文件
dji_kmz <config.toml>
```

### 快速开始

```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) 文件。

## 作者

**张壹** — 浙江大学地球科学学院  
邮箱：yizhang-geo@zju.edu.cn

---

> **参考文档**：[DJI WPML 协议 — 上云 API 文档](https://developer.dji.com/doc/cloud-api-tutorial/cn/api-reference/dji-wpml/overview.html)