ZegoCharacterHelper instructions
Overview
To simplify the integration process of the initialization, serialization, data caching, path splicing, and resource mapping features during virtual avatar creation, the ZegoAvatar SDK provides the open-source ZegoCharacterHelper class to help developers create virtual avatars quickly. When you use ZegoCharacterHelper, go to SDK downloads to obtain the related code of the ZegoCharacterHelper class.
The ZegoCharacterHelper class encapsulates IZegoCharacter. If the ZegoCharacterHelper class is used, no APIs related to IZegoCharacter need to be called.
1 Optional: Preload resources
To preload resources, do this before initializing the ZegoCharacterHelper:
First, upload the absolute path of the resource packages. For details, see Import resource packages.
Call the
preload
method, and pass the absolute path of the model resource to preload the resource to reduce the time required to initialize ZegoCharacterHelper later.
- base.bundle: Head model
- human.bundle: Full-body model
The following is an example of the preloading of a header model. You can select the required model to be loaded according to the requirements of the scenario.
//This directory is the absolute path of base.bundle. You need to copy this file to the storage directory of your mobile phone.
ZegoCharacterHelper.preload(getFilesDir().getAbsolutePath() + "/assets/base.bundle");
### 2. Initialize ZegoCharacterHelper
<div class="mk-warning">
If the `preload` method has been used, the incoming path must be consistent with the preload path when initializing ZegoCharacterHelper.
</div>
1. Upload the absolute paths of the aesthetics resource packages. For more information, see [Import resource packages\|_blank](/article/14622#3).
2. Introduce the absolute path of the resource packages and initialize the **ZegoCharacterHelper** class.
```java
// This directory is the absolute path of base.bundle. You need to copy this file to the storage directory of your mobile phone.
ZegoCharacterHelper mCharacterHelper = new ZegoCharacterHelper(getFilesDir().getAbsolutePath() + "/assets/base.bundle");
// Set the directories of the makeup, clothing, hair, and other resources. The resource content can be downloaded from the Internet based on your needs.
mCharacterHelper.setExtendPackagePath(getFilesDir().getAbsolutePath() + "/assets/Packages");
3. Set the default avatar
When no virtual avatar data exists, you can call the setDefaultAvatar
API to set a default virtual avatar.
- Male role: MODEL_ID_MALE="male"
- Female role: MODEL_ID_FEMALE="female"
// MODEL_ID_MALE is used as an example to set the appearance.
mCharacterHelper.setDefaultAvatar(ZegoCharacterHelper.MODEL_ID_FEMALE);
4. Create a virtual avatar view
- After ZegoCharacterHelper is initialized, call the
findViewById
API to create an avatar view and configure the width, height, and other information of the view. - Call the
setCharacterView
API, introduce avatarView, and associate it with the view of the virtual avatar.
Before using this interface, make sure that the AvatarJson data is set correctly, that is, the setDefaultAvatar
or setAvatarJson
method has been called.
// Obtain the avatarView stated in the activity xml.
mZegoAvatarView = findViewById(R.id.zego_avatar_view);
// Display the avatar view on the screen.
// The view must be set on a UI thread by ZegoCharacterHelper.
mCharacterHelper.setCharacterView(mZegoAvatarView);
In this case, a default virtual avatar is created.
Adjust the appearance of the virtual avatar
After the basic virtual avatar is created, refer to the following content to adjust the appearance of the virtual avatar.
Set the face shape
Call the setFaceShape
API and introduce the faceshapeID (adjustable facial dimension), value (avatar creation coefficient), and other parameters to set or modify the dimensions of facial parts. For more information about adjustable facial dimensions, see Manual avatar creation. We also describe all adjustable facial dimensions (faceshapeID) in helper/ZegoCharacterHelper.java.
// Example: Set the eyebrow thickness.
mCharacterHelper.setFaceShape(ZegoCharacterHelper.FACESHAPE_BROW_SIZE_Y, 0.3);
Set and obtain the hair color
Call the setHairColor
API to set the hair color of the virtual avatar.
The first parameter indicates the color of the hair root, and the second parameter indicates the color of the hair tail. The valid values are red, green, blue, and alpha.
You can set the same or different colors for the hair root and tail. If different colors are set, the color gradually changes from the hair root to the hair tail.
mCharacterHelper.setHairColor(redColor, blurColor);
To obtain the hair color, call the getHairColor
API. The hair color array is returned.
0 indicates the color of the hair root, and 1 indicates the color of the hair tail. The valid values are red, green, blue, and alpha.
ZegoColor[] colors = mCharacterHelper.getHairColor();
Set and obtain the skin color
The ZegoAvatar SDK provides a fixed color picking card, which cannot be replaced. You can copy this image to a directory of your project.
)
Take the color picking card as a coordinate system. (0, 0) lies in the top left corner and indicates the white skin, (0.3, 0.3) indicates the yellow skin, and (1.0, 1.0) lies in the bottom right corner indicates the black skin. The larger the coordinates (rightwards in the horizontal direction and downward in the vertical direction), the darker the skin color.
// Set the coordinates of the skin color.
mCharacterHelper.setSkinColorCoordinates(new ZegoPoint(0.5, 0.1));
// Obtain the coordinates of the current skin color.
ZegoPoint point = mCharacterHelper.getSkinColorCoordinates();
Automatic avatar generation
To automatically generate a virtual avatar based on an image, perform the following steps:
- After the image is prepared, call the detectFaceFeature API and introduce the image using the
bitmap
format to generate a virtual avatar. - After a virtual avatar is created, call the
applyFaceFeature
API and introduce the feature parameter to set the dimensions of facial parts.
// Extract facial features based on the introduced image.
ZegoFaceFeature feature = ZegoAvatarService.getInteractEngine().detectFaceFeature(bitmap);
// Set the appearance of the avatar based on facial features.
mCharacterHelper.applyFaceFeature(feature);
- During automatic avatar generation, you do not need to set the default gender or other JSON data in advance because the data will be generated automatically after the API is called.
- Before automatic avatar generation, you need to set
ExtendPackagesPath
in advance to prevent the related resources from failing to be found and the automatic avatar generation effect failing to be restored.
Set facial expressions
- Before you start the facial expression detection, ensure that the camera permission is enabled.
- If the ZegoCharacterHelper class is used, no APIs related to IZegoCharacter need to be called.
After the basic virtual avatar is created, call the startDetectExpression API, set the drive mode to Camera
, and use the front camera to detect facial expressions. Then, use the setExpression
API of ZegoCharacterHelper to set facial expressions and drive facial expression changes of the virtual avatar.
// Start facial expression detection. Before you start the facial expression detection, you need to apply for the camera permission in advance. It is assumed that the camera permission is enabled.
ZegoAvatarService.getInteractEngine().startDetectExpression(ZegoExpressionDetectMode.Camera, expression -> {
// Transfer the facial expressions to the avatar drive.
mCharacterHelper.setExpression(expression);
});
Styles and materials
If the ZegoCharacterHelper class is used, no APIs related to IZegoCharacter need to be called. Even though IZegoCharacter also has the setPackage API, do not call it directly. If you call the IZegoCharacter API skipping the ZegoCharacterHelper class, cache at the ZegoCharacterHelper layer will become untrusted.
Before changing the makeup or clothing for the virtual avatar, perform the following operations:
- If you set the Packages import method to dynamic downloading, call the
setExtendPackagesPath
API of ZegoCharacterHelper to set the Packages download directory to the downloadPath parameter before using the packages to facilitate resource indexing. The downloadPath parameters needs to be specified to the folder of Packages, for example,/data/data/im.zego.zegoavatarexample/files/assets/Packages
. - Call the setPackage API and introduce the packageID to adjust the appearance of the virtual avatar. The packageID parameter indicates the resource that needs to be set. For more information, see Styles and materials.
// Ensure that the external directory of Packages is set before the API is called.
// This directory can be the integrated directory for setting the makeup, clothing, hair, and other resources in the app. The resource content can be downloaded from the Internet based on your needs.
mCharacterHelper.setExtendPackagePath(downloadPath);
// Call the Styles and materials API.
String packageID = "facepaint1"; // Ensure that this directory is under the downloadPath directory.
mCharacterHelper.setPackge(packageID);
Obtain appearance data
After appearance data is set, you can call the getAvatarJson
API of the ZegoCharacterHelper class to obtain JSON data of the virtual avatar and store the data to the user profile on the server end for restoration.
String json = mCharacterHelper.getAvatarJson();
Restore appearance data
If you call the getAvatarJson
API of the ZegoCharacterHelper class to save the appearance data of the virtual avatar, you can call the setAvatarJson
API and introduce the data to restore the personalized virtual avatar.
mCharacterHelper.setAvatarJson(avatarJson);
Play animation
To play the animation, call the playAnimation API, and pass the corresponding Key parameter.
For more resources, you can go to SDK downloads for downloading.
mCharacterHelper.playAnimation(walk);
The following shows the supported animation keys:
Animation Key | Description |
---|---|
relax | Relax |
walk | Walking |
run | Running |
think | Thinking |
Enable/Disable animation
To enable animation, call the enableAnimation API and pass YES
. To disable it, pass NO
instead.
mCharacterHelper.enableAnimation(true);
Set view angles
To set view angles, call the setViewport API. The parameter description is as follows:
Parameter | Description |
---|---|
ZegoAvatarViewPortType_FullBody | Full-length portrait |
ZegoAvatarViewPortType_HalfBody | Half-length portrait |
ZegoAvatarViewPortType_Head | Head portrait |
// Set full-length portrait.
mCharacterHelper.setViewport(ZegoAvatarViewState.whole);
Set default expression
- First, call the
setDefaultExpression
method, and pass the default expression data file path (the path can be customized. The default expression data files can be obtained in the SDK download. - Call the
enableDefaultExpression
method to control whether to enable the default expression. **Please ensure that you have calledsetDefaultExpression
to pass in the correct default expression data, otherwise, the default expression will not be displayed properly. **
// Set the default expression. Get the absolute path to the default emoji data file (path can be customized)
mCharacterHelper.setDefaultExpression(getFilesDir().getAbsolutePath() + "/assets/ZADefaultExpressionData.txt");
// Enable the default expression.
mCharacterHelper.enableDefaultExpression(true);
Export Avatar texture
After creating a basic virtual avatar, you can directly call the startCaptureAvatar
method, and pass AvatarCaptureConfig (configures the width and height of the exported texture) to start exporting the Metal texture.
You can also refer to Using avatars when publishing streams to use avatars when publishing streams.
- To export the Avatar Texture, don’t use the
setAvatarView
method, that is, do not use AvatarView for rendering, otherwise it may be unable to obtain the Avatar texture to publish the stream. - When exporting the Avatar Texture, it is equivalent to doing offline rendering, the previous Avatar will not be rendered to the screen.
// Start exporting Avatar Texture.
// Set the [captureWidth] and [captureHeight] of the content returned by the Avatar as required.
AvatarCaptureConfig config = new AvatarCaptureConfig(captureWidth, captureHeight);
mCharacterHelper.startCaptureAvatar(config, new OnAvatarCaptureCallback() {
@Override
public void onAvatarTextureAvailable(int textureID, int width, int height) {
// The Texture ID, width, and height.
}
});
//Stop exporting Avatar Texture.
mCharacterHelper.stopCaptureAvatar();
- 1 Overview
- 1.1 1 Optional: Preload resources
- 1.2 3. Set the default avatar
- 1.3 4. Create a virtual avatar view
- 2 Adjust the appearance of the virtual avatar
- 2.1 Set the face shape
- 2.2 Set and obtain the hair color
- 2.3 Set and obtain the skin color
- 2.4 Automatic avatar generation
- 2.5 Set facial expressions
- 2.6 Styles and materials
- 2.7 Obtain appearance data
- 2.8 Restore appearance data
- 2.9 Play animation
- 2.10 Enable/Disable animation
- 2.11 Set view angles
- 2.12 Set default expression
- 2.13 Export Avatar texture