V1

V1 单目固定式视觉位移计 API 参考手册

型号: V1 | 版本: 1.0 | 更新: 2026-09-28

V1 是单目固定式视觉位移计。

1. 快速开始

2. API 列表

基础 API

方法	说明
`getAttr`	获取属性
`setAttr`	设置属性
`reboot`	重启设备
`syncTime`	同步时间

标靶管理 API

方法	说明
`initRefTargets`	初始化标靶参考位置
`addTargets`	添加标靶
`getTargets`	获取标靶列表
`setTargets`	更新标靶配置
`deleteTargets`	删除标靶

测量控制 API

方法	说明
`startMeasurement`	启动测量
`stopMeasurement`	停止测量
`setLightLevel`	设置补光灯发光挡位
`getLightLevel`	获取补光灯发光挡位
`snapshot`	获取快照

3. API 详情

标靶管理 API 的完整字段约束参考 API参考。

getAttr

获取设备属性。不带 keys 参数时返回全部属性。

属性列表：

属性	类型	读写	说明
`deviceId`	String	R	设备 ID
`deviceModel`	String	R	型号
`fwVer`	String	R	固件版本
`resolution`	String	R	图像分辨率，通常为 `3840x2160`
`deviceStatus`	String	R	设备整体工作状态：`Initializing`、`Measuring`、`Idle`、`Testing`、`Calibrating`、`Sleeping`。休眠前上报 `Sleeping`，唤醒启动后上报 `Idle`
`measureStatus`	String	R	测量状态
`sampleFreq`	Integer	RW	采样频率 (整数 Hz，1-60)
`reportMetrics`	Array	RW	上报指标
`showROI`	Boolean	RW	告警抓拍图像是否叠加 ROI 标注
`showTs`	Boolean	RW	告警抓拍图像是否叠加时间戳
`showSensorId`	Boolean	RW	告警抓拍图像是否叠加视觉传感器 ID

标靶配置变化时，设备会通过 vdm/{deviceId}/attributes 上报只读 targets 摘要属性。单独调用 getTargets 只通过 RPC 响应返回；订阅方需要当前标靶快照时应调用 getTargets。targets 不是 setAttr 的可写字段，标靶配置请使用 addTargets、setTargets 或 deleteTargets，参考位置初始化使用 initRefTargets。

targets 摘要只包含 targetId、sensorId、roi、distance、role、targetModel、skipMeasurement、initialized、initializedAt 等对外字段。

Protobuf / JSON 示例。

setAttr

设置设备属性。

Protobuf / JSON 示例。

initRefTargets

对指定标靶执行参考位置初始化/标定。通常先通过 addTargets 或 setTargets 保存标靶配置；初始化时可只传 targetId。如需覆盖保存配置，可在本次请求中提供 roi、distance 或 targetModel。

参数：

字段	类型	必填	说明
`targets`	Array	是	要初始化标靶参考位置的标靶数组，不能为空
`targets[].targetId`	String	是	标靶 ID，1-64 字节，非空，不包含控制字符
`targets[].roi`	Object	否	ROI 区域；不传时使用已保存标靶配置
`targets[].distance`	Float	否	测量距离 (m)；不传时使用已保存标靶配置
`targets[].targetModel`	String	否	标靶型号，取值 `T10`、`T20`、`T50`、`T100`、`T200`

Protobuf / JSON 示例。

addTargets

在已有标靶基础上添加新标靶。

Protobuf / JSON 示例。

getTargets

获取当前标靶列表。

响应字段：

字段	类型	说明
`targets[].targetId`	String	标靶 ID，1-64 字节，非空，不包含控制字符
`targets[].sensorId`	Integer	视觉传感器 ID，单目设备为 `0`
`targets[].roi`	Object	标靶 ROI 区域
`targets[].distance`	Float	测量距离，单位 m
`targets[].role`	String	标靶角色：`MP` 为被测点，`RP` 为稳定基准点，`CP` 为控制/校核点
`targets[].targetModel`	String	标靶型号，取值 `T10`、`T20`、`T50`、`T100`、`T200`
`targets[].skipMeasurement`	Boolean	是否跳过测量
`targets[].initialized`	Boolean	是否已经初始化标靶参考位置
`targets[].initializedAt`	Integer \| Null	初始化标靶参考位置的 Unix 秒时间戳；未初始化或无记录时为 `null`