VDM-X2W

X2W/X2W4M 双目旋转式视觉位移计 API 参考手册

型号: X2W / X2W4M | 版本: 1.0 | 更新: 2026-01-08

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

1. API 列表

基础 API

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

标靶管理 API

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

测量控制 API

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

存储 API

方法	说明
`getStorageInfo`	获取存储信息
`queryTelemetry`	查询历史数据
`uploadS3`	上传数据到 S3

电机控制 API

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

巡航控制 API

方法	说明
`getCruisePaths`	获取巡航路径
`setCruisePoint`	设置巡航点
`removeCruisePoint`	移除巡航点
`startPatrol`	启动巡航
`stopPatrol`	停止巡航
`getPatrolStatus`	获取巡航状态

2. API 详情

initRefTargets

双目设备需要指定 sensorId 参数。

参数：

字段	类型	必填	说明
`targets`	Array	是	标靶配置
`targets[].targetId`	String	否	标靶 ID
`targets[].sensorId`	Integer	是	视觉传感器 ID (0 或 1)
`targets[].roi`	Object	是	ROI 区域
`targets[].distance`	Float	是	测量距离 (m)

请求（X2W）：

{"reqId": 1, "method": "initRefTargets", "params": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 1200, "y": 600, "width": 400, "height": 400}, "distance": 5.0}
  ]
}}

请求（X2W4M）：

{"reqId": 1, "method": "initRefTargets", "params": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 500, "y": 300, "width": 200, "height": 200}, "distance": 5.0},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 600, "y": 350, "width": 200, "height": 200}, "distance": 5.0}
  ]
}}

注意： X2W4M 分辨率为 2560×1440，ROI 坐标需相应调整。

addTargets

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

请求：

{"reqId": 1, "method": "addTargets", "params": {
  "targets": [
    {"targetId": "3", "sensorId": 0, "roi": {"x": 800, "y": 400, "width": 400, "height": 400}, "distance": 6.0}
  ]
}}

响应：

{"reqId": 1, "code": 0, "data": {"addedIds": ["3"]}}

getTargets

获取当前标靶列表。

请求：

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

响应：

{"reqId": 1, "code": 0, "data": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0, "status": "tracking"},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 1200, "y": 600, "width": 400, "height": 400}, "distance": 5.0, "status": "tracking"}
  ]
}}

setTargets

更新已有标靶的配置。

请求：

{"reqId": 1, "method": "setTargets", "params": {
  "targets": [{"targetId": "1", "distance": 5.5}]
}}

deleteTargets

删除指定标靶。

请求：

{"reqId": 1, "method": "deleteTargets", "params": {
  "targetIds": ["2"]
}}

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}}

setCruisePoint

设置巡航点。

参数：

字段	类型	必填	说明
`pathId`	Integer	是	路径 ID
`pointId`	Integer	是	巡航点 ID
`pan`	Float	是	水平角度
`tilt`	Float	是	垂直角度
`targets`	Array	是	标靶 ID 列表
`dwellTime`	Integer	否	停留时间 (秒)

请求：

{"reqId": 1, "method": "setCruisePoint", "params": {
  "pathId": 1,
  "pointId": 1,
  "pan": 45.0,
  "tilt": -10.0,
  "targets": ["1", "2"],
  "dwellTime": 60
}}

setAttr

支持配置 3D 融合上报指标。

请求：

{"reqId": 1, "method": "setAttr", "params": {
  "reportMetrics": ["dx", "dy", "dz", "tilt"]
}}

指标	说明
`dx`	X方向累积位移变化
`dy`	Y方向累积位移变化
`dz`	Z方向累积位移变化
`tilt`	倾斜角度变化

3. 遥测数据

测量运行时，设备按采样频率上报位移数据。

主题： vdm/{deviceId}/telemetry

{"disp":{"t":1734567890,"d":{"1":{"dx":[0.01,0.02],"dy":[0.00,0.01],"dz":[0.01,0.02],"tilt": 0.01}}}}

字段	单位	说明
`t`	秒	Unix 时间戳
`dx`	mm	X方向累积位移变化
`dy`	mm	Y方向累积位移变化
`dz`	mm	Z方向累积位移变化
`tilt`	″（角秒）	倾斜角度变化

4. 告警数据

位移超限时通过 3A 主题上报。

主题： vdm/{deviceId}/3A

{
  "3A": "DISPLACEMENT_EXCEEDED",
  "level": 2,
  "targetId": "1",
  "value": 12.5,
  "threshold": 10.0,
  "ts": 1734567890
}

告警级别：

级别	名称	说明
0	-	恢复
1	alert	预警
2	alarm	告警
3	action	紧急

5. 事件数据

设备状态变化时通过 event 主题上报。

主题： vdm/{deviceId}/event

{
  "event": "cruisePointReached",
  "ts": 1734567890,
  "data": {"pathId": 1, "pointId": 1}
}

事件类型：

事件	说明	data 内容
`measurementStarted`	测量开始	`{}`
`measurementStopped`	测量停止	`{}`
`TARGET_LOST`	标靶丢失	`{"targetId": "1"}`
`targetRecovered`	标靶恢复	`{"targetId": "1"}`
`motorMoved`	电机移动完成	`{"pan": 45.0, "tilt": -10.0}`
`cruisePointReached`	到达巡航点	`{"pathId": 1, "pointId": 1}`

6. 错误码

码	说明
0	成功
1	参数无效
2	缺少必填参数
100	标靶不存在
102	标靶初始化失败
104	标靶丢失
200	测量未启动
201	测量已在运行
300	电机不可用
302	电机运动中
303	电机到达限位
400	巡航功能不可用
403	巡航已在运行

7. 典型工作流程

多点巡航监测

1. 设置巡航点 1 (pan=0, tilt=0)
   └─ 初始化标靶 1, 2

2. 设置巡航点 2 (pan=45, tilt=-10)
   └─ 初始化标靶 3

3. 启动巡航
   └─ 设备自动在各点之间循环
   └─ 每个点停留 dwellTime 秒进行测量

4. 接收遥测数据
   └─ 位移数据包含当前巡航点的标靶

8. 快速开始

1. 移动到位置

{"reqId": 1, "method": "setMotorAngle", "params": {"pan": 0, "tilt": 0}}

2. 初始化标靶

{"reqId": 2, "method": "initRefTargets", "params": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0}
  ]
}}

3. 设置巡航点

{"reqId": 3, "method": "setCruisePoint", "params": {
  "pathId": 1, "pointId": 1, "pan": 0, "tilt": 0, "targets": ["1", "2"], "dwellTime": 60
}}

4. 启动测量

{"reqId": 4, "method": "startMeasurement", "params": {}}