Avatar SDK UE Plugin C++ functions

All of the Plugin’s functionality is available in Blueprints and C++. Here is an overview of the most important C++ functions and classes.

AvatarSDKCloudConnection

Before any of the Plugin’s methods can be used, you should correctly initialize UAvatarSDKCloudConnection for your app. Since version 2.0.0 of Plugin, we use the UAvatarSDKCloudConnection class to handle connection with Avatar SDK Cloud.

void UAvatarSDKCloudConnection::AuthorizeAsync(TFunction<void(const FString&, int32 code)> callback);

AuthorizeAsync method is responsible for that initialization. ClientId and ClientSecret fields of UAvatarSDKCloudConnection instance should be initialized before calling AuthorizeAsync. This method is asynchronous: once the request is performed, the callback will be called. Callback arguments are access token and request result code.

Avatar SDK HTTP Library

Methods of UAvatarSDKHTTPLibrary are responsible for communication with Avatar SDK Cloud API and provide the core functionality of Avatar SDK UE Plugin. These methods perform HTTP requests and return received data as delegate arguments. The last delegate parameter is Code, which is equal to 0 if the request was successful (e.g. HTTP status is 200 OK) and equal to HTTP status code otherwise. If the request was not successful at all, or it was not possible to parse data, the Code is equal to -1. The "Code" field of the FAvatarData-type argument should contain the correct avatar code for methods that are responsible for requesting the information about a specific avatar (for example, GetAvatarData or GetModelInfo).

static void CreateAvatar(UAvatarSDKCloudConnection*, const FAvatarSDKParams& params, FAsyncAvatarDataDelegate OnComplete);

Create a new avatar calculation task. After POSTing a request, the avatar's photo for the calculation is being uploaded to the calculation backend. This method is asynchronous: once the request is performed, the OnComplete delegate will be called and FAvatarData will be passed as its argument.

static void GetAvatarData(UAvatarSDKCloudConnection*, const FAvatarData& avatarData, FAsyncAvatarDataDelegate OnComplete);

GetAvatarData allows getting the FAvatarData by avatar code ("Code" field of FAvatarData structure). Also used for tracking the avatar calculation progress. This method is asynchronous: once the request is performed, the OnComplete delegate will be called and FAvatarData will be passed as its argument. Fields Status and Progress contain information about current calculation task status. When Status changes to "Completed", files of the calculated avatar may be downloaded.

static void GetAvatarFile(UAvatarSDKCloudConnection*, const FAvatarData& avatarData, const FString& dstDirPath, EAvatarFile fileType, EAvatarLod lod, FAsyncFileResultDelegate OnComplete);

GetAvatarFile allows you to download avatar's files to the directory dstDirPath. Appropriate fileType argument should be passed for each type (mesh, texture, or blendshapes). For some of the requests LOD (level of details) parameter is applicable. "EAvatarLod::default_lod" value should be used in other cases. This method is asynchronous: once a file is downloaded, FAsyncFileResultDelegate will be called.

static void GetAvatarHaircutsInfo(UAvatarSDKCloudConnection*, const FAvatarData& avatarData, FAsyncAvatarDataDelegate OnComplete);    

This request may be performed for the sake of obtaining the available haircuts list. This method is asynchronous: once the request is performed, the OnComplete delegate will be called and FAvatarData will be passed as its argument. An array of available haircuts will be written to the AvatarsAvailableHaircuts field of FAvatarData.

static void DownloadFileByUrl(UAvatarSDKCloudConnection*, const FString& Url, const FString& PathToSave, FAsyncFileResultDelegate OnComplete);

DownloadFileByUrl method saves the URL to a file on your local drive. This method is asynchronous: once the file is downloaded, FAsyncFileResultDelegate will be called.

static void GetAvailableParameters(UAvatarSDKCloudConnection*, EPipelineType Type, FAvatarParametersDelegate OnComplete);

Retrieves all available parameters for specified pipeline and default pipeline subtype. Parameters are represented by the FAvatarGenerationParams structure. This method is asynchronous: once the request is performed, the OnComplete delegate will be called and the FAvatarGenerationParams instance will be passed as its argument.

static void GetModelInfo(UAvatarSDKCloudConnection*, const FAvatarData& avatarData, FAsyncModelInfoDelegate OnComplete);

Avatar SDK is capable of providing some meta-information about computed avatar from source photo like haircut, skin, eyes color, etc. This data is represented by the FModelInfo structure. GetModelInfo method allows you to acquire an avatar's Model info. This method is asynchronous: once the request is performed, the OnComplete delegate will be called and FModelInfo will be passed as its argument.

static void GetExportParameters(UAvatarSDKCloudConnection* connection, EPipelineType Type, FAsyncExportParametersDelegate OnComplete);

Query all available enumerable export parameters for the body_0.3 pipeline (Full body avatars). Please note that this request is useful during parameters discovery and should be omitted during regular application workflow once you figure out which parameters fit you best. This method is asynchronous: once the request is performed, the OnComplete delegate will be called and the FAvatarExportParams instance will be passed as its argument.

static void GetAvatarExport(UAvatarSDKCloudConnection* connection, const FAvatarData& avatarData, FAsyncAvatarExportDelegate OnComplete);

GetAvatarExport allows getting the FAvatarExport by avatar code ("Code" field of FAvatarData structure). Also used for tracking the avatar exports progress. This method is asynchronous: once the request is performed, the OnComplete delegate will be called and FAvatarExport will be passed as its argument. Field Status contains information about current exports' status. When Status changes to "Completed", avatar export files may be downloaded.

static void GetAvatarDataPage(UAvatarSDKCloudConnection* connection, const FString& link, FAsyncAvatarDataPageDelegate OnComplete);

GetAvatarDataPage is responsible for obtaining page with list of available avatar models for your account (see https://api.avatarsdk.com/#id1 and https://api.avatarsdk.com/#id41 for more information). To get the first page this method should be called with link parameter equal to https://api.avatarsdk.com/avatars/. When the request is ready, OnComplete delegate will be called. It contains FAvatarDataPage parameter, which includes an array with data and links to other pages: next, first and last.

Avatar SDK Storage

Methods of UAvatarSDKStorage provide a convenient way to work with files in Avatar SDK UE Plugin. Most of them have self-exploratory names and simply construct paths for avatar files. There are also helpers that solve common storage problems:

static void Unzip(const FString& archive, const FString& destination, bool createSubFolder, bool removeArchive);

As some of the avatar's files are downloaded as .zip archives, Unzip method may be useful. Some advanced behavior is implemented here: parameter createSubFolder controls whether directory should be created for archive's files and parameter removeArchive controls whether source archive should be deleted from the disk.

static FString OpenFileDialog();

Provides a convenient way to open file selection dialog and load a selfie from disk.

Avatar SDK Actor

AAvatarSDKActor class inherits Unreal's AActor and contains high level functions for managing an instance of Avatar. The most important of them are:

void InitializeHead(UObject* WorldContextObject, FRuntimeMeshImportResult MeshInfo, UTexture2D* BaseColor);

InitializeHead function is responsible for setting parameters of Avatar's head mesh: geometry and texture. Avatar's MorphTargets are also added here.

void AddHair(UObject* WorldContextObject, FRuntimeMeshImportResult MeshInfo, UTexture2D* BaseColor, FString HairName);

AddHair function adds new haircut data (name, texture and mesh) to the set of Avatar's haircuts.

void AddHairWithPointCloud(UObject* WorldContextObject, FRuntimeMeshImportResult MeshInfo, FRuntimeMeshImportResult PointCloud, UTexture2D* BaseColor, FString HairName);

AddHairWithPointCloud function adds new haircut data (name, texture, mesh and pointcloud) to the set of Avatar's haircuts. The same haircuts meshes are interchangeable between different avatars if the corresponding pointcloud is applied. E.g. you could store mesh from haircut1 of avatar1, then download only pointclouds for haircut1 of avatar2, avatar3, etc. and replace pointcloud in the previously-stored mesh. This way you could save customer's network traffic.

void SelectHair(FString HairName);

SelectHair method is used to display one of Avatar's haircuts (previously added by one of AddHair- methods).

bool HasHaircut(FString HairName);

HasHaircut method returns true if haircut with HairName was found among Avatar's haircuts, false otherwise.

void SetMorphTarget(FString MorphName, float MorphTarget);

Set the weight value for the morph target.

void ResetAvatarSDKActor();

Clear all Avatar's data (haircuts, meshes, morph targets).

Full Body Avatar Actor

AFullBodyAvatarActor class inherits Unreal's AActor and contains high level functions for managing an instance of Avatar. The most important of them are:

void LoadAvatar(const FString& RootPath, USkeleton* Skeleton, const FAvatarExport& ExportData, const FAvatarData& AvatarData);

Function loads avatar from files located at RootPath directory. Avatar's skeletal mesh will reuse the skeleton passed as a corresponding argument of this function. We provide a template skeleton located at "AvatarSDK\Content\Templates\FullBodyTemplate_Skeleton" that should be used by default. Avatar's data and export data are initialized in this function.

void AddHair(UObject* WorldContextObject, const FString& MeshPath, const FString& BaseColorPath, FString HairName);

AddHair function adds new haircut data (name, texture and mesh) to the set of Avatar's haircuts.

void SetSkeletonType(ESkeletonType InSkeletonType);

Set the target skeleton type, the generated model will be loaded with. FitPerson avatars can be loaded with Epic skeleton and default Avatar SDK skeleton. MetaBody avatars currenly can be loaded with Mixamo compatible skeleton only. Please note that skeleton asset selection is based on bones mapping which gets applied during model loading. It does not affect the downloaded model on disk (e.g. for downloaded model file skeleton remains the same).

void SelectHair(FString HairName);

SelectHair method is used to display one of Avatar's haircuts (previously added by one of AddHair- methods).

void SetMorphTarget(FString MorphName, float MorphTarget);

Set the weight value for the morph target.

void ResetFullBodyAvatarSDKActor();

Clear all Avatar's data (haircuts, meshes, outfits, morph targets).

void ApplyAnimationAsset(UAnimationAsset* Asset, bool Looping);

Play skeletal animation on the avatar.

void NextOutfit();

Select next outfit.

void PreviousOutfit();

Select previous outfit.

void ChangeOutfit(int32 Index);

Select outfit with number Index.

int NumOutfits();

Get total number of available outfits.

Async Request Nodes

Avatar SDK HTTP Library functionality is also implemented as a set of classes inherited from UBlueprintAsyncActionBase for convenient usage with Blueprints. Each class wraps a corresponding method. See Blueprints documentation