# Module: VisageAnalyserUnityPlugin

## VisageAnalyserUnityPlugin

The VisageAnalyserUnityPlugin is a native plugin (see Native Plugins) written in JavaScript for Unity. The plugin exposes face analysis features of visage|SDK for use in Unity WebGL build.
The plugin code is placed in VisageAnalyserUnityPlugin.jslib file and can be found in /lib folder.

### Dependencies

The plugin depends on visageSDK.js file that loads visageSDK.data and visageAnalysisData.js that loads visageAnalysisData.data. Therefore, visageSDK.js has to be loaded along with visageAnalysisData.js script by calling _preloadExternalJS function with the scripts' path relative to the main .html file.
For example, if visageAnalysisData.js is placed in the same folder as the main .html file:

    	VisageTrackerNative._preloadExternalJS("visageSDK.js.js");
    	VisageTrackerNative._preloadExternalJS("visageAnalysisData.js");

visageAnalysisData.data file, can be placed at any location on the server relative to the WEBGL build outputed main index.html file, by setting the data path using _setDataPath function.
Note that calling the _setDataPath function will change the search path of all .data files.

### Usage

For the functions to be accessible from C#, a C# wrapper interface is used. The example can be seen in the following function:

    	[DllImport("__Internal")]
    	public static extern void _initAnalyser(string initCallback);

The usage is demonstrated in VisageTrackerUnityDemo sample, VisageTrackerNative.HTML5.cs file. All C# scripts are located in Assets/Scripts folder of the project.
The frame that will be forwarded to the functions for estimating age, gender and emotions has to be processed before using VisageTracker.

### Callbacks

Generally, it is common to use callback functions in JavaScript, due to its asynchronous nature.
Within the plugin, some functions are implemented so they expect a callback function name as a parameter. Callback functions are defined in C# code. Examples can be seen in _initAnalyser function.

### Methods

#### <static> _initAnalyser(callback)

  Initializes VisageAnalyser.
  In order to use VisageAnalyser functions visageAnalysisData.data must be preloaded with visageAnalysisData.js script by calling _preloadExternalJS function at the very beginning of the code execution. The recommendation is to call this function in Awake() function in Unity. Parameter callback is name of function defined in Unity script. An example of a callback function definition and _initAnalyser function call:

      	//callback function
      	void initAnalyserCallback()
      	{
      		Debug.Log("AnalyserInited");
      		AnalyserInitialized = true;
      	}
      	//call of the _initAnalyser() function:
      	VisageTrackerNative._initAnalyser("initAnalyserCallback");

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `callback` | string | the name of the callback function.

#### <static> _analyseImage(faceIndex, options, resultsArray) → {VFAReturnCode}

  Performs the specified face analysis tasks on a given image.
  This function is primarily intended for performing face analysis on a single image, or consecutive unrelated images. As such, it outputs raw, unfiltered estimation data without smoothing or averaging.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `faceIndex` | number | value between 0 and MAX_FACES-1, used to access the data of a particular tracked face.
  `options` | number | Bitwise combination of VFAFlags which determines the analysis operations to be performed.
  `resultsArray` | Array | 12-dimension float array where the results of the performed face analysis will be stored. Array elements correspond with AnalysisData class elements.

  ##### Returns:

  Return code indicating status of performed face analysis.
  Type
    VFAReturnCode

#### <static> _analyseStream(faceIndex, options, resultsArray) → {VFAReturnCode}

  Performs the specified face analysis tasks on a given frame.
  This function is primarily intended for performing face analysis on a continuous stream of related frames, such as a video or camera feed. Sampling face analysis data from multiple frames can increase estimation accuracy by averaging the result over multiple frames. Internally, the suitability of frames chosen for analysis is continually evaluted based on head pose and overall tracking quality. This guarantees that the analysis buffer is always working with the best available frames, ensuring highest possible estimation accuracy.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `faceIndex` | number | value between 0 and MAX_FACES-1, used to access the data of a particular tracked face.
  `options` | number | Bitwise combination of VFAFlags which determines the analysis operations to be performed.
  `resultsArray` | Array | 12-dimension float array where the results of the performed face analysis will be stored. Array elements correspond with AnalysisData class elements.

  ##### Returns:

  Return code indicating status of performed face analysis.
  Type
    VFAReturnCode

#### <static> _resetStreamAnalysis(faceIndex)

  Resets face analysis.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `faceIndex` | number | value between 0 and MAX_FACES-1, used to access the data of a particular tracked face.