图传绘制

2026-11-05评分加载中…

一、功能介绍

图传绘制能把标注框、区域、文字实时叠加到 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_LEFT0左对齐(默认)
ALIGN_CENTER1居中对齐
ALIGN_RIGHT2右对齐

效果预览:

图传绘制


三、API 参考

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

ICameraViewDrawingManager 是图传绘制管理接口总入口,对外开放以下方法:

项说明
ICameraViewDrawingManager图传绘制管理接口总入口
updateDrawingBoxInfo更新绘制框(传空列表清除)
updateDrawingPolygonInfo更新绘制区域(传空列表清除)
updateDrawingTextInfo更新绘制文字(传空列表清除)

四、Sample 源码获取

图传绘制 Sampleopen in new window


五、常见问题(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 后重试
最近修改: