【背景】

从5.6版本开始，在项目中引入wpmzSDK可以使用WPMZManager去实现KMZ文件的读取和生成。

这里是WPMZManager的在线API文档地址：https://developer.dji.com/cn/api-reference-v5/android-api/Components/IWaypointMissionManager/IWPMZManager.html#iwpmzmanager

【如何使用WPMZManager】

流程图结合API文档，开发者可以了解到各个接口的作用和使用顺序。

这些是一些补充讲解：

WPMZManager下的两个同名generateKMZFile接口之间的差别是在于接收不同的航线任务信息。

Template对应kmz文件里的template.kml文件。

Wayline对应kmz文件里的waylines.wpml。

如果您需要生成的文件在Pilot 2中可以使用，推荐使用参数为Template的generateKMZFile接口。

【如何生成kmz文件】

WPMZManager下的generateKMZFile用于生成kmz文件。下面将详细讲解如何使用以参数为Template的generateKMZFile接口生成航线文件。

*接口和参数定义：

void generateKMZFile(String kmzPath , WaylineMission waylineMission , WaylineMissionConfig config , Template waylineTemplate )

kmzPath：生成文件的存放路径

WaylineMission：航点任务文件信息，例如任务创建时间，作者等

WaylineMissionConfig：航点任务全局信息，例如失控动作，结束动作，安全起飞高度等

Template：航点任务信息，即航点以及对应的航点动作

WaylineMission中的内容较少且不会影响到航点任务的执行，因此这里将不作详细说明。开发者可以直接在代码中查看其注释（建议使用wpmzSDK 1.0.1.5及其以上）。

*WaylineMissionConfig的全部属性：

 class WaylineMissionConfig implements DJIValue, JNIProguardKeepTag, ByteStream{
    /**
     *  飞向首航点模式，必需
     *  fly to wayline mode
     *  refs:flyToWaylineMode
     */
    WaylineFlyToWaylineMode flyToWaylineMode = WaylineFlyToWaylineMode.UNKNOWN;
    /**
     *  航线结束动作，必需
     *  wayline route end action
     *  refs:finishAction
     */
    WaylineFinishedAction finishAction = WaylineFinishedAction.UNKNOWN;
    /**
     *  失控动作类型,必填
     *  Out of control action type
     *  refs:exitOnRCLost
     */
    WaylineExitOnRCLostBehavior exitOnRCLostBehavior = WaylineExitOnRCLostBehavior.UNKNOWN;
    /**
     *  失控动作，在失控动作类型为执行失控动作是必填，其他时刻非必填
     *  Out of control action
     *  refs:executeRCLostAction
     */
    WaylineExitOnRCLostAction exitOnRCLostType = WaylineExitOnRCLostAction.UNKNOWN;
    /**
     *  全局航线过度速度, m/s，必填
     *  Global route transition speed
     *  refs:globalTransitionalSpeed
     */
    Double globalTransitionalSpeed = 0d;
    /**
     *  安全起飞高度，必填
     *  safe takeoff altitude
     *  refs:takeOffSecurityHeight
     */
    Double securityTakeOffHeight = 0d;
    /**
     *  安全起飞高度是否设置，必填
     *  Is the safe takeoff altitude set
     */
    Boolean isSecurityTakeOffHeightSet = false;
    /**
     *  参考起飞点,高度为椭球高，非必填
     *  Reference take-off point, height is ellipsoid height
     *  refs:takeOffRefPoint
     */
    WaylineLocationCoordinate3D takeOffPositionRef;
    /**
     *  参考起飞点是否设置，非必填
     */
    Boolean isTakeOffPositionRefSet = false;
    /**
     *  参考起飞点,编辑高度,AGL，非必填
     */
    Double takeOffPositionAGL = 0d;
    /**
     *  是否设置参考起飞点AGL，非必填
     */
    Boolean isTakeOffPositionAGLSet = false;
    /**
     *  任务飞机设备，非必填
     *  mission aircraft equipment
     *  refs:droneInfo
     */
    WaylineDroneInfo droneInfo;
    /**
     *  任务挂载负载设备,定位负载类型,负载镜头及参数由使用到的template指定,非必填,
     *  payload infomations
     *  refs:payloadInfo
     */
    List<WaylinePayloadInfo> payloadInfo = new ArrayList<WaylinePayloadInfo>();
    /**
     *  全局返航高度，仅在机场生效
     *  Global return altitude
     *  refs:globalRTHHeight
     */
    Double globalRTHHeight = 0d;
    /**
     *  全局返航高度是否设置，仅在机场生效
     *  Is the global return altitude set
     */
    Boolean isGlobalRTHHeightSet = false;
    /**
     *  航线绕行信息，仅在机场生效
     *  Route detour information
     */
    WaylineAvoidInfo avoidInfo;
    /**
     *  是否设置绕行，仅在机场生效
     *  Whether to set a bypass
     */
    Boolean isAvoidInfoSet = false;
}

上述属性可以根据定义在template.kml中找到对应的元素，以了解取值范围和详细描述。

这里是template.kml的格式和标准：

https://developer.dji.com/doc/cloud-api-tutorial/cn/api-reference/dji-wpml/template-kml.html

这里是一些补充说明：

1.exitOnRCLostType当且仅当exitOnRCLostBehavior为EXCUTE_RC_LOST_ACTION时生效；

2.WaylineAvoidInfo和isAvoidInfoSet仅支持M3TD和M3TD；

3.takeOffPositionRef仅做航线规划参考，飞行器执行航线时以飞行器真实的起飞点为准，高度使用椭球高。

*Template的定义：

public class Template {

    /**
     * 模版id 默认0 参考文档中字段templateId
     * Template id defaults to 0. Refer to the field templateId in the document.
     * refs:templateId
     */
    private Integer templateId;
    /**
     * 坐标系参数，必填
     * Coordinate system parameters
     * refs:waylineCoordinateSysParam
     */
    private WaylineCoordinateParam coordinateParam;
    /**
     * 全局航线过渡速度，必填
     * Global route transition speed
     * refs:globalTransitionalSpeed
     */
    private Double transitionalSpeed;
    /**
     * 是否使 transitionalSpeed 字段生效，必填
     */
    private Boolean useGlobalTransitionalSpeed;
    /**
     * 全局航线飞行速度，必填
     * Global route flight speed
     * refs:autoFlightSpeed
     */
    private Double autoFlightSpeed;
    /**
     * 负载设置
     * payload settings
     * refs:payloadParam
     */
    private List<WaylinePayloadParam> payloadParam;

    /**
     * 航点飞行模板元素，详细介绍可见
     * Waypoint flight template elements
     */
    private WaylineTemplateWaypointInfo waypointInfo;
}

上述属性可以根据定义在template.kml中找到对应的元素，以了解取值范围和详细描述。

这里是template.kml的格式和标准：

https://developer.dji.com/doc/cloud-api-tutorial/cn/api-reference/dji-wpml/template-kml.html

其中WaylineCoordinateParam的属性如下：

//经纬度坐标系，即coordinateMode
WaylineCoordinateMode coordinateMode = WaylineCoordinateMode.UNKNOWN;
//高度模式，即heightMode
WaylineAltitudeMode altitudeMode = WaylineAltitudeMode.UNKNOWN;
/**
 * 非必填,全局飞机离被摄面高度
 */
Double globalShootHeight = 0d;
Boolean isGlobalShootHeightSet = false;
/**
 * 非必填,仿地飞行参数
 */
SurfaceFollowParam surfaceFollowParam;
Boolean isSurfaceFollowParamSet = false;
/**
 * 非必填,经纬度与高度数据源，即wpml:positioningType
 */
WaylinePositioningType positioningType = WaylinePositioningType.UNKNOWN;
Boolean isWaylinePositioningTypeSet = false;

WaylineTemplateWaypointInfo是存储航点和航点动作的模板类。下面是WaylineTemplateWaypointInfo属行介绍。

/**
 *  自由航点,非必填,航向模式,Placemark可重新配置该值，即wpml:globalWaypointHeadingParam
 */
WaylineWaypointYawParam globalYawParam;
Boolean isTemplateGlobalYawParamSet = false;
/**
 *  自由航点,非必填,gimbal航向模式,Placemark可重新配置该值
 */
WaylineWaypointGimbalHeadingParam globalGimbalHeadingParam;
Boolean isTemplateGlobalGimbalHeadingParamSet = false;
/**
 *  自由航点,转弯模式参数,Placemark可重新配置该值,当是协调转弯时,每个点需要设置转弯半径
即wpml:globalWaypointTurnMode
 */
WaylineWaypointTurnMode globalTurnMode = WaylineWaypointTurnMode.UNKNOWN;
Boolean isTemplateGlobalTurnModeSet = false;
/**
 *  必填, 航段是否为直线
 */
Boolean useStraightLine = false;
/**
 *  自由航点,全局航点动作，非必需（对应startActionGroup)
 */
WaylineActionGroup globalAction;
Boolean isGlobalActionSet = false;
/**
 *  非必填,自由航点,全局航线飞行编辑高度,根据heightmode,表示意义不同,每个航点的实际飞行高度,在航点中写入
 */
Double globalFlightHeight = 0d;
Boolean isGlobalFlightHeightSet = false;
/**
 *  自由航点,Placemark
 */
List<WaylineWaypoint> waypoints = new ArrayList<WaylineWaypoint>();
/**
 *  自由航点,动作
 */
List<WaylineActionGroup> actionGroups = new ArrayList<WaylineActionGroup>();
/**
 *  非必填,航线云台控制参数，即wpml:gimbalPitchMode
 */
WaylineWaypointPitchMode pitchMode = WaylineWaypointPitchMode.UNKNOWN;
/**
 *  是否开启标定飞行
 */
Boolean caliFlightEnable = false;

WaylineWaypoint和WaylineActionGroup即为航点任务中最为重要和关键的航点和动作组。下面是WaylineWaypoint所含属性：

/**
 *  必填，航点序号，不可重复
 */
Integer waypointIndex = 0;
/**
 *  必填，航点位置
 */
WaylineLocationCoordinate2D location;
/**
 *  航点高度
 */
Double height = 0d;
/**
 *  是否使用全局高度；WaylineCoordinateParam中的globalFlightHeight
 */
Boolean useGlobalFlightHeight = false;
/**
 *  航点使用的椭球高
 */
Double ellipsoidHeight = 0d;
/**
 *  非必填,航向参数。对应<wpml:waypointHeadingParam>
 */
WaylineWaypointYawParam yawParam;
Boolean isWaylineWaypointYawParamSet = false;
/**
 *  是否使用全局heading设置,来源于:全局的WaylineTemplateWaypointInfo中的globalYawParam
 */
Boolean useGlobalYawParam = false;

WaylineWaypointGimbalHeadingParam gimbalHeadingParam;
Boolean isWaylineWaypointGimbalHeadingParamSet = false;
/**
 *  是否使用全局heading设置,来源于:全局的WaylineTemplateWaypointInfo中的globalHeadingParam
 */
Boolean useGlobalGimbalHeadingParam = false;
/**
 *  非必填,转弯参数，对应<wpml:waypointTurnParam>
 */
WaylineWaypointTurnParam turnParam;
Boolean isWaylineWaypointTurnParamSet = false;
/**
 *  是否使用全局WaylineWaypointTurnParam,来源于:全局的WaylineTemplateWaypointInfo中的WaylineWaypointTurnMode
 */
Boolean useGlobalTurnParam = false;
/**
 *  非必填,航点巡航速度，单位 m/s
 */
Double speed = 0d;
/**
 *  是否使用全局速度,全局速度来自:autoFlightSpeed
 */
Boolean useGlobalAutoFlightSpeed = false;
/**
 *  必填, 航段是否为直线
 */
Boolean useStraightLine = false;
/**
 *  云台俯仰角度
 */
Double gimbalPitchAngle = 0d;
/**
 *  该航点是否使用全局动作
 */
Boolean useGlobalActionGroup = false;
/**
 *  表示该点是否为不可向上返航点，仅用于机场
 */
Boolean isRisky = false;

WaylineActionGroup的属性如下：

Integer groupId = 0; //动作组序号，必填且唯一
Integer startIndex = 0;//开始航点序号
Integer endIndex = 0;//结束航点序号
WaylineActionTrigger trigger;//动作触发器
List<WaylineActionNodeList> nodeLists = new ArrayList<WaylineActionNodeList>();//动作树，决定动作执行顺序
List<WaylineActionInfo> actions = new ArrayList<WaylineActionInfo>();//航点动作

WaylineActionNodeList管理了一个WaylineActionTreeNode列表。下面是WaylineActionTreeNode的属性介绍：

//节点类型。LEAF表示当前节点为子节点，SEQUENCE表示顺序执行，可以用在父节点。
WaylineActionsRelationType nodeType = WaylineActionsRelationType.UNKNOWN; 
Integer childrenNum = 0;//子节点数量
Integer actionIndex = 0;//对应动作序号

WaylineActionInfo存储了航点动作类型和动作参数，用于表示动作执行内容。下面是WaylineActionInfo的属性介绍：

Integer actionId = 0;//动作序号
WaylineActionType actionType = WaylineActionType.UNKNOWN;//动作类型。根据动作类型，使用下面对应的动作参数。
/**
 *  相机单拍
 */
ActionTakePhotoParam takePhotoParam;
/**
 *  开始录像
 */
ActionStartRecordParam startRecordParam;
/**
 *  结束录像
 */
ActionStopRecordParam stopRecordParam;
/**
 *  对焦
 */
ActionFocusParam focusParam;
/**
 *  变焦
 */
ActionZoomParam zoomParam;
/**
 *  自定义文件或文件夹名
 */
ActionCustomDirNameParam customDirNameParam;
/**
 *  开始定时拍
 */
ActionStartTimeLapseParam startTimeLapseParam;
/**
 *  结束定时拍
 */
ActionStopTimeLapseParam stopTimeLapseParam;
/**
 *  云台旋转
 */
ActionGimbalRotateParam gimbalRotateParam;
/**
 *  均匀转云台
 */
ActionGimbalEvenlyRotateParam gimbalEvenlyRotateParam;
/**
 *  开始摆拍
 */
ActionStartSmartObliqueParam startSmartObliqueParam;
/**
 *  关闭摆拍
 */
ActionStopSmartObliqueParam stopSmartObliqueParam;
/**
 *  悬停
 */
ActionAircraftHoverParam aircraftHoverParam;
/**
 *  飞机转yaw
 */
ActionAircraftRotateYawParam aircraftRotateYawParam;
/**
 *  精准拍照
 */
ActionAccuratePhotoParam accuratePhotoParam;
/**
 *  点云开关
 */
ActionRecordPointCloudParam recordPointCloudParam;
/**
 *  PSDK自定义动作
 */
ActionPSDKParam psdkParam;
/**
 *  飞机标定动作
 */
ActionAircraftCaliParam aircraftCaliParam;
/**
 *  开始连拍
 */
ActionStartContinuousShootingParam startContinuousShootingParam;
/**
 *  结束连拍
 */
ActionStopContinuousShootingParam stopContinuousShootingParam;
/**
 *  农业-打开喷洒
 */
ActionSprayOpenParam sprayOpenParam;
/**
 *  农业-关闭喷洒
 */
ActionSprayCloseParam sprayCloseParam;
/**
 *  农业-定量喷洒
 */
ActionSprayCapacityParam sprayCapacityParam;
/**
 *  农业 - 按角速度转yaw 
 */
ActionAircraftRotateFollowSpeedParam aircraftRotateFollowSpeedParam;
/**
 *  低光智能拍照
 */
ActionLowLightSmartShootingParam lowLightSmartShootingParam;
/**
 *  定向拍照
 */
ActionOrientedPhotoParam orientedPhotoParam;