精细化美型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的开发过程示例及效果展示;需要扩展算法能力的开发者,可根据示例中的代码快速进行算法接入。