简体中文

下载 App

输入关键字搜索

开发者能力认证

鸿蒙高校创新赛

HarmonyOS 7

animation

HarmonyOS行业解决方案

layoutWeight

HarmonyOS模板&组件

bindPopup

bindsheet

CTRL+K

文档管理中心

我的

Hello，

欢迎来到开发者联盟

ARSession

更新时间: 2025-04-09 06:18

展开

Class Info
public class ARSession 用于管理AR Engine的整个运行状态，是AR Engine运行的基础，启动ARSession前，使用ARSession.configure()设置相关配置，通过ARSession可以实现：控制AR Engine的启动、暂停、结束等行为。更新并获取AR Engine内部数据，如：锚点、平面、可跟踪对象等。

Class Info

public class ARSession

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

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

Public Field Summary

展开

Qualifier and Type	Field and Description
public static final int	AR_TRACKABLE_OBJECT AR可追踪对象信息。
public static final int	CURRENT_SDK_VERSIONCODE AR Engine SDK版本信息。

Qualifier and Type

Field and Description

public static final int

AR_TRACKABLE_OBJECT

AR可追踪对象信息。

public static final int

CURRENT_SDK_VERSIONCODE

AR Engine SDK版本信息。

Public Constructor Summary

展开

Constructor Name
public ARSession(Context context) 创建与Application context绑定的Session。

Constructor Name

public ARSession(Context context)

创建与Application context绑定的Session。

Public Method Summary

展开

Qualifier and Type	Method Name and Description
void	addServiceListener(ServiceListener listener) 添加事件监听器。
void	configure(ARConfigBase config) 配置session。service通过修改config中的启用项EnableItem适配设备支持的选项。应用使用config.getEnableItem()检查对应的设置项，以便获取当前Session的启用项。
ARAnchor	createAnchor(ARPose pose) 使用pose创建一个持续跟踪的锚点。
Collection<ARAnchor>	getAllAnchors() 获取所有锚点，包括TrackingState为PAUSED、TRACKING和STOPPED。应用处理时需要仅绘制TRACKING状态的锚点，删除STOPPED状态的锚点。
Collection<ARPlane>	getAllPlanes() 获取所有检测到的平面，如果ARConfigBase.PlaneFindingMode为DISABLED，则返回空。注意该方法已废弃，请使用getAllTrackables()。
<T extends ARTrackable> Collection<T>	getAllTrackables(Class<T> filterType) 获取所有指定类型的可跟踪对像集合，使用方法如：Collection<ARPlane> allFaces = mSession.getAllTrackables(ARPlane.class)获取所有跟踪到的平面。
ARCameraConfig	getCameraConfig() 返回当前Session对应的相机配置实例。
void	getProjectionMatrix(float[] dest, int offset, float near, float far) 返回投影矩阵，该矩阵用于在相机预览的图像中渲染虚拟物体和平面。注意该方法已废弃，请使用ARCamera上的对应接口。
int	getSupportedSemanticMode() 获取支持的语义识别模式，可同时支持多种模式，如同时支持平面和目标语义模式，则返回3，即SEMANTIC_PLANE \| SEMANTIC_TARGET。
boolean	isSupported(ARConfig config) 注意该方法已废弃。目前该函数仅返回true。
void	pause() 暂停AR Engine ，停止相机预览流，不清除平面和锚点数据，释放相机（否则其他应用无法使用相机服务），不会断开与服务端的连接。调用后需要使用resume()恢复。
void	removeAnchors(Collection<ARAnchor> anchors) 删除anchors中的锚点，请使用ARAnchor.detach()单独删除。注意该方法已废弃，无替代。
void	resume() 开始运行ARSession，或者在调用pause()以后恢复ARSession的运行状态。
void	resume(ARConfig config) 根据config恢复session，有两种使用场景：启动服务和服务被暂停后重启。注意：调用了ARSession.stop()之后，该方法不能恢复。注意该方法已废弃，请使用resume()方法，不支持在session pause以后重新修改config。
void	setCameraTextureName(int textureId) 设置可用于存储相机预览流数据的openGL textureId，应用调用ARSession.update()后，AR Engine会更新相机预览到纹理textureId中。textureId使用时需要指定为GL_TEXTURE_EXTERNAL_OES，如：GLES20.glBindTexture(GLES11Ext.GL_TEXTURE_EXTERNAL_OES, mTextureId)。
void	setCloudServiceAuthInfo(String authInfo) 2D云识别和3D云识别需设置云服务特性所需的认证参数，字符串格式为Json，包含modelName、 appId和appSecret。
void	setDisplayGeometry(float width, float height) 设置显示的高和宽（以像素为单位）。该高和宽是显示view的高和宽，如果不一致，会导致显示相机预览出错。注意该方法已废弃，请使用setDisplayGeometry(int displayRotation, int widthPx, int heightPx)替换。
void	setDisplayGeometry(int displayRotation, int widthPx, int heightPx) 设置显示界面的旋转角度、宽和高。
void	setEnvironmentTextureProbe(float[] arBoundBox) 设置环境纹理探针。AR Engine Server 3.15及以后版本可用。作用：设置虚拟物体在世界坐标系下的空间包围盒，包围盒采用AABB形式，float[]{xmin, ymin, zmin, xmax, ymax, zmax}。
void	setEnvironmentTextureUpdateMode(EnvironmentTextureUpdateMode textureUpdateMode) 设置环境纹理更新模式。AR Engine Server 3.15及以后版本可用。
void	stop() 停止AR Engine，停止相机预览流，清除平面和锚点数据，并释放相机，终止本次会话。调用后，如果要再次启动，需要新建ARSession。
ARFrame	update() 更新AR Engine的计算结果，应用应在需要获取最新的数据时调用此接口，如相机发生移动以后，使用此接口可以获取新的锚点坐标、平面坐标、相机获取的图像帧等。如果ARConfigBase.UpdateMode为BLOCKING，那么该函数会阻塞至有新的帧可用。

Public Fields

AR_TRACKABLE_OBJECT

展开

Field
public static final int AR_TRACKABLE_OBJECT AR可追踪对象信息。该常量AR Engine Server 3.11及以后可用。另请参阅：Constant-values

Field

public static final int AR_TRACKABLE_OBJECT

AR可追踪对象信息。该常量AR Engine Server 3.11及以后可用。

另请参阅：Constant-values

CURRENT_SDK_VERSIONCODE

展开

Field
public static final int CURRENT_SDK_VERSIONCODE AR Engine SDK版本信息。另请参阅：Constant-values

Field

public static final int CURRENT_SDK_VERSIONCODE

AR Engine SDK版本信息。

另请参阅：Constant-values

Public Constructors

ARSession

展开

Constructor
public ARSession(Context context) 创建与context绑定的session，AR Engine SDK内部使用context读取包内资源文件。对于普通应用，请传入Application context，对于插件应用，传入插件对应的context。

Constructor

public ARSession(Context context)

创建与context绑定的session，AR Engine SDK内部使用context读取包内资源文件。对于普通应用，请传入Application context，对于插件应用，传入插件对应的context。

Parameters

展开

Name	Description
context	当前应用的上下文信息。

Throws

展开

Name	Description
ARUnavailableServiceNotInstalledException	设备上没有安装AR Engine Service。
ARUnavailableServiceApkTooOldException	设备上安装的AR Engine Service版本过旧，与SDK版本不符。
ARUnavailableClientSdkTooOldException	应用使用的SDK版本过旧，与AR Engine Service版本不符。

Public Methods

addServiceListener

展开

Method
public void addServiceListener(ServiceListener listener) 添加事件监听器。该方法AR Engine Server 3.11及以后可用。

Method

public void addServiceListener(ServiceListener listener)

添加事件监听器。该方法AR Engine Server 3.11及以后可用。

Parameters

展开

Name	Description
listener	事件监听器。

configure

展开

Method
public void configure(ARConfigBase config) 配置session。注意由于设备能力差异，在调用该函数后，config中的启用项EnableItem会被service尝试修改成设备支持的选项。应用需要在调用此接口后使用config.getEnableItem()检查对应的设置项以便获取当前Session的启用项。

Method

public void configure(ARConfigBase config)

配置session。

注意

由于设备能力差异，在调用该函数后，config中的启用项EnableItem会被service尝试修改成设备支持的选项。应用需要在调用此接口后使用config.getEnableItem()检查对应的设置项以便获取当前Session的启用项。

Parameters

展开

Name	Description
config	session配置信息。

Throws

展开

Name	Description
ARUnSupportedConfigurationException	用于设置session的config不支持。
ARDeadlineExceededException	session没有创建或者已经释放。
ARUnavailableServiceNotInstalledException	AR Engine Service应用没有安装。
ARSessionPausedException	session没有处于pause状态下配置session，需要先使用ARSession.pause()暂停session，配置完成后使用ARSession.resume()恢复。

createAnchor

展开

Method
public ARAnchor createAnchor(ARPose pose) 使用pose创建一个持续跟踪的锚点。

Method

public ARAnchor createAnchor(ARPose pose)

使用pose创建一个持续跟踪的锚点。

Parameters

展开

Name	Description
pose	创建锚点时使用的pose信息。

Throws

展开

Name	Description
IllegalArgumentException	pose参数为空。
ARResourceExhaustedException	设备资源不足，创建锚点失败。

Returns

展开

Type	Description
ARAnchor	创建的锚点。

getAllAnchors

展开

Method
public Collection<ARAnchor> getAllAnchors() 获取所有锚点，包括TrackingState为PAUSED，TRACKING和STOPPED。应用处理时需要仅绘制TRACKING状态的锚点，删除STOPPED状态的锚点。

Method

public Collection<ARAnchor> getAllAnchors()

获取所有锚点，包括TrackingState为PAUSED，TRACKING和STOPPED。应用处理时需要仅绘制TRACKING状态的锚点，删除STOPPED状态的锚点。

Returns

展开

Type	Description
Collection<ARAnchor>	所有锚点集合。

getAllPlanes

注意

该方法已废弃，请使用getAllTrackables()。

展开

Method
public Collection<ARPlane> getAllPlanes() 获取所有检测到的平面，如果ARConfigBase.PlaneFindingMode为DISABLED，则返回空。

Method

public Collection<ARPlane> getAllPlanes()

获取所有检测到的平面，如果ARConfigBase.PlaneFindingMode为DISABLED，则返回空。

Returns

展开

Type	Description
Collection<ARPlane>	所有检测到的平面。

getAllTrackables

展开

Method
public <T extends ARTrackable> Collection<T> getAllTrackables(Class<T> filterType) 获取所有指定类型的可跟踪对像集合，使用方法如：Collection<ARPlane> allFaces = mSession.getAllTrackables(ARPlane.class)获取所有跟踪到的平面。

Method

public <T extends ARTrackable> Collection<T> getAllTrackables(Class<T> filterType)

获取所有指定类型的可跟踪对像集合，使用方法如：Collection<ARPlane> allFaces = mSession.getAllTrackables(ARPlane.class)获取所有跟踪到的平面。

Parameters

展开

Name	Description
filterType	需要获取类型。

Returns

展开

Type	Description
<T extends ARTrackable> Collection<T>	指定类型的可跟踪对象集合。

getCameraConfig

展开

Method
public ARCameraConfig getCameraConfig() 返回当前Session对应的相机配置实例。

Method

public ARCameraConfig getCameraConfig()

返回当前Session对应的相机配置实例。

Returns

展开

Type	Description
ARCameraConfig	当前Session对应的相机配置实例。

getProjectionMatrix

注意

该方法已废弃，请使用ARCamera上的对应接口。

展开

Method
public void getProjectionMatrix(float[] dest, int offset, float near, float far) 返回投影矩阵，该矩阵用于在相机预览的图像中渲染虚拟物体和平面。dest为存放矩阵的数组，offset为初始偏移，near为近裁剪面的距离，far为远裁剪面的距离（单位为米）。

Method

public void getProjectionMatrix(float[] dest, int offset, float near, float far)

返回投影矩阵，该矩阵用于在相机预览的图像中渲染虚拟物体和平面。dest为存放矩阵的数组，offset为初始偏移，near为近裁剪面的距离，far为远裁剪面的距离（单位为米）。

Parameters

展开

Name	Description
dest	获取得到的投影矩阵。
offset	存放在dest中数据的初始偏移。
near	近裁剪面距离，以米为单位。
far	远裁剪面距离，以米为单位。

getSupportedSemanticMode

展开

Method
public int getSupportedSemanticMode() 获取支持的语义识别模式，可同时支持多种模式，如同时支持平面和目标语义模式，则返回3，即SEMANTIC_PLANE \| SEMANTIC_TARGET。

Method

public int getSupportedSemanticMode()

获取支持的语义识别模式，可同时支持多种模式，如同时支持平面和目标语义模式，则返回3，即SEMANTIC_PLANE | SEMANTIC_TARGET。

Returns

展开

Type	Description
int	语义识别模式，返回值可以是：SEMANTIC_NONE、SEMANTIC_PLANE、SEMANTIC_TARGET。

isSupported

注意

该方法已废弃。目前该函数仅返回true。

展开

Method
public boolean isSupported(ARConfig config)

Parameters

展开

Name	Description
config	需要检查的配置信息。

Returns

展开

Type	Description
boolean	设备是否支持： true：支持。 false：不支持。

Type

Description

boolean

设备是否支持：

true：支持。
false：不支持。

pause

展开

Method
public void pause() 暂停AR Engine，停止相机预览流，不清除平面和锚点数据，释放相机（否则其他应用无法使用相机服务），不会断开与服务端的连接。调用后需要使用resume()恢复。

Method

public void pause()

暂停AR Engine，停止相机预览流，不清除平面和锚点数据，释放相机（否则其他应用无法使用相机服务），不会断开与服务端的连接。调用后需要使用resume()恢复。

Throws

展开

Name	Description
ARFatalException	致命错误，session没有创建或已经释放。

removeAnchors

注意

该方法已废弃，无替代。

展开

Method
public void removeAnchors(Collection<ARAnchor> anchors) 删除anchors中的锚点，请使用ARAnchor.detach()单独删除。

Method

public void removeAnchors(Collection<ARAnchor> anchors)

删除anchors中的锚点，请使用ARAnchor.detach()单独删除。

Parameters

展开

Name	Description
anchors	需要删除的锚点信息。

resume

展开

Method
public void resume() 开始运行ARSession，或者在调用pause()以后恢复ARSession的运行状态。

Method

public void resume()

开始运行ARSession，或者在调用pause()以后恢复ARSession的运行状态。

Throws

展开

Name	Description
ARFatalException	致命错误，session没有创建或已经释放。

resume(ARConfig config)

注意

该方法已废弃，请使用resume()方法，不支持在session pause以后重新修改config。

调用了ARSession.stop()之后，该方法不能恢复。

展开

Method
public void resume(ARConfig config) 根据config恢复session，有两种使用场景：启动服务和服务被暂停后重启。

Method

public void resume(ARConfig config)

根据config恢复session，有两种使用场景：启动服务和服务被暂停后重启。

Parameters

展开

Name	Description
config	恢复session时使用的配置信息。

Throws

展开

Name	Description
ARCameraPermissionDeniedException	当前应用没有相机权限。
ARUnSupportedConfigurationException	传入的config不支持。

setCameraTextureName

展开

Method
public void setCameraTextureName(int textureId) 设置可用于存储相机预览流数据的openGL textureId，应用调用ARSession.update()后，AR Engine会更新相机预览到纹理textureId中。textureId使用时需要指定为GL_TEXTURE_EXTERNAL_OES，如：GLES20.glBindTexture(GLES11Ext.GL_TEXTURE_EXTERNAL_OES, mTextureId)。

Method

public void setCameraTextureName(int textureId)

设置可用于存储相机预览流数据的openGL textureId，应用调用ARSession.update()后，AR Engine会更新相机预览到纹理textureId中。textureId使用时需要指定为GL_TEXTURE_EXTERNAL_OES，如：GLES20.glBindTexture(GLES11Ext.GL_TEXTURE_EXTERNAL_OES, mTextureId)。

Parameters

展开

Name	Description
textureId	相机预览数据流的openGL textureId。

setCloudServiceAuthInfo

展开

Method
public void setCloudServiceAuthInfo(String authInfo) 2D云识别和3D云识别需设置云服务特性所需的认证参数。该方法AR Engine Server 3.11及以后可用。

Method

public void setCloudServiceAuthInfo(String authInfo)

2D云识别和3D云识别需设置云服务特性所需的认证参数。该方法AR Engine Server 3.11及以后可用。

Parameters

展开

Name	Description
authInfo	云服务特性所需的认证参数，是JSON字符串，由modelName、appId和appSecret构成形如{"modelName": "xxx","appId": "xxx","appSecret": "xxx"}的格式。 modelName：AR云服务上创建并训练的模型库名称，可以识别一个或多个对象，该名称由云服务创建模型库时自动生成。 appId：华为应用的唯一标识。 appSecret：华为应用的私匙。

Name

Description

authInfo

云服务特性所需的认证参数，是JSON字符串，由modelName、appId和appSecret构成形如{"modelName": "xxx","appId": "xxx","appSecret": "xxx"}的格式。

modelName：AR云服务上创建并训练的模型库名称，可以识别一个或多个对象，该名称由云服务创建模型库时自动生成。

appId：华为应用的唯一标识。

appSecret：华为应用的私匙。

setDisplayGeometry(float width, float height)

注意

该方法已废弃，请使用setDisplayGeometry(int displayRotation, int widthPx, int heightPx)替换。

展开

Method
public void setDisplayGeometry(float width, float height) 设置显示的高和宽（以像素为单位）。该高和宽是显示view的高和宽，如果不一致，会导致显示相机预览出错。

Method

public void setDisplayGeometry(float width, float height)

设置显示的高和宽（以像素为单位）。该高和宽是显示view的高和宽，如果不一致，会导致显示相机预览出错。

Parameters

展开

Name	Description
width	显示的宽度。
height	显示的高度。

setDisplayGeometry(int displayRotation, int widthPx, int heightPx)

展开

Method
public void setDisplayGeometry(int displayRotation, int widthPx, int heightPx) 设置显示界面的旋转角度、宽和高。

Method

public void setDisplayGeometry(int displayRotation, int widthPx, int heightPx)

设置显示界面的旋转角度、宽和高。

Parameters

展开

Name	Description
displayRotation	旋转角度。
widthPx	显示的宽度。
heightPx	显示的高度。

setEnvironmentTextureProbe

展开

Method

public void setEnvironmentTextureProbe(float[] arBoundBox)

设置环境纹理探针。

作用：设置虚拟物体在世界坐标系下的空间包围盒，包围盒采用AABB形式，float[]{xmin, ymin, zmin, xmax, ymax, zmax}。

用于EnvironmentTexture。

只接受一个，取最后一次放置的虚拟物生效

Parameters

展开

Name	Description
arBoundBox	AABB（轴对齐包围盒），定义AABB的数据按照(xmin, ymin, zmin, xmax, ymax, zmax)的顺序排布，每6个数值表示一个AABB。长方体包围盒左下角坐标和右上角坐标。

setEnvironmentTextureUpdateMode

展开

Method

public void setEnvironmentTextureUpdateMode(EnvironmentTextureUpdateMode textureUpdateMode)

设置环境纹理更新模式。

Parameters

展开

Name	Description
textureUpdateMode	环境纹理更新模式。

stop

展开

Method

public void stop()

停止AR Engine，停止相机预览流，清除平面和锚点数据，并释放相机，终止本次会话。调用后，如果要再次启动，需要新建ARSession。

update

展开

Method

public ARFrame update()

更新AR Engine的计算结果，应用应在需要获取最新的数据时调用此接口，如相机发生移动以后，使用此接口可以获取新的锚点坐标、平面坐标、相机获取的图像帧等。如果ARConfigBase.UpdateMode为BLOCKING，那么该函数会阻塞至有新的帧可用。

Throws

展开

Name	Description
ARSessionPausedException	ARSession在暂停状态时调用了update()方法。
ARMissingGlContextException	当前线程没有GL上下文。
ARTextureNotSetException	在调用update方法前没有调用setCameraTextureName()设置接收相机预览流的纹理。