ARKit API

ARAnchor

@interface ARAnchor : NSObject

/**

 标识符

 */

@property (nonatomic, readonly) NSUUID *identifier;

/**

 锚点的旋转变换矩阵，定义了锚点的旋转、位置、缩放。是一个4x4的矩阵（读者可以自行科普什么叫4x4矩阵）

 */

@property (nonatomic, readonly) matrix_float4x4 transform;

/**

 构造方法,一般我们无需构造。因为添加一个3D物体时ARKit会有代理告知我们物体的锚点

 */

- (instancetype)initWithTransform:(matrix_float4x4)transform;

@end

ARError

/作用域，一般会表示是哪一个类出现问题

NSString *const ARErrorDomain;

//错误码描述  100：不支持会话追踪配置，主线由于A9芯片以下的机型会报错  101：失活状态 102：传感器故障  200：追踪失败

typedef NS_ERROR_ENUM(ARErrorDomain, ARErrorCode) {

    /** Unsupported session configuration. */

    ARErrorCodeUnsupportedConfiguration  = 100,

    /** A sensor required to run the session is not available. */

    ARErrorCodeSensorUnavailable          = 101,

    /** A sensor failed to provide the required input. */

    ARErrorCodeSensorFailed              = 102,

    /** World tracking has encountered a fatal error. */

    ARErrorCodeWorldTrackingFailed        = 200,

};

ARFrame

@interface ARFrame : NSObject

/**

时间戳.

 */

@property (nonatomic, readonly) NSTimeInterval timestamp;

/**

 缓冲区图像帧

 */

@property (nonatomic, readonly) CVPixelBufferRef capturedImage;

/**

相机（表示这个ARFrame是哪一个相机的，iPhone7plus有两个摄像机）

 */

@property (nonatomic, copy, readonly) ARCamera *camera;

/**

 返回当前相机捕捉到的锚点数据（当一个3D虚拟模型加入到ARKit中时，锚点值得就是这个模型在AR中的位置）

 */

@property (nonatomic, copy, readonly) NSArray *anchors;

/**

灯光，详情可见本章节ARLightEstimate类介绍（指的是灯光强度 一般是0-2000，系统默认1000）

 */

@property (nonatomic, copy, nullable, readonly) ARLightEstimate *lightEstimate;

/**

特征点（应该是捕捉平地或者人脸的，比较苹果有自带的人脸识别功能）

 */

@property (nonatomic, nullable, readonly) ARPointCloud *rawFeaturePoints;

/**

根据2D坐标点搜索3D模型，这个方法通常用于，当我们在手机屏幕点击某一个点的时候，可以捕捉到这一个点所在的3D模型的位置，至于为什么是一个数组非常好理解。手机屏幕一个是长方形，这是一个二维空间。而相机捕捉到的是一个由这个二维空间射出去的长方体，我们点击屏幕一个点可以理解为在这个长方体的边缘射出一条线，这一条线上可能会有多个3D物体模型

point：2D坐标点（手机屏幕某一点）

ARHitTestResultType：捕捉类型  点还是面

(NSArray *)：追踪结果数组  详情见本章节ARHitTestResult类介绍

 */

- (NSArray *)hitTest:(CGPoint)point types:(ARHitTestResultType)types;

/**

相机窗口的的坐标变换（可用于相机横竖屏的旋转适配）

 */

- (CGAffineTransform)displayTransformWithViewportSize:(CGSize)viewportSize orientation:(UIInterfaceOrientation)orientation;

@end

ARHitTestResult

//捕捉类型枚举

typedef NS_OPTIONS(NSUInteger, ARHitTestResultType) {

    /**点. */

    ARHitTestResultTypeFeaturePoint              = (1 << 0),

    /**水平面 y为0. */

    ARHitTestResultTypeEstimatedHorizontalPlane  = (1 << 1),

    /**已结存在的平面. */

    ARHitTestResultTypeExistingPlane            = (1 << 3),

    /**已结存在的锚点和平面. */

    ARHitTestResultTypeExistingPlaneUsingExtent  = (1 << 4),

} NS_SWIFT_NAME(ARHitTestResult.ResultType);

/**

捕捉类型

 */

@property (nonatomic, readonly) ARHitTestResultType type;

/**

 3D虚拟物体与相机的距离（单位：米）

 */

@property (nonatomic, readonly) CGFloat distance;

/**

本地坐标矩阵（世界坐标指的是相机为场景原点的坐标，而每一个3D物体自身有一个场景，本地坐标就是相对于这个场景的坐标）类似于frame和bounds的区别

 */

@property (nonatomic, readonly) matrix_float4x4 localTransform;

/**

世界坐标矩阵

 */

@property (nonatomic, readonly) matrix_float4x4 worldTransform;

/**

 锚点（3D虚拟物体，在虚拟世界有一个位置，这个位置参数是SceneKit中的SCNVector3：三维矢量），而锚点anchor是这个物体在AR现实场景中的位置，是一个4x4的矩阵

 */

@property (nonatomic, strong, nullable, readonly) ARAnchor *anchor;

@end

@interface ARLightEstimate : NSObject

/**

灯光强度  范围0-2000 默认1000

 */

@property (nonatomic, readonly) CGFloat ambientIntensity;

@end

/**

平地类型，目前只有一个，就是水平面

 */

@property (nonatomic, readonly) ARPlaneAnchorAlignment alignment;

/**

3轴矢量结构体，表示平地的中心点  x/y/z

 */

@property (nonatomic, readonly) vector_float3 center;

/**

3轴矢量结构体，表示平地的大小（宽度和高度）  x/y/z

 */

@property (nonatomic, readonly) vector_float3 extent;

@end

@interface ARPointCloud : NSObject

/**

 点的数量

 */

@property (nonatomic, readonly) NSUInteger count;

/**

每一个点的位置的集合（结构体带*表示的是结构体数组）

 */

@property (nonatomic, readonly) const vector_float3 *points;

@end

//会话追踪配置类

@interface ARSessionConfiguration : NSObject

/**

当前设备是否支持，一般A9芯片以下设备不支持

 */

@property(class, nonatomic, readonly) BOOL isSupported;

/**

会话的对其方式，这里的对其指的是3D世界的坐标。枚举值见下方

 */

@property (nonatomic, readwrite) ARWorldAlignment worldAlignment;

/**

是否需要自适应灯光效果，默认是YES

 */

@property (nonatomic, readwrite, getter=isLightEstimationEnabled) BOOL lightEstimationEnabled;

@end

//世界会话追踪配置，苹果建议我们使用这个类，这个子类只有一个属性，也就是可以帮助我们追踪相机捕捉到的平地

@interface ARWorldTrackingSessionConfiguration : ARSessionConfiguration

/**

侦查类型。枚举值见下方（默认侦查平地）

 */

@property (nonatomic, readwrite) ARPlaneDetection planeDetection;

@end

ARSCNView

@interface ARSCNView : SCNView

/**

代理

 */

@property (nonatomic, weak, nullable) id delegate;

/**

AR会话

 */

@property (nonatomic, strong) ARSession *session;

/**

场景

 */

@property(nonatomic, strong) SCNScene *scene;

/**

是否自动适应灯光

 */

@property(nonatomic) BOOL automaticallyUpdatesLighting;

/**

返回对应节点的锚点，节点是一个3D虚拟物体，它的坐标是虚拟场景中的坐标，而锚点ARAnchor是ARKit中现实世界的坐标。

 */

- (nullable ARAnchor *)anchorForNode:(SCNNode *)node;

/**

返回对应锚点的物体

 */

- (nullable SCNNode *)nodeForAnchor:(ARAnchor *)anchor;

/**

根据2D坐标点搜索3D模型，这个方法通常用于，当我们在手机屏幕点击某一个点的时候，可以捕捉到这一个点所在的3D模型的位置，至于为什么是一个数组非常好理解。手机屏幕一个是长方形，这是一个二维空间。而相机捕捉到的是一个由这个二维空间射出去的长方体，我们点击屏幕一个点可以理解为在这个长方体的边缘射出一条线，这一条线上可能会有多个3D物体模型

point：2D坐标点（手机屏幕某一点）

ARHitTestResultType：捕捉类型  点还是面

(NSArray *)：追踪结果数组  详情见本章节ARHitTestResult类介绍

数组的结果排序是由近到远

 */

- (NSArray *)hitTest:(CGPoint)point types:(ARHitTestResultType)types;

@end

ARSCNViewDelegate

//代理

#pragma mark - ARSCNViewDelegate

//代理的内部实现了SCNSceneRendererDelegate：scenekit代理 和ARSessionObserver：ARSession监听（KVO机制）

@protocol ARSCNViewDelegate

@optional

/**

自定义节点的锚点

 */

- (nullable SCNNode *)renderer:(id )renderer nodeForAnchor:(ARAnchor *)anchor;

/**

当添加节点是会调用，我们可以通过这个代理方法得知我们添加一个虚拟物体到AR场景下的锚点（AR现实世界中的坐标）

 */

- (void)renderer:(id )renderer didAddNode:(SCNNode *)node forAnchor:(ARAnchor *)anchor;

/**

将要刷新节点

 */

- (void)renderer:(id )renderer willUpdateNode:(SCNNode *)node forAnchor:(ARAnchor *)anchor;

/**

 已经刷新节点

 */

- (void)renderer:(id )renderer didUpdateNode:(SCNNode *)node forAnchor:(ARAnchor *)anchor;

/**

 移除节点

 */

- (void)renderer:(id )renderer didRemoveNode:(SCNNode *)node forAnchor:(ARAnchor *)anchor;

@end

ARSession

@interface ARSession : NSObject

/**

 代理

 */

@property (nonatomic, weak) id delegate;

/**

指定代理执行的线程（主线程不会有延迟，子线程会有延迟），不指定的话默认主线程

 */

@property (nonatomic, strong, nullable) dispatch_queue_t delegateQueue;

/**

相机当前的位置（是由会话追踪配置计算出来的）

 */

@property (nonatomic, copy, nullable, readonly) ARFrame *currentFrame;

/**

 会话追踪配置

 */

@property (nonatomic, copy, nullable, readonly) ARSessionConfiguration *configuration;

/**

运行会话（这行代码就是开启AR的关键所在）

 */

- (void)runWithConfiguration:(ARSessionConfiguration *)configuration NS_SWIFT_UNAVAILABLE("Use run(_:options:)");

/**

运行会话，只是多了一个参数ARSessionRunOptions：作用就是会话断开重连时的行为。ARSessionRunOptionResetTracking：表示充值追踪  ARSessionRunOptionRemoveExistingAnchors：移除现有锚点

 */

- (void)runWithConfiguration:(ARSessionConfiguration *)configuration options:(ARSessionRunOptions)options NS_SWIFT_NAME(run(_:options:));

/**

暂停会话

 */

- (void)pause;

/**

添加锚点

 */

- (void)addAnchor:(ARAnchor *)anchor NS_SWIFT_NAME(add(anchor:));

/**

移除锚点

 */

- (void)removeAnchor:(ARAnchor *)anchor NS_SWIFT_NAME(remove(anchor:));

@end

//session代理分类两部分，一个是观察者（KVO） 一个是委托者（代理）

#pragma mark - ARSessionObserver

//session KVO观察者

@protocol ARSessionObserver

@optional

/**

 session失败

 */

- (void)session:(ARSession *)session didFailWithError:(NSError *)error;

/**

相机改变追踪状态

 */

- (void)session:(ARSession *)session cameraDidChangeTrackingState:(ARCamera *)camera;

/**

 session意外断开（如果开启ARSession之后，APP退到后台就有可能导致会话断开）

 */

- (void)sessionWasInterrupted:(ARSession *)session;

/**

session会话断开恢复（短时间退到后台再进入APP会自动恢复）

 */

- (void)sessionInterruptionEnded:(ARSession *)session;

@end

#pragma mark - ARSessionDelegate

@protocol ARSessionDelegate

@optional

/**

 更新相机位置

 */

- (void)session:(ARSession *)session didUpdateFrame:(ARFrame *)frame;

/**

添加锚点

 */

- (void)session:(ARSession *)session didAddAnchors:(NSArray*)anchors;

/**

刷新锚点

 */

- (void)session:(ARSession *)session didUpdateAnchors:(NSArray*)anchors;

/**

移除锚点

 */

- (void)session:(ARSession *)session didRemoveAnchors:(NSArray*)anchors;

@end

ARCamera

@interface ARCamera : NSObject

/**

 4x4矩阵表示相机位置，同ARAnchor

 */

@property (nonatomic, readonly) matrix_float4x4 transform;

/**

相机方向（旋转）的矢量欧拉角

分别是x/y/z

 */

@property (nonatomic, readonly) vector_float3 eulerAngles;

/**

 相机追踪状态（在下方会有枚举值介绍）

 */

@property (nonatomic, readonly) ARTrackingState trackingState NS_REFINED_FOR_SWIFT;

/**

追踪运动类型

 */

@property (nonatomic, readonly) ARTrackingStateReason trackingStateReason NS_REFINED_FOR_SWIFT;

/**

相机曲率（笔者有点费解，反复揣摩应该是与焦距相关参数）

3x3矩阵

 fx 0  px

 0  fy  py

 0  0  1

 */

@property (nonatomic, readonly) matrix_float3x3 intrinsics;

/**

摄像头分辨率

 */

@property (nonatomic, readonly) CGSize imageResolution;

/**

投影矩阵

*/

@property (nonatomic, readonly) matrix_float4x4 projectionMatrix;

/**

创建相机投影矩阵

 */

- (matrix_float4x4)projectionMatrixWithViewportSize:(CGSize)viewportSize orientation:(UIInterfaceOrientation)orientation zNear:(CGFloat)zNear zFar:(CGFloat)zFar;

@end

//相机追踪状态枚举

typedef NS_ENUM(NSInteger, ARTrackingState) {

    /**不被允许 */

    ARTrackingStateNotAvailable,

    /**最小 */

    ARTrackingStateLimited,

    /**正常. */

    ARTrackingStateNormal,

} NS_REFINED_FOR_SWIFT;

/**

 追踪运动类型

 */

API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos)

typedef NS_ENUM(NSInteger, ARTrackingStateReason) {

    /**无. */

    ARTrackingStateReasonNone,

    /**运动. */

    ARTrackingStateReasonExcessiveMotion,

    /**脸部捕捉. */

    ARTrackingStateReasonInsufficientFeatures,

} NS_REFINED_FOR_SWIFT;