iOS~ARKit开发(OC)文档翻译
2020-08-10 本文已影响0人
羽化行云
1.ARAnchor.h
ARAnchor表示一个物体在3D控件的位置和方向(ARAnchor通常称为物体的3D锚点,有点像UIKit框架中的CALayer的Anchor)。
ARFrame表示的也是物体的位置和方向, 但是ARFrame通常表示的是AR相机的位置和方向已经追踪相机的时间, 还可以捕捉相机的帧图片。
也就是说ARFrame用于捕捉相机的移动, 其他虚拟物体用ARAnchor。
@interface ARAnchor : NSObject
/**
锚的惟一标识符
*/
@property (nonatomic, readonly) NSUUID *identifier;
/**
锚点的旋转变换矩阵，定义了锚点的旋转、位置、缩放。是一个4x4的矩阵
*/
@property (nonatomic, readonly) matrix_float4x4 transform;
/**
构造方法,一般我们无需构造。因为添加一个3D物体时ARKit会有代理告知我们物体的锚点
*/
- (instancetype)initWithTransform:(matrix_float4x4)transform;
@end
/**
在被跟踪的场景中,一个真实的世界物体或位置。
*/
@protocol ARTrackable
/**
跟踪锚的状态
使用isTracked值来确定锚变换的有效性。当被跟踪的对象不再被检测到摄像头图像，它的锚定将返回不为isTracked。
*/
@property (nonatomic, readonly) BOOL isTracked;
@end
2.ARCamera.h
表示相机的模型及其参数。
ARCamera是一个相机，它是连接虚拟场景与现实场景之间的枢纽。在ARKit中，它是捕捉现实图像的相机，在SceneKit中它又是3D虚拟世界中的相机。（一般第一人称3D游戏，主角其实就是一个3D相机，我们电脑屏幕看到的画面就是这个相机捕捉的画面）
一般我们无需去创建一个相机，因为当我们初始化一个AR试图时，他会为我们默认创建一个相机，而且这个相机就是摄像头的位置，同时也是3D世界中的原点所在（x=0,y=0,z=0）
ARCamera的API一般我们无需关心，因为ARKit会默认帮助我们配置好
/**
描述摄像机跟踪状态的值。
*/
typedef NS_ENUM(NSInteger, ARTrackingState) {
/** 不被允许. */
ARTrackingStateNotAvailable,
/** 最小. */
ARTrackingStateLimited,
/**正常. */
ARTrackingStateNormal,
} NS_REFINED_FOR_SWIFT;
/**
描述为什么相机的跟踪状态是有限的一个原因 : 追踪运动类型
*/
typedef NS_ENUM(NSInteger, ARTrackingStateReason) {
/** 无. */
ARTrackingStateReasonNone,
/** 初始化. */
ARTrackingStateReasonInitializing,
/** 运动. */
ARTrackingStateReasonExcessiveMotion,
/** 脸部捕捉. */
ARTrackingStateReasonInsufficientFeatures,
} NS_REFINED_FOR_SWIFT;
@interface ARCamera : NSObject
/**
4x4矩阵表示相机位置，同ARAnchor
在世界坐标中定义摄像机旋转和平移的变换矩阵。
*/
@property (nonatomic, readonly) matrix_float4x4 transform;
/**
* 相机方向（旋转）的矢量欧拉角。
* @dicussion组件的顺序在这个向量场的轴旋转:
* 1。音高(x分量)是关于节点的轴的旋转(弧度)
* 2。偏航(y分量)是关于节点的轴的旋转(弧度)
* 3所示。卷(z分量)是关于节点的z轴的旋转(弧度)
* ARKit适用这些旋转的倒序组件:
* 1 第一卷
* 2 然后偏航
* 3 所示。然后投球
*/
@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
* fx和fy是像素的焦距。
* px和py是像素点的坐标。
* 原点位于左上角的像素中心。
*/
@property (nonatomic, readonly) matrix_float3x3 intrinsics;
/**
摄像头分辨率
*/
@property (nonatomic, readonly) CGSize imageResolution;
/**
投影矩阵
*/
@property (nonatomic, readonly) matrix_float4x4 projectionMatrix;
/**
将世界坐标系统的三维点投射到二维视窗空间。
@ param点三维点在世界坐标系统。
@param取向视窗取向。
@param viewportSize Viewport(或图像)大小。
@return 2D点，在viewport坐标系中，原点在左上角。
*/
- (CGPoint)projectPoint:(vector_float3)point orientation:(UIInterfaceOrientation)orientation viewportSize:(CGSize)viewportSize;
/**
* 创建相机投影矩阵
* @discussion 返回的投影矩阵提供了一个方面填补和旋转提供视窗的大小和方向。
* @param - viewportSize视窗大小。
* @param - 取向视窗取向。
* @param - zNear附近深度的限制。
* @param - zFar深度限制
*/
- (matrix_float4x4)projectionMatrixForOrientation:(UIInterfaceOrientation)orientation viewportSize:(CGSize)viewportSize zNear:(CGFloat)zNear zFar:(CGFloat)zFar;
/**
为摄像机创建一个视图矩阵，并给出一个界面朝向。
@ discussion这个视图矩阵可以用来将几何图形转换为一个给定方向的摄像机空间
@ param定位用于渲染相机视图的界面朝向。
*/
- (matrix_float4x4)viewMatrixForOrientation:(UIInterfaceOrientation)orientation;
/** 不可用 */
- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;
@end
3.ARError.h
/**
* 错误码描述
* 100：不支持会话追踪配置，主线由于A9芯片以下的机型会报错
* 101：失活状态
* 102：传感器故障
* 200：追踪失败
*/
typedef NS_ERROR_ENUM(ARErrorDomain, ARErrorCode) {
/** 不支持会话配置 */
ARErrorCodeUnsupportedConfiguration = 100,
/** 一个传感器运行会话所需是不可用的 */
ARErrorCodeSensorUnavailable = 101,
/** 一个传感器未能提供必要的输入 */
ARErrorCodeSensorFailed = 102,
/** 跟踪世界遇到了一个致命错误 */
ARErrorCodeWorldTrackingFailed = 200,
};
4.ARConfiguration.h
ARConfiguration会话追踪配置，主要就是追踪相机的配置
注意：该类还有一个子类：ARWorldTrackingConfiguration，它们在同一个API文件中
/**
世界会话的对齐方式，这里的对齐指的是3D世界的坐标，枚举值见下方
*/
typedef NS_ENUM(NSInteger, ARWorldAlignment) {
/** 相机位置 vector (0, -1, 0) */
ARWorldAlignmentGravity,
/** 相机位置及方向. vector (0, -1, 0) heading ：(0, 0, -1) */
ARWorldAlignmentGravityAndHeading,
/** 用相机的方向对准世界 */
ARWorldAlignmentCamera
} NS_SWIFT_NAME(ARConfiguration.WorldAlignment);
/**
侦查类型 - 选项设置指示飞机探测的类型。.
*/
typedef NS_OPTIONS(NSUInteger, ARPlaneDetection) {
/** 不侦查 */
ARPlaneDetectionNone = 0,
/** 平地侦查 - 飞机在现场检测确定横向飞机 */
ARPlaneDetectionHorizontal = (1 << 0),
} NS_SWIFT_NAME(ARWorldTrackingConfiguration.PlaneDetection);
/**
描述和配置在ARSession中使用的增强现实技术的对象, 主要就是追踪相机的配置
注意：该类还有一个子类：ARWorldTrackingSessionConfiguration，它们在同一个API文件中
*/
@interface ARConfiguration : NSObject
/**
当前设备是否支持，一般A9芯片以下设备不支持
*/
@property(class, nonatomic, readonly) BOOL isSupported;
/**
如何构建基于真实世界设备运动的场景坐标系的选项
确定坐标系统应该如何与世界对齐。这里的对其指的是3D世界的坐标。枚举值见上方
讨论默认的是ARWorldAlignmentGravity。
*/
@property (nonatomic, readwrite) ARWorldAlignment worldAlignment;
/**
是否需要自适应灯光效果，默认是YES
*/
@property (nonatomic, readwrite, getter=isLightEstimationEnabled) BOOL lightEstimationEnabled;
/**
确定是否捕获和提供音频数据, 默认禁用。
*/
@property (nonatomic, readwrite) BOOL providesAudioData;
/** 不可用 */
- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;
@end
/**
运行世界跟踪的配置。
世界跟踪提供了6个自由度跟踪装置。
通过在场景中找到特征点，世界跟踪可以在帧上执行hit- test。
一旦会话暂停，跟踪不能再恢复。
所有AR配置在设备居住的现实世界和可以对内容建模的虚拟3D坐标空间之间建立对应关系。当您的应用程序将内容与实时摄像机图像一起显示时，用户体验到您的虚拟内容是真实世界的一部分。
创建和维护空格之间的对应关系需要跟踪设备的运动。所述类跟踪设备的具有六个自由度（6DOF）移动：即，三个旋转轴（滚动，俯仰和偏转），三个平移轴（运动中的x，y和z）。ARWorldTrackingSessionConfiguration
这种级别的跟踪可以创建沉浸式的AR体验：虚拟对象似乎可以保持在相对于现实世界的相同位置，即使用户倾斜设备来查看对象的上方或下方，也可以移动设备以查看物体的侧面和背面。
*/
@interface ARWorldTrackingConfiguration : ARConfiguration
/**
侦查类型 默认为不侦查，不侦查ARPlaneDetectionNone = 0 .
如果设置，新的飞机将继续被检测和更新。探测到的飞机将被添加到会话中ARPlaneAnchor对象。当两架飞机合并后，新飞机将被移除。默认为ARPlaneDetectionNone。
*/
@property (nonatomic, readwrite) ARPlaneDetection planeDetection;
- (instancetype)init;
// Swift不能使用这个初始化方法
+ (instancetype)new NS_SWIFT_UNAVAILABLE("Use init() instead");
@end
/**
用于运行定向跟踪的配置。
定向跟踪提供了设备的3个自由度跟踪。
*/
@interface AROrientationTrackingConfiguration : ARConfiguration
- (instancetype)init;
// Swift不能使用这个初始化方法
+ (instancetype)new NS_SWIFT_UNAVAILABLE("Use init() instead");
@end
/**
用于运行面部跟踪的配置。
面部跟踪利用前置摄像头跟踪3D人脸，提供脸部的拓扑图和面部表情。
一个检测到的人脸将被添加到会话中作为一个ARFaceAnchor对象，它包含关于头部姿势，网格，眼睛姿势和混合形状的信息系数。如果光估计能使被检测的脸被当作一个光探针，用来估计入射光的方向。
*/
@interface ARFaceTrackingConfiguration : ARConfiguration
- (instancetype)init;
// Swift不能使用这个初始化方法
+ (instancetype)new NS_SWIFT_UNAVAILABLE("Use init() instead");
@end
5.ARFaceAnchor.h
混合形状位置的人脸几何
每个位置定义了一个可以被提供的系数替换的面部区域。
typedef NSString *ARBlendShapeLocation NS_STRING_ENUM NS_SWIFT_NAME(ARFaceAnchor.BlendShapeLocation) API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationBrowDownLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationBrowDownRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationBrowInnerUp API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationBrowOuterUpLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationBrowOuterUpRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationCheekPuff API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationCheekSquintLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationCheekSquintRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeBlinkLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeBlinkRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookDownLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookDownRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookInLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookInRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookOutLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookOutRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookUpLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookUpRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeSquintLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeSquintRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeWideLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeWideRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationJawForward API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationJawLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationJawOpen API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationJawRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthClose API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthDimpleLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthDimpleRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthFrownLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthFrownRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthFunnel API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthLowerDownLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthLowerDownRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthPressLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthPressRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthPucker API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthRollLower API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthRollUpper API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthShrugLower API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthShrugUpper API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthSmileLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthSmileRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthStretchLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthStretchRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthUpperUpLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthUpperUpRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationNoseSneerLeft API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationNoseSneerRight API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
@class ARFaceGeometry;
/**
代表脸孔及其几何形状的锚。
*/
@interface ARFaceAnchor : ARAnchor
/**
基于计算的混合形状的面部几何更新。
*/
@property (nonatomic, readonly) ARFaceGeometry *geometry;
/**
一种混合形状系数的字典。
@discussion Blend shape系数定义了一个在面部特定位置的中性形状的位移量.
*/
@property (nonatomic, readonly) NSDictionary *blendShapes;
/** 不可用 */
- (instancetype)initWithTransform:(matrix_float4x4)transform NS_UNAVAILABLE;
@end
6.ARFaceGeometry.h
/**
表示一个面几何形状的物体。
*/
@interface ARFaceGeometry : NSObject
/**
几何图形的网格顶点数。
*/
@property (nonatomic, readonly) NSUInteger vertexCount NS_REFINED_FOR_SWIFT;
/**
几何图形的网格顶点.
*/
@property (nonatomic, readonly) const vector_float3 *vertices NS_REFINED_FOR_SWIFT;
/**
面几何的纹理坐标的数目.
*/
@property (nonatomic, readonly) NSUInteger textureCoordinateCount NS_REFINED_FOR_SWIFT;
/**
几何的纹理坐标.
*/
@property (nonatomic, readonly) const vector_float2 *textureCoordinates NS_REFINED_FOR_SWIFT;
/**
面几何的三角形数.
*/
@property (nonatomic, readonly) NSUInteger triangleCount;
/**
几何的三角指数.
*/
@property (nonatomic, readonly) const int16_t *triangleIndices NS_REFINED_FOR_SWIFT;
/**
通过应用一组给定的混合形状系数来创建和返回一个面几何。
可以提供一个空字典来创建一个中立的面几何。
@param blendshape是一个混合形状系数的字典。
@return Face几何学应用了混合形状。
*/
- (nullable instancetype)initWithBlendShapes:(NSDictionary *)blendShapes;
/** 不可用 */
- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;
@end
/**
一个代表面孔的场景.
*/
@interface ARSCNFaceGeometry : SCNGeometry
/**
使用金属器件创建一个新的面部几何图形。
@ param设备是一个金属设备。
@ return一个新的face几何学
*/
+ (nullable instancetype)faceGeometryWithDevice:(id)device;
/**
使用金属器件创建一个新的面部几何图形。
默认情况下，眼睛lids和区域之间的区域嘴唇之间没有几何形状。将面部几何作为一个occlusion几何设置\ p fillMesh为YES。这将填补在额外的几何图形中，眼睛的间隙和进入的间隙嘴唇之间的差距。
@param fillMesh是否填入额外的几何图形 眼睛之间的间隙和嘴唇之间的空隙。
@ return一个新的face几何学
*/
+ (nullable instancetype)faceGeometryWithDevice:(id)device
fillMesh:(BOOL)fillMesh;
/**
用一个面几何的顶点更新几何图形。
@param face几何学A face几何学。
*/
- (void)updateFromFaceGeometry:(ARFaceGeometry *)faceGeometry;
/** 不可用 */
- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;
@end
7.ARFrame.h
ARFrame主要是追踪相机当前的状态，这个状态不仅仅只是位置，还有图像帧及时间等参数
一个对象，它封装了所有被跟踪的时刻的状态。
模型提供呈现给定帧所需的所有数据的快照。
@interface ARFrame : NSObject
/**
标识帧的时间戳。
*/
@property (nonatomic, readonly) NSTimeInterval timestamp;
/**
帧的图像捕获 - 缓冲区图像帧
*/
@property (nonatomic, readonly) CVPixelBufferRef capturedImage;
/**
框架捕获的深度数据
Depth数据只提供在捕获深度数据的帧上的face跟踪
*/
@property (nonatomic, strong, readonly, nullable) AVDepthData *capturedDepthData;
/**
确定深度数据的时间戳。
*/
@property (nonatomic, readonly) NSTimeInterval capturedDepthDataTimestamp;
/**
摄像机用来捕捉画面的画面。
The camera提供了设备的位置和方向以及相机参数。
表示这个ARFrame是哪一个相机的，iPhone7plus有两个摄像机
*/
@property (nonatomic, copy, readonly) ARCamera *camera;
/**
现场的一个锚点列表。
返回当前相机捕捉到的锚点数据（当一个3D虚拟模型加入到ARKit中时，锚点值得就是这个模型在AR中的位置）
*/
@property (nonatomic, copy, readonly) NSArray *anchors;
/**
一种表示场景中光线的光估计。
如果没有光估计，就返回nil。
灯光，详情可见本章节ARLightEstimate类介绍（指的是灯光强度 一般是0-2000，系统默认1000）
*/
@property (nonatomic, strong, nullable, readonly) ARLightEstimate *lightEstimate;
/**
特征点（应该是捕捉平地或者人脸的，比较苹果有自带的人脸识别功能）
场景中的特征点与框架的原点有关。
只提供了使用世界跟踪的配置。
*/
@property (nonatomic, strong, nullable, readonly) ARPointCloud *rawFeaturePoints;
/**
根据2D坐标点搜索3D模型，这个方法通常用于，当我们在手机屏幕点击某一个点的时候，可以捕捉到这一个点所在的3D模型的位置，至于为什么是一个数组非常好理解。手机屏幕一个是长方形，这是一个二维空间。而相机捕捉到的是一个由这个二维空间射出去的长方体，我们点击屏幕一个点可以理解为在这个长方体的边缘射出一条线，这一条线上可能会有多个3D物体模型
point：2D坐标点（手机屏幕某一点）(点在被捕获图像的图像空间坐标系统中。取值范围从(0,0)-左上角到(1,1)-右下角。)
ARHitTestResultType：捕捉类型 点还是面(类型的搜索结果类型)
(NSArray *)：追踪结果数组 详情见本章节ARHitTestResult类介绍
*/
- (NSArray *)hitTest:(CGPoint)point types:(ARHitTestResultType)types;
/**
返回提供的viewport大小和方向的显示转换。
可以用来转换图像空间坐标系统中的归一化点在视图的坐标空间中被捕获的图像到归一化点。转换提供了正确的旋转并在给定的方向和大小中显示捕获的图像。
定位视图端口的朝向。
viewportSize大小的viewport。
相机窗口的的坐标变换（可用于相机横竖屏的旋转适配）- 原来的API
*/
- (CGAffineTransform)displayTransformForOrientation:(UIInterfaceOrientation)orientation viewportSize:(CGSize)viewportSize;
/** 不可用 */
- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;
@end
8.ARHitTestResult.h
ARHitTestResult：点击回调结果，这个类主要用于虚拟增强现实技术（AR技术）中现实世界与3D场景中虚拟物体的交互。 比如我们在相机中移动。拖拽3D虚拟物体，都可以通过这个类来获取ARKit所捕捉的结果
/**
hittest结果类型的选项集。
捕捉类型枚举
*/
typedef NS_OPTIONS(NSUInteger, ARHitTestResultType) {
/** 结果类型与最接近的特征点相交 : 点*/
ARHitTestResultTypeFeaturePoint = (1 << 0),
/**结果类型从相交的水平平面估计，确定为当前帧 : 水平面 y为0 */
ARHitTestResultTypeEstimatedHorizontalPlane = (1 << 1),
/** 结果类型与现有的平面锚相交 : 已结存在的平面 */
ARHitTestResultTypeExistingPlane = (1 << 3),
/** 结果类型与现有的平面锚点相交，考虑到飞机的范围 : 已结存在的锚点和平面*/
ARHitTestResultTypeExistingPlaneUsingExtent = (1 << 4),
} NS_SWIFT_NAME(ARHitTestResult.ResultType);
@interface ARHitTestResult : NSObject
/**
测试结果的类型 : 捕捉类型
*/
@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;
/**
hit- test交叉的锚, 只会为现有的飞机结果类型提供锚点.
锚点（3D虚拟物体，在虚拟世界有一个位置，这个位置参数是SceneKit中的SCNVector3：三维矢量），而锚点anchor是这个物体在AR现实场景中的位置，是一个4x4的矩阵
*/
@property (nonatomic, strong, nullable, readonly) ARAnchor *anchor;
/** 不可用 */
- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;
@end
9.ARLightEstimate.h
ARLightEstimate是一个灯光效果，它可以让你的AR场景看起来更加的好
一种表示场景中光线的光估计。
@interface ARLightEstimate : NSObject
/**
照明的环境强度。
在一个照明良好的环境中，这个值接近1000。它通常从0(非常暗)到大约2000(非常明亮)。
*/
@property (nonatomic, readonly) CGFloat ambientIntensity;
/**
灯光的环境色温。
这指定了开尔文(6500对应于纯白色)照明的环境色温。
*/
@property (nonatomic, readonly) CGFloat ambientColorTemperature;
/** 不可用 */
- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;
@end
/**
A directional light estimate representing the light intensity and direction in the scene.
*/
API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos)
@interface ARDirectionalLightEstimate : ARLightEstimate
/**
Second degree spherical harmonics coefficients representing the intensity of light.
@discussion The data is an array of 27 32-bit floating-point values, containing three non-interleaved data sets
corresponding to the red, green, and blue sets of coefficients.
*/
@property (nonatomic, copy, readonly) NSData *sphericalHarmonicsCoefficients;
/**
The primary direction of light.
*/
@property (nonatomic, readonly) vector_float3 primaryLightDirection;
/**
The intensity of light in the primary direction.
*/
@property (nonatomic, readonly) CGFloat primaryLightIntensity;
@end
10.ARPlaneAnchor
ARPlaneAnchor是ARAnchor的子类，笔者称之为平地锚点,平面在X和Z方向上定义，其中Y是表面的正常。。ARKit能够自动识别平地，并且会默认添加一个锚点到场景中，当然要想看到真实世界中的平地效果，需要我们自己使用SCNNode来渲染这个锚点
锚点只是一个位置
/**
一种描述平面锚定值的值。
*/
typedef NS_ENUM(NSInteger, ARPlaneAnchorAlignment) {
/** 与重力平行的平面 */
ARPlaneAnchorAlignmentHorizontal
} NS_SWIFT_NAME(ARPlaneAnchor.Alignment);
@interface ARPlaneAnchor : ARAnchor
/**
:平面的对准 : 平地类型，目前只有一个，就是水平面 。
*/
@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;
/** 不可用 */
- (instancetype)initWithTransform:(matrix_float4x4)transform NS_UNAVAILABLE;
@end
11.ARPointCloud.h
ARPointCloud：点状渲染云，主要用于渲染场景
@interface ARPointCloud : NSObject
/**
点云中的点个数。
*/
@property (nonatomic, readonly) NSUInteger count;
/**
包含点云的3D点 : 每一个点的位置的集合（结构体带*表示的是结构体数组）
*/
@property (nonatomic, readonly) const vector_float3 *points;
/**
包含点云的3D点标识符
*/
@property (nonatomic, readonly) const uint64_t *identifiers;
/** 不可用 */
- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;
@end
12.ARSCNView.h
ARSCNView是3D的AR场景视图
将ARSession渲染集成到SceneKit中的视图
视图绘制相机背景，提供和更新相机，管理锚点的节点，并更新照明
@interface ARSCNView : SCNView
/**
代理
*/
@property (nonatomic, weak, nullable) id delegate;
/**
视图用来更新场景的会话 : AR会话视图使用更新的场景
*/
@property (nonatomic, strong) ARSession *session;
/**
指定视图的场景。
*/
@property(nonatomic, strong) SCNScene *scene;
/**
确定视图是否将更新场景的灯光
视图将自动创建和更新照明光。默认值为YES。
*/
@property(nonatomic) BOOL automaticallyUpdatesLighting;
/**
搜索与提供节点相关的锚点的场景层次结构。
@ param节点在视图的场景中。
* 返回对应节点的锚点，节点是一个3D虚拟物体，它的坐标是虚拟场景中的坐标，而锚点ARAnchor是ARKit中现实世界的坐标
*/
- (nullable ARAnchor *)anchorForNode:(SCNNode *)node;
/**
返回已映射到特定锚的节点。
@ param用现有的节点映射锚定锚。
* 返回对应锚点的物体
*/
- (nullable SCNNode *)nodeForAnchor:(ARAnchor *)anchor;
/**
在当前帧中搜索与视图中某个点对应的对象。
在视图的坐标空间中，一个2D点可以参考线段上的任意点
在三维空间中。hit- testing是在这个线段上找到世界上的物体的过程。
@ param点在视图的坐标系统中。
@ param类型的搜索结果类型。
@返回一个所有的hittest结果的数组，从最近到最远。
* 根据2D坐标点搜索3D模型，这个方法通常用于，当我们在手机屏幕点击某一个点的时候，可以捕捉到这一个点所在的3D模型的位置，至于为什么是一个数组非常好理解。手机屏幕一个是长方形，这是一个二维空间。而相机捕捉到的是一个由这个二维空间射出去的长方体，我们点击屏幕一个点可以理解为在这个长方体的边缘射出一条线，这一条线上可能会有多个3D物体模型
point：2D坐标点（手机屏幕某一点）
ARHitTestResultType：捕捉类型 点还是面
(NSArray *)：追踪结果数组 详情见本章节ARHitTestResult类介绍
数组的结果排序是由近到远
*/
- (NSArray *)hitTest:(CGPoint)point types:(ARHitTestResultType)types;
@end
// 代理
#pragma mark - ARSCNViewDelegate
/**
* 代理的内部实现了SCNSceneRendererDelegate：scenekit代理 和ARSessionObserver：ARSession监听（KVO机制）
*/
@protocol ARSCNViewDelegate
@optional
/**
实现此功能，为给定的锚提供一个自定义节点。
@ discussion这个节点将自动添加到场景图中。如果未实现此方法，则将自动创建一个节点。如果返回nil，锚将被忽略。
@ param渲染器渲染场景。
@ param锚点添加。
@ return将被映射到锚或nil的节点。
*/
- (nullable SCNNode *)renderer:(id )renderer nodeForAnchor:(ARAnchor *)anchor;
/**
当一个新节点映射到给定的锚时调用。
@ param渲染器渲染场景。
@ param节点映射到锚的节点。
@ param锚点添加。
* 当添加节点是会调用，我们可以通过这个代理方法得知我们添加一个虚拟物体到AR场景下的锚点（AR现实世界中的坐标
*/
- (void)renderer:(id )renderer didAddNode:(SCNNode *)node forAnchor:(ARAnchor *)anchor;
/**
当节点将从给定的锚点更新数据时调用。
@ param渲染器渲染场景。
@ param节点将被更新的节点。
@ param锚点更新。
* 将要刷新节点
*/
- (void)renderer:(id )renderer willUpdateNode:(SCNNode *)node forAnchor:(ARAnchor *)anchor;
/**
当节点已从给定的锚点更新数据时调用。
@ param渲染器渲染场景。
@ param节点被更新的节点。
@ param锚点更新。
* 已经刷新节点
*/
- (void)renderer:(id )renderer didUpdateNode:(SCNNode *)node forAnchor:(ARAnchor *)anchor;
/**
当给定的锚点被从场景图中移除时调用。
@ param渲染器渲染场景。
@ param节点被删除的节点。
@ param锚点被移除。
* 移除节点
*/
- (void)renderer:(id )renderer didRemoveNode:(SCNNode *)node forAnchor:(ARAnchor *)anchor;
@end
/**
扩展了ARSCNView的调试选项
*/
struct ARSCNDebugOptions {} API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(macos, watchos, tvos);
/** 在场景中展示世界起源 */
FOUNDATION_EXTERN const SCNDebugOptions ARSCNDebugOptionShowWorldOrigin Swift名字(ARSCNDebugOptions.showWorldOrigin);
/** 显示在世界上检测到的3D特征点 */
FOUNDATION_EXTERN const SCNDebugOptions ARSCNDebugOptionShowFeaturePoints Swift名字(ARSCNDebugOptions.showFeaturePoints);
13.ARSession.h
ARSession是一个连接底层与AR视图之间的桥梁，其实ARSCNView内部所有的代理方法都是由ARSession来提供的
ARSession获取相机位置数据主要有两种方式:
第一种：push。 实时不断的获取相机位置，由ARSession主动告知用户。通过实现ARSession的代理- (void)session:(ARSession *)session didUpdateFrame:(ARFrame *)frame来获取
第二种：pull。 用户想要时，主动去获取。ARSession的属性currentFrame来获取
/**
运行会话的选项集。
这些选项改变了在会话中调用run的行为, 没有提供选项将导致恢复跟踪的默认行为, 从最后一个已知位置和保持所有现有的锚。
*/
typedef NS_OPTIONS(NSUInteger, ARSessionRunOptions) {
/** 会话将重置跟踪 */
ARSessionRunOptionResetTracking = (1 << 0),
/** 会话将删除现有的锚 */
ARSessionRunOptionRemoveExistingAnchors = (1 << 1)
} NS_SWIFT_NAME(ARSession.RunOptions);
@interface ARSession : NSObject
/**
代理
*/
@property (nonatomic, weak) id delegate;
/**
执行委托调用的分派队列。
@ discussion如果没有提供或nil，委托调用将在主队列上执行。
* 指定代理执行的线程（主线程不会有延迟，子线程会有延迟），不指定的话默认主线程
*/
@property (nonatomic, strong, nullable) dispatch_queue_t delegateQueue;
/**
会话的当前框架 : 相机当前的位置（是由会话追踪配置计算出来的.
*/
@property (nonatomic, copy, nullable, readonly) ARFrame *currentFrame;
/**
会话目前正在使用的配置 : 会话追踪配置.
*/
@property (nonatomic, copy, nullable, readonly) ARConfiguration *configuration;
/**
* 运行会话（这行代码就是开启AR的关键所在）
使用提供的配置运行会话。
@ discussion调用运行在已经启动的会话上, 转换立即使用新的配置。配置使用的配置。
*/
- (void)runWithConfiguration:(ARConfiguration *)configuration NS_SWIFT_UNAVAILABLE("Use run(_:options:) instead");
/**
* 运行会话，只是多了一个参数ARSessionRunOptions：作用就是会话断开重连时的行为。ARSessionRunOptionResetTracking：表示充值追踪 ARSessionRunOptionRemoveExistingAnchors：移除现有锚点
使用提供的配置和选项运行会话。
@ discussion调用运行在已经启动的会话上, 转换立即使用新的配置。选项可用于在转换配置时更改默认行为。配置使用的配置。
@ param选项使用的运行选项。
*/
- (void)runWithConfiguration:(ARConfiguration *)configuration options:(ARSessionRunOptions)options NS_SWIFT_NAME(run(_:options:));
/**
暂停会话。
@ discussion一旦暂停，就不会收到更多的更新会话直到运行再次调用。
*/
- (void)pause;
/**
在会话中添加一个锚。
@ discussion这个锚将在下一个帧更新中添加。
@ param锚点添加。
*/
- (void)addAnchor:(ARAnchor *)anchor NS_SWIFT_NAME(add(anchor:));
/**
从会话中删除一个锚。
在随后的帧更新中将删除锚点。
@ param锚定要删除。
*/
- (void)removeAnchor:(ARAnchor *)anchor NS_SWIFT_NAME(remove(anchor:));
@end
/**
session代理分类两部分，一个是观察者（KVO） 一个是委托者（代理）
*/
#pragma mark - ARSessionObserver
// session KVO观察者
@protocol ARSessionObserver
@optional
/**
这在会话失败时调用 : session失败
关于失败的讨论将暂停。
@ param会话失败了。
@ param错误被报告的错误(见ARError.h)。
*/
- (void)session:(ARSession *)session didFailWithError:(NSError *)error;
/**
当相机的跟踪状态发生变化时，就会调用这个功能。
@ param会话正在运行。
@ param相机改变追踪状态的相机。
*/
- (void)session:(ARSession *)session cameraDidChangeTrackingState:(ARCamera *)camera;
/**
这在会话被中断时调用 : session意外断开（如果开启ARSession之后，APP退到后台就有可能导致会话断开）
讨论会话将被中断，不再能够跟踪
它无法接收所需的传感器数据。当视频捕捉被打断时，
例如，当应用程序被发送到后台或者当应用程序出现时
多个前台应用程序(参见AVCaptureSessionInterruptionReason)。
没有附加的帧更新将被传送到中断结束。
@ param会话被中断的会话。
*/
- (void)sessionWasInterrupted:(ARSession *)session;
/**
这在会话中断结束时调用 : session会话断开恢复（短时间退到后台再进入APP会自动恢复）
讨论会话将继续从上一次已知状态运行中断已经结束。如果设备移动了，锚就会偏离方向。为了避免这种情况，一些应用程序可能需要重新设置跟踪(参见ARSessionRunOptions)。
@ param会话被中断的会话。
*/
- (void)sessionInterruptionEnded:(ARSession *)session;
/**
当会话输出一个新的音频样本缓冲区时，调用这个方法。
@ param会话正在运行。
@param audioSampleBuffer捕获的音频样本缓冲区。
*/
- (void)session:(ARSession *)session didOutputAudioSampleBuffer:(CMSampleBufferRef)audioSampleBuffer;
@end
// session 代理
#pragma mark - ARSessionDelegate
@protocol ARSessionDelegate
@optional
/**
* 相机当前状态（ARFrame：空间位置，图像帧等）更新
这是在新框架被更新时调用的。
@ param会话正在运行。
@ param框架已经更新的框架。
*/
- (void)session:(ARSession *)session didUpdateFrame:(ARFrame *)frame;
/**
当在会话中添加新锚时调用此方法。
@ param会话正在运行。
@ param锚定了一系列添加的锚。
*/
- (void)session:(ARSession *)session didAddAnchors:(NSArray*)anchors;
/**
这是当锚被更新时的调用
@ param会话正在运行。
@ param锚定了一系列更新的锚点。
*/
- (void)session:(ARSession *)session didUpdateAnchors:(NSArray*)anchors;
/**
当从会话中删除锚时，调用此方法。
@ param会话正在运行。
@ param锚定了一组被移除的锚。
*/
- (void)session:(ARSession *)session didRemoveAnchors:(NSArray*)anchors;
14.ARSKView.h
ARSKView也是AR视图，他是2D的
ARSKView基本与ARSCNView类似
#pragma mark ARSKViewDelegate
/**
* 协议
*/
@protocol ARSKViewDelegate
@optional
/**
* 实现这个提供一个自定义为给定的锚节点
* @discussion这个节点将自动添加到场景图。如果没有实现这个方法,将自动创建一个节点。如果返回nil锚将被忽略。
* @param - 渲染场景视图的视图。
* @param - 锚添加的锚。
* @return - 节点将映射到锚或零。
*/
- (nullable SKNode *)view:(ARSKView *)view nodeForAnchor:(ARAnchor *)anchor;
/**
* 当一个新节点映射到给定的锚
* @param - 渲染场景视图的视图。
* @param - 映射到锚节点的节点。
* @param - 锚添加的锚。
*/
- (void)view:(ARSKView *)view didAddNode:(SKNode *)node forAnchor:(ARAnchor *)anchor;
/**
* 当一个节点将更新数据从给定的锚。
* @param - 渲染场景视图的视图。
* @param - 节点的节点将被更新。
* @param - 锚锚的更新。
*/
- (void)view:(ARSKView *)view willUpdateNode:(SKNode *)node forAnchor:(ARAnchor *)anchor;
/**
* 当一个节点和数据从给定的锚已经更新。
* @param - 渲染场景视图的视图。
* @param - 节点的节点更新。
* @param - 锚锚的更新。
*/
- (void)view:(ARSKView *)view didUpdateNode:(SKNode *)node forAnchor:(ARAnchor *)anchor;
/**
* 时调用映射节点已被删除从给定的锚的场景图
* @param - 渲染场景视图的视图。
* @param - 点的节点删除。
* @param - 锚锚的更新。
*/
- (void)view:(ARSKView *)view didRemoveNode:(SKNode *)node forAnchor:(ARAnchor *)anchor;
@end
#pragma mark ARSKView
/**
将ARSession渲染集成到SpriteKit中的视图。
@ discussion视图绘制相机背景，项目和地图锚点到节点。
*/
@interface ARSKView : SKView
/**
指定视图的委托。
*/
@property (nonatomic, weak, nullable) NSObject *delegate;
/**
视图用来更新视图的会话。
*/
@property (nonatomic, strong) ARSession *session;
/**
搜索与提供节点相关的锚点的场景层次结构。
@ param节点在视图的场景中。
*/
- (nullable ARAnchor *)anchorForNode:(SKNode *)node;
/**
返回已映射到特定锚的节点。
@ param用现有的节点映射锚定锚。
*/
- (nullable SKNode *)nodeForAnchor:(ARAnchor *)anchor;
/**
在当前帧中搜索与视图中某个点对应的对象。
在视图的坐标空间中，一个2D点可以参考线段上的任意点
在三维空间中。hit- testing是在这个线段上找到世界上的物体的过程。
@ param点在视图的坐标系统中。
@ param类型的搜索结果类型。
@返回一个所有的hittest结果的数组，从最近到最远。
*/
- (NSArray *)hitTest:(CGPoint)point types:(ARHitTestResultType)types;
Git到的ARKit说明，供大家参考学习
