ARSession

控制AR体验的主要对象


声明

class ARSession : NSObject

概述

ARSession对象协调了ARKit为你创造增强现实体验的主流程。这些流程包括了从设备的运动传感硬件读取数据,控制设备内置摄像头,和对摄像头捕获的图像进行图像分析。会话通过结合这些结果,来实现设备所处的真实世界与创建AR内容建模的虚拟世界的一致性。

创建一个会话

任何一个AR体验都需要一个ARSession。如果你实现了一个自定义的渲染器,你就需要自行实例化会话。

let session = ARSession()
session.delegate = self

如果你使用了任何一个标准的渲染器(例如ARView, ARSCNView或者ARSKView),渲染器便会为你创建一个会话对象。当你想要与你的app的会话进行交互时,直接通过app的渲染器访问即可。

let session = myView.session

运行一个会话

运行一个会话需要一个配置项。ARConfiguration的一系列子类决定了ARkit如何追踪设备的位置和相对真实世界的移动,因此它也决定了你创建AR体验的类型。例如,ARWorldTrackingConfiguration可以让你通过设备的后置摄像头增强用户对周围世界的视野。


主题

1. 配置和运行一个会话

func run(ARConfiguration, options: ARSession.RunOptions)

针对传入指定的配置项和可选性的会话启动AR进程

声明
func run(_ configuration: ARConfiguration, 
 options: ARSession.RunOptions = [])
参数
  • configuration - 定义了会话中运动和场景追踪行为的对象
  • options - Options影响了已经存在的会话状态怎样转变成新的配置项。如果会话是第一次运行,那么这个参数不会产生影响。
讨论

会话追踪了设备的运动,并从设备的摄像头中捕获和处理场景图像,并且只在运行期间才会与的设定的delegate对象或者ARSCNView或者ARSKView相协调。

在一个已经启动的会话上调用该方法将会立即转换到新的会话配置项。options参数将决定当前的会话状态如何转换到新的会话配置。默认情况下,会话将会恢复设备上次已知状态下追踪的位置并保存已经包含在会话中的任意一个锚点(那些你已经通过add(anchor:)手动添加过的,和被ARKit特性如平面检测或者人脸识别自动添加的锚点)。

该方法被调用后会立即返回,但是会话将会继续运行。


var identifier: UUID

运行中的会话的唯一标识

声明
var identifier: UUID { get }
讨论

这个属性可能会在你盗用run方法之后发生变化,但是不会立即发生。因此,为了获取新的值,需要通过key-value observation的方法监听它的变化。

// Use key-value observation to monitor my ARSession's identifier.
var sessionIDObservation: NSKeyValueObservation?
...
sessionIDObservation = observe(
    .arView.session.identifier,
    options: [.old, .new]) { 
        object, change in
        print("SessionID changed to: \(change.newValue!)")
    }

struct ARSession.RunOptions

当你改变AR会话当前状态的配置项时,发生的转变相关的可选项

声明
struct RunOptions
主题
  • 创建运行可选项(Run Options)

init(rawValue: UInt) 创建一个 run options

  • 可选项

static var resetTracking: ARSession.RunOptions 重置会话上一次运行的位置的可选项。

讨论: 后续翻译

static var removeExistingAnchors: ARSession.RunOptions 删除会话上一次运行中所有相关锚点的可选项。

讨论: 后续翻译

static var stopTrackedRaycasts: ARSession.RunOptions 停止所有被激活的被追踪的光线投射。

讨论: 后续翻译


var configuration: ARConfiguration?

定义了会话中运动和场景追踪行为的对象

声明
@NSCopying var configuration: ARConfiguration? { get }

func pause()

暂停会话的进程

声明
func pause()
讨论

当会话被暂停时,它不会追踪设备的运动和捕获图像,也不会与它的delegate方法相协调或者更新任何相关的ARSCNView或者ARSKView。

2. 事件响应

var delegate: ARSessionDelegate?

为了接受捕获的视频图片和追踪信息,或者对于会话状态变化做出相应的对象

声明
weak var delegate: ARSessionDelegate? { get set }
讨论

如果你使用ARSCNView或者ARSKView类来展示你的AR体验,一个会话代理是不必要的。这些视图将会自动展示捕获的视频图片,并使得SceneKit或者SpriteKit的内容与追踪设备和摄像头运动相一致。

如果你使用Metal或者其他的渲染技术创建自己的AR体验可视化层,你需要设置一个会话代理。你的代理对象将周期性的接受会话捕获的ARFrame对象。这些对象包含了用来展示的视频帧图像和你可以用来协调你渲染场景元素展示的AR场景信息。


var delegateQueue: DispatchQueue?

当会话调用你的代理方法时的分发队列

声明
var delegateQueue: DispatchQueue? { get set }
讨论

如果这个值是nil(默认), 会话将会通过主队列调用你的代理方法


protocol ARSessionDelegate

你可以实现用于从一个ARSession中接收捕获的视频帧图像和追踪状态的方法

声明
protocol ARSessionDelegate
概述

当你需要直接操作被会话捕获的ARFrame的对象或者跟随会话追踪的一些列ARAnchor对象的变化时,你需要实现这个协议。典型的情况,当你要建立一个用来展示AR内容的自定义的视图时,你就需要采用这个协议。如果你是通过SceneKit或者SpriteKit来展示内容的,那么ARSCNView和ARSKViewDelegate协议将会提供类似的信息并与这些技术进行交互。

这个协议扩展了ARSessionObServer协议,所以你的会话代理可以同样实现相应会话状态变化的一些列方法。

主题
  • 接收摄像头帧

func session(ARSession, didUpdate: ARFrame) 提供一个新捕获到的摄像头图片以及相关的AR信息给代理

参数、讨论: 后续翻译

  • 处理内容更新

func session(ARSession, didAdd: [ARAnchor]) 告知代理,一个或更多的锚点被加入了会话。

参数、讨论: 后续翻译

func session(ARSession, didUpdate: [ARAnchor]) 告知代理,会话已经调整了一个或多个锚点的属性。

参数、讨论: 后续翻译

func session(ARSession, didRemove: [ARAnchor])

告知代理,一个或多个锚点已经在会话中被删除。


protocol ARSessionObserver

你可以实现对AR会话各个状态变化响应的方法

声明
protocol ARSessionObserver
概述

这个协议定义了ARSessionDelegate, ARSCNViewDelegate, and ARSKViewDelegate 协议共有的可选方法。当你采用这些协议中的任何一个时,你便可以实现这个协议。

主题
  • 对追踪质量变化的响应 (Responding to Tracking Quality Changes)

func session(ARSession, cameraDidChangeTrackingState: ARCamera) 告知监听ARKit设备位置追踪质量变化的代理

参数、讨论: 后续翻译

  • 处理中断 (Handling Interruptions)

func sessionWasInterrupted(ARSession) 告知代理,会话临时停止了帧的处理和设备位置的追踪

参数、讨论: 后续翻译

func sessionInterruptionEnded(ARSession) 告知代理,会话已经恢复了帧的处理和设备位置的追踪

参数、讨论: 后续翻译

func sessionShouldAttemptRelocalization(ARSession) -> Bool 在一次中断恢复后询问代理,是否尝试恢复世界追踪的状态

参数、讨论: 后续翻译

  • 接收音频数据 (Receiving Audio Data)

func session(ARSession, didOutputAudioSampleBuffer: CMSampleBuffer) 告知代理,一个完成记录音频的样例缓冲区已经可用了。

  • 处理错误(Handling Errors)

func session(ARSession, didFailWithError: Error) 告知代理,会话已经因为一个错误而停止运行了

let ARErrorDomain: String 一个AR会话生成的NSError对象的错误对应的域名

enum ARError.Code AR会话生成的错误码

struct ARError ARKit方法跑出错误的类型

  • 管理协作(Managing Collaboration)

func session(ARSession, didOutputCollaborationData: ARSession.CollaborationData) 当会话创建了协作数据时被调用

3. 访问摄像头帧数据

var currentFrame: ARFrame? 最近的一个被使用中的摄像头信息流捕获的帧数据,包含了ARKit对其的解释

4. 管理锚点

func add(anchor: ARAnchor) 添加指定锚点到会话中,使其可以被追踪

func remove(anchor: ARAnchor) 移除会话中指定的被追踪的锚点

5. 保存共享状态

func getCurrentWorldMap(completionHandler: (ARWorldMap?, Error?) -> Void) 返回一个封装了 世界追踪会话的空间映射状态和一些列锚点 的对象

6. 扫描3D物体

func createReferenceObject(transform: simd_float4x4, center: simd_float3, extent: simd_float3, completionHandler: (ARReferenceObject?, Error?) -> Void) 在会话的世界空间中的某个特定区域创建一个引用对象(针对3D物体检测)

7. 更新世界原点

func setWorldOrigin(relativeTransform: simd_float4x4) 通过制定的变换方式更改AR世界坐标空间的基础

8. 找到真实世界的平面

从屏幕上的一个点射出一道射线来找到与真实世界平面的交汇

func raycast(ARRaycastQuery) -> [ARRaycastResult] 在射线和真实世界平面的交汇处检查一次

func trackedRaycast(ARRaycastQuery, updateHandler: ([ARRaycastResult]) -> Void) -> ARTrackedRaycast? 反复进行射线(ray-cast)轮询来通知你物理环境中平面的更新

9. 管理协同

func update(with: ARSession.CollaborationData) 将其他用户收集到的关于物理环境的信息更新到你的会话中

class ARSession.CollaborationData 一个用来保存用户收集的关于物理环境的信息的对象

参数、讨论: 后续翻译

10. 提供一个会话

protocol ARSessionProviding 提供会话的对象

参数、讨论: 后续翻译