X1

X1 单目双轴旋转式视觉位移计 API 参考手册

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

X1 是单目双轴旋转式视觉位移计，支持水平和垂直云台控制及自动巡航。

1. 快速开始

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

2. API 列表

基础 API

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

标靶管理 API

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

测量控制 API

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

电机控制 API

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

ISP 控制 API

方法说明
ispCtlISP 图像参数控制（曝光、降噪、翻转/镜像等）

巡航查询 API

方法说明
getCruisePaths获取巡航路径

3. API 详情

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

initRefTargets

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

Protobuf / JSON 示例。

addTargets

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

Protobuf / JSON 示例。

getTargets

获取当前标靶列表。

响应字段：

字段类型说明
targets[].targetIdString标靶 ID，1-64 字节，非空，不包含控制字符
targets[].sensorIdInteger视觉传感器 ID，单目设备为 0
targets[].roiObject标靶 ROI 区域
targets[].distanceFloat测量距离，单位 m
targets[].roleString标靶角色：MP 为被测点，RP 为稳定基准点，CP 为控制/校核点
targets[].targetModelString标靶型号，取值 T10、T20、T50、T100、T200
targets[].skipMeasurementBoolean是否跳过测量

Protobuf / JSON 示例。

setTargets

更新已有标靶的配置。

Protobuf / JSON 示例。

deleteTargets

删除指定标靶。

Protobuf / JSON 示例。

setMotorAngle

设置电机角度。

参数：

字段类型范围说明
panFloat-180 ~ 180水平角度 (°)
tiltFloat-90 ~ 90垂直角度 (°)
speedInteger1-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}}

ispCtl

ISP 图像参数控制，支持曝光、降噪、画面翻转/镜像/旋转等设置。

getStatus - 获取当前 ISP 状态

请求：

{"reqId": 1, "method": "ispCtl", "params": {
  "action": "getStatus"
}}

响应：

{"reqId": 1, "code": 0, "data": {
  "vdmModeEnabled": true,
  "exposureLocked": false,
  "exposureMode": "manual",
  "nrLevel": "mediumNoise",
  "enable3dnr": true,
  "exposurePreset": "medium",
  "cameraCount": 1,
  "flip": false,
  "mirror": false,
  "rotation": 0,
  "exposureInfo": {
    "iso": 200,
    "expTime": 20000,
    "aGain": 1024,
    "dGain": 1024,
    "ispDGain": 256,
    "aveLum": 128
  }
}}

setConfig - 设置画面翻转/镜像/旋转

支持画面翻转、镜像和旋转。

注意：翻转/镜像/旋转设置需要重启设备后生效。 设置后配置会自动持久化，多相机设备（如双目型号）所有相机会同时生效。

参数：

字段类型必填说明
flipBoolean否画面垂直翻转
mirrorBoolean否画面水平镜像
rotationInteger否画面旋转角度，仅支持 0/90/180/270

请求 - 启用垂直翻转：

{"reqId": 1, "method": "ispCtl", "params": {
  "action": "setConfig",
  "config": {
    "flip": true
  }
}}

请求 - 启用水平镜像：

{"reqId": 1, "method": "ispCtl", "params": {
  "action": "setConfig",
  "config": {
    "mirror": true
  }
}}

请求 - 同时启用翻转和镜像（等效 180° 旋转）：

{"reqId": 1, "method": "ispCtl", "params": {
  "action": "setConfig",
  "config": {
    "flip": true,
    "mirror": true
  }
}}

请求 - 恢复默认（关闭翻转和镜像）：

{"reqId": 1, "method": "ispCtl", "params": {
  "action": "setConfig",
  "config": {
    "flip": false,
    "mirror": false
  }
}}

请求 - 设置旋转 90°：

{"reqId": 1, "method": "ispCtl", "params": {
  "action": "setConfig",
  "config": {
    "rotation": 90
  }
}}

请求 - 设置旋转 270°：

{"reqId": 1, "method": "ispCtl", "params": {
  "action": "setConfig",
  "config": {
    "rotation": 270
  }
}}

请求 - 取消旋转：

{"reqId": 1, "method": "ispCtl", "params": {
  "action": "setConfig",
  "config": {
    "rotation": 0
  }
}}

响应：

{"reqId": 1, "code": 0}

setConfig - 设置曝光参数

参数：

字段类型必填说明
exposureModeString否曝光模式：auto, semiAuto, manual
manualExpTimeInteger否手动曝光时间 (微秒)，范围 100-100000
manualAgainInteger否手动模拟增益，1024=1x, 4096=4x, 8192=8x
nrLevelString否降噪等级：off, lowNoise, mediumNoise, highNoise, veryHighNoise
enable3dnrBoolean否是否启用 3DNR 时域降噪

请求 - 手动曝光 20ms + 4x 增益：

{"reqId": 1, "method": "ispCtl", "params": {
  "action": "setConfig",
  "config": {
    "exposureMode": "manual",
    "manualExpTime": 20000,
    "manualAgain": 4096
  }
}}

setConfig - 多相机独立配置

通过 isp 数组对每个相机独立配置曝光参数。

参数（isp 数组项）：

字段类型必填说明
cameraIdInteger是相机索引 (0, 1, …)
expTimeInteger否曝光时间 (微秒)，范围 1000-40000
gainInteger否增益，范围 1024-16384
flipBoolean否画面垂直翻转（重启后生效）
mirrorBoolean否画面水平镜像（重启后生效）
rotationInteger否画面旋转角度 0/90/180/270（重启后生效）

请求：

{"reqId": 1, "method": "ispCtl", "params": {
  "action": "setConfig",
  "isp": [
    {"cameraId": 0, "expTime": 20000, "gain": 4096, "flip": true, "mirror": false}
  ]
}}

setExposurePreset - 设置曝光档位

参数：

字段类型必填说明
exposurePresetString是档位：low, medium, high
档位曝光时间增益场景
low10ms1x近距离/强 IR 补光
medium20ms1x标准模式
high30ms10x远距离/弱 IR 补光

请求：

{"reqId": 1, "method": "ispCtl", "params": {
  "action": "setExposurePreset",
  "exposurePreset": "medium"
}}

4. 遥测数据

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

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