所有文档

          人脸识别

          美妆试妆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 美妆

          说明:美妆是运用AR能力对人的面部、五官及其他部位进行渲染、增强立体印象,调整形色效果,以及调整其程度值。

          3.1.1 加载美妆

          /**
           @abstract 美妆加载
           @param casePath 资源路径
           @return 需要调节的property
           */
          - (NSString *)adjustFilterWithCasePath:(NSString *)casePath;

          3.1.2 设置美妆透明度

          /** 
          调节美妆透明度 (不支持BARMakeupTypeAll) 
          @param type 美妆类型 
          @param alpha 透明度 0-1 
          */ 
          - (void)adjustMakeupType:(BARMakeupType)type alpha:(CGFloat)alpha;

          3.1.3 设置美妆开关

          /** 
          开启、关闭美妆效果 (支持BARMakeupTypeAll) (注意:需要先设置美妆,才可以设置美妆的开启关闭状态) 
          @param type 美妆类型 @param enable 
          0:关闭 1:开启。default is 0. 
          */ 
          - (void)adjustMakeupType:(BARMakeupType)type enable:(NSInteger)enable;

          3.2 case加载相关

          case类型的内容可实现人脸贴纸、动漫脸、人脸小游戏、特效滤镜等创意内容,也可支持手势识别触发、人脸表情触发等交互类特效,具体请参考已授权产品能力的说明。

          case包内有特效素材,人脸美化参数,交互逻辑代码等,具体可参考相关素材制作规范文档。

          3.2.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.2.2 清空case

          /** 
          停止AR 
          */ 
          - (void)stopAR;

          说明:加载case和清空case需要做状态保护,即case加载完成之前不能继续加载case或清空case。

          3.3 录制

          说明:录制使用了BARVideoRecorder类

          3.3.1 开始录制

          - (void)startRecordingWithAudioTrack:(BOOL)enable;

          3.3.2 录制每帧数据

          - (void)processVideoSampleBuffer:(CMSampleBufferRef)sampleBuffer atTime:(CMTime)time;

          3.3.3 结束录制

          - (void)stopRecording:(void (^)(void))handler;

          3.4 拍照

          说明:BARMaincontroller中的方法

          /** 
          拍照 
          @param finishBlock 拍照回调 
          */ 
          - (void)takePicture:(BARTakePictureFinishBlock)finishBlock;

          4 Demo说明

          • 基础功能:对AR SDK能力接口调用展示,包括拍摄器初始化,加载内容CASE,人脸美颜特效展示等。开发者可以基于此demo,快速将AR SDK集成到工程项目中。
          • 案例展示:AR开放的各算法特效应用示例;开发者可快速查看对应算法的应用效果。
          • 算子开发:新算法接入AR SDK的开发过程示例及效果展示;需要扩展算法能力的开发者,可根据示例中的代码快速进行算法接入。
          上一篇
          产品简介
          下一篇
          美妆试妆SDK-Android