dji-wasm-wayline

DJI 航线生成与导出能力包，覆盖：

• 面状航线（WASM 生成 + KMZ 导出）
• 带状航线（WASM 生成 + KMZ 导出）
• 航点航线（模板导出 KMZ）

1. 安装

npm i dji-wasm-wayline

或：

yarn add dji-wasm-wayline

2. 运行环境要求

• 仅支持浏览器环境（依赖 window、document、fetch、File、DOMParser）。
• Vite 项目建议配置：

// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    exclude: ['dji-wasm-wayline']
  }
})

3. 包导出总览

核心推荐 API：

• 统一生成入口：generateWayline
• 面状 WASM：generateAreaWaylineByWasm（别名：generateAreaWaylineLegacyByWasm）
• 带状 WASM：generateBeltWaylineByWasm（别名：generateStripWaylineByWasm）
• 面状导出：exportAreaRouteWithTemplate
• 带状导出：exportBeltRouteWithWasm
• 航点导出：exportWaypointWaylineFiles（别名：getXml，已废弃不推荐）
• 照片估算：estimateWasmWaylinePhotoCount

4. 快速开始

import {
  generateWayline,
  generateAreaWaylineByWasm,
  generateBeltWaylineByWasm,
  exportAreaRouteWithTemplate,
  exportBeltRouteWithWasm,
  exportWaypointWaylineFiles
} from 'dji-wasm-wayline'

5. API 详情（含必填参数）

5.1 统一生成 generateWayline

generateWayline(request: 
  | { type: 'mapping2d'; params: GenerateAreaWaylineOptions }
  | { type: 'mappingStrip'; params: GenerateStripWaylineOptions }
)

示例：

const areaResult = await generateWayline({
  type: 'mapping2d',
  params: areaOptions
})

const stripResult = await generateWayline({
  type: 'mappingStrip',
  params: stripOptions
})

5.2 面状 WASM 生成 generateAreaWaylineByWasm

函数签名：

generateAreaWaylineByWasm(options: GenerateAreaWaylineOptions): Promise<WaylineFileResult>

必填参数（GenerateAreaWaylineOptions）

| 参数 | 类型 | 说明 | | --- | --- | --- | | polygonPoints | { longitude:number; latitude:number; height?:number }[] | 多边形点，至少 3 个 | | takeoffPoint | { longitude:number; latitude:number; height:number } | 起飞参考点，不能为 null | | routeHeight | number | 航线高度 | | autoFlightSpeed | number | 全局航线速度 | | inclinedFlightSpeed | number | 倾斜航线速度 | | globalTransitionalSpeed | number | 过渡速度 | | takeOffSecurityHeight | number | 安全起飞高度 | | finishAction | 'goHome' \| 'noAction' \| 'autoLand' \| 'gotoFirstWaypoint' | 完成动作 | | collectionMode | 'ortho' \| 'oblique' | 正射/倾斜 | | shootType | 'time' \| 'distance' | 拍照模式 | | margin | number | 外扩距离 | | direction | number | 航线方向 | | smartObliqueGimbalPitch | number | 倾斜云台俯仰 | | orthoCameraOverlapH | number | 正射航向重叠率 | | orthoCameraOverlapW | number | 正射旁向重叠率 | | inclinedCameraOverlapH | number | 倾斜航向重叠率 | | inclinedCameraOverlapW | number | 倾斜旁向重叠率 | | area | number | 区域面积（用于适配 legacy 输出） |

可选参数

| 参数 | 类型 | 默认值 | | --- | --- | --- | | droneEnumValue | number \| null | 67 | | droneSubEnumValue | number \| null | 1 | | payloadEnumValue | number \| null | 53 |

示例

const areaRes = await generateAreaWaylineByWasm({
  polygonPoints: [
    { longitude: 117.18, latitude: 31.84, height: 120 },
    { longitude: 117.19, latitude: 31.84, height: 120 },
    { longitude: 117.19, latitude: 31.85, height: 120 }
  ],
  takeoffPoint: { longitude: 117.18, latitude: 31.84, height: 30 },
  routeHeight: 120,
  autoFlightSpeed: 10,
  inclinedFlightSpeed: 10,
  globalTransitionalSpeed: 10,
  takeOffSecurityHeight: 20,
  finishAction: 'goHome',
  collectionMode: 'ortho',
  shootType: 'distance',
  margin: 0,
  direction: 90,
  smartObliqueGimbalPitch: -45,
  orthoCameraOverlapH: 80,
  orthoCameraOverlapW: 70,
  inclinedCameraOverlapH: 80,
  inclinedCameraOverlapW: 70,
  area: 12345
})

5.3 带状 WASM 生成 generateBeltWaylineByWasm

函数签名：

generateBeltWaylineByWasm(options: GenerateStripWaylineOptions): Promise<any>

必填参数（GenerateStripWaylineOptions）

| 参数 | 类型 | 说明 | | --- | --- | --- | | routePoints | { longitude:number; latitude:number; height?:number }[] | 中心线点，至少 2 个 | | routeHeight | number | 执行航高 | | autoFlightSpeed | number | 全局航线速度 | | globalTransitionalSpeed | number | 过渡速度 | | takeOffSecurityHeight | number | 安全起飞高度 | | finishAction | 'goHome' \| 'noAction' \| 'autoLand' \| 'gotoFirstWaypoint' | 完成动作 | | shootType | 'time' \| 'distance' | 拍照模式 | | orthoCameraOverlapH | number | 航向重叠率 | | orthoCameraOverlapW | number | 旁向重叠率 | | elevationOptimizeEnable | 0 \| 1 | 高程优化开关 | | singleLineEnable | 0 \| 1 | 单航线/弓字航线 | | leftExtend | number | 左外扩 | | rightExtend | number | 右外扩 | | cuttingDistance | number | 切割距离 | | stripDirection | 0 \| 90 | 航线方向（0 平行中心线，90 垂直中心线） |

可选参数

| 参数 | 类型 | 默认值 | | --- | --- | --- | | centerlineHeight | number | 30（当点高缺失时用于回退） | | droneEnumValue | number \| null | 77 | | droneSubEnumValue | number \| null | 1 | | payloadEnumValue | number \| null | 67 | | payloadSubEnumValue | number \| null | 2 |

示例

const stripRes = await generateBeltWaylineByWasm({
  routePoints: [
    { longitude: 117.18, latitude: 31.84, height: 30 },
    { longitude: 117.20, latitude: 31.85, height: 30 }
  ],
  centerlineHeight: 30,
  routeHeight: 120,
  autoFlightSpeed: 15,
  globalTransitionalSpeed: 15,
  takeOffSecurityHeight: 20,
  finishAction: 'goHome',
  shootType: 'time',
  orthoCameraOverlapH: 80,
  orthoCameraOverlapW: 70,
  elevationOptimizeEnable: 1,
  singleLineEnable: 0,
  leftExtend: 50,
  rightExtend: 50,
  cuttingDistance: 1000,
  stripDirection: 0
})

5.4 面状导出 exportAreaRouteWithTemplate

函数签名：

exportAreaRouteWithTemplate(
  data: AreaRouteParam,
  res: WaylineFileResultDaum[],
  hooks?: { upload?: (options: { file: File; waylineName: string }) => Promise<void> }
): Promise<{ file: File; blob: Blob; waylineName: string } | null>

必填参数

| 参数 | 类型 | 说明 | | --- | --- | --- | | data.waylineName | string | 导出文件名 | | data.polygonPoints | { longitude:number; latitude:number; height:number }[] | 面顶点，至少 3 个 | | data.routeHeight | number | 航高 | | data.imageFormat | string[] | 图片格式，如 ['wide'] | | res | WaylineFileResultDaum[] | 面状 WASM/legacy 生成结果里的 flight_routes |

常用可选参数

• data.takeoffPoint
• data.finishAction
• data.flyToWaylineMode
• data.takeOffSecurityHeight
• data.autoFlightSpeed
• data.globalTransitionalSpeed
• data.droneEnumValue / data.droneSubEnumValue / data.droneKey

示例（含上传回调）

const exportRes = await exportAreaRouteWithTemplate(areaData, flightRoutes, {
  upload: async ({ file, waylineName }) => {
    // 接入你的上传接口
    console.log(file.name, waylineName)
  }
})

5.5 带状导出 exportBeltRouteWithWasm

函数签名：

exportBeltRouteWithWasm(
  data: BeltRouteParam,
  wasmResult: any,
  hooks?: { upload?: (options: { file: File; waylineName: string; templateData?: string | null; waylineId?: string | null }) => Promise<void> }
): Promise<{ file: File; blob: Blob; waylineName: string }>

必填参数

| 参数 | 类型 | 说明 | | --- | --- | --- | | data.waylineName | string | 导出文件名 | | data.takeoffPoint | { longitude:number; latitude:number; height:number } | 起飞点 | | data.routePoints | { longitude:number; latitude:number; height:number }[] | 中心线点，至少 2 个 | | data.beltWidth | number | 带宽 | | data.routeHeight | number | 航高 | | data.imageFormat | string[] | 图片格式 | | wasmResult | any | generateBeltWaylineByWasm 的返回值 |

常用可选参数

• data.finishAction
• data.heightMode
• data.customConfig（导出模板覆盖）
  • takeOffSecurityHeight
  • autoFlightSpeed
  • globalTransitionalSpeed
  • globalRTHHeight
  • elevationOptimizeEnable
  • shootType
  • direction
  • singleLineEnable
  • leftExtend/rightExtend
  • cuttingDistance
  • orthoCameraOverlapH/W
  • droneEnumValue / droneSubEnumValue / payloadEnumValue / payloadSubEnumValue

示例（含上传回调）

const exportRes = await exportBeltRouteWithWasm(stripData, stripRes, {
  upload: async ({ file, waylineName }) => {
    console.log(file.name, waylineName)
  }
})

5.6 航点导出 exportWaypointWaylineFiles

函数签名：

exportWaypointWaylineFiles(
  data: WaypointRouteExportParam,
  hooks?: { upload?: (options: { file: File; templateData: string; waylineId?: string | null }) => Promise<void> }
): Promise<{ file: File; blob: Blob; waylineName: string }>

必填参数（WaypointRouteExportParam）

| 参数 | 类型 | 说明 | | --- | --- | --- | | templateType | 'waypoint' \| 'mapping2d' \| 'mapping3d' \| 'mappingStrip' | 模板类型 | | data | IPositions[] | 航点数组 | | waylineConfig | IModalForm | 航线配置 | | newWaylineModal | newWaylineModalType | 新建弹窗配置快照 |

常用可选参数

• droneKey
• waylineName

IPositions[] 必备字段

每个航点至少包含：

• id: string
• position: [number, number, number]
• edited: boolean
• actions: { photos?: Array<{ lng; lat; height; heading; pitch; cameraPitch; roll; fov; near; far; aspectRatio; type? }> }

IModalForm 必备字段（建议按类型完整传）

• imageFormat
• orientedPhotoMode
• flyToWaylineMode
• takeOffSecurityHeight
• heightMode
• globalHeight
• autoFlightSpeed
• globalTransitionalSpeed
• waypointTurnMode
• waypointHeadingMode
• gimbalPitchMode
• finishAction
• takeoffPosition
• droneEnumValue
• droneSubEnumValue

示例

const exportRes = await exportWaypointWaylineFiles(xmlParam, {
  upload: async ({ file, templateData }) => {
    console.log(file.name, templateData)
  }
})

5.7 照片数估算 estimateWasmWaylinePhotoCount

函数签名：

estimateWasmWaylinePhotoCount(wayline: WasmWaylineLike): number

适用于带状/面状生成后，基于 WASM 输出的 wayline 结构估算照片数。

6. 返回值说明

导出类 API 返回统一结构：

{
  file: File      // 可直接上传/下载
  blob: Blob      // 二进制内容
  waylineName: string
}

7. 兼容别名（不推荐新代码使用）

• getXml：等价 exportWaypointWaylineFiles
• generateAreaWaylineLegacyByWasm：等价 generateAreaWaylineByWasm
• generateStripWaylineByWasm：等价 generateBeltWaylineByWasm

8. 构建

npm install
npm run build

npm pack 会自动触发 prepack 构建，发布内容仅包含 dist。