精细化美型SDK-iOS

人脸识别

所有文档

          人脸识别

          • 人脸识别
          • >
          • SDK文档
          • >
          • 精细化美型SDK
          • >
          • 精细化美型SDK-iOS

          精细化美型SDK-iOS

          更新时间：2020-10-16


          本文档主要介绍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的开发过程示例及效果展示；需要扩展算法能力的开发者，可根据示例中的代码快速进行算法接入。
          上一篇
          产品简介
          下一篇
          精细化美型SDK-Android