From 143ff39327442f0a12ec83e097261f0957917d09 Mon Sep 17 00:00:00 2001 From: Yi Zhang Date: Thu, 9 Jul 2026 17:21:03 +0800 Subject: [PATCH] update readme --- README.md | 392 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 368 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 343f9a5..352c465 100644 --- a/README.md +++ b/README.md @@ -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 导出的路径（``）或多边形（``）坐标（参见 [`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 文件（`` 路径和 `` 多边形） +- ✅ 支持自定义纯文本坐标文件 +- ✅ 支持 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] +```bash +# 查看帮助 +dji_kmz -h + +# 生成航线文件 +dji_kmz ``` -### 配置文件示例 -见 `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 + + + + + 作者名称 + + + + safely + goHome + goContinue + 50.0 + 10.0 + 50.0 + + 89 + 0 + + + + + + waypoint + 0 + + + + WGS84 + relativeToStartPoint + GPS + + + + 8.0 + 30.0 + 0 + manual + + + + followWayline + 0.0 + 0.0,0.0,0.0 + 0 + + + + coordinateTurn + 1 + + + + + 经度,纬度 + + 0 + 30 + 30 + 1 + 1 + 1 + 1 + 0 + + + + + +``` + +--- + +## 无人机型号支持列表 + +| 无人机型号 | `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 导出的几何类型？ + +当前支持 ``（路径）和 ``（多边形）两种类型。``（点标记）暂不支持。 + +### 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 \ No newline at end of file + +**张壹** — 浙江大学地球科学学院 +邮箱：yizhang-geo@zju.edu.cn + +--- + +> **参考文档**：[DJI WPML 协议 — 上云 API 文档](https://developer.dji.com/doc/cloud-api-tutorial/cn/api-reference/dji-wpml/overview.html)