AR 投射

2026-11-05评分加载中…

一、功能介绍

AR 投射能把标注实时绘制到无人机的图传画面上,让操控者在实景视频里直观看到目标点、警戒线、禁飞区等信息。所有标注都以真实经纬高(WGS-84)为坐标锚点,系统会根据云台姿态、镜头焦距和飞行器位置,自动把它们投影到图传画面的对应像素上,实现「标注跟随视角自然移动」。

在 Pilot 上叠加空间标注有两种途径:AR 投射(本文)把标注绘制到图传画面(第一人称视角,标注不做持久化);地图控件把标注绘制到地图(俯视二维、可持久化,见地图控件文档)。两者面向不同视图,可同时使用。本文聚焦 AR 投射。

1.1 能力总览

AR 能力描述
AR 点在指定位置投射图标和文字
AR 线在指定位置投射带端点的折线
AR 面在指定位置投射多边形面或立面体
AR 圆在指定位置投射圆或圆柱体
AR 雷达扫描范围在图传画面中绘制飞行器的雷达扫描范围

1.2 应用场景

AR 投射适用于需要把空间信息实时叠加在图传画面上的场景,例如:

  • 电力线巡检:标出杆塔位置
  • 森林火情:圈出可疑热源区域
  • 边境巡逻:绘出巡逻线路
  • 工地安全:标出临时禁飞区域

二、接口调用示例

以下示例假设你已完成 SDK 初始化,且插件与 Pilot 已连接就绪。

2.0 上传 SVG 图标(前置)

AR 点用到的 SVG 图标必须先通过 IFileTransferManager 上传,上传后以文件名作为服务端唯一标识(例如后续代码中 "star_max.svg")。上传流程参见文件传输文档。

AR 图标必须是 SVG,提交前至少满足以下必备项:

  • 用 SVG 格式,单位只用 px 或不写。
  • 每个图形元素的 id 带状态后缀(_normal / _select × _color / _bg);需要外部动态染色(withIconColor)时,id 中必须包含 _normal_color。
  • 颜色只用 #RRGGBB / rgb() / 命名色;不要用 currentColor(它会被渲染成灰色,无法染色)。
<!-- ✅ 正确示例:支持染色(id 含 _normal_color,颜色用 #RRGGBB) -->
<g id="my_icon_normal_color">
  <path d="M12 2L2 22h20L12 2z" fill="#FF0000"/>
</g>

<!-- ❌ 错误示例:id 中没有状态后缀,落入兜底层,不能染色、选中时消失 -->
<g id="my_icon">...</g>

完整的格式、画布尺寸、图层命名、颜色写法、镂空等要求与自查清单,见 AR 图标 SVG 规范。

后续示例假设已上传 star_max.svg / star_min.svg 两个图标。

2.1 添加 AR 点(uploadARPointConfig + uploadARPointInfo)

AR 点采用两阶段模型:由 ARPointConfig 与 ARPointInfo 两个对象共同定义。可以用印章来类比:

  • ARPointConfig(配置)= 印章模板——刻好的图案和字体样式,决定「盖出来长什么样」。一枚印章可以反复盖很多次。
  • ARPointInfo(信息)= 每一次盖章——决定「盖在纸的哪个位置、旁边写什么字」。每个 Info 通过 configId 引用某枚「印章」。

所以流程天然是「先做印章、再盖章」:必须先上传配置、拿到 configId,再用它构建信息并上传。下图是两者的字段结构:

一个配置可被多个信息复用(一枚印章盖多处),因此下面分两步。(AR 线 / 面 / 圆只有一个 Info 对象、无独立配置,但它们的端点仍是 AR 点,使用端点时同样需要预先准备好配置。)

Step 1:上传 Config(「长什么样」)

val arManager = ARManager.getInstance()                         // 获取管理器单例

val config = ARPointConfig.Builder.builder()
    .withUseText(true)                                          // 是否叠加文字
    .withTextConfig(
        ARTextConfig.Builder.builder()
            .withTextSize(40f)                                  // 字号(dp)
            .withFontGravity(ARFontGravity.TOP)                 // 文字位于图标上方
            .build()
    )
    .withArProjectionType(ARIconProjectionType.PERSPECTIVE)     // 近大远小
    .withIconPerspectiveConfig(
        ARIconPerspectiveConfig.Builder.builder()
            .withRealSize(3f)                                   // 真实世界大小(米)
            .withMinSize(60f).withMaxSize(180f)                 // 屏幕像素上下限
            .withMaxIconFileName("star_max.svg")                // 近距离用大图
            .withMinIconFileName("star_min.svg")                // 远距离用小图
            .build()
    )
    .build()

arManager.uploadARPointConfig(config, object : CommonCallbacks.CompletionCallbackWithParam<String> {
    override fun onSuccess(configId: String) {
        // configId 即该配置的服务端 id,后续每个 ARPointInfo 都用它引用本配置(见 Step 2)
    }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

withArProjectionType 指定图标的投影方式,可选值如下:

枚举效果适用场景
PERSPECTIVE近大远小(透视投影),像素大小随距离变化表达真实物理尺寸的物体:车、人、建筑
ORTHOGRAPHIC固定像素大小(正交投影),不受距离影响需要恒定视觉大小的标记:航点、目标点
NONE不显示图标,仅显示文字纯文字标注

若选 ORTHOGRAPHIC,上面的 withIconPerspectiveConfig(...) 改为传 withIconOrthographicConfig(...),其内部只需 withSize(80f) + withIconFileName("xxx.svg") 两项。

Step 2:用 configId 上传 Info(「画在哪里」)

拿到 Step 1 回调返回的 configId 后,用它构建 ARPointInfo 并上传:

val point = ARPointInfo.Builder.builder()
    .withConfigId(configId)                                     // Step 1 回调返回的 configId
    .withVisible(true).withIconVisible(true).withTextVisible(true)
    .withShowEdgeGuide(true)                                    // 出屏时在屏幕边缘给方向提示
    .withText("Target A")
    .withTextColor(0xFF2D8CF0.toInt())                          // 蓝
    .withIconColor(0xFFFFA500.toInt())                          // 橙(SVG 需含 _normal_color 才生效)
    .withLocation(OpenLocation(0.0, 0.0, 60.0))                 // TODO: 替换为你的实际坐标(纬度, 经度, 海拔米)
    .build()

arManager.uploadARPointInfo(point, object : CommonCallbacks.CompletionCallbackWithParam<String> {
    override fun onSuccess(id: String) { /* 服务端赋予的 id,已同步到 point.id */ }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

注意: 保留 point 对象引用,后续 update / delete 都要用到(详见 2.6)。

效果预览:

AR 点

2.2 添加 AR 线(uploadARLineInfo)

AR 线由若干端点连接而成,每个端点复用 ARPointInfo(因此也需要预先准备好 configId)。

// 1. 准备两个端点(复用 2.1 的 configId)
val p1 = ARPointInfo.Builder.builder()
    .withConfigId(configId)
    .withVisible(true).withIconVisible(true).withTextVisible(true)
    .withText("A")
    .withLocation(OpenLocation(0.0, 0.0, 50.0))                 // TODO: 替换为端点 A 实际坐标
    .build()

val p2 = ARPointInfo.Builder.builder()
    .withConfigId(configId)
    .withVisible(true).withIconVisible(true).withTextVisible(true)
    .withText("B")
    .withLocation(OpenLocation(0.0, 0.0, 50.0))                 // TODO: 替换为端点 B 实际坐标
    .build()

// 2. 构造线段样式:颜色 + 距离-宽度映射
val stroke = ARStrokeInfo.Builder.builder()
    .withColor(0xFF000000.toInt())                              // 黑色实线
    .withDistLineWidth(
        ARDistLineWidth.Builder.builder()
            .withMaxLineWidth(20f).withMaxWidthDist(30f)        // 30 米内线宽 20 px
            .withMinLineWidth(5f).withMinWidthDist(60f)         // 60 米外线宽 5 px
            .build()
    )
    .withIsDash(false)
    .build()

// 3. 组装并上传
val line = ARLineInfo.Builder.builder()
    .withPoints(listOf(p1, p2))                                 // 端点顺序即连线顺序
    .withStrokeInfo(stroke)
    .withUseDepth(false)                                        // false = 不受地形/物体遮挡
    .build()

arManager.uploadARLineInfo(line, object : CommonCallbacks.CompletionCallbackWithParam<String> {
    override fun onSuccess(id: String) { /* 成功;line.id 已被赋值 */ }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

常见变体:

  • 端点 ARPointInfo 的 visible / iconVisible / textVisible 决定端点自身是否可见;线段本体总是可见(由 strokeInfo 控制样式)。
  • 虚线:withIsDash(true)。
  • 多段线:withPoints(listOf(p1, p2, p3, p4, ...)),按顺序连接。

效果预览:

AR 线

2.3 添加 AR 面(uploadARPolygonInfo)

AR 面由 ≥3 个端点组成的多边形底面 + 沿高度方向拉伸出的柱体构成,含顶面、侧面、底面三个 ARPolygonFace。

// 1. 三角形三个顶点(复用 2.1 的 configId)
val p1 = ARPointInfo.Builder.builder().withConfigId(configId)
    .withVisible(true).withIconVisible(false).withTextVisible(true).withText("A")
    .withLocation(OpenLocation(0.0, 0.0, 50.0))                 // TODO: 顶点 A
    .build()
val p2 = ARPointInfo.Builder.builder().withConfigId(configId)
    .withVisible(true).withIconVisible(false).withTextVisible(true).withText("B")
    .withLocation(OpenLocation(0.0, 0.0, 50.0))                 // TODO: 顶点 B
    .build()
val p3 = ARPointInfo.Builder.builder().withConfigId(configId)
    .withVisible(true).withIconVisible(false).withTextVisible(true).withText("C")
    .withLocation(OpenLocation(0.0, 0.0, 50.0))                 // TODO: 顶点 C
    .build()

// 2. 侧面填充(正/背面双色),顶/底面用默认空 Builder 即可
val sideFace = ARPolygonFace.Builder.builder()
    .withVisible(true)
    .withFrontFaceColor(0x3374C0FC.toInt())                     // 半透明蓝(正面)
    .withBackFaceColor(0x33FFFFFF.toInt())                      // 半透明白(背面)
    .build()
val emptyFace = ARPolygonFace.Builder.builder().withVisible(false).build()

// 3. 组装并上传
val polygon = ARPolygonInfo.Builder.builder()
    .withPoints(listOf(p1, p2, p3))                             // 至少 3 个点
    .withExtrusionAnchor(OpenLocation(0.0, 0.0, 0.0))           // 柱体底面锚点,(0,0,0) 表示不额外偏移
    .withSideFace(sideFace)                                     // 只显示侧面
    .withTopFace(emptyFace).withBottomFace(emptyFace)
    .withIs3dMesh(false)
    .build()

arManager.uploadARPolygonInfo(polygon, object : CommonCallbacks.CompletionCallbackWithParam<String> {
    override fun onSuccess(id: String) { /* 成功 */ }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

常见变体:

  • 若希望顶 / 底面也有填充,把 emptyFace 替换成配好色的 ARPolygonFace。
  • 需要面边线(描边)时可传 withSideFaceStroke(ARFaceStroke.Builder.builder().withVisible(true).withStroke(strokeInfo).build())。
  • withFaceDistAlpha(...) 可设置面的透明度随距离变化(近距离更清晰、远距离更淡)。

效果预览:

AR 多边形

2.4 添加 AR 圆(uploadARCircleInfo)

AR 圆结构与 AR 面类似,但底面是圆而不是多边形,只需要圆心 + 半径。

// 1. 圆的样式:填充 + 边线
val face = ARPolygonFace.Builder.builder()
    .withVisible(true)
    .withFrontFaceColor(0x3374C0FC.toInt())                     // 半透明蓝
    .withBackFaceColor(0x33FFFFFF.toInt())                      // 半透明白
    .build()

val stroke = ARStrokeInfo.Builder.builder()
    .withColor(0xFF2D8CF0.toInt())                              // 蓝色边线
    .withDistLineWidth(
        ARDistLineWidth.Builder.builder()
            .withMaxLineWidth(12f).withMaxWidthDist(50f)
            .withMinLineWidth(3f).withMinWidthDist(100f)
            .build()
    )
    .withIsDash(false)
    .build()
val edge = ARFaceStroke.Builder.builder().withVisible(true).withStroke(stroke).build()

// 2. 距离-透明度映射(远处更透明,避免遮挡视野)
val distAlpha = ARDistAlpha.Builder.builder()
    .withEnable(true)
    .withMinDist(30f).withMinAlpha(0.3f)                        // 30 米内 alpha=0.3
    .withMaxDist(60f).withMaxAlpha(0.8f)                        // 60 米外 alpha=0.8
    .build()

// 3. 组装并上传
val circle = ARCircleInfo.Builder.builder()
    .withCenter(OpenLocation(0.0, 0.0, 30.0))                   // TODO: 替换为实际圆心坐标
    .withRadius(20f)                                            // 底面半径 20 米
    .withExtrusionAnchor(OpenLocation(0.0, 0.0, 0.0))           // 柱体底面锚点
    .withTopFace(face).withSideFace(face).withBottomFace(face)  // 三面同色
    .withTopFaceStroke(edge).withSideFaceStroke(edge).withBottomFaceStroke(edge)
    .withFaceDistAlpha(distAlpha)
    .withFaceStrokeDistAlpha(distAlpha)
    .build()

arManager.uploadARCircleInfo(circle, object : CommonCallbacks.CompletionCallbackWithParam<String> {
    override fun onSuccess(id: String) { /* 成功 */ }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

常见变体:

  • 圆台效果:额外调用 .withTRadius(30f),与 radius 不同即形成圆台;不设或 ≤0 自动等于 radius(正圆柱)。
  • 只画一个圆环:把 topFace / bottomFace 的 visible 设为 false,只留 sideFace。

效果预览:

AR 圆

2.5 开关 AR 雷达(enableARRadar)

雷达用于在图传画面上显示当前云台的水平扫描范围(扇形),全局仅一份配置生效。

// 启用:enable=true,label 为空字符串则不显示文字标签
val enable = ARRadarConfig.Builder.builder()
    .withEnable(true)
    .withLabel("Front Radar")
    .build()
arManager.enableARRadar(enable, object : CommonCallbacks.CompletionCallback {
    override fun onSuccess() { /* 已开启 */ }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

// 关闭:同一方法,传 enable=false 的配置即可
arManager.enableARRadar(
    ARRadarConfig.Builder.builder().withEnable(false).build(),
    object : CommonCallbacks.CompletionCallback {
        override fun onSuccess() { /* 已关闭 */ }
        override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
    }
)

效果预览:

AR 雷达扫描范围

2.6 查询 / 更新 / 删除(CRUD 通用模式)

前面 2.1 ~ 2.4 讲了「增」(upload),本节讲剩下的查、改、删。四类几何元素(点 / 线 / 面 / 圆)的 CRUD 完全同构:把方法名里的 ARPolygon 换成 ARPoint / ARLine / ARCircle、把数据模型对应替换即可。下面统一以 AR 面为例。

① 查询(queryARPolygonInfo)

查询返回服务端当前所有 AR 面,常用于「拿到对象再改 / 删」或页面重建时回显:

arManager.queryARPolygonInfo(object : CommonCallbacks.CompletionCallbackWithParam<List<ARPolygonInfo>> {
    override fun onSuccess(list: List<ARPolygonInfo>) {
        // list 中每个对象的 id 都是服务端有效 id,可直接用于后续 update / delete
    }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

② 更新(updateARPolygonInfo)

推荐「query → 改字段 → update」:直接修改从服务端拿到的对象,再传回。服务端按 id 匹配,其余字段按新值整体覆盖(详见 Q4)。下例把平面多边形沿高度方向拉伸成多棱柱——只需改 extrusionAnchor 的高度分量:

// 1. 从服务端拉取当前列表
arManager.queryARPolygonInfo(object : CommonCallbacks.CompletionCallbackWithParam<List<ARPolygonInfo>> {
    override fun onSuccess(list: List<ARPolygonInfo>) {
        // 2. 找到目标对象(此处按 name 匹配,业务里也可用 id / 其他字段)
        val target = list.firstOrNull { it.name == "demo_polygon" } ?: return

        // 3. 直接改字段:把底面沿高度拉伸 40m,平面多边形 → 多棱柱
        target.extrusionAnchor = OpenLocation(0.0, 0.0, 40.0)   // 高度分量即拉伸高度(米)

        // 4. 传回 update
        arManager.updateARPolygonInfo(target, object : CommonCallbacks.CompletionCallback {
            override fun onSuccess() { /* 更新成功,画面上多边形变为棱柱 */ }
            override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
        })
    }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

改面的填充色 / 描边 / 顶底面显隐同理——直接改 target.topFace / target.sideFaceStroke 等字段再 update 即可。

注意: 不要重新 Builder.build() 一个新对象再传给 update——那样会生成新 id,服务端找不到匹配,回调 AR_POLYGON_INFO_NOT_FOUND(详见 Q3)。

③ 删除(deleteARPolygonInfo)

删除只按 id 定位,直接把 query 拿到的对象整体传回即可(其他字段忽略):

// target 为 query 返回的某个 ARPolygonInfo
arManager.deleteARPolygonInfo(target, object : CommonCallbacks.CompletionCallback {
    override fun onSuccess() { /* 删除成功 */ }
    override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})

接口没有「删全部」的批量方法。要清空某类元素,遍历 query 结果依次 deleteXxxInfo 即可。

效果预览(update 前后:多边形拉伸为多棱柱):

AR 多边形投射

update 前:AR 多边形投射

AR 多棱柱投射

update 后:AR 多棱柱投射

三、API 参考

以下接口方法的完整定义(含入参数据模型、枚举)请查看 API 文档:IARManageropen in new window。

接口

IARManager 是 AR 管理接口总入口,对外开放以下方法:

项说明
IARManagerAR 管理接口总入口
queryARPointConfig查询 AR 点配置
uploadARPointConfig上传 AR 点配置(一个配置可对应多个 AR 点)
queryARPointInfo查询 AR 点信息
uploadARPointInfo上传 AR 点信息
updateARPointInfo更新 AR 点信息
deleteARPointInfo删除 AR 点信息
queryARLineInfo查询 AR 线信息
uploadARLineInfo上传 AR 线信息
updateARLineInfo更新 AR 线信息
deleteARLineInfo删除 AR 线信息
queryARPolygonInfo查询 AR 面信息
uploadARPolygonInfo上传 AR 面信息
updateARPolygonInfo更新 AR 面信息
deleteARPolygonInfo删除 AR 面信息
queryARCircleInfo查询 AR 圆信息
uploadARCircleInfo上传 AR 圆信息
updateARCircleInfo更新 AR 圆信息
deleteARCircleInfo删除 AR 圆信息
enableARRadar设置 AR 雷达扫描范围配置(enable=false 关闭)

四、Sample 源码获取

AR 投射 Sampleopen in new window


五、常见问题(FAQ)

Q1:为什么 AR 点必须先上传 Config 才能上传 Info?

ARPointConfig 定义外观模板(图标 SVG、文字样式、投影方式),ARPointInfo 定义位置和内容。将两者拆开的收益:

  • 一个 Config 可被成百上千个 Info 复用(如「所有电力杆」都用同一个星形图标 Config),网络传输和内存都省
  • 想统一改所有点的图标,只需 update Config 一次,不需要遍历所有 Info

AR 线 / 面 / 圆 本身没有独立 Config(因为线宽、面填充这些字段直接嵌在 Info 里),但它们内部的端点仍然是 ARPointInfo,所以只要用了端点,就得先有 Config。

Q2:上传 SVG 图标后不显示 / 颜色不生效?

按下列顺序排查:

  1. SVG 是否推送到 Pilot? 必须先通过 IFileTransferManager.pushFileToRemote 把文件推过去,然后可用 queryFileListFromRemote 验证
  2. 图层命名是否带状态后缀? 每个图形元素的 id 需带 _normal / _select × _color / _bg 后缀;缺后缀会落入兜底层,既不能染色、选中时也会消失
  3. 染色是否生效? 需要用 withIconColor 染色时,id 必须包含 _normal_color,且颜色用 #RRGGBB 等支持的写法;不要用 currentColor,它会被渲染成灰色、无法染色(规则见 AR 图标 SVG 规范)
  4. 文件名大小写是否完全一致? Pilot 端的文件系统区分大小写

Q3:调用 update / delete 返回 AR_POINT_INFO_NOT_FOUND?

根因:服务端按 id 匹配对象,而这个 id 是首次 upload 成功时才有意义。如果重新 Builder.build() 一个新对象,会得到一个本地临时 id,服务端从没见过它,因此报「未找到」。

// ❌ 错误:新 Builder 会生成新 id,服务端找不到
val newInfo = ARPointInfo.Builder.builder().withConfigId(cfg).withLocation(newLoc).build()
arManager.updateARPointInfo(newInfo, ...)   // AR_POINT_INFO_NOT_FOUND

// ✅ 正确:复用 upload 成功回调或 query 返回的对象
originalInfo.location = newLoc
arManager.updateARPointInfo(originalInfo, ...)

推荐做法:每次都从 queryXxxInfo 拉最新对象,改字段,再 update / delete(详见 2.6)。

Q4:update 时需要传全量字段吗?

服务端是「整体替换」,不是「字段合并」:update 后,服务端对该 id 的对象保存的就是你传过去的那个对象的所有字段。

所以最安全的写法是:先 query 拿到当前对象 → 改想改的字段 → 传回 update。这样没修改的字段会保持原值,不会被意外清空。

Q5:ARManager.getInstance() 什么时候可以调用?

单例本身随时可以获取,但内部 delegate 只有在 SDK 与 Pilot 建立 AIDL 连接后才被注入。在连接建立前调用任何方法都会立刻回调 REMOTE_DISCONNECTED 错误。

建议:在 Pilot 连接成功事件后再调用 AR 相关接口;或在业务代码里对每个回调处理 REMOTE_DISCONNECTED 的重试。

Q6:调用 upload 成功,但画面上看不到 AR 元素?

按下列顺序排查:

  1. visible 字段为 true 吗? withVisible(true) + withIconVisible(true) + withTextVisible(true) 三件套
  2. 位置在视锥外? 云台镜头不朝那个方向就看不到。开启 withShowEdgeGuide(true) 观察屏幕边缘是否有方向提示
  3. iconColor 是全透明的 0? 检查 ARGB 的 A 通道是否为 0(0x00000000)
  4. 距离-透明度设得太苛刻? ARDistAlpha 的 enable=true 且当前相机距离让 alpha 计算成了接近 0
  5. SVG 未推送(针对图标不显示):见 Q2

Q7:删除单个元素 vs 批量删除,delete 需要什么字段?

deleteXxxInfo 只用 info.id 定位服务端对象,其他字段可以为空。推荐直接把从 queryXxxInfo 拿到的对象整体传回去,最省心。

如果要「清空某类元素」,遍历 query 结果依次 delete 即可,接口本身没有「删全部」的批量方法。

附录:错误码速查

以下错误码来自 dji.open.pilot.base.error.RemoteError 与 CSDK 通用错误:

错误码常量触发场景处理建议
REMOTE_DISCONNECTEDPilot 端 AIDL 尚未连接等 Pilot 连接就绪后重试;见 Q5
AR_POINT_CONFIG_EXIST重复上传相同的 ARPointConfig 对象检查本地是否已缓存 configId,避免重复调用
AR_POINT_CONFIG_NOT_FOUNDuploadARPointInfo 时 configId 无效先确认 Config 已上传成功,用回调返回的 id
AR_POINT_INFO_EXIST重复上传同一 ARPointInfo 对象首次 upload 已保存到服务端,无需再传
AR_POINT_INFO_NOT_FOUNDupdate / delete 的 info id 在服务端不存在确认对象来源是 upload / query 返回的实例;见 Q3
AR_LINE_INFO_NOT_FOUND同上,AR 线同上
AR_POLYGON_INFO_NOT_FOUND同上,AR 面同上
AR_CIRCLE_INFO_NOT_FOUND同上,AR 圆同上
最近修改: