X2-H

X2-H 双目双轴旋转式视觉位移计 API 参考手册

型号: X2-H | 版本: 1.0 | 更新: 2026-09-11

X2-H 系列是双目双轴旋转式视觉位移计，支持双轴云台和自动巡航，适用于多点巡航监测场景。

1. 快速开始

连接与数据接收见快速入门。完整代码见 GitHub SDK 和告警接入示例。

2. 典型工作流程

定点测量

使用 setMotorAngle 移动到测量位置。
调用 initRefTargets 初始化该位置可见的标靶，等待 event 中的 REF_INIT_RESULT 成功结果。
调用 startMeasurement，从 telemetry Topic 接收位移数据。

3. API 列表

基础 API

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

标靶管理 API

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

测量控制 API

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

电机控制 API

方法	说明
`setMotorAngle`	设置电机角度
`getMotorAngle`	获取电机角度
`setMotorZero`	设置电机零点
`enableMotor`	启用电机
`disableMotor`	禁用电机

巡航查询 API

方法	说明
`getCruisePaths`	获取巡航路径

4. API 详情

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

initRefTargets

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

参数：

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

注意： X2-H 4M 分辨率为 2560×1440，ROI 坐标需相应调整。

Protobuf / JSON 示例。

addTargets

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

Protobuf / JSON 示例。

getTargets

获取当前标靶列表。

响应字段：

字段	类型	说明
`targets[].targetId`	String	标靶 ID，1-64 字节，非空，不包含控制字符
`targets[].sensorId`	Integer	视觉传感器 ID，双目设备为 `0` 或 `1`
`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	是否跳过测量

Protobuf / JSON 示例。

setTargets

更新已有标靶的配置。

Protobuf / JSON 示例。

deleteTargets

删除指定标靶。

Protobuf / JSON 示例。

setMotorAngle

设置电机角度。

参数：

字段	类型	范围	说明
`pan`	Float	-180 ~ 180	水平角度 (°)
`tilt`	Float	-90 ~ 90	垂直角度 (°)
`speed`	Integer	1-100	转动速度 (%)

请求：

{"reqId": 1, "method": "setMotorAngle", "params": {"pan": 45.0, "tilt": -10.0, "speed": 50}}

getMotorAngle

获取当前电机角度。

请求：

{"reqId": 1, "method": "getMotorAngle", "params": {}}

响应：

{"reqId": 1, "code": 0, "data": {"pan": 45.0, "tilt": -10.0}}

setAttr

reportMetrics 支持 dx、dy。

指标	说明
`dx`	X方向累积位移变化
`dy`	Y方向累积位移变化

Protobuf / JSON 示例。

5. 遥测数据

设备通过 vdm/{deviceId}/telemetry 上报位移和设备状态；环境字段按设备传感器能力提供。字段、单位及 Protobuf / JSON 示例见遥测数据。

6. 公共告警、事件和错误

告警生命周期和强类型字段见告警上报。
告警抓拍图像包格式和 ACK 流程见告警抓拍图像包分块 Header。
事件类型及明细字段见事件上报。
外层响应使用统一数值错误码：code=0 成功，任意非零码均为失败，见错误码。