zhangyiss/dji_kmz

Fork 0

Go to file

Yi Zhang 143ff39327 update readme

2026-07-09 17:21:03 +08:00

.vscode

tmp

2025-07-15 22:22:11 +08:00

example

tmp

2025-07-15 22:22:11 +08:00

src

tmp

2025-07-15 22:22:11 +08:00

.gitignore

v1.0

2025-07-11 14:35:06 +08:00

CMakeLists.txt

v1.0

2025-07-11 14:35:06 +08:00

LICENSE

Initial commit

2025-07-11 13:07:43 +08:00

README.md

update readme

2026-07-09 17:21:03 +08:00

README.md

DJI KMZ Generator

将 Google Earth 的 KML 文件或普通坐标文本文件转换为 DJI Pilot 2 可识别的航线文件（.kmz），遵循 DJI WPML（Waypoint Markup Language）协议标准。

工作原理

┌─────────────┐    ┌──────────────┐    ┌─────────────────┐
│ config.toml  │───▶│              │    │                 │
│ (航线参数)    │    │   dji_kmz    │────▶  output.kmz     │
├─────────────┤    │   (C++17)    │    │  (DJI Pilot 2   │
│ points.kml   │───▶│              │    │   航线文件)      │
│ 或 points.txt │    │              │    │                 │
└─────────────┘    └──────────────┘    └─────────────────┘

程序执行流程：

读取 TOML 格式的配置文件（example/config.toml），解析无人机型号、飞行参数、航点文件路径等
读取航点坐标文件：
- KML 文件：解析 Google Earth 导出的路径（<LineString>）或多边形（<Polygon>）坐标（参见 src/simple_kml.hpp）
- 文本文件：按行解析经度、纬度、高度
生成符合 DJI WPML 1.0.5 规范的 template.kml（参见 src/dji_kmz.cpp:374-423）
将 template.kml 压缩为 .kmz 格式（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	v4.3.0	TOML 解析库（已包含在 `src/toml11/` 中）
CMake	≥ 3.11	构建系统生成工具
zip	—	系统命令行压缩工具（macOS/Linux 默认包含）

构建说明

从源码构建

# 克隆仓库
git clone https://github.com/your-repo/dji_kmz.git
cd dji_kmz

# 创建构建目录
mkdir build
cd build

# 生成构建系统
cmake ..

# 编译项目
make

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

使用方法

# 查看帮助
dji_kmz -h

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

快速开始

# 使用示例配置生成航线文件
dji_kmz example/config.toml

该命令会读取 example/config.toml 中的配置，将 example/ZJGFP01.kml 中的航点转换为航线文件，输出到 example/ZJGFP01_OUT.kmz。

生成的 .kmz 文件可直接导入 DJI Pilot 2 App 使用。

配置文件详解

配置文件使用 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

多边形（Polygon） — 适用于区域测绘（开发中）：

在 Google Earth 中使用"多边形"工具绘制测区
保存为 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 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 文件。

作者

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

参考文档：DJI WPML 协议 — 上云 API 文档

README.md Unescape Escape

DJI KMZ Generator

目录

工作原理

功能特性

依赖项

构建说明

从源码构建

使用方法

快速开始

配置文件详解

输入文件格式

KML 文件（推荐）

纯文本坐标文件

输出文件结构

template.kml 结构（DJI WPML 1.0.5）

无人机型号支持列表

常见问题

Q: 生成的 KMZ 文件如何导入 DJI Pilot 2？

Q: 如何自定义每个航点的高度？

Q: 支持哪些 Google Earth 导出的几何类型？

Q: 如何规划区域测绘航线？

Q: 编译时提示找不到 toml11？

许可证

作者

README.md