HTEffect 3D Avatar | Agora Docs

The HTEffect 3D Avatar extension enables you to quickly and seamlessly integrate 3D portrait special effects capabilities into your app. It encapsulates the Hongtu HTAvatar core API. You call API functions by setting the appropriate extension parameters.

Understand the tech

You use Video SDK methods to pass the appropriate key and value parameters to the extension. The key parameter corresponds exactly to the Hongtu API name, and the value parameter wraps some or all API parameters in JSON format.

Prerequisites

Android Studio 4.1 or later.
A physical Android device.
Implemented the SDK quickstart.

Project setup

Download the Android package.
Copy all .aar files to /app/libs.
Contact support@agora.io to obtain the resource package and save the required model and prop files to /app/src/main/assets.

Add the Gradle dependency:

implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])

Import the required Agora classes.

Integrate the extension

Enable the plug-in

private void enableExtension(boolean enabled) {
  agoraEngine.enableExtension("Texeljoy", "HTAvatar", enabled);
}

Initialize the plug-in

private void initExtension() {
  try {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("license", HTKey);
    setExtensionProperty("htARInitOffline", jsonObject.toString());
  } catch (JSONException e) {
    Log.e(TAG, e.toString());
  }
}

Set up a 3D effect

Call setExtensionProperty with keys such as htARRenderEnable and htARSetModel to enable effects and switch models.

Reference

Sample project

Run the sample project from AgoraHTAvatarExtensionDemo.

API reference

Interface description

When you call setExtensionProperty, the following keys and their corresponding functions are supported:

Initialization

Key	Description
htARInitOffline	Initialization, offline authentication.

Destroy

Key	Description
htARReleaseBufferRenderer	Resource release function.

Functional interface

Key	Description
htARRenderEnable	Turn on/off the AR special effects function.
htARSetModel	Switch AR model function.
htARMirror	Set whether the image has a mirror function.
htARImageFormat	Set image format function.
htARRotation	Set image rotation angle function.
htARMaxFaces	Set the maximum number of supported faces function.
htARCopyResource	Copy the resource path to the sandbox function.

Value description of method keys

htARInitOffline

value contains the following parameters:

Value parameter	Description
`license`	String type, AR offline authentication key.

htARReleaseBufferRenderer

value contains the following parameters:

Value parameter	Description
`enable`	BOOL type, whether to confirm the release of resources.

htARRenderEnable

value contains the following parameters:

Value parameter	Description
`enable`	BOOL type, whether to enable the AR function.

htARSetModel

value contains the following parameters:

Value parameter	Description
`name`	String type, the name of the model.

htARMirror

value contains the following parameters:

Value parameter	Description
`isMirror`	BOOL type, whether to set the mirror display of prop special effects. The default is `true`.

htARImageFormat

value contains the following parameters:

Value parameter	Description
`imageFormat`	Int type, enumeration value of image format. For details, see HTEARImageFormat.

htARRotation

value contains the following parameters:

Value parameter	Description
`rotation`	Int type, enumeration value of image rotation angle. For details, see HTEAROrientation.

htARMaxFaces

value contains the following parameters:

Value parameter	Description
`maxFaces`	Int type, the maximum number of supported faces. The value range is `[1, 5]`.

htARCopyResource

value contains the following parameters:

Value parameter	Description
`path`	String type, the path that needs to be copied to the sandbox.

Understand the tech

Prerequisites

Xcode 12.0 or later.
A physical iOS device.
Implemented the SDK quickstart.

Project setup

Download the iOS package.
Copy the .framework library files to your project folder.
Save HTKey.h and HTEffect.bundle to the project folder.
Ensure the dynamic libraries are set to Embed & Sign.

Integrate the extension

Enable the plug-in

[self.agoraKit enableExtensionWithVendor:@"Texeljoy"
                               extension:@"HTAvatar"
                                 enabled:self.enable];

Key	Description
htARInitOffline	Initialization, offline authentication.

Destroy

Key	Description
htARReleaseBufferRenderer	Resource release function.

Functional interface

Key	Description
htARRenderEnable	Turn on/off the AR special effects function.
htARSetModel	Switch AR model function.
htARMirror	Set whether the image has a mirror function.
htARImageFormat	Set image format function.
htARRotation	Set image rotation angle function.
htARMaxFaces	Set the maximum number of supported faces function.
htARCopyResource	Copy the resource path to the sandbox function.

Value description of method keys

htARInitOffline

value contains the following parameters:

Value parameter	Description
`license`	String type, AR offline authentication key.

htARReleaseBufferRenderer

value contains the following parameters:

Value parameter	Description
`enable`	BOOL type, whether to confirm the release of resources.

htARRenderEnable

value contains the following parameters:

Value parameter	Description
`enable`	BOOL type, whether to enable the AR function.

htARSetModel

value contains the following parameters:

Value parameter	Description
`name`	String type, the name of the model.

htARMirror

value contains the following parameters:

Value parameter	Description
`isMirror`	BOOL type, whether to set the mirror display of prop special effects. The default is `true`.

htARImageFormat

value contains the following parameters:

Value parameter	Description
`imageFormat`	Int type, enumeration value of image format. For details, see HTEARImageFormat.

htARRotation

value contains the following parameters:

Value parameter	Description
`rotation`	Int type, enumeration value of image rotation angle. For details, see HTEAROrientation.

htARMaxFaces

value contains the following parameters:

Value parameter	Description
`maxFaces`	Int type, the maximum number of supported faces. The value range is `[1, 5]`.

htARCopyResource

value contains the following parameters:

Value parameter	Description
`path`	String type, the path that needs to be copied to the sandbox.

Interface description

When calling setExtensionProperty on Android or setExtensionPropertyWithVendor on iOS, use the following keys to call the corresponding HTAvatar functions.

Initialization

Key	Description
`htARInitOffline`	Initializes offline authentication.

Destroy

Key	Description
`htARReleaseBufferRenderer`	Releases resources.

Functional interface

Key	Description
`htARRenderEnable`	Turns AR special effects on or off.
`htARSetModel`	Switches the AR model.
`htARMirror`	Sets whether the image uses mirroring.
`htARImageFormat`	Sets the image format.
`htARRotation`	Sets the image rotation angle.
`htARMaxFaces`	Sets the maximum number of supported faces.
`htARCopyResource`	Copies the resource path to the sandbox.

Value description of method keys

htARInitOffline

value contains the following parameter:

Value parameter	Description
`license`	String. The AR offline authentication key.

htARReleaseBufferRenderer

value contains the following parameter:

Value parameter	Description
`enable`	Boolean. Whether to confirm resource release.

htARRenderEnable

value contains the following parameter:

Value parameter	Description
`enable`	Boolean. Whether to enable AR.

htARSetModel

value contains the following parameter:

Value parameter	Description
`name`	String. The model name.

htARMirror

value contains the following parameter:

Value parameter	Description
`isMirror`	Boolean. Whether to mirror prop effects. The default value is `true`.

htARImageFormat

value contains the following parameter:

Value parameter	Description
`imageFormat`	Integer. The image format enumeration value. For specific values, see HTEARImageFormat.

htARRotation

value contains the following parameter:

Value parameter	Description
`rotation`	Integer. The image rotation angle enumeration value. For specific values, see HTEAROrientation.

htARMaxFaces

value contains the following parameter:

Value parameter	Description
`maxFaces`	Integer. The maximum number of supported faces. The value range is `[1, 5]`.

htARCopyResource

value contains the following parameter:

Value parameter	Description
`path`	String. The path to copy to the sandbox.

Contact Us

Contact Us