AR 投射
一、功能介绍
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)。
效果预览:

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, ...)),按顺序连接。
效果预览:

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(...)可设置面的透明度随距离变化(近距离更清晰、远距离更淡)。
效果预览:

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。
效果预览:

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() */ }
}
)
效果预览:

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 前后:多边形拉伸为多棱柱):


三、API 参考
以下接口方法的完整定义(含入参数据模型、枚举)请查看 API 文档:IARManager。
接口
IARManager 是 AR 管理接口总入口,对外开放以下方法:
| 项 | 说明 |
|---|---|
IARManager | AR 管理接口总入口 |
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 源码获取
五、常见问题(FAQ)
Q1:为什么 AR 点必须先上传 Config 才能上传 Info?
ARPointConfig 定义外观模板(图标 SVG、文字样式、投影方式),ARPointInfo 定义位置和内容。将两者拆开的收益:
- 一个 Config 可被成百上千个 Info 复用(如「所有电力杆」都用同一个星形图标 Config),网络传输和内存都省
- 想统一改所有点的图标,只需 update Config 一次,不需要遍历所有 Info
AR 线 / 面 / 圆 本身没有独立 Config(因为线宽、面填充这些字段直接嵌在 Info 里),但它们内部的端点仍然是 ARPointInfo,所以只要用了端点,就得先有 Config。
Q2:上传 SVG 图标后不显示 / 颜色不生效?
按下列顺序排查:
- SVG 是否推送到 Pilot? 必须先通过
IFileTransferManager.pushFileToRemote把文件推过去,然后可用queryFileListFromRemote验证 - 图层命名是否带状态后缀? 每个图形元素的
id需带_normal/_select×_color/_bg后缀;缺后缀会落入兜底层,既不能染色、选中时也会消失 - 染色是否生效? 需要用
withIconColor染色时,id必须包含_normal_color,且颜色用#RRGGBB等支持的写法;不要用currentColor,它会被渲染成灰色、无法染色(规则见 AR 图标 SVG 规范) - 文件名大小写是否完全一致? 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 元素?
按下列顺序排查:
visible字段为 true 吗?withVisible(true)+withIconVisible(true)+withTextVisible(true)三件套- 位置在视锥外? 云台镜头不朝那个方向就看不到。开启
withShowEdgeGuide(true)观察屏幕边缘是否有方向提示 iconColor是全透明的 0? 检查 ARGB 的 A 通道是否为 0(0x00000000)- 距离-透明度设得太苛刻?
ARDistAlpha的enable=true且当前相机距离让 alpha 计算成了接近 0 - SVG 未推送(针对图标不显示):见 Q2
Q7:删除单个元素 vs 批量删除,delete 需要什么字段?
deleteXxxInfo 只用 info.id 定位服务端对象,其他字段可以为空。推荐直接把从 queryXxxInfo 拿到的对象整体传回去,最省心。
如果要「清空某类元素」,遍历 query 结果依次 delete 即可,接口本身没有「删全部」的批量方法。
附录:错误码速查
以下错误码来自 dji.open.pilot.base.error.RemoteError 与 CSDK 通用错误:
| 错误码常量 | 触发场景 | 处理建议 |
|---|---|---|
REMOTE_DISCONNECTED | Pilot 端 AIDL 尚未连接 | 等 Pilot 连接就绪后重试;见 Q5 |
AR_POINT_CONFIG_EXIST | 重复上传相同的 ARPointConfig 对象 | 检查本地是否已缓存 configId,避免重复调用 |
AR_POINT_CONFIG_NOT_FOUND | uploadARPointInfo 时 configId 无效 | 先确认 Config 已上传成功,用回调返回的 id |
AR_POINT_INFO_EXIST | 重复上传同一 ARPointInfo 对象 | 首次 upload 已保存到服务端,无需再传 |
AR_POINT_INFO_NOT_FOUND | update / delete 的 info id 在服务端不存在 | 确认对象来源是 upload / query 返回的实例;见 Q3 |
AR_LINE_INFO_NOT_FOUND | 同上,AR 线 | 同上 |
AR_POLYGON_INFO_NOT_FOUND | 同上,AR 面 | 同上 |
AR_CIRCLE_INFO_NOT_FOUND | 同上,AR 圆 | 同上 |