开放能力
开发平台
行业应用
生态合作
开发与教学
资讯 社区 控制台
技术能力
语音技术
图像技术
文字识别
人脸与人体识别
视频技术
AR与VR
自然语言处理
知识图谱
数据智能
场景方案
部署方案
行业应用
智能教育
智能医疗
智能零售
智能工业
企业服务
智能政务
智能农业
信息服务
智能园区
智能硬件
人脸识别

    人脸特效贴纸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及工程配置

    工程引入SDK到您的工程

    您下载的DumixDemo中会生成多个能力对应的静态.a文件,将 DumixDemo/lib 下的静态库都放入您的工程之中。

    配置工程设置

    工程中加入系统库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 case加载相关

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

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

    3.1.2 加载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.1.3 清空case

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

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

    3.2 录制

    说明:录制使用了BARVideoRecorder类

    3.2.1 开始录制

    - (void)startRecordingWithAudioTrack:(BOOL)enable;

    3.2.2 录制每帧数据

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

    3.2.3 结束录制

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

    3.3 拍照

    说明:BARMaincontroller中的方法

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

    4 Demo说明

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