文档首页/ 云地图服务 KooMap/ API参考/ API/ 空间定位/ 视觉定位 - StartVps
更新时间：2025-10-22 GMT+08:00
查看PDF
分享

视觉定位 - StartVps

功能介绍

视觉定位是根据图像耦合GPS数据确定设备的位置的一项技术。首先通过拍摄一系列具有已知位置的图像并分析它们的关键视觉特征（例如建筑物或桥梁的轮廓）来创建地图，以创建这些视觉特征的大规模且可快速搜索的索引。将设备图像中的特征与索引中的特征进行比较，可获得目标设备的位姿。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见权限和授权项。

URI

POST /v1/algo/vps

请求参数

表1 请求Header参数

参数

是否必选

参数类型

描述

X-Trace-Id

否

String

参数解释：

追踪请求ID。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

App-Id

否

String

参数解释：

可选项，场景模板分配的app_id。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

Uuid

是

String

参数解释：

设备或者用户唯一标识。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

X-Auth-Token

否

String

参数解释：

IAM Token，和Authorization二选一必传。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

Authorization

否

String

参数解释：

AK/SK签名结果，和X-Auth-Token二选一必传。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表2 请求Body参数

参数

是否必选

参数类型

描述

payload

是

payload object

参数解释：

客户端发送给服务器的数据，包含用户相关信息、相机内参、IMU（惯性测量单元）内参、GPS定位相关信息、SLAM（Simultaneous Localization and Mapping，即同时定位与地图构建）的相关信息。

约束限制：

不涉及。
表3 payload

参数

是否必选

参数类型

描述

user

是

user object

参数解释：

用户相关信息。

约束限制：

不涉及。

camera

是

camera object

参数解释：

相机内参，在计算机视觉和图像处理中，描述相机如何将三维世界映射到二维图像平面的一组参数。

约束限制：

不涉及。

imu

是

Array of imu objects

参数解释：

IMU内参。用于测量和报告一个物体的特定力、角速度以及在某些情况下，磁场周围物体的方向的设备。

约束限制：

不涉及。

gps

是

Array of gps objects

参数解释：

GPS相关信息，用户确定其地理位置的经纬度。

约束限制：

不涉及。

slam

是

Array of slam objects

参数解释：

SLAM即同时定位与建图，是一种让机器人在未知环境中进行自主导航和建图的技术。在SLAM中，机器人使用传感器数据来确定自己在环境中的位置，并同时构建环境的地图。

约束限制：

不涉及。
表4 user

参数

是否必选

参数类型

描述

vpsMode

否

String

参数解释：

VPS的运行模式 。

约束限制：

选取特定参数 。

取值范围：

  • Offline：离线模式。

  • LocalMode：本地模式。

  • FullMode：全功能模式。

  • TrackingMode：跟踪模式。

默认取值：

不涉及。

vpsType

否

String

参数解释：

VPS的定位方法，目前支持GVPS。

约束限制：

字符串类型选，取特定参数。

取值范围：

  • GVPS：通用。

  • DVPS：数字视频。

  • LODVPS：卫星。

默认取值：

不涉及。

requestType

否

Integer

参数解释：

请求的设备类型 。

约束限制：

选取特定参数 。

取值范围：

  • 0：安卓手机。

  • 1：IOS手机。

  • 2：安卓web端。

  • 3：IOS web端。

  • 4：AR眼镜 。

默认取值：

0。

image

是

String

参数解释：

base64编码的图片信息 。

约束限制：

不涉及。

取值范围：

不涉及 。

默认取值：

不涉及。
表5 camera

参数

是否必选

参数类型

描述

fx

是

Float

参数解释：

相机内参，沿着x轴的焦距fx，单位为像素。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

fy

是

Float

参数解释：

相机内参，沿着y轴的焦距fy，单位为像素。

约束限制：

不涉及 。

取值范围：

不涉及。

默认取值：

不涉及。

cx

是

Integer

参数解释：

相机内参，相机光心沿x轴的坐标，单位为像素。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

cy

是

Integer

参数解释：

相机内参，相机光心沿y轴的坐标，单位为像素。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表6 imu

参数

是否必选

参数类型

描述

accuracy

是

Double

参数解释：

表示IMU测量的误差值，数值越小表示测量结果越准确。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

azimuth

是

Double

参数解释：

方位角，表示物体绕垂直轴的旋转角度。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

roll

是

Double

参数解释：

横滚角，表示物体绕前进轴的旋转角度。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

pitch

是

Double

参数解释：

俯仰角，表示物体绕水平轴的旋转角度。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

qx

是

Double

参数解释：

四元数的x轴方向的虚部分量。它与旋转轴在x轴方向上的投影有关。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

qy

是

Double

参数解释：

四元数的y轴方向的虚部分量。它与旋转轴在y轴方向上的投影有关。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

qz

是

Double

参数解释：

四元数的z轴方向的虚部分量。它与旋转轴在z轴方向上的投影有关。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

qw

是

Double

参数解释：

四元数的实部qw通常与旋转的余弦值相关。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表7 gps

参数

是否必选

参数类型

描述

longitude

是

Double

参数解释：

经度，正值表示东经，负值表示西经。

约束限制：

不涉及。

取值范围：

-180° ~ 180°。

默认取值：

不涉及。

latitude

是

Double

参数解释：

纬度，正值表示北纬，负值表示南纬。

约束限制：

不涉及。

取值范围：

-90° ~ 90°。

默认取值：

不涉及。

accuracy

是

Float

参数解释：

误差值，表示位置数据的不确定性半径。数值越小表示GPS测量的精度越高。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表8 slam

参数

是否必选

参数类型

描述

x

是

Double

参数解释：

位置坐标参数，在三维空间中的前后位置。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

y

是

Double

参数解释：

位置坐标参数，在三维空间中的上下位置。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

z

是

Double

参数解释：

位置坐标参数，在三维空间中的左右位置。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

qx

是

Double

参数解释：

四元数的x轴方向的虚部分量。它与旋转轴在x轴方向上的投影有关。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

qy

是

Double

参数解释：

四元数的y轴方向的虚部分量。它与旋转轴在y轴方向上的投影有关。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

qz

是

Double

参数解释：

四元数的z轴方向的虚部分量。它与旋转轴在z轴方向上的投影有关。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

qw

是

Double

参数解释：

四元数的实部qw通常与旋转的余弦值相关。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

响应参数

状态码：200

表9 响应Header参数

参数

参数类型

描述

X-Trace-Id

String

参数解释：

追踪请求ID。

取值范围：

不涉及。
表10 响应Body参数

参数

参数类型

描述

utmcode

String

参数解释：

地区UTM编码，用于地理空间数据的编码，表示服务区域的特定位置。

取值范围：

不涉及。

isCalibrationSucc

Boolean

参数解释：

是否启用在线云标定。

取值范围：

  • false：否

  • true：是

cacheData

String

参数解释：

缓存数据，用于存储会话信息或临时数据。

取值范围：

不涉及。

pose

pose object

参数解释：

位姿信息，包含姿态矩阵和位置信息。

取值范围：

不涉及。

requestId

String

参数解释：

请求ID，用于标识和追踪特定的服务请求。

取值范围：

不涉及。

couplingTime

Integer

参数解释：

根据云端负载建议端侧重定位时间（单位ms）。

取值范围：

不涉及。

vpsMode

Integer

参数解释：

建议预检测模式。

取值范围：

  • 0：gvps

  • 1：lod

processMode

String

参数解释：

云端处理模式。

取值范围：

  • gvps：高精视觉定位。

  • lodvps：模型视觉定位。

vpsFloor

Integer

参数解释：

楼层信息，表示服务所在的楼层编号。

取值范围：

不涉及。

VpsCode

Integer

参数解释：

状态码，用于表示服务的状态或结果。

取值范围：

  • 0：成功。

  • 1：无法提供服务。

  • 2：相机位姿错误。

  • 3：低置信度。

  • 4：GPS位置错误。

  • 5：图像错误。

  • 6：语义错误。

  • -1：内部错误。

retry

Integer

参数解释：

限制端侧手动单击的时间间隔（单位ms）。

取值范围：

不涉及。

status

String

参数解释：

请求结果是否成功。

取值范围：

  • succeeded：成功

  • failed：失败
表11 pose

参数

参数类型

描述

r

Array of floats

参数解释：

VPS姿态矩阵，按照左上到右下排列。

取值范围：

不涉及。

t

Array of floats

参数解释：

VPS位置，包含X、Y、Z三个浮点数，代表在空间中的位置。

取值范围：

不涉及。

confidence

Double

参数解释：

VPS结果置信度。

取值范围：

0~1，1表示完全置信。

K

Array of floats

参数解释：

在线云标定默认内参，包含相机的焦距和光心坐标。

取值范围：

不涉及。

请求示例

vps请求体示例，image信息xxx需改为图片base64编码。

POST https://{Endpoint}.com/v1/algo/vps

{
  "payload" : {
    "user" : {
      "vpsType" : "GVPS",
      "vpsMode" : "FullMode",
      "requestType" : 3,
      "image" : "xxx"
    },
    "camera" : {
      "fx" : 1120,
      "fy" : 1120,
      "cx" : 720,
      "cy" : 540
    },
    "slam" : [ {
      "x" : "3457914.888789408",
      "y" : "43.618999587185016",
      "z" : "-366678.1012069998",
      "qx" : "-0.6027525895972902",
      "qy" : "0.6696625505117437",
      "qz" : "-0.31343264698264584",
      "qw" : "0.30000227171514465",
      "mode" : "0",
      "index" : "4"
    } ],
    "imu" : [ {
      "azimuth" : "38.6508926149583",
      "pitch" : "-3.3327073554530315",
      "roll" : "85.58219500612942",
      "qx" : "0.6383440820986672",
      "qy" : "-0.25189259238432615",
      "qz" : "-0.21407681135529025",
      "qw" : "0.6951532824524337",
      "accuracy" : "0"
    } ],
    "gps" : [ {
      "longitude" : "xxx",
      "latitude" : "xxx",
      "accuracy" : "12"
    } ]
  }
}

响应示例

无

状态码

状态码

描述

200

空间定位服务请求成功。

错误码

请参见错误码。

父主题： 空间定位

相关文档