精细化美型SDK-iOS
本文档主要介绍SDK集成和接口调用。在使用本文档前，建议您先了解相关产品简介，并已经开通了应用授权，申请并下载好相关SDK文件。
1 快速入门
1.1 支持的系统和硬件版本
- 系统：支持 iOS9.0及以后
- CPU架构：arm64 （注：sdk只支持arm64架构真机效果，使用过程中与ar相关的代码请使用
defined (__arm64__)符号隔离开。）
1.2 开发包说明及结构
您使用的Demo中包含基础功能、案例展示、算子开发三部分。
Demo的目录结构为
|--sdk 算子文件夹
|--demo demo项目文件夹
1.3 引入SDK及工程配置
1.3.1 工程引入SDK到您的工程
您下载的DumixDemo中会生成多个能力对应的静态.a文件，将 DumixDemo/lib 下的静态库都放入您的工程之中。
1.3.2 配置工程设置
工程中加入系统库libc++.tbd、Accelerate.fram、 WebKit.framework、libsqlite3.0.tbd
工程Build Settings中Other Linker Flags 加入-ObjC
工程Build Settings中Other Linker Flags设置force_load，路径为libArFrameworkForceload.a所在的路径。请参考DumixDemo配置
工程Build Settings中Header Search Paths加上 lib/component/include 路径，这是ar的头文件
1.4 引入SDK所依赖的资源
SDK所依赖的资源都在 DumixDemo/Resource 下，请将资源都引入到工程中
1.5 SDK鉴权
鉴权说明：SDK在使用之前需要申请鉴权文件（dumixar.license）并在工程中引入
在主线程中调用鉴权函数，方法如下：
/**
设置license数
@param licenseData license文件中的二进制数据
@param onlineFeatures server在线返回的模块授权码 备注：需要在ARController初始化完成后，才会返回在线授权码 @param unsupportedFeature 校验失败的模块授权码
@return license文件中配置的模块授权码
*/
+ (NSArray *_Nullable) setLicenseData:(NSData *_Nonnull)licenseData
onlineFeatures:(nullable void (^)(NSArray *_Nullable onLinefeatures))onlineFeatures
unsupportedFeature:(nullable void (^)(NSInteger unsupportedfeature))unsupportedFeature;2 初始化SDK
2.1 主要类及主要方法介绍
BARMainController为SDK使用的主对象，是AR SDK统一对外输出接口，基于该对象，可以完成对AR SDK环境初始化和各种能力调用
2.2 版本号获取
/** ARSDK版本
@return 当前ARSDK版本号
*/
+ (NSString *)arSDKVersion;2.3 初始化
目前SDK初始化分为两种，按照您的需求进行初始化工作
2.3.1 标准初始化
大部分用户用该方式进行初始化，比如直播、小视频等项目
/**
@abstract 初始化方法
@param cameraSize 相机尺寸
@param previewSize 预览尺寸
@return BARMainController实例
*/
- (instancetype)initARWithCameraSize:(CGSize)cameraSize
previewSize:(CGSize)previewSize
extraInfo:(NSDictionary *)info;2.3.2单帧图片初始化方式
若您想进行单帧图片的处理，请按照该方式进行SDK初始化
/**
@abstract 进行单帧图片处理的初始化方法
@param videoSize size的width、height都大于0即可
@param videoRotaion 传0即可
@param info 扩展信息，暂无
*/
- (instancetype)initARWithVideoSize:(CGSize)videoSize
videoRotation:(NSInteger)videoRotation
info:(NSDictionary* _Nullable)info;2.4 设置模型及资源路径
2.4.1 设置人脸模型路径
/**
人脸算法为基本能力，美颜、美型、人脸贴纸等相关能力都必须设置人脸模型，具体用到下面几个方法
*/
- (void)initFaceData;
- (void)setFaceDetectModelPaths:(NSArray *)paths;
- (void)setFaceAnimateModelPaths:(NSArray *)paths;
- (void)setFaceTrackModelPaths:(NSArray *)trackPaths;
- (void)setFaceAttributesModelPaths:(NSArray *)paths;2.4.2 设置非人脸算法模型路径
若您没有非人脸的玩法，可以不设置该模型
/**
@abstract 设置非人脸算法模型总包路径：json配置文件+模型
@param path 算法模型路径
*/
- (void)setAlgorithmModelsPath:(NSString *)path; 2.4.3 设置必须的滤镜资源路径
注意：使用特效能力必须设置一份初始化滤镜资源(arFilterInit.bundle)
2.5 SDK生命周期
说明：ARSDK核心流程：初始化、销毁、pause、reusme，sdk运行期间需要注意的问题：
1.创建SDK有两种方式，分为普通单帧数据处理和图片类单帧处理
2.销毁ar，注意 leavear的时机不要在vc的dealloc中调用，在dealloc之前就要调用，防止上一个ar没有销毁的同时已经创建了新的ar
3.AR不支持后台渲染，所以在app在后台的时候要pause
4.在系统恢复到前台的时候要resume
2.6 其他BARMainController接口说明
2.6.1 开始SDK
/**
@abstract 启动AR
*/
- (void)startAR;2.6.2 暂停SDK
/**
@abstract 暂停AR
*/
- (void)pauseAR;2.6.3 恢复SDK
/**
@abstract 恢复AR
*/
- (void)resumeAR;2.6.4 销毁SDK
/**
@abstract 离开AR
*/
- (void)leaveAR;2.7 单帧处理
处理CMSampleBufferRef格式数据
说明：需要按照第1种方式初始化arcontroller，目前该方法有两种调用方式，同步模式和异步模式
/**
设置同步、异步模式
@param syncOutputMode,YES同步调用,NO异步调用。
*/
- (void) setSyncOutputMode:(BOOL)syncOutputMode;2.7.1 异步模式单帧处理
/**
@abstract 处理相机数据
@param sampleBuffer 相机数据
@param data 附加数据
*/
- (void)updateSampleBuffer:(CMSampleBufferRef)sampleBuffer extraInfo:(id)data;说明：该方法为异步方法，回调为
/**
@abstract 设置引擎渲染完成的回调
@param block 引擎渲染完成block
@param sampleBuffer为处理之后的buffer数据，extraData为传入的extraData数据
*/
- (void)setRenderSampleBufferCompleteBlock:(void (^)(CMSampleBufferRef sampleBuffer,id extraData))block;2.7.2 同步模式单帧处理
/**
init 之后调用,否则不生效
@param sampleBuffer 传入的图像数据
@parma extraInfo,返回的handle化的数据，可以为空。
@return 经过渲染后的图像数据。如果不没有CFRetain,则不需要CFRelease。
需要在下一次调用之前使用完成，否则需要对返回值使用深拷贝。
*/
- (CMSampleBufferRef) syncUpdateSampleBuffer:(CMSampleBufferRef) sampleBuffer
extraInfo:(NSDictionary ** ) extraInfo;2.8 处理UIImage格式数据
说明：需要按照第2种方式初始化arcontroller
/**
@abstract 处理UIImage
@param image 传入image
@param timeoutSecond 超时时间，传2即可
@return 处理之后的image
*/
- (UIImage *_Nullable) processUIImage:(UIImage *_Nonnull) image
timeoutSecond:(CGFloat)timeoutSecond;2.9 屏幕触控
说明：当您需要进行点击、滑动屏幕等和case进行交互的场景，可以使用下列方法进行参数传递
- (void)onViewGesture:(UIGestureRecognizer *)gesture;
- (void)ar_touchesBegan:(NSSet<UITouch *> *)touches scale:(CGFloat)scale;
- (void)ar_touchesMoved:(NSSet<UITouch *> *)touches scale:(CGFloat)scale;
- (void)ar_touchesEnded:(NSSet<UITouch *> *)touches scale:(CGFloat)scale;
- (void)ar_touchesCancelled:(NSSet<UITouch *> *)touches scale:(CGFloat)scale;2.10 设置相机位置
说明：当您反转相机之后需要将相机位置传递给sdk
/**
@abstract 设置当前是前置还是后置摄像头
@param position 前置传1，后置传0
@param needArMirrorBuffer 传NO
*/
- (void)setDevicePosition:(int)position needArMirrorBuffer:(BOOL)needArMirrorBuffer;2.11 Native发消息给Lua
说明：当您需要将一些native操作传递给case，以便case中的lua脚本相应的时候，可以调用该方法
/**
@abstrac 向lua发送消息(新方式)
@param eventName 消息名
@param eventData 消息内容
@discussion lua中通过注册监听，获得消息Event:addEventListener("session_find_anchor", find_anchor)
*/
- (void)sendMsgToLua:(NSString *)eventName eventData:(NSDictionary *)eventData;2.12 监听Lua发来的消息
说明：此函数callback主要处理接收lua发送的内部消息，主要包括切换camera消息，控制浏览器url打开等
typedef void (^BARLuaMsgBlock)(BARMessageType msgType, NSDictionary *dic);
//Lua callBack 枚举说明
typedef enum {
BARMessageTypeNone = -1,
BARMessageTypeCustom = 1000,//自定义
BARMessageTypeOpenURL = 1001,//打开URL
BARMessageTypeEnableFrontCamera = 1002,//开启前置摄像头
BARMessageTypeChangeFrontBackCamera = 1003,//前后摄像头切换
BARMessageTypeIntitialClick = 1004,//引导页点击
BARMessageTypeNativeUIVisible = 1005,//Native UI处理（显示、隐藏）
BARMessageTypeCloseAR = 1006,//关闭AR
BARMessageTypeShowAlert = 1007,//弹出alert
BARMessageTypeShowToast = 1008,//弹出toast
BARMessageTypeSwitchCase = 1009,//切换case
BARMessageTypeLogoStart = 1010,//Logo识别开始
BARMessageTypeLogoStop = 1011,//Logo识别结束 BARMessageTypeBatchDownloadRetryShowDialog = 1012,//分布加载batch包(失败后弹窗) BARMessageTypeLuaStatistic = 1013,//case内统计信息
BARMessageTypeLuaMakeupState = 1014,//是否需要显示原生美妆调节页面:event_id : 0不显示 1显示 BARMessageTypeLuaCaseFilterCreated = 1015,//case内是否开启了滤镜
BARMessageTypeVPSSessionInvalid = 1016,//vps sesison失效
BARMessageTypeVPSHideUIBtn = 1017//vps 隐藏按钮
} BARMessageType;3 SDK能力调用
3.1 滤镜
加载Lut色调滤镜
说明：Lut(Look Up Table)滤镜,主要是通过Lut文件将原始颜色通过LUT的颜色查找表映射到新的色彩上去。通过AR内处理后，输出到上屏的图像的各种特殊效果。
/**
@abstrac 切换滤镜
@param dic filter_type：
滤镜类型 filter_name：滤镜名称
resource_path：滤镜文件路径
*/
- (void)switchFilterWithDictionary:(NSDictionary *)dic;说明：当您想设置调节程度值的时候需要调用adjustFilterType方法，设置BARFaceBeautyType参数，具体BARFaceBeautyType说明如下
| 参数 | 说明 | 取值范围 [0.0, 1.0] |
|---|---|---|
| BARFaceBeautyTypeNormalFilter | 色调滤镜 | 0为无效果，1为最大效果 |
3.2 美肤（基础美颜）
说明：美肤包括美白、磨皮，调整其程度值如下
/**
调节/美妆/美型滤镜 @param type 效果参数枚举
枚举滤镜类别 @param value 参数调节
*/
- (void)adjustFilterType:(BARFaceBeautyType)type value:(CGFloat)value;说明：当您想设置调节程度值的时候需要调用adjustFilterType方法，设置BARFaceBeautyType参数，具体BARFaceBeautyType说明如下
| 参数 | 说明 | 取值范围 [0.0, 1.0] |
|---|---|---|
| BARFaceBeautyTypeNormalFilter | 色调滤镜 | 0为无效果，1为最大效果 |
| BARFaceBeautyTypeSkin | 磨皮 | 0为无效果，1为最大效果 |
| BARFaceBeautyTypeWhiten | 美白 | 0为无效果，1为最大效果 |
3.3 美型（五官精准塑形）
说明：美型是基于人脸局部部位进行美化，包括大眼，瘦脸，脸长，发际线等脸部进行调整，以及调整其程度值。
其中基础版包含大眼、瘦脸两项能力；高级版包含大眼、瘦脸、及其它16个子项调节能力、模版脸能力
/**
调节/美妆/美型滤镜 @param type 效果参数枚举
枚举滤镜类别 @param value 参数调节
*/
- (void)adjustFilterType:(BARFaceBeautyType)type value:(CGFloat)value;说明：当您想设置调节程度值的时候需要调用adjustFilterType方法，设置BARFaceBeautyType参数，具体BARFaceBeautyType说明如下
| 参数 | 说明 | 取值范围 [0.0, 1.0] |
|---|---|---|
| BARFaceBeautyTypeEye | 大眼 | 0为无效果，1为最大效果 |
| BARFaceBeautyTypeThinFace | 瘦脸 | 0为无效果，1为最大效果 |
| BARFaceBeautyTypeChin | 下巴高度 | 无效果值：0.5，小于0.5缩小，大于0.5放大 |
| BARFaceBeautyTypeFaceWidth | 脸宽调整程度 | 0为无效果，1为最大效果 |
| BARFaceBeautyTypemandibleAndle | 下颌角宽度 | 0为无效果，1为最大效果 |
| BARFaceBeautyTypeEyeLength | 双眼间距 | 无效果值：0.5，小于0.5缩小，大于0.5放大 |
| BARFaceBeautyTypeEyeAngle | 双眼旋转角度 | 无效果值：0.5，小于0.5缩小，大于0.5放大 |
| BARFaceBeautyTypeBrowLength | 眉毛间距 | 无效果值：0.5，小于0.5缩小，大于0.5放大 |
| BARFaceBeautyTypeMouthWidth | 嘴宽调整程度 | 无效果值：0.5，小于0.5缩小，大于0.5放大 |
| BARFaceBeautyTypeThreePartLength | 脸长调整程度 | 无效果值：0.5，小于0.5缩小，大于0.5放大 |
| BARFaceBeautyTypeTopPartLength | 发际线高度 | 无效果值：0.5，小于0.5缩小，大于0.5放大 |
| BARFaceBeautyTypeMediumPartLength | 中庭高度 | 无效果值：0.5，小于0.5缩小，大于0.5放大 |
| BARFaceBeautyTypeBottomPartLength | 下庭高度 | 无效果值：0.5，小于0.5缩小，大于0.5放大 |
| BARFaceBeautyTypeNoseWidth | 鼻宽度 | 0为无效果，1为最大效果 |
| BARFaceBeautyTypeNoseLength | 鼻长度 | 无效果值：0.5，小于0.5缩小，大于0.5放大 |
| BARFaceBeautyTypeCheekBone | 颧骨 | 0为无效果，1为最大效果 |
3.4 模版脸
说明：模版脸由上述16个美型子项，选出部分调节项进行模板化调节，定义了自然脸、精致脸（网红脸）、娃娃脸等几款脸型，能方便您快速的看到不同的脸的效果。
加载模版脸
/**
@abstract 加载模版脸
@param casePath 资源路径
@return 需要调节的property
*/
- (NSString *)adjustFilterWithCasePath:(NSString *)casePath;3.5 case加载相关
case类型的内容可实现人脸贴纸、动漫脸、人脸小游戏、特效滤镜等创意内容，也可支持手势识别触发、人脸表情触发等交互类特效，具体请参考已授权产品能力的说明。
case包内有特效素材，人脸美化参数，交互逻辑代码等，具体可参考相关素材制作规范文档。
3.5.1 加载case
/**
从本地路径加载case
@param filePath case资源包路径,下载并解压完后的路径
@param arType ARKey（case唯一标识）
@param successBlock 加载成功回调
@param failureBlock 加载失败回调：case包有问题或者鉴权失败
*/
- (void)loadARFromFilePath:(NSString *)filePath
arKey:(NSString *)arKey
arType:(NSString *)arType
success:(BARLoadSuccessBlock)successBlock
failure:(BARLoadFailedBlock)failureBlock;3.5.2 清空case
/**
停止AR
*/
- (void)stopAR;说明：加载case和清空case需要做状态保护，即case加载完成之前不能继续加载case或清空case。
3.6 录制
说明：录制使用了BARVideoRecorder类
3.6.1 开始录制
- (void)startRecordingWithAudioTrack:(BOOL)enable;3.6.2 录制每帧数据
- (void)processVideoSampleBuffer:(CMSampleBufferRef)sampleBuffer atTime:(CMTime)time;3.6.3 结束录制
- (void)stopRecording:(void (^)(void))handler;3.7 拍照
说明：BARMaincontroller中的方法
/**
拍照
@param finishBlock 拍照回调
*/
- (void)takePicture:(BARTakePictureFinishBlock)finishBlock;4 Demo说明
- 基础功能：对AR SDK能力接口调用展示，包括拍摄器初始化，加载内容CASE，人脸美颜特效展示等。开发者可以基于此demo，快速将AR SDK集成到工程项目中。
- 案例展示：AR开放的各算法特效应用示例；开发者可快速查看对应算法的应用效果。
- 算子开发：新算法接入AR SDK的开发过程示例及效果展示；需要扩展算法能力的开发者，可根据示例中的代码快速进行算法接入。