快手人像美化SDK Objective-C API

1. SDK依赖

1.1 依赖库

• MagicEngine.framework 为特效引擎（人像美化）静态framework
• opencv2.framework 依赖库
• libtensorflowlite.a 依赖库
• CoreML.framework 依赖库
• MetalPerformanceShader.framework 依赖库
• StreamLakeLicensing.framework 鉴权库
• StreamLakeOpenAPI.framework 鉴权库

1.2 依赖资源

• MagicEngine.bundle 人像美化SDK内置素材，细条特效需要用到，实例化sdk时设到MEEngineConfig 的builtinPath
• ycnn_metal.bundle AI推理所需的资源文件，需要内置放在打包的.ipa根目录

2. 工程配置

• 在Xcode中依次点击打开 target->Build Phases->Link Binary With Libraries。
• 点击下方的+再从弹窗最下面选择Add Other按钮，点击Add Files从弹出的文件选择框中选择你本地的MagicEngine.framework,opencv2.framework,StreamLakeLicensing.framework,StreamLakeOpenAPI.framework,libtensorflowlite.a进行添加。
• 点击下方的+再从弹窗最下面选择Add Other按钮，点击Add Files从弹出的文件选择框中选择你本地的``进行添加。
• 再次点击下方的+再弹窗中依次搜搜CoreML.framework，MetalPerformanceShader.framework点击Add进行添加依赖库。
• 点击 target->Build Settings 搜 Other Linker Flags, 双击点击底下加号添加 $(inherited),-ObjC, -l"c++"
• 关闭bitcode

3. 数据结构与枚举

/**
 * 业务类型
 */
typedef enum MEBusinessType
{
    MEBusinessType_Camera = 0, ///< 相机业务
    MEBusinessType_Video,      ///< 视频业务
    MEBusinessType_Image       ///< 图片业务
} MEBusinessType;

/**
 * 引擎配置
 */
typedef struct MEEngineConfig
{
    char builtinPath[ME_PATH_MAX]; ///< 内置资源跟目录
    MEBusinessType businessType;   ///< 业务类型
    int width;                     ///< 渲染尺寸
    int height;                    ///< 渲染尺寸
} MEEngineConfig;

/**
 * 色域类型
 */
typedef enum MEColorSpace
{
    MEColorSpace_601VideoRange = 0,
    MEColorSpace_601FullRange,
    MEColorSpace_709VideoRange,
    MEColorSpace_709FullRange,
    MEColorSpace_2020VideoRange,
    MEColorSpace_2020FullRange
} MEColorSpace;

/**
 * YUV数据类型
 */
typedef enum MEYUVDataFormat
{
    MEYUVDataFormat_NV21,
    MEYUVDataFormat_NV12,
    MEYUVDataFormat_I420
} MEYUVDataFormat;

/**
 * 相机位置
 */
typedef enum MECameraPosition
{
    MECameraPosition_Unknown = 0, ///< 未定义的相机位置
    MECameraPosition_Front,       ///< 前置
    MECameraPosition_Back         ///< 后置
} MECameraPosition;

typedef struct MEFrameData
{
    const unsigned char* data[3]; ///< YUV像素数据
    int stride;                   ///< data的Y平面一行字节数
    MECameraPosition position;    ///< 相机位置(前置,后置)
    MEColorSpace colorSpace;      ///< 色域类型
    MEYUVDataFormat format;       ///< 像素数据格式
    int width;                    ///< 宽度
    int height;                   ///< 高度
    int rotation;                 ///< 顺时针旋转这个角度后为正图
    float fov;                    ///< 相机视野角度
    bool mirror;                  ///< 镜像
    void* extraData;              ///< 额外数据
} MEFrameData;

/**
 * 特效类型
 */
typedef enum MEEffectType
{
    MEEffectType_Beautify = 0, ///< 美颜
    MEEffectType_Makeup,       ///< 美妆
    MEEffectType_Deform,       ///< 美型
    MEEffectType_Lookup,       ///< 滤镜
    MEEffectType_BodySlimming  ///< 美体
} MEEffectType;

/**
 * 滤镜Lut类型
 */
typedef enum MELookupType
{
    MELookupType_NxN = 0, ///< 方形NxN的Lut
    MELookupType_Nx1      ///< 横向Nx1的Lut
} MELookupType;

/**
 * 滤镜配置
 */
typedef struct MELookupInfo
{
    char path[ME_PATH_MAX]; ///< Lut图路径
    float intensity;        ///< 强度
    int dimension;          ///< 维数
    MELookupType type;      ///< Lut类型
} MELookupInfo;

/**
 * 美妆配置
 */
typedef struct MEMakeupInfo
{
    char resourceDir[ME_PATH_MAX]; ///< 资源路径
    char key[ME_PATH_MAX];         ///< 资源key, 用于替换
    float intensity;               ///< 强度
} MEMakeupInfo;

/**
 * 美颜调节类型
 */
typedef enum MEBeautyType
{
    MEBeautyType_Bright = 0,    ///< 美白
    MEBeautyType_Soften,        ///< 磨皮
    MEBeautyType_WrinkleRemove, ///< 法令纹
    MEBeautyType_EyeBagRemove,  ///< 黑眼圈
    MEBeautyType_Teeth,         ///< 白牙
    MEBeautyType_EyeBrighten,   ///< 亮眼
    MEBeautyType_FaceShadow,    ///< 立体
    MEBeautyType_Clarity,       ///< 清晰
    MEBeautyType_EvenSkin,      ///< 匀肤
} MEBeautyType;

/**
 * 美体调节
 */
typedef enum MEBodySlimmingType
{
    MEBodySlimmingType_Head = 0, ///< 小头
    MEBodySlimmingType_Neck,     ///< 天鹅颈
    MEBodySlimmingType_Waist,    ///< 瘦腰
    MEBodySlimmingType_Hip,      ///< 美胯
    MEBodySlimmingType_Leg,      ///< 长腿
    MEBodySlimmingType_Shoulder, ///< 瘦肩
    MEBodySlimmingType_Breast,   ///< 丰胸
} MEBodySlimmingType;

/**
 * 传感器配置类型
 */
typedef enum MESensorConfigType
{
    MESensorConfigType_Reset = 0, ///<重置
    MESensorConfigType_Remove     ///<移除
} MESensorConfigType;

/**
 * 传感器配置
 */
typedef struct MESensorConfig
{
    float updateInterval;          ///< 更新时间间隔
    MESensorConfigType configType; ///< 传感器配置配型
} MESensorConfig;

/**
 * 传感器数据
 */
typedef struct MESensorData
{
    double timestamp;       ///< 传感器时间戳
    float rotation;         ///< 旋转角度
    double attitude[4];     ///< 设备姿态
    double acceleration[3]; ///< 加速度
} MESensorData;

/**
 * 日志类型
 */
typedef enum MELogType
{
    MELogType_Debug = 0, ///< 调试
    MELogType_Info,      ///< 信息
    MELogType_Warning,   ///< 警告
    MELogType_Error,     ///< 错误
} MELogType;

4. API说明

4.1 鉴权API说明：

人像美化SDK的使用依赖StreamlakeLicensing，请务必先初始化Licensing SDK，否则人像美化SDK会调用失败，不生效

• step 1. 优先初始化StreamLakeOpenAPI

OpenAPI 网络库配置：

1. 设置 Class协议实现
   a. openAPI_AccessKey 返回对应申请好的AK
   b. onlineHosts线上域名设置为https://vod.streamlakeapi.com
   c. deployVersion设置为2022-02-10

#import <StreamLakeOpenAPI/SLONetworkingSetupConfig.h>

@interface SLAppDelegate()<SLONetworkingSetup>
@end

@implementation SLAppDelegate

// 填写申请的AK
+ (NSString *)openAPI_AccessKey {
    return @"xx";
}

+ (NSString *)openAPI_DeployVersion {
    return @"2022-02-10";
}

+ (NSArray<NSString *> *)openAPI_OnlineHosts {
    return @[@"https://vod.streamlakeapi.com"];
}


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  	// 尽早设置 配置实现类
  	[SLONetworkingSetupConfig setupNetworking:self.class];
    return YES;
}

• step 2. 在使用人像美化功能前完成初始化StreamLakeLicensing

ProdCode传入"y-tech"
RSAPublicKey传入申请好的公钥。注意公钥格式换行

举个例子：每行都需要换行，第2行-第8行需要靠左顶到头，不要多余空格

    NSString *publicKey = @"-----BEGIN RSA PUBLIC KEY-----\n\
MIIBCgKCAQEA6l1y9YEIxzJ7ZaVyQQZbi0FyNTDom0Bhe68Vb5ep8/jqsL4pHvDc\n\
tc5b5jiqmW8mNXNP6dQ4wHmDeq/YtDk27bGTJ/vKTtqrGf6iZrpTwcDoq4+1fsgv\n\
KsO2c3Mw7mo7t/4Z4R2gW8qng1ZSU27WlWJakcDUcV3NJW1znIdkLzxbadX2apWl\n\
FBjfon6TLK/VTmbwYxavKPBfmqAmMeh9e1jfP/swk7O5BT3KhfYaltflMaUODZ2D\n\
YO88uVslHCX4WhGlCLrbDgVhCNMQ6ANEKOr1U6iEujC98h+2oKgw41Pj0f6rcii6\n\
ksCBQBpc5ngug/dOgVT8e2sB6xDpPzppmQIDAQAB\n\
-----END RSA PUBLIC KEY-----";

_ytechLicensingMgr = [[SLLicensingManager alloc] initWithRSAPublicKey:publicKey prodCode:@"y-tech"];
   [_ytechLicensingMgr setupWithCompletion:^(BOOL success) {
       NSLog(@"y-tech setup %@, begin verify", @(success));
   }];

4.2 渲染API说明：

人像美化SDK需要引以下的头文件：

#import <MagicEngine/MagicEngine.h>

API中的参数和返回值类型以及每个属性的含义请看上面的**3.数据结构与枚举**
人像美化SDK主要包含滤镜，美妆，美颜，美型，美体。需要单独开启和关闭并设定参数

4.2.1 引擎实例化

/**
 * @brief 实例化人像美化SDK
 * @param config 引擎的配置数据
 * @return 引擎实例
 */
+ (id<MagicEngineSync>)createSyncMagicEngine:(MEEngineConfig*)config;

4.2.2 数据处理接口

/**
 * @brief 同步渲染接口，结果写入返回值frameData中，不要求在GL上下文中调用
 * @param frameData 帧数据描述
 * @return 带渲染结果的MEFrameData
 */
- (MEFrameData*)processWithFrameData:(MEFrameData*)frameData;

4.2.4 通用调节接口

下面这些接口主要是用来设定及调节美颜，美型，美妆，美体，滤镜等。

/**
 * @brief 人像美化协议
 */
@property (nonatomic, weak) id<MagicEngineDelegate> delegate;

/**
 * @brief 设定模型路径
 * @param pathDic 模型key和path的字典
 */
- (void)setModelPathDic:(NSDictionary<NSString*, NSString*>*)pathDic;

/**
 * @brief 开启/关闭 单个特效
 * @param effectType 需要开启的特效类型
 * @param enable 开启或者关闭状态
 */
- (void)setEffectEnabledWidthEffectType:(MEEffectType)effectType enable:(bool)enable;

/**
 * @brief 设定滤镜资源
 * @param lookupInfo 需要设定的拍前滤镜信息
 */
- (void)setLookupInfo:(MELookupInfo)lookupInfo;

/**
 * @brief 设定滤镜强度
 * @param intensity 滤镜强度
 */
- (void)setLookupIntensity:(float)intensity;

/**
 * @brief 设定美妆资源
 * @param makeupInfo  需要设定的美妆信息，每个部分都是一个MakeupInfo结构
 */
- (void)setMakeupInfo:(NSArray<NSValue*>*)makeupInfo;

/**
 * @brief 设定美妆强度
 * @param key 需要调整的美妆key（设定美妆时用户自定义）
 * @param intensity 强度
 */
- (void)setMakeupIntensityWithKey:(NSString*)key intensity:(float)intensity;

/**
 * @brief 设定美颜强度
 * @param type 需要调节的美颜类型
 * @param intensity 强度
 */
- (void)setBeautyIntensityWithType:(MEBeautyType)type intensity:(float)intensity;

/**
 * @brief 设定美型强度
 * @param mode 美型类型
 * @param intensity  强度
 */
- (void)setDeformIntensityWithMode:(int)mode intensity:(float)intensity;

/**
 * @brief 设定美体强度
 * @param type  需要调整的美体类型
 * @param intensity  强度
 */
- (void)setBodySlimmingIntensityWithType:(MEBodySlimmingType)type intensity:(float)intensity;

/**
 * 更新传感器数据
 * @param sensorData 传感器数据
 */
- (void)setSensorData:(MESensorData)sensorData;

/**
 * 清理内部正在处理的数据帧队列
 */
- (void)clearFrameQueue;

/**
 * @brief 销毁引擎. 调用之后此实例不可再使用. 此方法主要用于保障 MagicEngine 在合适的时机合适的线程释放资源.
 */
- (void)destroy;

4.3模型配置

美颜美型等都需要一些AI模型的支持。模型的路径通过上面所说的setModelPathDic 方法设定。模型资源都放在了resource目录中的model.7z中，解压之后就能看到。其中模型的key为文件夹名字，path设此文件夹的路径。例如：key为magic_ycnn_model_landmark的路径设为/path/to/magic_ycnn_model_landmark。

当前所有的模型为：

magic_mmu_model_animoji1 	
magic_mmu_model_basewhite
magic_ycnn_model_cloth_seg
magic_ycnn_model_face_attributes
magic_ycnn_model_face_seg
magic_ycnn_model_finger
magic_ycnn_model_general_handpose
magic_ycnn_model_gesture
magic_ycnn_model_hair
magic_ycnn_model_head_seg
magic_ycnn_model_humanpose
magic_ycnn_model_landmark
magic_ycnn_model_matting
magic_ycnn_model_skin_seg

• 美颜模块所需模型：

magic_ycnn_model_landmark

• 美妆模块所需模型：

magic_ycnn_model_landmark
magic_ycnn_model_face_attributes
magic_ycnn_model_face_seg

• 美型模块所需模型：

magic_ycnn_model_landmark

• 美体模块所需模型：

magic_ycnn_model_landmark
magic_ycnn_model_humanpose

• 滤镜模块所需模型：

不需要AI模型

通过setModelPathDic可以多次设定或刚开始把模型key和对应的路径先设定，应用对应功能之前确保再该路径中下载好或者放好对应模型。原则上需要模型的功能在被调用之前把对应的key和path通过这个dictionary设进去即可。

例如：刚开始只调用美颜和美型可以设定magic_ycnn_model_landmark ,magic_ycnn_model_face_attributes ，后面调节美体可以在之前的基础上添加magic_ycnn_model_humanpose三个一起设进去。可以一直累加，外部维护一个dictionary，或者全部一起设定，之后在确保模型存于早先设定的路径。

5. 调用流程

1.调用鉴权API进行授权
2.调用 createSyncMagicEngine:创建人像美化
3.调用 processWithFrameData: 进行数据处理
4.准备退出时调用 destroy 方法销毁SDK