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.

1 Optional: Preload resources

To preload resources, do this before initializing the ZegoCharacterHelper:

1. First, upload the absolute path of the ​​resource packages. For details, see Import resource packages.

2. 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

1. After ZegoCharacterHelper is initialized, call the findViewById API to create an avatar view and configure the width, height, and other information of the view.
2. Call the setCharacterView API, introduce avatarView, and associate it with the view of the virtual avatar.

// 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

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:

1. After the image is prepared, call the detectFaceFeature API and introduce the image using the bitmap format to generate a virtual avatar.
2. 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);

Set facial expressions

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

Before changing the makeup or clothing for the virtual avatar, perform the following operations:

1. 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.
2. 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.

mCharacterHelper.playAnimation(walk);

The following shows the supported animation keys:

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:

// Set full-length portrait.
mCharacterHelper.setViewport(ZegoAvatarViewState.whole);

Set default expression

1. 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.
2. Call the enableDefaultExpression method to control whether to enable the default expression. **Please ensure that you have called setDefaultExpression 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.

// 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();