wsadexq DJI WPML 航线文件
WPML（WayPoint Markup Language）是大疆基于 KML 2.2 扩展的航线文件格式标准，航线文件一律以 .kmz 后缀归档（ZIP 格式）。本技能帮助你生成、解析、修改、校验符合 DJI 官方标准的航线文件。
何时使用
- 生成新的航线文件（航点飞行 / 建图航拍 / 倾斜摄影 / 航带飞行 / 目标检测巡逻）
- 解析或修改已有的
template.kml/waylines.wpml - 打包或解包
.kmz归档 - 校验航线文件是否合法、能否被 DJI Pilot 2 / 司空 2 正确解析
基础知识
文件结构
一个标准 WPML .kmz 解压后包含：
| 文件/目录 | 名称 | 职责 |
|---|---|---|
template.kml |
模板文件 | 定义业务属性，方便用户快速调整编辑（测区、重叠率、模板参数） |
waylines.wpml |
执行文件 | 定义明确的飞行与负载动作指令，由软件依据模板参数演算生成，供无人机执行 |
res/ |
资源目录 | 航线所需辅助资源（精准复拍参考照片 / 目标检测区域 / 仿地 DSM 高程） |
航线名称即文件名（new_waypoints.kmz 的航线名是 new_waypoints）。内部各文件/文件夹命名必须遵循此规范，否则航线文件读取失败。
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.2">
两种高度体系（最容易出错，务必分清）
- template.kml 用
wpml:heightMode+wpml:height（编辑体系）：EGM96（海拔高）/relativeToStartPoint（相对起飞点）/aboveGroundLevel（AGL，仅司空2）/realTimeFollowSurface（实时仿地，仅建图航拍模版，M3E/M3T/M3M） - waylines.wpml 用
wpml:executeHeightMode+wpml:executeHeight（执行体系）：WGS84（椭球高）/relativeToStartPoint（相对起飞点高）/realTimeFollowSurface（仅 M3E/M3T/M3M） ellipsoidHeight与height是同一位置不同高程参考平面的表达，需配合使用- 若数据来自非椭球坐标系（如 EGM96），转换为 WGS84 需做高程转换，否则飞行高度不准
硬性规则
- 文件头：XML 声明必须是
<?xml version="1.0" encoding="UTF-8"?>，根元素必须是带上述两个命名空间的<kml> - 航点序号：
wpml:index必须从 0 开始单调连续递增，在一条航线内唯一，范围 [0, 65535] - 模板/航线/动作 ID：
wpml:templateId、wpml:waylineId、wpml:actionGroupId、wpml:actionId建议从 0 开始单调连续递增，范围 [0, 65535] - 必需字段：
missionConfig下的flyToWaylineMode、finishAction、exitOnRCLost、takeOffSecurityHeight、globalTransitionalSpeed、globalRTHHeight必填；droneInfo/payloadInfo必填 - 枚举值：所有枚举字段必须使用官方文档定义的值（如
finishAction只能是goHome/noAction/autoLand/gotoFirstWaypoint），禁止自造枚举 - 坐标格式：
<coordinates>经度,纬度</coordinates>（经度在前、纬度在后），经度 [-180,180]、纬度 [-90,90] - 条件必需：注意"当且仅当"类规则，例如
wpml:height/ellipsoidHeight仅在useGlobalHeight=0时必需，waypointSpeed仅在useGlobalSpeed=0时必需，executeRCLostAction仅在exitOnRCLost=executeLostAction时必需 - 数值范围：速度 [1,15] m/s、
takeOffSecurityHeight遥控器 [1.2,1500]/机场 [8,1500] m、重叠率 [0,100] 等，超范围值会导致解析失败 - 生成后必须校验：生成或修改文件后，运行
scripts/validate_wayline.py检查
安全与隐私边界（重要）
本技能会生成实际控制无人机飞行的航线文件，以下边界必须严格执行，不能只依赖校验脚本：
- 执行前用户确认：航线执行前，必须由用户确认坐标、飞行高度、返航高度（
globalRTHHeight）、失控动作（exitOnRCLost/executeRCLostAction）等关键参数 - 不写入用户真实航线：不得把用户提供/导出的真实航线数据写入示例文件或文档；示例必须使用虚构坐标
- 脱敏义务：坐标、设备 SN、Token、密钥、日志等敏感信息在输出前必须先脱敏（替换为占位符或虚构值）
- 高风险动作再次确认：涉及远程起飞、返航、指飞、目标检测等动作时，必须再次向用户确认后才能执行
- 校验通过 ≠ 飞行安全：
validate_wayline.py只验证格式与字段合法性，不代表飞行安全或符合当地法规；生成者需自行确认作业区域适航性 - 不主动提权：未经用户明确要求，不得尝试连接设备、读取日志或进行任何网络操作
工作流
- 明确用户要生成哪种模板：
waypoint（航点飞行）/mapping2d（建图航拍）/mapping3d（倾斜摄影）/mappingStrip（航带飞行）/targetdetection（目标检测巡逻） - 按需加载对应参考文档（见下方"按需加载"）
- 生成文件内容，遵守上述硬性规则
- 用校验脚本验证：
python scripts/validate_wayline.py <file> - 如需打包 KMZ，用
python scripts/package_kmz.py <template.kml> <waylines.wpml> -o <输出.kmz> [--res <res目录>]（详见reference/kmz-archive.md）
按需加载
- 要生成或修改 template.kml → 加载
reference/template-kml.md - 要生成或修改 waylines.wpml → 加载
reference/waylines-wpml.md - 要查询共用元素（droneInfo/payloadInfo/actionGroup/偏航角/转弯参数/动作参数） → 加载
reference/common-elements.md - 要打包/解包 KMZ 归档 → 加载
reference/kmz-archive.md（配合scripts/package_kmz.py打包、scripts/validate_wayline.py校验） - 涉及目标检测巡逻（targetdetection） → 加载
reference/template-kml.md+reference/common-elements.md+reference/kmz-archive.md（res/area区域与res/dsm高程）
模板速查
| 模板 | wpml:templateType |
关键结构 |
|---|---|---|
| 航点飞行 | waypoint |
Folder 下多个 Placemark(Point)，每个含 index/高度/速度/偏航/转弯参数，可挂 actionGroup |
| 建图航拍 | mapping2d |
Placemark 内 Polygon 定义测区，含 overlap/direction/margin/shootType/height 等 |
| 倾斜摄影 | mapping3d |
同建图航拍，另有 inclinedGimbalPitch/inclinedFlightSpeed，生成 5 条航线（1 正射 + 4 倾斜） |
| 航带飞行 | mappingStrip |
LineString 定义航带，含 singleLineEnable/cuttingDistance/leftExtend/rightExtend 等 |
| 目标检测巡逻 | targetdetection |
测区 Polygon + targetDetectionActionEnable + targetDetection 动作（含 targetParam 模型参数），可选仿地（dsmFile） |