GB/T 45287-2025 信息技术 移动设备增强现实系统应用程序接口

ICS35.240.01
CCS L70
中华人民共和国国家标准
GB/T45287—2025
信息技术 移动设备增强现实系统
应用程序接口
Informationtechnology—Applicationprogramminginterfacesofthe
augmentedrealitysystemformobiledevices
2025-01-24发布2025-01-24实施
国家市场监督管理总局
国家标准化管理委员会发布

目 次
前言………………………………………………………………………………………………………… Ⅲ
1 范围……………………………………………………………………………………………………… 1
2 规范性引用文件………………………………………………………………………………………… 1
3 术语和定义……………………………………………………………………………………………… 1
4 缩略语…………………………………………………………………………………………………… 2
5 应用程序接口框架……………………………………………………………………………………… 2
6 数据类型………………………………………………………………………………………………… 3
6.1 返回结果…………………………………………………………………………………………… 3
6.2 设备类型…………………………………………………………………………………………… 3
6.3 数据流模式………………………………………………………………………………………… 4
6.4 节点类型…………………………………………………………………………………………… 4
6.5 算法类型…………………………………………………………………………………………… 4
6.6 算法模式…………………………………………………………………………………………… 4
6.7 可用性……………………………………………………………………………………………… 5
6.8 跟踪状态…………………………………………………………………………………………… 5
6.9 跟踪运行模式……………………………………………………………………………………… 5
6.10 世界坐标对齐模式………………………………………………………………………………… 6
6.11 顶点格式…………………………………………………………………………………………… 6
6.12 像素格式…………………………………………………………………………………………… 6
6.13 参数………………………………………………………………………………………………… 7
6.14 左右眼视角………………………………………………………………………………………… 7
6.15 光照估计模式……………………………………………………………………………………… 7
6.16 光照估计状态……………………………………………………………………………………… 7
6.17 求交查询模式……………………………………………………………………………………… 7
6.18 云锚点状态………………………………………………………………………………………… 8
6.19 平面类型…………………………………………………………………………………………… 8
6.20 手势类型…………………………………………………………………………………………… 9
6.21 左右手类型………………………………………………………………………………………… 9
6.22 手掌心朝向……………………………………………………………………………………… 10
7 应用程序接口…………………………………………………………………………………………… 10
7.1 功能地址…………………………………………………………………………………………… 10
7.2 能力检测…………………………………………………………………………………………… 10
7.3 位姿………………………………………………………………………………………………… 11
Ⅰ
GB/T45287—2025
7.4 配置………………………………………………………………………………………………… 12
7.5 增强现实会话……………………………………………………………………………………… 15
7.6 增强现实世界地图………………………………………………………………………………… 21
7.7 帧画面……………………………………………………………………………………………… 22
7.8 相机模型…………………………………………………………………………………………… 28
7.9 相机内参…………………………………………………………………………………………… 29
7.10 点云……………………………………………………………………………………………… 31
7.11 稠密重建………………………………………………………………………………………… 31
7.12 光照估计………………………………………………………………………………………… 33
7.13 锚点列表………………………………………………………………………………………… 34
7.14 锚点……………………………………………………………………………………………… 35
7.15 节点列表………………………………………………………………………………………… 36
7.16 节点……………………………………………………………………………………………… 37
7.17 平面节点………………………………………………………………………………………… 38
7.18 查询结果列表…………………………………………………………………………………… 40
7.19 查询结果………………………………………………………………………………………… 41
7.20 参考图数据库…………………………………………………………………………………… 42
7.21 图像节点………………………………………………………………………………………… 44
7.22 手势节点………………………………………………………………………………………… 45
Ⅱ
GB/T45287—2025
前 言
本文件按照GB/T1.1—2020《标准化工作导则 第1部分:标准化文件的结构和起草规则》的规定
起草。
请 注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。
本文件由全国信息技术标准化技术委员会(SAC/TC28)提出并归口。
本文件起草单位:浙江商汤科技开发有限公司、浙江大学、中国电子技术标准化研究院、厦门赛西科
技发展有限责任公司、山东大学、北京邮电大学、OPPO 广东移动通讯有限公司、北京津发科技股份有
限公司、海信视像科技股份有限公司、青岛理工大学、北京理工大学、深圳市安之眼科技有限公司、南昌
虚拟现实研究院股份有限公司、咪咕文化科技有限公司、中国石油大学(华东)、广州卓远虚拟现实科技
股份有限公司、联通沃音乐文化有限公司、希尔盛精密电子(昆山)有限公司、山东科洋工控自动化有限
公司、北京亮亮视野科技有限公司、珠海莫界科技有限公司、浙江威星电子系统软件股份有限公司、中影
年年(北京)科技有限公司、南京魔数团信息科技有限公司、湖北华中电力科技开发有限责任公司。
本文件主要起草人:盛崇山、章国锋、蒋慧、潘榕、李亚健、姜翰青、耿一丹、曾洁琪、康峰、陈成军、
王涌天、宋维涛、李寅、王乐、孙其民、毕蕾、乔秀全、姜军毅、秦学英、赵起超、曾翔宇、庞善臣、郑梦丽、
柯绍棠、林金怡、余育雄、彭福刚、赵伟、王兆民、彭德华、郭勇、王勇、徐韬。
Ⅲ
GB/T45287—2025

信息技术 移动设备增强现实系统
应用程序接口
1 范围
本文件规定了移动设备增强现实系统开发的数据类型和应用程序接口。
本文件适用于移动设备增强现实系统的设计和应用。
2 规范性引用文件
下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中,注日期的引用文
件,仅该日期对应的版本适用于本文件;不注日期的引用文件,其最新版本(包括所有的修改单)适用于
本文件。
GB/T38247—2019 信息技术 增强现实 术语
3 术语和定义
GB/T38247—2019界定的以及下列术语和定义适用于本文件。
3.1
增强现实系统 augmentedrealitysystem
通过跟踪注册、显示和交互,将计算机生成的虚拟信息与真实环境实时、有机融合的系统。
3.2
参考图像 referenceimage
在环境中可被识别的二维图像。
[来源:GB/T38247—2019,2.2.18]
3.3
增强现实会话 augmentedrealitysession
负责管理增强现实系统的整个运行过程。
注:包括创建、启动、更新、关闭、销毁等各个过程。
3.4
节点 node
增强现实运行过程中识别出的平面、图像、手势等具体对象信息。
3.5
点云 pointcloud
在增强现实应用中,用于恢复三维场景而使用的场景物体表面的三维点数据集合。
[来源:GB/T 38247—2019,2.2.47]
3.6
稠密网格 densemesh
稠密三维重建过程中,恢复的场景三角形网格。
1
GB/T45287—2025
4 缩略语
下列缩略语适用于本文件。
AR:增强现实(AugmentedReality)
FOV:视场角(FieldofView)
SDK:软件开发工具包(SoftwareDevelopmentKit)
SLAM:同步定位与地图构建(SimultaneousLocalizationAndMapping)
6DoF:六自由度(SixDegreesofFreedom)
5 应用程序接口框架
移动设备增强现实系统通过接口和结构来完成相关的功能。系统利用增强现实会话实现统一管
理,启动时设置系统的运行配置,运行过程中获取帧画面管理当前帧的图像信息;在线跟踪定位利用移
动设备的输入数据计算出相机模型和相机内参,并在运行过程中构建了增强现实世界地图;三维重建利
用尺度估计计算的尺度信息和在线跟踪定位计算的6DoF位姿等信息,计算出平面节点、点云和稠密网
格等。用户在同移动设备交互过程中,利用平面和网格信息,可生成锚点和查询结果;标志物识别跟踪
基于视频流识别跟踪图像节点;光照估计利用视频流实现解算全局光照估计信息;如果移动设备具备云
计算服务,还支持将数据通过网络传输到云服务端实现更高效率的云端重定位、云端标志物识别和云端
三维重建,并将解算结果传输回移动设备处理单元。移动设备增强现实系统应用程序接口框架见图1。
图1 移动设备增强现实系统应用程序接口框架
2
GB/T45287—2025
6 数据类型
6.1 返回结果
返回结果数据类型命名为ARResult,其值定义见表1。
表1 返回结果数据类型ARResult定义
ARResult值描述
ARRESULT_SUCCESS=0 成功或者正确
ARRESULT_ERROR_INVALID_ARGUMENT=-1 包含无效参数
ARRESULT_ERROR_FATAL=-2 严重错误
ARRESULT_ERROR_SESSION_PAUSED=-3 当前操作ARSession暂停状态错误
ARRESULT_ERROR_SESSION_NOT_PAUSED=-4 当前操作ARSession未暂停状态错误
ARRESULT_ERROR_NOT_TRACKING=-5 目前不处于跟踪状态导致的错误
ARRESULT_ERROR_TEXTURE_NOT_SET=-6 未设置纹理参数导致的错误
ARRESULT_ERROR_UNSUPPORTED_VIDEOFORMAT=-7 指定的视频格式不支持错误
ARRESULT_ERROR_CAMERA_NOT_AVAILABLE=-8 摄像机服务不可用错误
ARRESULT_ERROR_CAMERA_PERMISSION_NOT_GRANTED=-9 摄像机服务未授权导致的错误
ARRESULT_ERROR_UNSUPPORTED_CONFIG=-10 设置的配置选项不支持导致的错误
ARRESULT_ERROR_RESOURCE_EXHAUSTED=-11 没有可用资源导致的错误
ARRESULT_ERROR_CLOUD_ANCHORS_NOT_CONFIGURED=-12 没有对云锚点模式进行设置导致的错误
ARRESULT_ERROR_ANCHOR_NOT_SUPPORTED_FOR_HOSTING=-
13 该锚点不支持托管导致的错误
ARRESULT_ERROR_DEVICE_UNSUPPORT=-14 移动设备不支持增强现实导致的错误
ARRESULT_ERROR_ALGORITHM_UNSUPPORT=-15 使用不支持的算法导致的错误
ARRESULT_ERROR_APPLICATION_AUTHORIZED=-16 该应用未授权使用增强现实功能导致的错误
6.2 设备类型
设备类型数据类型命名为ARDeviceType,其值定义见表2。
表2 设备类型数据类型ARDeviceType定义
ARDeviceType值描述
ARDEVICE_TYPE_HANDHOLD=100 手持式移动设备
ARDEVICE_TYPE_HEADMOUNTED=200 头戴式移动设备
3
GB/T45287—2025
6.3 数据流模式
数据流模式数据类型命名为ARStreamMode,其值定义见表3。
表3 数据流模式数据类型ARStreamMode定义
ARStreamMode值描述
ARSTREAM_MODE_FRONT_RGB=100 数据流采用前置RGB相机模式
ARSTREAM_MODE_BACK_RGB=2000 数据流采用后置RGB相机模式
ARSTREAM_MODE_BACK_RGBD=2100 数据流采用后置RGBD相机模式
ARSTREAM_MODE_BACK_STEREO=2200 数据流采用后置立体相机模式
6.4 节点类型
节点类型数据类型命名为ARNodeType,其值定义见表4。
表4 节点类型数据类型ARNodeType定义
ARNodeType值描述
ARNODE_TYPE_UNKNOWN=-1 无效节点类型
ARNODE_TYPE_PLANE=1 平面节点类型
ARNODE_TYPE_IMAGE=2 图像节点类型
ARNODE_TYPE_HAND_GESTURE=3 手势节点类型
6.5 算法类型
算法类型数据类型命名为ARAlgorithmType,其值定义见表5。
表5 算法类型数据类型ARAlgorithmType定义
ARAlgorithmType值描述
ARALGORITHM_TYPE_UNKNOWN=-1 无效算法类型
ARALGORITHM_TYPE_SLAM=1 SLAM 算法类型
ARALGORITHM_TYPE_HAND_GESTURE=2 手势算法类型
ARALGORITHM_TYPE_DENSE_RECON=3 稠密网格重建算法类型
ARALGORITHM_TYPE_IMAGE_TRACKING=4 图像跟踪算法类型
ARALGORITHM_TYPE_PLANE_DETECTION=5 平面检测算法类型
ARALGORITHM_TYPE_ILLUMINATION_ESTIMATION=6 光照估计算法类型
ARALGORITHM_TYPE_CLOUD_ANCHOR=7 云锚点算法类型
6.6 算法模式
算法模式数据类型命名为ARAlgorithmMode,其值定义见表6。
4
GB/T45287—2025
表6 算法模式数据类型ARAlgorithmMode定义
ARAlgorithmMode值描述
ARALGORITHM_MODE_DISABLE=0 算法关闭模式
ARALGORITHM_MODE_ENABLE=1 算法激活模式
6.7 可用性
可用性数据类型命名为ARAvailability,其值定义见表7。
表7 可用性数据类型ARAvailability定义
ARAvailability值描述
ARAVAILABILITY_SUPPORTED=1 设备支持,并且可用
ARAVAILABILITY_UNKNOWN_ERROR=-1 未知错误
ARAVAILABILITY_UNSUPPORTED_DEVICE_NOT_CAPABLE=-100 设备不支持AR
ARAVAILABILITY_SUPPORTED_NOT_INSTALLED=—201 设备支持,模块未安装导致不可用
ARAVAILABILITY_SUPPORTED_VERSION_TOO_OLD=—202 设备支持,模块版本太旧导致不可用
6.8 跟踪状态
跟踪状态数据类型命名为ARTrackingState,其值定义见表8。
表8 跟踪状态数据类型ARTrackingState定义
ARTrackingState值描述
ARTRACKING_STATE_SUCCESS=0 正常跟踪状态
ARTRACKING_STATE_LOST=1 跟踪丢失状态
ARTRACKING_STATE_STOPPED=2 停止跟踪状态
ARTRACKING_STATE_INITIALIZING=10 跟踪初始化中状态
6.9 跟踪运行模式
跟踪运行模式数据类型命名为ARTrackingRunMode,其值定义见表9。
表9 跟踪运行模式数据类型ARTrackingRunMode定义
ARTrackingRunMode值描述
ARTRACKING_RUN_MODE_AUTO=0 自动跟踪模式,增强现实会话恢复运行后,算法自
动启动运行
ARTRACKING_RUN_MODE_MANUAL=1 手动跟踪模式,增强现实会话恢复运行后,算法默
认不启动,需要手动启动运行
5
GB/T45287—2025
6.10 世界坐标对齐模式
世界坐标对齐模式数据类型命名为ARWorldAlignmentMode,其值定义见表10。
表10 世界坐标对齐模式数据类型ARWorldAlignmentMode定义
ARWorldAlignmentMode值描述
ARWORLD_ALIGNMENT_MODE_GRAVITY0=0 根据初始化时候屏幕的朝向和重力方向构建
世界坐标系
ARWORLD_ALIGNMENT_MODE_GRAVITY_HEADING=1
根据指南针和重力方向构建世界坐标系,y 轴
同重力方向平行,(0,-1,0)朝下,z 轴同南北
方向平行,(0,0,1)指向所在位置的朝南方向
6.11 顶点格式
顶点格式数据类型命名为ARVertexFormat,其值定义见表11。
表11 顶点格式数据类型ARVertexFormat定义
ARVertexFormat值描述
ARVERTEX_FORMAT_UNKNOWN=-1 无效顶点数据
ARVERTEX_FORMAT_3D_POSITION=0 顶点数据包含3个float值,表示该点坐标
ARVERTEX_FORMAT_3D_POSITION_NORMAL=1 顶点数据包含6个float值,表示该点坐标和经过该
点的平面法线向量
ARVERTEX _ FORMAT _ 3D _ POSITION _ NORMAL _
COLOR=2
顶点数据包含10个float值,表示该点坐标、经过该
点的平面法线向量和该点的RGBA数据
6.12 像素格式
像素格式数据类型命名为ARPixelFormat,其值定义见表12。
表12 像素格式数据类型ARPixelFormat定义
ARPixelFormat值描述
ARPIXEL_FORMAT_UNKNOWN=-1 无效图像数据
ARPIXEL_FORMAT_LUMINANCE8=0 图像数据采用LUMINANCE8格式
ARPIXEL_FORMAT_RG16=1 图像数据采用RG16格式
ARPIXEL_FORMAT_RGB24=2 图像数据采用RGB24格式
ARPIXEL_FORMAT_RGBA32=3 图像数据采用RGBA32格式
ARPIXEL_FORMAT_DEPTH16=4 图像数据采用Depth16格式
ARPIXEL_FORMAT_YUV_NV21=1000 图像数据采用YUVNV21格式
6
GB/T45287—2025
6.13 参数
参数数据类型命名为ARParameterEnum,其值定义见表13。
表13 参数数据类型ARParameterEnum 定义
ARParameterEnum 值描述
ARPARAMETER_VIDEO_VERTICAL_FOV=50 视频垂直方向FOV
ARPARAMETER_ALGORITHM_SLAM_INFO=100 SLAM 算法运行信息
ARPRARMETER_ALGORITHM_SLAM_MAP_QUALITY=101 SLAM 地图质量
ARPARAMETER_ALGORITHM_SLAM_DETAIL_STATE=102 SLAM 算法内部详细的运行状态
ARPARAMETER_CAMERA_TEXTURE_TARGET=3000 视频流纹理标识
6.14 左右眼视角
左右眼视角数据类型命名为AREyeSide,其值定义见表14。
表14 左右眼视角数据类型AREyeSide定义
AREyeSide值描述
AREYE_LEFT=0 左眼视角
AREYE_RIGHT=1 右眼视角
6.15 光照估计模式
光照估计模式数据类型命名为ARIlluminationEstimateMode,其值定义见表15。
表15 光照估计模式数据类型ARIlluminationEstimateMode定义
ARIlluminationEstimateMode值描述
ARILLUMINATION_ESTIMATE_MODE_AMBIENT_INTENSITY=1 环境光亮度模式,包含单一亮度值
6.16 光照估计状态
光照估计状态数据类型命名为ARIlluminationEstimateState,其值定义见表16。
表16 光照估计状态数据类型ARIlluminationEstimateState定义
ARIlluminationEstimateState值描述
ARILLUMINATION_ESTIMATE_STATE_NOT_VALID=0 光照估计结果暂时不可用
ARILLUMINATION_ESTIMATE_STATE_VALID=1 光照估计结果可用
6.17 求交查询模式
求交查询模式数据类型命名为ARQueryMode,其值定义见表17。
7
GB/T45287—2025
表17 求交查询模式数据类型ARQueryMode定义
ARQueryMode值描述
ARQUERY_MODE_POLYGON_ONLY=0 只能跟多边形平面求交查询
ARQUERY_MODE_POLYGON_AND_HORIZONPLANE=1 能跟多边形平面以及水平多边形所在整个无限平
面求交查询
ARQUERY_MODE_POLYGON_PERSISTENCE=2 能跟多边形平面以及多边形平面所在的无限平面
求交查询,多边形平面优先
6.18 云锚点状态
云锚点状态数据类型命名为ARCloudAnchorState,其值定义见表18。
表18 云锚点状态数据类型ARCloudAnchorState定义
ARCloudAnchorState值描述
ARCLOUD_ANCHOR_STATE_NONE=0 该锚点不是云锚点
ARCLOUD_ANCHOR_STATE_TASK_IN_PROGRESS=1 正在托管或是解析中
ARCLOUD_ANCHOR_STATE_SUCCESS=2 托管或解析成功
ARCLOUD_ANCHOR_STATE_ERROR_INTERNAL=-1 托管或解析发生内部错误
ARCLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED=-2 托管或解析没有被授权
ARCLOUD_ANCHOR_STATE_ERROR_SERVICE_UNAVAILABLE=-3 当前服务不可用
ARCLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED=-4 资源已经被用尽
ARCLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_
FAILED=-5 云锚点数据错误,不能托管
ARCLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND=-6 该云锚点标识没有被找到
ARCLOUD_ANCHOR_STATE_ERROR_RESOLVING_LOCALIZATION_
NO_MATCH=-7 解析失败,环境无法匹配
ARCLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_
TOO_OLD=-8 解析锚点的SDK版本过旧
ARCLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_
TOO_NEW=-9 解析锚点的SDK版本过新
ARCLOUD_ANCHOR_STATE_ERROR_UNKNOWN=-11 未知错误
6.19 平面类型
平面类型数据类型命名为ARPlaneType,其值定义见表19。
8
GB/T45287—2025
表19 平面类型数据类型ARPlaneType定义
ARPlaneType值描述
ARPLANE_TYPE_UNKNOWN=-1 无效平面类型
ARPLANE_TYPE_UPWARD_FACING=0 水平朝上平面类型
ARPLANE_TYPE_DOWNWARD_FACING=1 水平朝下平面类型
ARPLANE_TYPE_VERTICAL=2 垂直平面类型
6.20 手势类型
手势类型数据类型命名为ARHandGestureType,其值定义见表20。
表20 手势类型数据类型ARHandGestureType定义
ARHandGestureType值描述
ARHAND_GESTURE_TYPE_UNKNOWN=-1 无效手势类型
ARHAND_GESTURE_TYPE_OK=0 OK手势类型
ARHAND_GESTURE_TYPE_SCISSORS=1 剪刀手势类型
ARHAND_GESTURE_TYPE_THUMBS_UP=2 竖起大拇指手势类型
ARHAND_GESTURE_TYPE_PAPER=3 布手势类型
ARHAND_GESTURE_TYPE_GUN=4 手枪手势类型
ARHAND_GESTURE_TYPE_ROCK=5 石头手势类型
ARHAND_GESTURE_TYPE_FINGER_HEART=6 比心手势类型
ARHAND_GESTURE_TYPE_FINGERTIP=7 指尖手势类型
ARHAND_GESTURE_TYPE_WELL_PLAYED=8 做得好手势类型
ARHAND_GESTURE_TYPE_THREE_FINGERS=9 3个手指手势类型
ARHAND_GESTURE_TYPE_FOUR_FINGERS=10 4个手指手势类型
ARHAND_GESTURE_TYPE_I_LOVE_YOU=11 我爱你手势类型
ARHAND_GESTURE_TYPE_INDEX_FINGER_AND_LITTLE_FINGER=12 竖起食指与小拇指手势类型
ARHAND_GESTURE_TYPE_LITTLE_FINGER=13 小拇指手势类型
6.21 左右手类型
左右手类型数据类型命名为ARHandType,其值定义见表21。
表21 左右手类型数据类型ARHandType定义
ARHandType值描述
ARHAND_TYPE_UNKNOWN=-1 无法区分左右手
ARHAND_TYPE_RIGHT=0 右手
ARHAND_TYPE_LEFT=1 左手
9
GB/T45287—2025
6.22 手掌心朝向
手掌心朝向数据类型命名为ARHandTowards,其值定义见表22。
表22 手掌心朝向数据类型ARHandTowards定义
ARHandTowards值描述
ARHAND_TOWARDS_UNKNOWN=-1 无效的手朝向
ARHAND_TOWARDS_PALM=0 手心方向
ARHAND_TOWARDS_THE_BACK_OF_HAND=1 手背方向
ARHAND_TOWARDS_SIDE_HAND=2 侧手方向
7 应用程序接口
7.1 功能地址
获取扩展函数地址
接口定义:PFN_arVoidFunctionarGetProcAddress(constchar* name)
功能描述:通过给定的字符串,获取功能扩展的函数指针。
输入参数:
类型:constchar*,值:函数指针的名字。
输出参数:
类型:PFN_arVoidFunction,值:typedefvoid (ARAPI_ PTR * PFN _arVoidFunction)
(void),定义了函数指针的类型,ARAPI_PTR定义的是调用方式,当无法获取到指定名
字的函数指针的时候,返回空指针。
注:符号“*”表示指针,用于声明一个指针变量或定义一个指针类型,后续出现的“*”也具有相同的含义,具体含
义随上下文而定。
7.2 能力检测
7.2.1 检测设备是否支持
接口定义:voidarCapabilityCheckAvailability(void*env,void*context,ARAvailability*out_
availability)
功能描述:检测设备是否支持运行增强现实模块。
输入参数:
类型:void*,值:运行环境。
类型:void*,值:运行上下文。
输出参数:
类型:ARAvailability*,值:是否可用,见表7定义。
7.2.2 检测是否支持算法
接口定义:ARResultarCapabilityCheckAlgorithm(void* env,void* context,ARAlgorithmType
type,ARStreamModemode)
10
GB/T45287—2025
功能描述:检测设备是否支持给定数据流模式的算法,返回ARRESULT_SUCCESS表示成功。
输入参数:
类型:void*,值:运行环境。
类型:void*,值:运行上下文。
类型:ARAlgorithmType,值:算法类型,见表5定义。
类型:ARStreamMode,值:数据流模式,见表3定义。
输出参数:
类型:ARResult,值:返回值,见表1定义。
7.2.3 检测是否授权
接口定义:ARResultarCapabilityCheckAuthorized(void* env,void*context,constchar* appId)
功能描述:检测应用程序是否授权运行增强现实模块,返回ARRESULT_SUCCESS表示成功。
输入参数:
类型:void*,值:运行环境。
类型:void*,值:运行上下文。
类型:constchar*,值:应用程序授权字符串。
输出参数:
类型:ARResult,值:返回值,见表1定义。
7.3 位姿
7.3.1 创建位姿
接口定义:voidarPoseCreate(constfloat* pose_raw,ARPose** out_pose)
功能描述:创建位姿结构,数组参数为6DoF信息(qx,qy,qz,qw,tx,ty,tz),数组长度为7。
输入参数:
类型:constfloat*,值:6DoF信息。
输出参数:
类型:ARPose**,值:创建新的位姿结构,结构地址保存到*out_pose中。
注:符号“**”表示指向指针的指针,用于传递可修改的指针,后续出现的“**”也具有相同的含义,具体含义随
上下文而定。
7.3.2 释放位姿
接口定义:voidarPoseDestroy(ARPose* pose)
功能描述:销毁位姿结构。
输入参数:
类型:ARPose*,值:位姿结构指针。
输出参数:不作定义。
7.3.3 获取位姿结构的6DoF信息
接口定义:voidarPoseGetPoseRaw(constARPose* pose,float* out_pose_raw)
功能描述:获取位姿结构对应的6DoF信息(qx,qy,qz,qw,tx,ty,tz),数组长度为7。
输入参数:
11
GB/T45287—2025
类型:constARPose*,值:位姿结构指针。
输出参数:
类型:float*,值:6DoF信息。
7.3.4 获取位姿结构的矩阵
接口定义:voidarPoseGetMatrix(constARPose* pose,float* out_matrix_col_major_4x4)
功能描述:获取位姿结构对应的4×4矩阵。
输入参数:
类型:constARPose*,值:位姿结构指针。
输出参数:
类型:float*,值:矩阵,该矩阵为列矩阵形式。
7.4 配置
7.4.1 创建配置
接口定义:voidarConfigCreate(ARConfig** out_config)
功能描述:创建配置结构。
输入参数:不做定义。
输出参数:
类型:ARConfig**,值:创建新的配置结构,结构地址保存到*out_config中。
7.4.2 销毁配置
接口定义:voidarConfigDestroy(ARConfig*config)
功能描述:销毁配置结构。
输入参数:
类型:ARConfig*,值:配置结构指针。
输出参数:不做定义。
7.4.3 获取配置中的设备类型
接口定义:voidarConfigGetDeviceType(constARConfig* config,ARDeviceType* out_device_
type)
功能描述:获取配置结构中的设备类型。
输入参数:
类型:constARConfig*,值:配置结构指针。
输出参数:
类型:ARDeviceType*,值:设备类型指针,见表2定义。
7.4.4 设置配置中的设备类型
接口定义:voidarConfigSetDeviceType(ARConfig*config,ARDeviceTypedevice_type)
功能描述:设置配置结构中的设备类型。
输入参数:
类型:ARConfig*,值:配置结构指针。
类型:ARDeviceType,值:设备类型,见表2定义。
12
GB/T45287—2025
输出参数:不做定义。
7.4.5 获取配置中的算法数据流模式
接口定义:voidarConfigGetAlgorithmStreamMode(constARConfig*config,ARAlgorithmType
type,ARStreamMode* out_stream_mode)
功能描述:获取配置结构中指定算法类型的数据流模式。
输入参数:
类型:constARConfig*,值:配置结构指针。
类型:ARAlgorithmType,值:算法类型,见表5定义。
输出参数:
类型:ARStreamMode*,值:数据流模式指针,见表3定义。
7.4.6 设置配置中的算法数据流模式
接口定义:voidarConfigSetAlgorithmStreamMode(ARConfig*config,ARAlgorithmTypetype,
ARStreamModestream_mode)
功能描述:设置配置结构中指定算法类型的数据流模式。
输入参数:
类型:ARConfig*,值:配置结构指针。
类型:ARAlgorithmType,值:算法类型,见表5定义。
类型:ARStreamMode,值:数据流模式,见表3定义。
输出参数:不做定义。
7.4.7 获取配置中的算法开关模式
接口定义:voidarConfigGetAlgorithmMode(constARConfig*config,ARAlgorithmTypetype,
ARAlgorithmMode* out_algorithm_mode)
功能描述:获取配置结构中指定算法类型的算法开关模式。
输入参数:
类型:constARConfig*,值:配置结构指针。
类型:ARAlgorithmType,值:算法类型,见表5定义。
输出参数:
类型:ARAlgorithmMode*,值:算法开关模式指针,见表6定义。
7.4.8 设置配置中的算法开关模式
接口定义:voidarConfigSetAlgorithmMode(ARConfig*config,ARAlgorithmTypetype,ARAlgorithmModealgorithm_
mode)
功能描述:设置配置结构中指定算法类型的算法开关模式。
输入参数:
类型:ARConfig*,值:配置结构指针。
类型:ARAlgorithmType,值:算法类型,见表5定义。
类型:ARAlgorithmMode,值:算法开关模式,见表6定义。输出参数:不做定义。
7.4.9 获取配置中光照估计模式
接口定义:voidarConfigGetIlluminationEstimateMode(constARConfig*config,ARIlluminatio-
13
GB/T45287—2025
nEstimateMode* out_mode)
功能描述:获取配置结构中的光照估计模式。
输入参数:
类型:constARConfig*,值:配置结构指针。
输出参数:
类型:ARIlluminationEstimateMode*,值:光照估计模式指针,见表15定义。
7.4.10 设置配置中光照估计模式
接口定义:voidarConfigSetIlluminationEstimateMode(ARConfig* config,ARIlluminationEstimateModemode)
功能描述:设置配置结构中的光照估计模式。
输入参数:
类型:ARConfig*,值:配置结构指针。
类型:ARIlluminationEstimateMode,值:光照估计模式,见表15定义。
输出参数:不做定义。
7.4.11 获取配置中的跟踪运行模式
接口定义:voidarConfigGetTrackingRunMode(constARConfig* config,ARTrackingRunMode
*tracking_run_mode)
功能描述:获取配置结构中的跟踪运行模式。
输入参数:
类型:constARConfig*,值:配置结构指针。
输出参数:
类型:ARTrackingRunMode*,值:跟踪运行模式指针,见表9定义。
7.4.12 设置配置中的跟踪运行模式
接口定义:void arConfigSetTrackingRunMode (ARConfig * config, ARTrackingRunMode
tracking_run_mode)
功能描述:设置配置结构中的跟踪运行模式。
输入参数:
类型:ARConfig*,值:配置结构指针。
类型:ARTrackingRunMode,值:跟踪运行模式,见表9定义。
输出参数:不做定义。
7.4.13 获取配置中的世界坐标对齐模式
接口定义:voidarConfigGetWorldAlignmentMode(constARConfig* config,ARWorldAlignmentMode*
world_alignment_mode)
功能描述:获取配置结构中的世界坐标对齐模式。
输入参数:
类型:constARConfig*,值:配置结构指针。
输出参数:
类型:ARWorldAlignmentMode*,值:世界坐标对齐模式指针,见表10定义。
14
GB/T45287—2025
7.4.14 设置配置中的世界坐标对齐模式
接口定义:voidarConfigSetWorldAlignmentMode(ARConfig*config,ARWorldAlignmentMode
world_alignment_mode)
功能描述:设置配置结构中的世界坐标对齐模式。
输入参数:
类型:ARConfig*,值:配置结构指针。
类型:ARWorldAlignmentMode,值:世界坐标对齐模式,见表10定义。
输出参数:不做定义。
7.4.15 获取配置中的参考图像数据集
接口定义:voidarConfigGetReferenceImageDatabase(constARConfig* config,ARReferenceImageDatabase*
out_image_database)
功能描述:获取配置结构中的参考图像数据集结构。
输入参数:
类型:constARConfig*,值:配置结构指针。
输出参数:
类型:ARReferenceImageDatabase*,值:参考图像数据集结构的指针。
7.4.16 设置配置中的参考图像数据集
接口定义:voidarConfigSetReferenceImageDatabase(ARConfig* config,constARReferenceImageDatabase*
image_database)
功能描述:设置配置结构中的参考图像数据集结构。
输入参数:
类型:ARConfig*,值:配置结构指针。
类型:constARReferenceImageDatabase*,值:参考图像数据集结构指针。
输出参数:不做定义。
7.5 增强现实会话
7.5.1 创建增强现实会话
接口定义:ARResultarSessionCreate(void*env,void*context,ARSession** out_session)
功能描述:创建增强现实会话结构,返回ARRESULT_SUCCESS表示成功。
输入参数:
类型:void*,值:运行环境。
类型:void*,值:运行上下文。
输出参数:
类型:ARSession**,值:创建新的增强现实会话结构,结构地址保存在*out_session中,如
果创建失败,*out_session指向的值为空指针。
类型:ARResult,值:返回值,见表1定义。
7.5.2 销毁增强现实会话
接口定义:voidarSessionDestroy(ARSession*session)
15
GB/T45287—2025
功能描述:销毁增强现实会话结构。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
输出参数:不做定义。
7.5.3 增强现实会话设置云服务密钥
接口定义:voidarSessionSetKeyAndSecret(ARSession*session,constchar* key,constchar*
secret)
功能描述:授权云服务。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
类型:constchar*,值:Key字符串。
类型:constchar*,值:Secret字符串。
输出参数:不做定义。
7.5.4 增强现实会话获取版本号
接口定义:voidarSessionGetVersion(constARSession*session,char*version,intversionSize)
功能描述:获取版本号。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
类型:int,值:版本号字符串数组的长度。
输出参数:
类型:char*,值:填充版本号的字符串。
7.5.5 设置增强现实会话配置
接口定义:ARResultarSessionConfigure(ARSession*session,constARConfig*config)
功能描述:设置增强现实会话结构的配置,返回ARRESULT_SUCCESS表示成功。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
类型:constARConfig*,值:配置指针。
输出参数:
类型:ARResult,值:返回值,见表1定义。
7.5.6 获取增强现实会话配置
接口定义:voidarSessionGetConfig(constARSession*session,ARConfig* out_config)
功能描述:获取增强现实会话结构的配置。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
输出参数:
类型:ARConfig*,值:配置指针。
7.5.7 恢复运行增强现实会话
接口定义:ARResultarSessionResume(ARSession*session)
16
GB/T45287—2025
功能描述:恢复运行增强现实会话,进入运行状态,该状态下才会对场景进行跟踪识别,返回ARRESULT_
SUCCESS表示成功。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
输出参数:
类型:ARResult,值:返回值,见表1定义。
7.5.8 暂停运行增强现实会话
接口定义:ARResultarSessionPause(ARSession*session)
功能描述:暂停运行增强现实会话,进入暂停状态,该状态下停止对物体场景的跟踪识别,返回
ARRESULT_SUCCESS表示成功。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
输出参数:
类型:ARResult,值:返回值,见表1定义。
7.5.9 更新增强现实会话
接口定义:ARResultarSessionUpdate(ARSession*session,ARFrame* out_frame)
功能描述:更新增强现实会话的内部数据,例如更新设备姿态信息,识别的平面节点、图像节点。该
函数需要按照一定的频率进行调用,使增强现实会话内部信息不断更新,返回ARRESULT_
SUCCESS表示成功。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
输出参数:
类型:ARFrame*,值:帧画面结构指针,需要预先创建,该结构内容会被更新。
类型:ARResult,值:返回值,见表1定义。
7.5.10 启动运行增强现实会话算法
接口定义:ARResultarSessionStartAlgorithm (ARSession*session,ARAlgorithmType type,
intoption)
功能描述:手动方式启动算法,返回ARRESULT_SUCCESS表示成功。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
类型:ARAlgorithmType,值:算法类型,见表5定义。
类型:int,值:启动算法选项。
输出参数:
类型:ARResult,值:返回值,见表1定义。
7.5.11 停止运行增强现实会话算法
接口定义:ARResultarSessionStopAlgorithm(ARSession*session,ARAlgorithmTypetype,int
option)
功能描述:手动方式停止算法,返回ARRESULT_SUCCESS表示成功。
输入参数:
17
GB/T45287—2025
类型:ARSession*,值:增强现实会话结构指针。
类型:ARAlgorithmType,值:算法类型,见表5定义。
类型:int,值:停止算法选项。
输出参数:
类型:ARResult,值:返回值,见表1定义。
7.5.12 设置增强现实会话显示区域
接口定义:voidarSessionSetDisplayGeometry(ARSession* session,introtation,intwidth,int
height)
功能描述:设置屏幕显示参数。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
类型:int,值:界面朝向模式。
类型:int,值:显示区域宽的像素数量。
类型:int,值:显示区域高的像素数量。
输出参数:不做定义。
7.5.13 获取增强现实会话地图
接口定义:ARResultarSessionAcquireWorldMap(ARSession* session,ARWorldMap**out
_map)
功能描述:获取增强现实会话当前的增强现实世界地图结构。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
输出参数:
类型:ARWorldMap* *,值:创建新的增强现实世界地图结构,结构地址保存在*out_
map中。
类型:ARResult,值:返回值,见表1定义。
7.5.14 获取增强现实会话跟踪状态
接口定义:voidarSessionGetTrackingState(ARSession*session,ARTrackingState*out_state)
功能描述:获取跟踪状态,不同状态表示内部的算法运行情况,比如:初始化、正常跟踪等。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
输出参数:
类型:ARTrackingState*,值:跟踪状态指针,见表8定义。
7.5.15 增强现实会话托管锚点
接口定义:ARResultarSessionHostAnchor(ARSession* session,const ARAnchor* anchor,
ARAnchor** out_cloud_anchor)
功能描述:将本地锚点托管至云端,创建对应的云锚点结构。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
类型:ARAnchor*,值:本地锚点。
18
GB/T45287—2025
输出参数:
类型:ARAnchor**,值:创建新的云锚点结构,结构地址保存在*out_cloud_anchor。
类型:ARResult,值:返回值,见表1定义。
7.5.16 增强现实会话解析锚点
接口定义:ARResultarSessionResolveAnchor(ARSession* session,constchar* cloud_anchor
_id,ARAnchor** out_cloud_anchor)
功能描述:通过云锚点ID解析并获取云锚点。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
类型:constchar*,值:云端锚点id。
输出参数:
类型:ARAnchor**,值:新创建的id对应的云锚点结构,结构地址保存在*out_cloud_anchor
。
类型:ARResult,值:返回值,见表1定义。
7.5.17 设置增强现实会话整型数据类型参数值
接口定义:voidarSessionSetIntValue(ARSession* session,ARParameterEnum type,int*
value,intsize)
功能描述:设置指定的整型数据类型参数的值。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
类型:ARParameterEnum,值:参数枚举,见表13定义。
类型:int*,值:参数对应的整形数组。
类型:int,值:整形数组长度。
输出参数:不做定义。
7.5.18 设置增强现实会话浮点型数据类型参数值
接口定义:voidarSessionSetFloatValue(ARSession* session,ARParameterEnumtype,float*
value,intsize)
功能描述:设置指定的浮点型数据类型参数的值。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
类型:ARParameterEnum,值:参数枚举,见表13定义。
类型:float*,值:参数对应的浮点数组。
类型:int,值:浮点数组长度。
输出参数:不做定义。
7.5.19 设置增强现实会话字符串数据类型参数值
接口定义:voidarSessionSetStringValue(ARSession*session,ARParameterEnumtype,char*
value,intsize)
功能描述:设置指定的字符数据类型参数的值。
输入参数:
19
GB/T45287—2025
类型:ARSession*,值:增强现实会话结构指针。
类型:ARParameterEnum,值:参数枚举,见表13定义。
类型:char*,值:参数对应的字符串数组。
类型:int,值:字符串数组长度。
输出参数:不做定义。
7.5.20 获取增强现实会话整型数据类型参数值
接口定义:voidarSessionGetIntValue(constARSession* session,ARParameterEnumtype,int
* out_value,intsize)
功能描述:获取指定的整型数据类型参数的值。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:ARParameterEnum,值:参数枚举,见表13定义。
类型:int,值:整型数组长度。
输出参数:
类型:int*,值:保存获取结果的整形数组。
7.5.21 获取增强现实会话获取浮点型数据类型参数值
接口定义:voidarSessionGetFloatValue (constARSession* session,ARParameterEnum type,
float* out_value,intsize)
功能描述:获取指定的浮点型数据类型参数的值。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:ARParameterEnum,值:参数枚举,见表13定义。
类型:int,值:参数数组长度。
输出参数:
类型:float*,值:保存获取结果的浮点数组。
7.5.22 获取增强现实会话字符串数据类型参数值
接口定义:voidarSessionGetStringValue (constARSession* session,ARParameterEnum type,
char* out_value,int* out_length,intsize)
功能描述:获取指定的字符数据类型参数的值。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:ARParameterEnum,值:参数枚举,见表13定义。
类型:int,值:字符串数组长度。
输出参数:
类型:char*,值:保存获取结果的字符串数组。
类型:int*,值:字符串数组被填充的长度。
7.5.23 开始增强现实会话头戴式设备左右眼视角绘制
接口定义:ARResultarSessionRenderBeginEye(ARSession*session,AREyeSideeye)
功能描述:开始头戴式设备左右眼视角绘制流程状态。
20
GB/T45287—2025
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
类型:AREyeSide,值:左右眼视角类型,见表14定义。
输出参数:
类型:ARResult,值:返回值,见表1定义。
7.5.24 结束增强现实会话头戴式设备左右眼视角绘制
接口定义:ARResultarSessionEndEye(ARSession*session,AREyeSideeye)
功能描述:结束头戴式设备左右眼视角绘制流程状态。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
类型:AREyeSide,值:左右眼视角类型,见表14定义。
输出参数:
类型:ARResult,值:返回值,见表1定义。
7.5.25 提交增强现实会话头戴式设备左右眼视角绘制结果
接口定义:ARResultarSessionRenderSubmitFrame(ARSession*session,constintleftEyeTextureId,
constintrightEyeTextureId)
功能描述:提交左右眼视角绘制结果给增强现实会话,实现异步时间扭曲(ATW)绘制。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
类型:constint,值:左眼离屏绘制结果纹理参数。
类型:constint,值:右眼离屏绘制结果纹理参数。
输出参数:
类型:ARResult,值:返回值,见表1定义。
7.5.26 设置增强现实会话头戴式设备绘制窗口环境
接口定义:ARResultarSessionRenderSetWindow(ARSession*session,void* window)
功能描述:设置窗口环境,使异步时间扭曲(ATW)绘制框架能创建所需的绘制环境。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
类型:void*,值:异步时间扭曲(ATW)绘制所需的窗口环境。
输出参数:
类型:ARResult,值:返回值,见表1定义。
7.6 增强现实世界地图
7.6.1 获取增强现实世界地图中新锚点
接口定义:ARResultarWorldMapAcquireNewAnchor(ARSession* session,ARWorldMap* ar
_map,constARPose* pose,ARAnchor** out_anchor)
功能描述:使用指定的位姿来创建锚点。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
21
GB/T45287—2025
类型:ARWorldMap*,值:增强现实世界地图结构指针。
类型:constARPose*,值:姿态信息。
输出参数:
类型:ARAnchor**,值:创建新的锚点结构,结构地址保存在*out_anchor。
类型:ARResult,值:返回值,见表1定义。
7.6.2 获取增强现实世界地图中所有锚点
接口定义:voidarWorldMapGetAllAnchors(constARSession*session,constARWorldMap*ar
_map,ARAnchorList* out_anchor_list)
功能描述:获取增强现实世界地图结构中所有锚点。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARWorldMap*,值:增强现实世界地图结构指针。
输出参数:
类型:ARAnchorList*,值:锚点列表,需要预先创建锚点列表结构。
7.6.3 获得增强现实世界地图中节点
接口定义:voidarWorldMapGetAllNodes(constARSession* session,constARWorldMap* ar
_map,ARNodeTypefilter_type,ARNodeList* out_node_list)
功能描述:获取增强现实世界地图中所有节点,包括平面、图像、手势节点。ARNodeType参数用
于过滤需要返回的节点类型。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARWorldMap*,值:增强现实世界地图结构指针。
类型:ARNodeType,值:指定获取节点的类型,见表4定义。
输出参数:
类型:ARNodeList*,值:节点列表,需要预先创建节点列表结构。
7.6.4 释放增强现实世界地图
接口定义:voidarWorldMapRelease(ARWorldMap*ar_map)
功能描述:释放增强现实世界地图。
输入参数:
类型:ARWorldMap*,值:增强现实世界地图结构指针。
输出参数:不做定义。
7.7 帧画面
7.7.1 创建帧画面
接口定义:voidarFrameCreate(ARSession*session,ARFrame**out_frame)
功能描述:创建帧画面结构。
输入参数:
类型:ARSession*,值:增强现实会话结构指针。
输出参数:
22
GB/T45287—2025
类型:ARFrame**,值:创建新的帧画面结构,结构地址保存在*out_frame中。
7.7.2 销毁帧画面
接口定义:voidarFrameDestroy(ARFrame*out_frame)
功能描述:销毁帧画面结构。
输入参数:
类型:ARFrame*,值:帧画面结构指针。
输出参数:不做定义。
7.7.3 判断显示区域是否发生变化
接口定义:voidarFrameGetDisplayGeometryChanged(constARSession*session,constARFrame
*frame,int* ut_geometry_changed)
功能描述:判断显示区域是否发生了变化。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
输出参数:
类型:int*,值:内容是否发生变化,0表示没有发生变化,非0为发生了变化。
7.7.4 根据设备旋转模式转化纹理坐标
接口定义:voidarFrameTransformDisplayUvCoords(constARSession*session,constARFrame
*frame,intnum_elements,constfloat* uvs_in,float* uvs_out)
功能描述:根据设备旋转模式,将纹理坐标转化为对应旋转模式下正确的纹理坐标。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
类型:int,值:需要转化的浮点数数量。
类型:constfloat*,值:需要转化的纹理坐标数组。
输出参数:
类型:float*,值:输出转化后的纹理坐标信息。
7.7.5 设置点求交查询模式
接口定义:voidarFrameSetPointQueryMode (const ARSession* session,const ARFrame*
frame,ARQueryModemode)
功能描述:设置求交查询模式。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
类型:ARQueryMode,值:求交查询模式,见表17定义。
输出参数:不做定义。
7.7.6 获取点求交查询结果列表
接口定义:voidarFramePointQuery(constARSession* session,constARFrame*frame,float
23
GB/T45287—2025
pixel_x,floatpixel_y,ARQueryResultList* query_result_list)
功能描述:从视点到屏幕交点投射光线,同节点求交,获得求交查询结果列表。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
类型:float,值:屏幕点击位置的X 坐标。
类型:float,值:屏幕点击位置的Y 坐标。
输出参数:
类型:ARQueryResultList*,值:求交获得的查询结果列表,需要预先创建该结构。
7.7.7 获取线求交查询结果列表
接口定义:voidarFrameRayQuery(constARSession* session,constARFrame*frame,const
float*ray_origin_3,constfloat*ray_direction_3,ARQueryResultList* hit_result_
list)
功能描述:发射任意一条射线,同节点求交,获得求交查询结果列表。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
类型:constfloat*,值:射线的起点坐标,包含3个浮点数。
类型:constfloat*,值:射线的方向向量,包含3个浮点数。
输出参数:
类型:ARQueryResultList*,值:求交获得的查询结果列表,需要预先创建该结构。
7.7.8 获取当前帧的光照估计
接口定义:voidarFrameGetIlluminationEstimate(constARSession* session,constARFrame*
frame,ARIlluminationEstimate* out_light_estimate)
功能描述:获取当前帧的光照估计结构。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
输出参数:
类型:ARIlluminationEstimate*,值:光照估计结构指针,需要预先创建该结构。
7.7.9 获取当前帧的稀疏点云
接口定义:ARResultarFrameAcquirePointCloud(constARSession* session,constARFrame*
frame,ARPointCloud** out_point_cloud)
功能描述:创建当前帧新的稀疏点云结构。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
输出参数:
类型:ARPointCloud**,值:创建新的稀疏点云结构,结构地址保存在*out_point_cloud中。
类型:ARResult,值:返回值,见表1定义。
24
GB/T45287—2025
7.7.10 获取当前帧的新相机
接口定义:void arFrameAcquireCamera (const ARSession * session,const ARFrame *
frame,ARCamera** out_camera)
功能描述:创建当前帧新的相机结构。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
输出参数:
类型:ARCamera**,值:创建新的相机结构,结构地址保存在*out_camera中。
7.7.11 获取当前帧的稠密网格
接口定义:ARResultarFrameAcquireDenseMesh(constARSession* session,constARFrame*
frame,ARDenseMesh**out_dense_mesh)
功能描述:创建当前帧新的稠密网格结构。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
输出参数:
类型:ARDenseMesh**,值:创建新的稠密网格结构,结构地址保存在*out_desh_mesh中。
7.7.12 获取更新的锚点列表
接口定义:voidarFrameGetUpdatedAnchors(const ARSession* session,const ARFrame*
frame,ARAnchorList* out_anchor_list)
功能描述:获得更新的锚点列表,增强现实会话更新过程中,部分锚点位置等信息会发生变化。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
输出参数:
类型:ARAnchorList*,值:锚点列表,该结构预先创建。
7.7.13 获取更新的节点列表
接口定义:voidarFrameGetUpdatedNodes(const ARSession * session,const ARFrame*
frame,ARNodeTypefilter_type,ARNodeList* out_node_list)
功能描述:获得更新的节点列表,增强现实会话更新过程中,部分节点位置等信息会发生变化,通过
设置节点类型,可返回指定类型的节点。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
类型:ARNodeType,值:节点类型,见表4定义。
输出参数:
类型:ARNodeList*,值:返回节点列表,该结构预先创建。
25
GB/T45287—2025
7.7.14 判断当前帧图像是否更新
接口定义:void arFrameIsImageUpdated (const ARSession * session,const ARFrame *
frame,int* data_updated)
功能描述:当前图像是否更新。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
类型:ARNodeType,值:节点类型,见表4定义。
输出参数:
类型:int*,值:数据内容是否更新过,非零表示更新过,0为未更新。
7.7.15 获取当前帧图像格式
接口定义:void arFrameGetImageFormat(const ARSession * session,const ARFrame*
frame,ARPixelFormat* video_image_format)
功能描述:获取当前帧图像格式。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
输出参数:
类型:ARPixelFormat*,值:画面的像素格式指针,见表12定义。
7.7.16 获取当前帧图像分辨率
接口定义:ARResultarFrameGetImageResolution(constARSession*session,constARFrame*
frame,int* outwidth,int* outheight)
功能描述:获取当前帧图像分辨率。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
输出参数:
类型:int*,值:画面宽像素数量。
类型:int*,值:画面高像素数量。
类型:ARResult,值:返回值,见表1定义。
7.7.17 获取当前帧图像数据
接口定义:ARResultarFrameGetImageData(const ARSession* session,const ARFrame*
frame,unsignedchar* out_data1,unsignedchar* out_data2,unsignedchar* out_
data3)
功能描述:获取当前帧图像数据,图像数据根据格式通过不同方式返回,例如目前支持的YUV 格
式,out_data1返回的Y通道的数据,out_data2返回的是UV 通道的数据,未来支持格
式的扩展,通过不同的方式进行返回。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
26
GB/T45287—2025
类型:constARFrame*,值:帧画面结构指针。
输出参数:
类型:unsignedchar*,值:YUV 格式时,返回图像Y通道数据。
类型:unsignedchar*,值:YUV 格式时,返回图像UV 通道数据。
类型:unsignedchar*,值:预留未使用。
类型:ARResult,值:返回值,见表1定义。
7.7.18 判断当前帧深度图像是否可用
接口定义:ARResult arFrameIsDepthImageAvaliable (const ARSession * session, const
ARFrame*frame)
功能描述:判断当前深度图像是否可用。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
输出参数:
类型:ARResult,值:返回值,见表1定义。
7.7.19 获取当前帧深度图像格式
接口定义:voidarFrameGetDepthImageFormat(constARSession* session,constARFrame*
frame,ARPixelFormat* out_format)
功能描述:获取当前帧深度图像格式。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
输出参数:
类型:ARPixelFormat*,值:深度图像格式,见表12定义。
7.7.20 获取当前帧深度图像分辨率
接口定义:ARResult arFrameGetDepthImageResolution (const ARSession * session,const
ARFrame*frame,int* out_width,int* out_height)
功能描述:获取当前帧深度图像分辨率。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
输出参数:
类型:int*,值:返回深度画面宽像素数量。
类型:int*,值:返回深度画面高像素数量。
类型:ARResult,值:返回值,见表1定义。
7.7.21 获取当前帧深度图像数据
接口定义:ARResultarFrameGetDepthImageData(constARSession*session,constARFrame*
frame,unsignedchar* out_depth_image_data)
功能描述:获取当前帧图像数据。
27
GB/T45287—2025
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARFrame*,值:帧画面结构指针。
输出参数:
类型:unsignedchar*,值:深度图像数据。
类型:ARResult,值:返回值,见表1定义。
7.8 相机模型
7.8.1 获取相机位姿
接口定义:voidarCameraGetPose(const ARSession* session,const ARCamera* camera,
ARPose* out_pose)
功能描述:获取相机结构的位姿信息。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARCamera*,值:相机结构指针。
输出参数:
类型:ARPose*,值:位姿结构指针。
7.8.2 获取相机视图矩阵
接口定义:voidarCameraGetViewMatrix (const ARSession * session,const ARCamera *
camera,float* out_col_major_4x4)
功能描述:获取相机结构的视图矩阵信息。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARCamera*,值:相机结构指针。
输出参数:
类型:float*,值:输出相机矩阵数组,是由16个单精度浮点数组成的一维数组。
7.8.3 获取相机跟踪状态
接口定义:voidarCameraGetTrackingState(const ARSession* session,const ARCamera*
camera,ARTrackingState* out_tracking_state)
功能描述:获取相机结构的跟踪状态信息。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARCamera*,值:相机结构指针。
输出参数:
类型:ARTrackingState*,值:相机跟踪状态指针,见表8定义。
7.8.4 获取相机投影矩阵
接口定义:voidarCameraGetProjectionMatrix(constARSession* session,constARCamera*
camera,floatnear,floatfar,float* dest_col_major_4x4)
功能描述:获取相机结构的投影矩阵信息。
28
GB/T45287—2025
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARCamera*,值:相机结构指针。
类型:float,值:相机近平面距离。
类型:float,值:相机远平面距离。
输出参数:
类型:float*,值:输出投影矩阵数组,是由16个单精度浮点数组成的列矩阵数据。
7.8.5 获取相机算法图像内参
接口定义:voidarCameraGetImageIntrinsics(constARSession* session,constARCamera*
camera,ARCameraIntrinsics* out_camera_intrinsics)
功能描述:获取相机结构的图像内参信息。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARCamera*,值:相机结构指针。
输出参数:
类型:ARCameraIntrinsics*,值:相机图像内参参数。
7.8.6 获取相机纹理图像内参
接口定义:voidarCameraGetTextureIntrinsics(constARSession* session,constARCamera*
camera,ARCameraIntrinsics* out_camera_intrinsics)
功能描述:获取相机结构的纹理内参信息。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARCamera*,值:相机结构指针。
输出参数:
类型:ARCameraIntrinsics*,值:相机纹理内参结构指针。
7.8.7 销毁相机
接口定义:voidarCameraRelease(ARCamera*camera)
功能描述:释放相机结构指针。
输入参数:
类型:ARCamera*,值:相机结构指针。
输出参数:不做定义。
7.9 相机内参
7.9.1 创建相机内参
接口定义:voidarCameraIntrinsicsCreate(constARSession* session,ARCameraIntrinsics**
out_camera_intrinsics)
功能描述:创建相机内参结构。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
29
GB/T45287—2025
输出参数:
类型:ARCameraIntrinsics**,值:创建新的相机内参结构,地址保存在out_intrinsics中。
7.9.2 销毁相机内参
接口定义:voidarCameraIntrinsicsDestroy(ARCameraIntrinsics*camera_intrinsics)
功能描述:销毁相机内参结构。
输入参数:
类型:ARCameraIntrinsics*,值:相机内参结构指针。
输出参数:不做定义。
7.9.3 获取相机焦距
接口定义:voidarCameraIntrinsicsGetFocalLength(constARSession* session,constARCameraIntrinsics*
intrinsics,float* out_fx,float* out_fy)
功能描述:获取相机内参结构中的焦距。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARCameraIntrinsics*,值:相机内参结构指针。
输出参数:
类型:float*,值:相机水平焦距长度。
类型:float*,值:相机竖直焦距长度。
7.9.4 获取相机图像中心点
接口定义:voidarCameraIntrinsicsGetPrincipalPoint(constARSession* session,constARCameraIntrinsics*
intrinsics,float* out_cx,float* out_cy)
功能描述:获取机内参结构中的图像中心点。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARCameraIntrinsics*,值:相机内参结构指针。
输出参数:
类型:float*,值:相机图像中心点水平值。
类型:float*,值:相机图像中心点竖直值。
7.9.5 获取相机图像大小
接口定义:voidarCameraIntrinsicsGetImageDimensions(constARSession* session,constARCameraIntrinsics*
intrinsics,int* out_width,int* out_height)
功能描述:获取相机内参结构中的图像尺寸。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARCameraIntrinsics*,值:相机内参结构指针。
输出参数:
类型:int*,值:相机图像宽的像素数量。
类型:int*,值:相机图像高的像素数量。
30
GB/T45287—2025
7.10 点云
7.10.1 获取点云数量
接口定义:voidarPointCloudGetNumberOfPoints(constARSession*session,constARPointCloud*
point_cloud,int* out_number_of_points)
功能描述:获取点云结构中稀疏点云数量。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARPointCloud*,值:点云结构指针。
输出参数:
类型:int*,值:稀疏点云数量指针。
7.10.2 获取点云坐标
接口定义:voidarPointCloudGetData(constARSession* session,constARPointCloud* point_
cloud,constfloat** out_point_cloud_data)
功能描述:获取点云结构中点云坐标,该函数返回点云结构中稀疏点云的数据地址,每个点3个浮
点数,该指针在点云结构未销毁之前有效。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARPointCloud*,值:点云结构指针。
输出参数:
类型:constfloat**,值:指向点云结构中稀疏点云数组的常量指针。
7.10.3 释放点云
接口定义:voidarPointCloudRelease(ARPointCloud* point_cloud)
功能描述:释放点云结构。
输入参数:
类型:ARPointCloud*,值:点云结构指针。
输出参数:不做定义。
7.11 稠密重建
7.11.1 销毁稠密重建
接口定义:voidarDenseMeshRelease(ARDenseMesh* mesh)
功能描述:释放稠密重建结构。
输入参数:
类型:ARDenseMesh*,值:稠密重建结构指针。
输出参数:不做定义。
7.11.2 获取稠密重建格式
接口定义:void arDenseMeshGetFormat(const ARSession * session,const ARDenseMesh
* mesh,ARVertexFormat* out_vertex_format)
功能描述:获取稠密重建结构网格顶点格式。
31
GB/T45287—2025
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARDenseMesh*,值:稠密重建结构指针。
输出参数:
类型:ARVertexFormat*,值:顶点格式指针,见表11定义。
7.11.3 获取稠密重建网格顶点数量
接口定义:voidarDenseMeshGetVertexCount(constARSession* session,constARDenseMesh
* mesh,int* out_vertex_count)
功能描述:获取稠密重建结构网格顶点数量。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARDenseMesh*,值:稠密重建结构指针。
输出参数:
类型:int*,值:顶点数量指针。
7.11.4 获取稠密重建三角面片索引数量
接口定义:voidarDenseMeshGetIndexCount(constARSession* session,constARDenseMesh
* mesh,int* out_index_count)
功能描述:获取稠密重建结构三角面片索引数量。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARDenseMesh*,值:稠密重建结构指针。
输出参数:
类型:int*,值:三角面片的索引数量指针。
7.11.5 获取稠密重建顶点数组
接口定义:void arDenseMeshGetVertex (const ARSession * session,const ARDenseMesh
* mesh,float* out_vertex_array)
功能描述:获取稠密重建结构网格顶点数组。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARDenseMesh*,值:稠密重建结构指针。
输出参数:
类型:float*,值:顶点数组指针。
7.11.6 获取稠密重建顶点法线数组
接口定义:void arDenseMeshGetNormal(const ARSession * session,const ARDenseMesh
* mesh,float* out_vertex_normal)
功能描述:获取稠密重建结构网格顶点法线数组。
输入参数:
类型:constARSession*,值:增强现实会话结构指针。
类型:constARDenseMesh*,值:稠密重建结构指针。
32
GB/T45287—2025
输出参数:
类型:float*,值:法线数组指针。
7.11.7 获取稠密重建面片索引数组
接口定义:voidarDenseMeshGetIndex(const ARSession* session,const ARDenseMesh*
mesh,unsignedshort* out_index_array)
功能描述:获取稠密重建结构三角面片