Avatar 虚拟形象
  • iOS : Objective-C
  • Android
  • Unity3D
  • 产品简介
  • 下载
  • 下载体验 App
  • 快速开始
    • 跑通示例源码
    • 集成 SDK
    • 在线鉴权
    • 创建虚拟形象
    • ZegoCharacterHelper 使用说明
  • 基本功能
  • 进阶功能
  • 最佳实践
  • 常见错误码
  • 服务端 API
  • 客户端 API
  • 常见问题

ZegoCharacterHelper 使用说明

更新时间:2022-11-02 21:23

Helper 概述

在创建虚拟人物形象时,为了简化 Character(虚拟人物形象) 的初始化、序列化、数据缓存、路径拼接、资源映射等功能的接入流程,ZEGO Avatar SDK 提供了 ZegoCharacterHelper 类(开源),帮助开发者快速创建人物虚拟形象。

使用时,请前往 下载 页面,获取 ZegoCharacterHelper 类(开源) 的相关代码。

ZegoCharacterHelper 类是对 IZegoCharacter 等的封装,开发者如果使用了 ZegoCharacterHelper,则无需再调用 IZegoCharacter 的任何相关接口。

使用步骤

1 (可选)预加载资源

如果开发者需要预加载资源,请在初始化 ZegoCharacterHelper 之前进行。

  1. 首先,需要上传美术等资源包的绝对路径,具体请参考 导入资源包

  2. 调用 preload 静态方法,传入模型资源包的绝对路径,预加载资源,减少后续初始化 ZegoCharacterHelper 的时间。

    • base.bundle:头模
    • human.bundle:全身人模

以下展示了头模的预加载示例,开发者请根据场景需求,选择加载所需模型,后续涉及到模型路径的地方同理。

// 获取美术资源的绝对路径(路径可自定义)
NSString *resPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingString:@"/assets/base.bundle"];

// 预加载资源
[ZegoCharacterHelper preload:resPath];

2 初始化 ZegoCharacterHelper

如果已使用了 preload 接口预加载资源,调用 init 接口初始化 ZegoCharacterHelper 时,传入的路径必须和预加载时的路径一致。

  1. 首先,需要上传美术等资源包的绝对路径,具体请参考 导入资源包

  2. 调用 init 接口,传入资源包的绝对路径,初始化 ZegoCharacterHelper。

// 定义 Helper
@property (nonatomic, strong) ZegoCharacterHelper *characterHelper;

// 获取美术资源的绝对路径(路径可自定义)
NSString *resPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingString:@"/assets/base.bundle"];

// 初始化 Helper
_characterHelper = [[ZegoCharacterHelper alloc] init:resPath];

3 设置默认形象

初次使用的用户,还没有虚拟形象数据,此时可以调用 setDefaultAvatar 接口,设置默认的虚拟形象。

  • 男性角色:MODEL_ID_MALE
  • 女性角色:MODEL_ID_FEMALE
// 以男性角色 MODEL_ID_MALE 设置外形为例
[_characterHelper setDefaultAvatar:MODEL_ID_MALE];

4 创建虚拟形象视图

  1. 初始化 ZegoCharacterHelper 后,调用 createAvatarView 接口,创建 Avatar 视图,并配置视图的宽、高等信息。
  2. 调用 setCharacterView 接口,传入 avatarView,关联虚拟人物形象的视图。

使用此接口前,请确保正确设置了 AvatarJson 数据,即已调用过 setDefaultAvatarsetAvatarJson 方法。

// 创建 AvatarView 
_avatarView = [[ZegoAvatarService sharedInstance] createAvatarView:CGRectMake(0, 0, width, height)];
[self.view addSubview:_avatarView];

// 关联 AvatarView,角色上屏
[_characterHelper setCharacterView:avatarView];

至此,开发者可以搭建起一个默认的虚拟人物形象。

调整虚拟人物外观

搭建出基本的虚拟人物形象后,可以参考下文,调整虚拟人物的形象外观。

设置脸型

调用 setFaceShape 接口,传入 faceshapID(可调整的脸部维度,请参考 手动捏脸)和 value(捏脸系数)等参数,设置或修改脸部相关位置的形状。我们在 helper/ZegoCharacterHelper.h 中,同样声明了所有可支持调整的脸部维度 faceshapeID。

// 设置眉毛粗细
[_characterHelper setFaceShape:FACESHAPE_BROW_SIZE_Y value:0.3];

设置发色 & 获取发色

调用 setHairColor 接口,设置人物的头发颜色。

其中,第一个参数是发根颜色,第二个参数是发尾颜色,颜色取值为 RGBA。

发根和发尾可以设置为相同或不同颜色;设置为不同颜色时,从发根至发尾,呈渐变色。

[_characterHelper setHairColor:[ZegoColor redColor] endColor:[ZegoColor blueColor]];

如果需要获取头发颜色,调用 getHairColor 接口,返回结果是头发颜色数组。

其中 [0] 发根颜色,[1] 发梢颜色,颜色取值为 RGBA。

NSArray<ZegoColor *> *colorList = [_characterHelper getHairColor];

设置肤色 & 获取肤色

ZEGO Avatar SDK 固定取色卡,不可替换。开发者使用时,请将此图拷贝至自己的项目路径下。

/Pics/ZegoAvatar/iOS/98.png

其中,左上角(0, 0)对应白种人,(0.3, 0.3)对应亚洲人,右下角(1.0, 1.0)对应黑人。坐标越大(指横向向右、纵向向下),颜色越深。

// 设置虚拟人模的肤色坐标,坐标取值请参考取色卡
[_characterHelper setSkinColorCoordinates:CGPointMake(0.5, 0.8)];
// 获取虚拟人模的肤色坐标
CGPoint coodr = [_characterHelper getSkinColorCoordinates];

AI 捏脸

如果用户想要根据图片,自动生成虚拟人物形象:

  1. 准备好图片后,调用 detectFaceFeature 接口,传入 UIImage,即可生成该图片对应的虚拟人物形象,

  2. 创建出虚拟人物形象后,调用 applyFaceFeature 接口,传入 feature,设置脸部特征。

// 根据传入的图片,提取人脸特征
ZegoFaceFeature *feature = [[[ZegoAvatarService sharedInstance] getInteractEngine] detectFaceFeature:image];

// 根据人脸特征,设置人物外形
[_characterHelper applyFaceFeature:feature];
  • AI 捏脸时,可以不用事先设置默认性别或其它 json 数据,因为调用捏脸接口后,会自动生成这些数据。
  • AI 捏脸之前,需要提前设置好 ExtendPackagesPath,避免找不到相关资源,无法还原 AI 捏脸效果。

设置表情

  • 开启表情检测前,请确认已开启摄像头权限。
  • 开发者如果使用了 ZegoCharacterHelper,则无需再调用 IZegoCharacter 的任何相关接口。

搭建出基本的虚拟人物形象后,调用 startDetectExpression 接口,设置驱动模式为 ZegoExpressionDetectModeCamera,通过前置摄像头,开始检测表情;然后可以直接通过 ZegoCharacterHelper 的 setExpression 接口设置表情,驱动当前虚拟人物的面部表情变化。

// 开始表情检测
___weak typeof(self) weakSelf = self;
BOOL ret = [[[ZegoAvatarService sharedInstance] getInteractEngine] startDetectExpression:ZegoExpressionDetectModeCamera callback:^(ZegoExpression *expression) {
    // 驱动虚拟人物的嘴形变化
    __strong typeof(self) strongSelf = weakSelf;
    [strongSelf.characterHelper setExpression: expression];
}];

妆容换装

开发者如果使用了 ZegoCharacterHelper,则无需再调用 IZegoCharacter 的任何相关接口。虽然 IZegoCharacter 也有同名的 setPackage 接口,但请不要直接调用。如果跳过 ZegoCharacterHelper 直接调用 IZegoCharacter 的接口,ZegoCharacterHelper 层的缓存将不再可信。

在给虚拟人模更换转容或服装配饰之前:

  1. 如果开发者把 Packages 资源包做成动态下载,则需要在使用 Packages 前,调用 ZegoCharacterHelper 的 setExtendPackagesPath 接口,设置 Packages 的下载目录到参数 downloadPath,以便资源索引。

    downloadPath 需指到 Packages 文件夹,例如:/Documents/downloads/Package/

  2. 调用 setPackage 接口,传入 packageID(需要设置的资源,具体请参考 妆容换装),调整虚拟人物相关位置的外观。

//确保换装调用前已经设置的外部 Packages 的目录
[_characterHelper setExtendPackagesPath:downloadPath]
// 调用换装接口
NSString *packageID = @"facepaint1"; // 需要确保 downloadPath 目录下有这个目录。
[_characterHelper setPackage:packageID];

获取外观数据

设置完外观数据后,开发者还可以通过 ZegoCharacterHelper 的 getAvatarJson 接口,获取该虚拟形象的 json 数据,并将该数据存放于服务端用户 profile 中,供下次还原使用。

NSString *json = [_characterHelper getAvatarJson];

还原外观数据

如果用户通过 ZegoCharacterHelper 的 getAvatarJson 接口,保存了虚拟人物的外观数据,就可以 setAvatarJson 接口,传入该数据,还原用户的个性化虚拟形象。

[_characterHelper setAvatarJson:json];

播放动画

调用 playAnimation 接口,传入指定的动画 Key 参数,即可播放对应动画。

相关资源请参考 下载 获取。

[_characterHelper playAnimation:@"walk"];

可用动画 Key 如下表所列:

动画 Key 说明
relax 放松
walk 走路
run 奔跑
think 思考

开启 or 禁用动画

调用 enableAnimation 接口,传入 YES,即可开启动画;传入 NO 则禁用动画。

[_characterHelper enableAnimation:NO];

设置视角

调用 setViewport 接口修改视角,参数说明如下:

参数 说明
ZegoAvatarViewPortType_FullBody 全身像
ZegoAvatarViewPortType_HalfBody 半身像
ZegoAvatarViewPortType_Head 头像
// 设置全身人像视角
[_characterHelper setViewport:ZegoAvatarViewPortType_FullBody];

设置默认表情

  1. 首先调用 setDefaultExpression 接口,传入默认表情数据文件的路径(路径可自定义,默认表情数据文件,请从 下载 获取)。
  2. 调用 enableDefaultExpression 接口,控制是否开启默认表情。请确保已调用 setDefaultExpression 传入正确的默认表情数据,否则无法正常显示默认表情。
// 获取默认表情数据文件的绝对路径(路径可自定义)
NSString *expressionPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingString:@"/ZADefaultExpressionData.txt"];
// 设置默认表情
[_characterHelper setDefaultExpression: expressionPath];
// 开启默认表情
[_characterHelper enabelDefaultExpression: YES];

导出 Avatar 纹理

搭建出基本的虚拟人物形象后,直接通过 startCaptureAvatar 接口,传入 AvatarCaptureConfig(配置导出纹理的宽、高)、开始导出 Metal 纹理。您可以参考 在 RTC 视频流中使用 Avatar,将渲染结果用于 RTC 推流中。

  • 如果要导出 Avatar 纹理,请不要使用 setAvatarView 接口,即不要用 AvatarView 进行渲染,否则可能会造成无法正常获取 Avatar 纹理来推流。
  • 导出 Avatar 纹理时,相当于做离线渲染,之前的虚拟形象将不会被渲染到屏幕。
// 开始导出纹理
//根据实际需求设置 Avatar 返回内容的宽(captureWidth)和高(captureHeight)
AvatarCaptureConfig* config = [[AvatarCaptureConfig alloc] initWithWidth:captureWidth height:captureHeight];
@weakify(self);    //解决 self 循环引用
[self.helper startCaptureAvatar:config callback:^(unsigned long long texture, int width, int height) {
    //纹理id、长、宽
}];

// 停止导出纹理
[self.helper stopCaptureAvatar];

导出 Avatar 头套纹理

搭建出基本的虚拟人物形象后,直接通过 startCaptureFaceMaskAvatar 接口,传入 AvatarCaptureConfig(配置导出纹理的宽、高)、开始导出头套纹理。您可以参考 AR 驱动,将渲染结果导出到客户端设备或推流到服务端。

  • 如果要导出 Avatar 头套纹理,请不要使用 setAvatarView 接口,即不要用 AvatarView 进行渲染,否则可能会造成无法正常获取 Avatar 纹理来推流。
  • 导出 Avatar 头套纹理,相当于 Avatar 做离线渲染,然后与相机视频融合出头套纹理。
// 开始导出
// 开发者需要设置 Avatar 返回内容的预期宽(captureWidth)和预期高(captureHeight),SDK 会自动匹配一个跟您的预期接近的相机视频输出分辨率。
// 例如:如果您设置为 600*400,SDK 在启动相机时会设置输出分辨率为 640*480。您可以自定义不同分辨率转换时的纹理画面处理。
AvatarCaptureConfig* config = [[AvatarCaptureConfig alloc] initWithWidth:captureWidth height:captureHeight];

[self.helper startCaptureFaceMaskAvatar:avconfig 
                               callback:^(id<MTLTexture> texture,int width,int height, int faceCount){
    // 纹理 id、输出纹理宽、输出纹理高、检测到的面部数
}];

// 停止导出头套纹理
[self.helper stopCaptureFaceMaskAvatar];