图传绘制
一、功能介绍
图传绘制能把标注框、区域、文字实时叠加到 Pilot 的图传画面上。与 AR 投射不同,它以归一化坐标(画面宽高的 0~1 百分比)定位,不依赖真实经纬度,适合把算法在画面上识别到的目标框、感兴趣区域直接绘制回图传上。每类图形通过「传一份新列表整体替换、传空列表清除」的方式刷新。
1.1 能力总览
| 图传绘制能力 | 描述 |
|---|---|
| 绘制框 | 在画面上叠加矩形框和标签,常用于目标框选 |
| 绘制区域 | 在画面上叠加实心多边形区域 |
| 绘制文字 | 在画面指定锚点叠加多行文字 |
1.2 应用场景
- 目标检测:把算法识别到的目标以矩形框 + 标签绘制到画面
- 区域告警:在画面上圈出感兴趣 / 危险区域
- 信息叠加:在画面角落叠加状态文字(如坐标、计数)
二、接口调用示例
以下示例假设你已完成 SDK 初始化,且插件与 Pilot 已连接就绪(连接状态获取见插件连接状态文档)。所有接口都通过管理器单例 CameraViewDrawingManager.getInstance() 调用。
三类绘制的调用模式一致:每次传入一份完整列表,整体替换画面上该类图形;传入空列表即清除该类图形。 坐标均为归一化值——矩形用中心点百分比坐标,多边形 / 文字用 0~1 的点。
2.1 绘制框(updateDrawingBoxInfo)
val drawingManager = CameraViewDrawingManager.getInstance() // 获取管理器单例
val box = DrawingBoxInfo().apply {
rect = OpenDoubleRect(0.5, 0.5, 0.2, 0.3) // 中心点(0.5,0.5),宽0.2高0.3(均为画面百分比)
label = "Target" // 框上标签文字
color = 0xFFFF0000.toInt() // 框线颜色(红)
labelColor = 0xFFFFFFFF.toInt() // 标签文字颜色(白)
}
drawingManager.updateDrawingBoxInfo(listOf(box), object : CommonCallbacks.CompletionCallback {
override fun onSuccess() { /* 已更新画面上的框 */ }
override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})
// 清除所有框:传空列表
drawingManager.updateDrawingBoxInfo(emptyList(), callback)
效果预览:

2.2 绘制区域(updateDrawingPolygonInfo)
多边形至少需要 3 个顶点才会绘制,系统自动闭合。顶点用归一化 OpenPoint(x、y 均为 0~1):
val polygon = DrawingPolygonInfo().apply {
points = listOf( // 至少 3 个点,自动闭合
OpenPoint(0.3, 0.3),
OpenPoint(0.7, 0.3),
OpenPoint(0.5, 0.7)
)
fillColor = 0x3300FF00.toInt() // 半透明绿填充
strokeWidth = 2f // 轮廓线宽(0 表示无轮廓)
strokeColor = 0xFF00FF00.toInt() // 轮廓颜色
label = "Zone A"
}
drawingManager.updateDrawingPolygonInfo(listOf(polygon), object : CommonCallbacks.CompletionCallback {
override fun onSuccess() { /* 已更新区域 */ }
override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})
// 清除所有区域:传空列表
drawingManager.updateDrawingPolygonInfo(emptyList(), callback)
2.3 绘制文字(updateDrawingTextInfo)
文字以归一化锚点定位,支持用 \n 换行:
val text = DrawingTextInfo().apply {
anchor = OpenPoint(0.05, 0.05) // 归一化锚点(画面左上角附近)
this.text = "Lat: 22.58\nLng: 113.94" // 支持 \n 多行
textSize = 14f // 字号(sp)
textColor = 0xFFFFFFFF.toInt() // 文字颜色(白)
backgroundColor = 0x80000000.toInt() // 背景色(半透明黑,alpha=0 则不绘制背景)
horizontalAlignment = DrawingTextInfo.ALIGN_LEFT // 水平对齐:LEFT / CENTER / RIGHT
}
drawingManager.updateDrawingTextInfo(listOf(text), object : CommonCallbacks.CompletionCallback {
override fun onSuccess() { /* 已更新文字 */ }
override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})
// 清除所有文字:传空列表
drawingManager.updateDrawingTextInfo(emptyList(), callback)
horizontalAlignment 的可选值:
| 常量 | 值 | 效果 |
|---|---|---|
ALIGN_LEFT | 0 | 左对齐(默认) |
ALIGN_CENTER | 1 | 居中对齐 |
ALIGN_RIGHT | 2 | 右对齐 |
效果预览:

三、API 参考
以下接口方法的完整定义(含入参数据模型)请查看 API 文档:ICameraViewDrawingManager。
ICameraViewDrawingManager 是图传绘制管理接口总入口,对外开放以下方法:
| 项 | 说明 |
|---|---|
ICameraViewDrawingManager | 图传绘制管理接口总入口 |
updateDrawingBoxInfo | 更新绘制框(传空列表清除) |
updateDrawingPolygonInfo | 更新绘制区域(传空列表清除) |
updateDrawingTextInfo | 更新绘制文字(传空列表清除) |
四、Sample 源码获取
五、常见问题(FAQ)
Q1:怎么清除画面上已绘制的图形?
给对应方法传空列表即可清除该类图形。三类图形相互独立:updateDrawingBoxInfo(emptyList()) 只清框,不影响区域和文字。
Q2:坐标应该传像素还是百分比?
全部是归一化坐标:矩形的 OpenDoubleRect 用画面宽高的百分比(中心点 x、y 及宽、高均为 0~1);多边形与文字的 OpenPoint 也是 0~1。这样画面分辨率变化时标注位置自动适配。
Q3:多边形传了 2 个点,为什么没画出来?
多边形至少需要 3 个顶点才会绘制。少于 3 个点时系统不生成图形。请确保 points 至少含 3 个点。
Q4:文字设了 backgroundColor 却没有背景?
当 backgroundColor 的 alpha 通道为 0(如 0x00000000)时不绘制背景。需要背景请给一个不透明或半透明的值(如 0x80000000)。
附录:错误码速查
| 错误码常量 | 触发场景 | 处理建议 |
|---|---|---|
REMOTE_DISCONNECTED | 连接未就绪时调用 | 等连接状态 CONNECTED 后重试 |