目录

Overview

AR Engine SDK提供对外接口,用于指导开发者使用AR Engine相关服务构建AR应用。

Interface Summary

Interface

Description

ARTrackable

被AR Engine识别的真实物体信息描述接口类。

FaceHealthServiceListener

健康检测事件监听接口,用于向应用传递健康检测状态和进度等信息。

ServiceListener

事件监听接口,应用实现相应的接口以后,SDK通过回调的方式向应用通知AR Engine相关事件。

Class Summary

Class

Description

ARAnchor

锚点是实际环境中一个固定的位置和指定的方向。当环境发生变化时,比如摄像头移动,为了维持这个物理空间的固定位置和方向,AR Engine会根据自己对于环境的检测结果,不断更新它的数值,以做到在该锚点上放置的物体固定不动的效果。

ARAugmentedImage

用于2D图像识别和跟踪时返回被跟踪的图像信息,派生自ARTrackableBase。

ARAugmentedImageDatabase

存储图片数据集,与2D图片识别配合使用,采集并保存到图片数据库中的图片越多,可识别的图片也越多。

ARBody

用于人体骨骼跟踪时返回跟踪结果,包含人体骨骼数据,派生自ARTrackableBase。

  1. 如果ARSession.configure()中传入ARBodyTrackingConfig或者ARWorldBodyTrackingConfig的对象时,AR Engine将实时检测相机预览中的人体。
  2. AR Engine默认配置可同时识别两个人体,将始终返回两个body对象,应用需要根据对象上的getTrackingState()的返回值判断该对象是否有效。当且仅当getTrackingState()返回值为ARTrackable.TrackingState.TRACKING时,识别到的人体才有效。
  3. 以器件为基础的3D类型Body跟踪(如支持TOF(深度相机)),getCoordinateSystemType()返回的结果是COORDINATE_SYSTEM_TYPE_3D_CAMERA),使用setPowerMode设置功耗模式以后,会影响相机输出帧率,普通模式:30fps,省电模式:20fps,超级省电模式:15fps。

ARBodyTrackingConfig

用于人体骨骼跟踪时配置session,派生自ARConfigBase。目前仅支持后置相机,默认自动对焦。

ARCamera

提供当前相机的信息,该类在引擎内部存在一个持久化对象,每次调用ARSession.update()时,该对象的值均会被更新。

ARCameraConfig

用于查询物理相机的相关配置。

ARCameraIntrinsics

用于查询物理相机的离线内参(AR Engine Server 2.10后可用)。

ARConfigBase

所有ARXXXTrackingConfig的基类,包含各类设置项的枚举和公有设置项的接口。

AREnginesApk

用于管理AR Engine服务端。

AREnginesSelector

用于查询设备支持的AR引擎,并设置应用使用的引擎。如果应用不需要切换引擎,可以直接略过该类,默认的引擎为AR Engine。

注意:

该类已废弃,目前只支持AR Engine,不支持切换。

ARFace

用于人脸跟踪时返回人脸跟踪的结果,包含人脸位置、姿态、拓扑和微表情,派生自ARTrackableBase。

ARFaceBlendShapes

用于描述微表情,包含若干个表情参数。

ARFaceGeometry

用于描述人脸拓扑结构,即人脸Mesh。

ARFaceTrackingConfig

用于人脸跟踪时配置session,派生自ARConfigBase。目前仅支持前置相机,具体参见预览流输入方式。

ARFrame

该类是AR Engine系统的快照,包含trackable对象、点云、深度图等信息,仅由ARSession.update()创建。

ARHand

用于人体手部跟踪时返回跟踪结果,包含手部骨骼数据和手势识别结果,派生自ARTrackableBase。

  1. 应用需要根据该对象上的TrackingState对数据进行处理。当且仅当TrackingState为TRACKING时,对象上的数据才有效。
  2. 对于3D类型的Hand跟踪(如支持3D结构光,getSkeletonCoordinateSystem()返回的结果是COORDINATE_SYSTEM_TYPE_3D_CAMERA),使用setPowerMode设置功耗模式以后,会影响相机输出帧率,普通模式:25fps,超级省电模式:15fps。
  3. 手势特性对硬件设备的依赖情况请参见特性依赖表,AR Engine Server 3.17版本以后,手部骨骼点及左右手识别功能支持更多机型。

ARHandTrackingConfig

用于手势跟踪时配置session,派生自ARConfigBase。目前仅支持后置相机,自动对焦模式。

ARHitResult

定义了射线(如以屏幕的点为起点的射线)与真实世界(如点云、平面等)的碰撞交点。

ARImage

实现Android里面的Image类,用于描述ARFrame获取到的预览图等Image信息,通过此类可以获取图片格式、宽高等信息。

ARImageMetadata

提供对相机图像捕获结果metadata信息的访问。

ARImageTrackingConfig

用于Image图像识别和跟踪时配置session,派生自ARConfigBase,默认使用后置摄像头,启用自动对焦。

ARInstantTrackingConfig

用于秒放物体跟踪时配置session,派生自ARConfigBase,只能使用后置摄像头,默认对焦到无穷远。

ARLightEstimate

用于表示AR Engine对当前环境光照的估计。

ARPlane

保存AR Engine识别的真实世界中的平面信息,派生自ARTrackableBase。两个或者多个平面法向量朝向一致,位置靠近时会自动合并到一个父平面中,合并之后每个子平面的getSubsumedBy()将返回父平面。被合并的子平面将继续被跟踪和返回。

ARPlaneHitResult

注意:

该类已废弃,请使用ARHitResult。

ARPoint

表示当前AR Engine正在跟踪的空间中的点,派生自ARTrackableBase。可从ARFrame.hitTest(float,float)返回的值中提取与点云碰撞点的信息。

ARPointCloud

点云类,存储场景中的所有地图点,包含点的位置及其对应的置信度。

ARPointCloudHitResult

注意:

该类已废弃,请使用ARHitResult。

ARPose

位姿数据类,包含平移向量和旋转向量(四元组)。

  1. 在AR Engine中,其用于描述物体从局部坐标系向世界坐标系的转换,局部坐标通过该类的对象转化成世界坐标系下的坐标。
  2. AR Engine中的世界坐标系是右手坐标系(与OpenGL一致),上对应y轴正方向,x和z轴在水平面上。该类的对象等价于OpenGL中的变换矩阵。

ARSceneMesh

用于环境Mesh跟踪时返回跟踪结果的环境识别信息,结果包括Mesh顶点坐标、三角形下标等。当前支持2.5米以内生成Mesh,在相机移动的情况下,支持Mesh动态刷新。

ARSession

用于管理AR Engine的整个运行状态,是AR Engine运行的基础,启动ARSession前,使用ARSession.configure()设置相关配置,通过ARSession可以实现:

  1. 控制AR Engine的启动、暂停、结束等行为。
  2. 更新并获取AR Engine内部数据,如:锚点、平面、可跟踪对象等。

ARTarget

用于扫描目标物体返回跟踪结果,包含目标物体的标签和形状,派生自ARTrackableBase。

目标语义识别标签类型可参见ARTarget.TargetLabel,形状类型可参见ARTarget.TargetShapeType。

该类AR Engine Server 3.13及以后可用。

ARTrackableBase

所有可跟踪对象类的基类,实现了ARTrackable接口,不可直接引用此类创建对象,请使用此类的子类(具体的可跟踪对象)进行操作。

ARWorldBodyTrackingConfig

用于运动跟踪和人体骨骼跟踪同时运行时配置session,派生自ARConfigBase。只能使用后置相机,默认对焦无穷远。

ARWorldTrackingConfig

用于运动跟踪时配置session,派生自ARConfigBase。只能使用后置相机,默认对焦到无穷远。

FaceHealthCheckStateEvent

作为ServiceListener.handleEvent(EventObject eventObject)的参数,向应用传递健康检测状态信息。

Enum Value Summary

Enum

Description

ARBody.ARBodySkeletonType

人体关节点定义。

ARConfigBase.CameraLensFacing

使用摄像头类型,前置或者后置。

ARConfigBase.FocusMode

对焦模式。

ARConfigBase.HandFindingMode

手部识别模式。

注意:

该枚举已废弃,无替代。

ARConfigBase.ImageInputMode

相机打开方式。

ARConfigBase.LightingMode

光照评估模式。

ARConfigBase.PlaneFindingMode

平面搜索模式。

ARConfigBase.PowerMode

功耗模式。

ARConfigBase.SurfaceType

Surface类型。

ARConfigBase.UpdateMode

更新模式。

ARCoordinateSystemType

3D坐标的空间类型。

AREnginesApk.ARAvailability

AR Engine服务端是否可用。

注意:

该枚举已废弃,无替代。

AREnginesApk.ARInstallStatus

AR Engine服务端安装状态。

注意:

该枚举已废弃,无替代。

AREnginesSelector.AREnginesAvaliblity

可用的AR引擎类型。

注意:

该枚举已废弃,当前仅支持AR Engine。

ARFaceBlendShapes.ARBlendShapeType

微表情类型。

ARFaceGeometry.TriangleLabel

人脸Mesh三角面标签。

ARFace.HealthParameter

健康检测参数。

ARHand.ARHandSkeletonType

手部关节点定义。

ARHand.ARHandType

手的类型,左手或右手。

ARLightEstimate.State

光照评估状态。

ARPlane.PlaneType

平面类型。

ARPlane.SemanticPlaneLabel

当前平面识别到的语义类型。

ARPoint.OrientationMode

朝向模式。

ARTrackable.TrackingState

当前可跟踪对象的跟踪状态。

FaceHealthCheckState

健康检测状态。

Exception Summary

Exception

Description

ARCameraNotAvailableException

继承自IllegalComponentStateException,用于表明当前相机为不可用状态。

ARCameraPermissionDeniedException

继承自RuntimeException,在ARSession.resume(configuration)调用中抛出,用于表明当前应用没有获得相机权限。

ARDeadlineExceededException

获取失败,因为正在获取的对象已经释放。

ARFatalException

继承自RuntimeException,当AR Engine遇到不能恢复的错误时,抛出该异常。

ARMissingGlContextException

继承自IllegalStateException,当前线程中缺少opengl es上下文时抛出。

ARNotTrackingException

继承自RuntimeException,当一个操作需要某个对象处于TRACKING状态(而实际不处于该状态)时抛出。

ARNotYetAvailableException

由于获取的对象尚不可用,因此获取失败。

ARResourceExhaustedException

设备资源耗尽,抛出异常,需要检查已申请的资源是否已经执行释放动作,如调用ARAnchor.detach()释放已经创建的锚点。

ARSessionNotPausedException

继承自IllegalStateException,当一个操作需要AR Engine停止(而实际不处于该状态)时抛出。

ARSessionPausedException

继承自IllegalStateException,当一个操作需要AR Engine运行(而实际不处于该状态)时抛出。例如:

  1. 在启动后未调用ARSession.resume(),而是直接调用ARSession.update()。
  2. 在调用ARSession.pause()后,未调用ARSession.resume前,调用了ARSession.update(),会抛出该异常。

ARTextureNotSetException

继承自IllegalStateException,当第一次调用ARSession.update()前,没有调用ARSession.setCameraTextureName()时,抛出该异常。

ARUnavailableClientSdkTooOldException

继承自ARUnavailableException,应用中使用的AR Engine SDK的版本低于当前安装的Service要求的最小版本时抛出该异常。

ARUnavailableConnectServerTimeOutException

继承自ARUnavailableException,连接服务器超时。通用在AREnginesApk.requestInstall(Activity,boolean)中抛出。

ARUnavailableDeviceNotCompatibleException

继承自ARUnavailableException,当检测到当前硬件设备不支持AR Engine时,抛出该异常。

ARUnavailableEmuiNotCompatibleException

继承自ARUnavailableException,当检测到当前EMUI版本不支持AR Engine时,抛出该异常。

ARUnavailableException

继承自RuntimeException,用于表明AR Engine不可用的异常。

ARUnavailableServiceApkTooOldException

继承自ARUnavailableException,系统中使用的AR Engine Service的版本低于当前使用的SDK要求的最小版本时抛出该异常。

ARUnavailableServiceNotInstalledException

继承自ARUnavailableException,系统中没有可用的AR Engine Service时抛出该异常。

ARUnavailableUserDeclinedInstallationException

继承自ARUnavailableException,用户拒绝安装AR Engine Service时抛出该异常。

ARUnSupportedConfigurationException

继承自ARUnavailableException,在ARSession.configure(ARConfigBase)调用中抛出,用于表明传入的配置不支持时,抛出该异常。