# Migration from older versions

Visage Technologies strives to minimize changes in API and configuration files when releasing new versions of the SDK. The inevitable changes are listed here together with specific instructions for developers who have existing applications built with older versions.

## Changes in this release

This section covers all changes introduced in all releases since 9.0.

### Landmark detection changes:

Additional eyebrows landmarks

- 8 additional eyebrows landmarks contained in the group 14 (14.5-14.12) are added as part of the extended eyebrows landmarks improvements.

Additional eyes landmarks

- 28 additional eyes landmarks contained in the group 16 (16.1-16.28) are added as part of the extended eyes landmarks improvements.

Additional lips landmarks

- 16 additional lips landmarks contained in the group 17 (17.5-17.20) are added as part of the extended lips landmarks improvements.

For more details please see FDP documentation.

### Changes in configuration file:

- enable_smoothing configuration parameter added. Controls whether the tracker output is smoothed with the smoothing_factors parameter or not.
  - Value 0 - Tracker outputs are not smoothed.
  - Value 1 - Tracker outputs are smoothed.
- temporally_denoise_input configuration parameter added. Controls whether the input frames are denoised in the time domain. This parameter is used to minimize noise (such as small variations in the light or electrical noise coming from the camera) in the input images to increase feature point stability and precision.
  - Value 0 - The input frame stream is not denoised.
  - Value 1 - The input frame stream is denoised.
- Major changes in fitting related parameters:
  - pose_fitting_model configuration parameter replaced with pose_fitting_model_configuration
  - pose_fitting_fdp configuration parameter removed
  - au_fitting_model configuration parameter replaced with au_fitting_model_configuration
  - au_fitting_fdp configuration parameter removed
  - mesh_fitting_model configuration parameter replaced with mesh_fitting_model_configuration
  - mesh_fitting_fdp configuration parameter removed
  - pose_fitting_au_use configuration parameter removed
  - pose_fitting_su_use configuration parameter removed
  - pose_fitting_pose_sensitivity configuration parameter removed
  - pose_fitting_au_sensitivity configuration parameter removed
  - pose_fitting_su_sensitivity configuration parameter removed
  - au_fitting_au_use configuration parameter removed
  - au_fitting_su_use configuration parameter removed
  - au_fitting_au_sensitivity configuration parameter removed
  - au_fitting_su_sensitivity configuration parameter removed
  - mesh_fitting_au_use configuration parameter removed
  - mesh_fitting_su_use configuration parameter removed
  - mesh_fitting_au_sensitivity configuration parameter removed
  - mesh_fitting_su_sensitivity configuration parameter removed
  - au_names configuration parameter removed
  - rotation_limit configuration parameter removed
  - translation_limit configuration parameter removed
  - action_unit_limit configuration parameter removed

For detailed description of these changes consult VisageTracker Configuration Manual, section 2.1. for additional information.

### API changes:

C++ API

VisageConfiguration API

Introducing new functions for getting and setting `enable_smoothing` parameter:

-     unsigned int getEnableSmoothing() const;

-     bool setEnableSmoothing(unsigned int enable_smoothing);

Introducing new functions for getting and setting `temporally_denoise_input` parameter:

-     unsigned int getTemporallyDenoiseInput() const;

-     bool setTemporallyDenoiseInput(unsigned int temporally_denoise_input);

Introducing major changes in fitting related parameters API.
The following API methods have been replaced:

-     get/setPoseFittingModel

  replaced with

      get/setPoseFittingModelConfiguration

-     get/setAuFittingModel

  replaced with

      get/setAuFittingModelConfiguration

-     get/setMeshFittingModel

  replaced with

      get/setMeshFittingModelConfiguration

The following API methods have been removed:

-     get/setPoseFittingFdp

-     get/setAuFittingFdp

-     get/setMeshFittingFdp

-     get/setPoseFittingAuUse

-     get/setPoseFittingSuUse

-     get/setPoseFittingPoseSensitivity

-     get/setPoseFittingAuSensitivity

-     get/setPoseFittingSuSensitivity

-     get/setAuFittingAuUse

-     get/setAuFittingSuUse

-     get/setAuFittingAuSensitivity

-     get/setAuFittingSuSensitivity

-     get/setMeshFittingAuUse

-     get/setMeshFittingSuUse

-     get/setMeshFittingAuSensitivity

-     get/setMeshFittingSuSensitivity

-     get/setAuNames

-     get/setRotationLimit

-     get/setTranslationLimit

-     get/setActionUunitLimit

Introducing new functions for getting and setting pose_fitting_model_configuration, au_fitting_model_configuration, mesh_fitting_model_configuration parameters respectively:

-     const std::string& getPoseFittingModelConfiguration() const;

-     bool setPoseFittingModelConfiguration(std::string pose_fitting_model_configuration);

-     const std::string& getAuFittingModelConfiguration() const;

-     bool setAuFittingModelConfiguration(std::string au_fitting_model_configuration);

-     const std::string& getMeshFittingModelConfiguration() const;

-     bool settMeshFittingModelConfiguration(std::string mesh_fitting_model_configuration);

FDP class:

- FDP group 14 (additional eyebrows landmarks) has been updated as part of extended eyebrows landmark tracking feature.

- FDP group 16 (additional eyes landmarks) has been added as part of extended eyes landmark tracking feature.

- FDP group 17 (additional lips landmarks) has been added as part of extended lips landmark tracking feature.

Additional information pertaining eyes and lips tracking are documented under paragraph Landmark detection changes.

Please note: FDP files saved with visage|SDK 9.1 will not be backwards compatible with previous versions due to the addition of new FDP points.
Using FDP::readFromFile() to load an 9.1 FDP file in an earlier version of the SDK will lead to undefined behaviour.

### Data files changes:

Modified

- Tracking algorithm data (vft/fa) - d1qy.vino.bin, d1qy.vino.xml, d2.vino.bin, d2.vino.xml and aux_file.bin.
- Face model data (vft/fm) - jk_300.fdp, which maps new lips landmarks to appropriate vertices of the face model.

Projects using older versions of these files should be updated to contain the newest data files from the data folder.

### Sample changes:

Samples displaying feature points are updated to draw additional lip points.

## Changes in older releases

## visage|SDK 9.0

### General:

Multi-frame analysis feature

VisageFaceAnalyser now offers multi-frame analysis functionality which performs estimations on the selected high-quality frames and returns an averaged, smoothed value. This functionality is available via the VisageFaceAnalyser::analyseStream() function.

New tracking algorithm models

Introducing smaller and faster tracking algorithm models while retaining the same accuracy which completely replace the old models that will no longer be distributed.

New age and gender estimation models

Introducing smaller, faster and more accurate age and gender estimation models which completely replace the old models that will no longer be distributed.

### API changes:

C++ API:

VisageSDK namespace

Introducing new FaceData class member for getting the face bounding box:

-     FaceData::faceBoundingBox

VisageFaceAnalyser API

VisageFaceAnalyser API was refactored to optimise usage and to include newly introduced multi-frame analysis feature.
Old face analysis functions were removed:

-     VisageFaceAnalyser::estimateAge()

-     VisageFaceAnalyser::estimateGender()

-     VisageFaceAnalyser::estimateEmotion()

and replaced with new ones:

-     VFAReturnCode VisageFaceAnalyser::analyseImage(const VsImage* image, const FaceData& faceData, const int options, AnalysisData& results)

-     VFAReturnCode VisageFaceAnalyser::analyseStream(const VsImage* frame, const FaceData& faceData, const int options, AnalysisData& results, const int faceIndex = 0)

-     void VisageFaceAnalyser::resetStreamAnalysis(const int faceIndex = -1)

Three separate calls to old analysis estimation functions can now be performed by a single call to analyseImage() or analyseStream() where parameter options specifies which analysis operations to perform.
For more details on the updated API please see VisageFaceAnalyser API documentation.

Introducing new AnalysisData structure which contains face analysis results (age, gender and emotions) returned by the VisageFaceAnalyser::analyseImage() and VisageFaceAnalyser::analyseStream() functions.

VisageFeaturesDetector API

Prototype of VisageFeaturesDetector constructor and the following method has been changed:

-     VisageFeaturesDetector()

  to:

      VisageFeaturesDetector(const char* detectorConfigFile)

-     bool VisageFeaturesDetector::Initialize(const char* path)

  to:

      bool VisageFeaturesDetector::Initialize()

For more details please see VisageFeaturesDetector API documentation.

VisageConfiguration API

Introducing new functions for getting and setting specific data paths required by tracking algorithm:

-     const string& getVftDataPath(void) const

-     const string& getVfdDataPath(void) const

-     const string& getPrDataPath(void) const

-     const string& getErDataPath(void) const

-     bool setVftDataPath(string vft_data_path)

-     bool setVfdDataPath(string vfd_data_path)

-     bool setPrDataPath(string pr_data_path)

-     bool setErDataPath(string er_data_path)

Removed functions for getting and setting the obsolete data path no longer required by tracking algorithm:

-     const string& getBdtsDataPath() const

-     bool setBdtsDataPath(string bdts_data_path)

VisageGazeTracker API

Prototype of following method has been changed:

-     virtual int track(int, int, const char*, FaceData*, int, int, int, long)

to:

    virtual int* track(int, int, const char*, FaceData*, int, int, int, long, int maxFaces = 1)

### Data folder changes:

Data folder structure has been rearranged:

Data files | Old location | New location
--- | --- | ---
Face analysis data files | bdtsdata/LBF/vfadata | vfa
Face recognition data files | bdtsdata/NN/fr.* | vfr
Tracking algorithm data files | bdtsdata/FF/vnn | vft/ff
bdtsdata/NN/vnn | vft/fa
Tracking features data files | bdtsdata/NN/pr.* | vft/pr
bdtsdata/NN/*.lbf | vft/er
3D models data files | root | vft/fm

### Data files changes:

Removed

- Old tracking algorithm data (vft/fa) - landmarks.bin and init_shape.bin

- Old gender estimation data (vfa/gd) - gd.lbf

- Old data path parameter - bdts_data_path parameter

Added

- New tracking algorithm data (vft/fa) - aux_file.bin

- New gender estimation data (vfa/gd) - gd.vino.bin and gd.vino.xml

- New data path parameters:

- vft_data_path - path to the folder tracking algorithm data files required by tracker

- vfd_data_path - path to the folder containing algorithm data file required by tracker and detector

- pr_data_path - path to the folder containing containing pupils' refinement data files

- er_data_path - path to the folder containing ears' refinement data files

Configuration files using the removed bdts_data_path parameter should be updated to use new data paths instead.

Modified

- Age estimation data (vfa/ad) - ae.vino.bin and ae.vino.xml

- Tracking algorithm data (vft/fa) - d1qy.vino.bin, d1qy.vino.xml, d2.vino.bin and d2.vino.xml

Projects using older versions of these files should be updated to contain the newest data files from the data folder.

## visage|SDK 8.8

### General:

Face tracking and detection algorithms

The default legacy algorithm that could be allowed via the use_vnn configuration parameter (value 0) has been removed. The VNN algorithm is now the default and only tracking and detection algorithm.
The algorithm can be configured to improve feature points precision and robustness, over tracking speed (performance) by setting the refine_landmarks parameter to 1 in the configuration file. Otherwise, when performance is preferred over feature points precision, the recommendation is to disable refine_landmarks parameter by setting it to 0 in the configuration file.

Face tracking and detection with protection masks

Face tracking and detection algorithms are enhanced so that they can track and detect faces wearing protective masks of various colors and patterns.

### Landmark detection changes:

Contour landmarks

- Visible contour landmarks from group 13 (13.1-13.17) are no longer available (not detected or estimated). Instead, contour landmarks are now provided only in the form of a physical contour within group 15 (15.1-15.17). For more details please see FDP documentation.

Changing the detection of contour points from visible to physical results in improved stability and accuracy of the 3D head-pose estimation.

### API changes:

VisageSDK namespace

Introducing new function for getting SDK version:

-     const char* getVisageSDKVersion(void)

Prototype is declared in the following headers; VisageTracker.h, VisageFeaturesDetector.h, VisageFaceRecognition.h, VisageFaceAnalyser.h and VisageGazeTracker.h.
Introducing new FaceData class member for getting the rotation of the face from the camera viewpoint:

-     FaceData::faceRotationApparent

Liveness API

Parameter *frame is now mandatory for the following method:

-     VisageLivenessBlink::update(const FaceData *faceData, VsImage *frame)

### Changes in configuration file:

Removed

- Parameters:

- use_vnn
- lbf_stage_modifier
- lbf_nperturb
- lbf_nperturb_threads

- Files:

- Facial Features Tracker - Ultra.cfg
- Facial Features Tracker - Low.cfg

Added

- refine_landmarks parameter

- value 0 - landmarks refinement is disabled
- value 1 - landmarks refinement is enabled

Renamed

- Facial Features Tracker - High.cfg to Facial Features Tracker.cfg

Modified

- Facial Features Tracker.cfg configuration file - new refine_landmarks parameter set to 1 (enabled)
- Head Tracker.cfg configuration file - new refine_landmarks parameter set to 0 (disabled)

Please refer to the VisageTracker Configuration Manual, section 2.1. for additional information.

If you want to update your existing configuration files, it is recommended to copy the parameters values from Facial Features Tracker.cfg configuration file supplied in this package.

### Data files changes:

Removed

- Legacy tracking and detection algorithm data files

- bdtsdata/NN/

- fa.lbf, fc.lbf, is.bin, model.vino.bin, model.vino.xml

- bdtsdata/FF/

- ff.dat

- bdtsdata/LBF/

- lv

- Default tracking and detection algorithm data files

- bdtsdata/NN/vnn

- std_dev_image.bin, mean_image.bin

Modified

- Tracking and detection algorithm data - bdtsdata/NN/vnn

Projects using older versions of these files should be updated to contain the newest data files from the bdtsdata folder along with libraries from lib folder.

### Dependencies changes:

OpenVINO™ toolikit is updated and therefore new dependencies of libVisageVision.a should now be included in projects along with other visage|SDK libaries.

- libOVPlugin.so,
- libinference_engine.so,
- libinference_engine_ir_reader.so,
- libinference_engine_lp_transformations.so,
- libinference_engine_transformations.so,
- libMKLDNNPlugin.so,
- libngraph.so,
- libtbb.so,
- libtbb.so.2,
- libtbbmalloc.so,
- libtbbmalloc.so.2

Additionally OpenVINO™ toolkit requires the plugins.xml file provided in Samples/data.

### Sample changes:

Samples displaying feature points are updated to draw physical contour points.

## visage|SDK 8.7

### General:

Neural network runner replacement

The in-house developed runner is no longer available and is being replaced by OpenVINO™ toolkit*, which is now the only and default neural network runner. OpenVINO™ toolkit significantly improves the performance of visage|SDK algorithms.

It is implemented in the following libraries:

- libOVPlugin.so,
- libinference_engine.so,
- libMKLDNNPlugin.so,
- libmkl_tiny_tbb.so,
- libtbb.so
- libtbb.so.2

These libraries are dependencies of libVisageVision.a and should now be included in projects along with other visage|SDK libraries. Additionally, OpenVINO™ toolkit requires its own set of data files with extensions .vino.bin and .vino.xml provided in Samples/data/bdtsdata.

New face recognition model

Introducing smaller, faster and more accurate face recognition model which completely replaces the old model that will no longer be distributed.

New face detection model

Introducing a more accurate and robust face detection model. The new model is used in face tracking and face detection when use_vnn configuration parameter is set to 1. Otherwise, the previous face detection model will be used.
For more information about using VNN detection algorithm, please consult VisageTracker Configuration Manual and VisageFeaturesDetector documentation.

VNN tracking algorithm fast mode

VNN algorithm can now be configured for better performance, at the cost of feature points precision. This mode is enabled by setting use_vnn parameter in configuration file to 1. This mode is typically used when performance is preferred over feature points precision, e.g. when interested in fast head pose (head rotation and translation) estimation.

*OpenVINO is a trademark of Intel Corporation or its subsidiaries.

### API changes:

VisageFaceRecognition:

- In addition to RGB and grayscale, method extractDescriptor() accepts RGBA input image.
- In addition to RGB, method addDescriptor() accepts RGBA and grayscale input image.

### Changes in configuration file:

- use_vnn configuration parameter added to VisageFeaturesDetector configuration file FaceDetector.cfg, set to value 1.

- use_vnn configuration parameter values changed and additional value added:

  - value 0 - VNN algorithm is disabled, default tracking algorithm and default detection model is used
  - value 1 - VNN algorithm enabled in fast mode, at the cost of feature points precision.
  - value 2 - VNN algorithm enabled

For detailed description of these changes consult VisageTracker Configuration Manual.

If you want to update your existing configuration files, it is recommended to copy the parameters values from Facial Features Tracker - High.cfg configuration file supplied in this package.

### Data files changes:

Removed

- Old face recognition data (bdtsdata/NN/) - fr.bin
- Deprecated runner data (bdtsdata/NN/) - pr.bin and model.bin
- Deprecated runner data (bdtsdata/LBF/vfadata/ad/) - ae.bin

Added

- New face detection data (bdtsdata/FF/vnn/) - ff.vino.bin and ff.vino.xml
- New face recognition data (bdtsdata/FF/vnn/) - fr.vino.bin and fr.vino.xml

Modified

- VNN algorithm data - bdtsdata/NN/vnn

Projects using older versions of these files should be updated to contain the newest data files from the bdtsdata folder.

## visage|SDK 8.6

### Build environment changes:

visage|SDK for Ubuntu is now built and tested on Ubuntu 18.04.

### General:

Configurable neural network runners

To improve the performance of our algorithms and to support a wider variety of neural network models we are introducing an API and a configurable framework for choosing between different neural network runners.

As a result, additional configuration file NeuralNet.cfg is now included in visage|SDK (located in Samples/data). This file allows the users to configure which runner will be used by visage|SDK. Users can choose between:

- Visage's in-house developed runner and
- OpenVINO™ toolkit (currently NOT SUPPORTED on Linux).

For more information on the parameters of NeuralNet.cfg file see the API page.

Configurable detection algorithm

New experimental algorithm for face and facial features detection introduced (VNN algorithm). While it significantly improves detection quality, it also reduces detection speed (performance).
Detector is currently configurable so VNN algorithm can be enabled or disabled via parameter use_vnn in configuration file.
It is recommended to use VNN algorithm only with OpenVINO™ toolkit which significantly improves speed of running neural networks.
For more information about using VNN detection algorithm, please consult VisageFeaturesDetector documentation.

Configurable tracking algorithm

New experimental algorithm for face tracking introduced (VNN algorithm). While it significantly improves tracking quality and robustness, it also reduces tracking speed (performance).
Tracker is currently configurable so VNN algorithm can be enabled or disabled via parameter use_vnn in configuration file.
It is recommended to use VNN algorithm only with OpenVINO™ toolkit which significantly improves speed of running neural networks.
For more information about using VNN tracking algorithm, please consult VisageTracker Configuration Manual and VisageTracker documentation.

### API changes:

VisageConfiguration API

Introducing new API for programatically changing VisageTracker configuration parameters, including classes and templates:

-     VisageConfiguration

  Class used to change, apply, load and save configuration parameters.

-     VsCfgArr

  Templated structure that can store an array of values of varying types.

used in conjunction with new VisageTracker methods:

-     VisageConfiguration VisageTracker::getTrackerConfiguration() and

-     void VisageTracker::setTrackerConfiguration(VisageConfiguration &configuration)

For more details and usage code examples please refer to Detailed Description section of VisageConfiguration and VsCfgArr.

FDP class:

- FDP group 10 (ears) has been extended from 10 to 24 points (12 points per ear) as part of ear tracking feature. Additional changes pertaining ear tracking are documented under paragraphs Model changes, Changes in configuration file and Data files changes.

  Please note: FDP files saved with visage|SDK 8.6 will not be backwards compatible with previous versions due to the addition of new FDP points.
  Using FDP::readFromFile() to load an 8.6 FDP file in an earlier version of the SDK will lead to undefined behaviour.

Deprecated API:

-     VisageTracker::stop()

Licensing:

- Prototype of method:

          void initializeLicenseManager(const char *licenseKeyFileName)

  changed to

          int initializeLicenseManager(const char *licenseKeyFileName)

- Additionally, prototype is now declared in the following headers: VisageTracker.h, VisageFeaturesDetector.h, VisageFaceRecognition.h, VisageFaceAnalyser.h so it is no longer necessary to declare it explicitly in the code where one of the aforementioned headears is included before the initializeLicenseManager() call.

Configuration changes
For improved performance of our algorithms, OpenVINO™ toolkit for running neural networks is added. Configuration file NeuralNet.cfg is now included in visage|SDK (located in Samples/data) which allows users to choose between OpenVINO™ toolkit and Visage's in-house runner. More information can be found here.

### Model changes:

A new model file has been added for ear tracking functionality - jk_300_wEars. The new model is based on the previous 'jk_300' model and contains an additional 334 polygons and 14 new FDP points in group 10 (10.11 - 10.24).

For detailed description of these changes consult VisageTracker Configuration Manual.

### Changes in configuration file:

- refine_ears parameter added, which is off by default. Toggles the tracking and refinement of ear points (group 10) for Visage Tracker.

- Facial Features Tracker - High - With Ears.cfg configuration file introduced specifically for purposes of ear tracking. It is largely identical to the regular high configuration with the exception that it uses 'jk_300_wEars' as the active model, and has the 'refine_ears' parameter set to 1 (on).

- Facial Features Tracker - Ultra.cfg configuration file introduced specifically for demonstrating VNN algorithm. It is largely identical to the regular high configuration with the exception that it enables 'use_vnn' option setting the parameter to 1 (on).

For detailed description of these changes consult VisageTracker Configuration Manual.

If you want to update your existing configuration files, it is recommended to copy the parameters values from Facial Features Tracker - High.cfg configuration file supplied in this package.

### Data files changes:

- New cascade files ('efa.lbf ' and 'efc.lbf ') have been added to Samples/data/bdtsdata/NN folder.
- New model files ('jk_300_wEars.fdp' and 'jk_300_wEars.wfm') and configuration file ('Facial Features Tracker - High - With Ears.cfg ') have been added to Samples/data folder.
- New data files required by VNN algorithm have been added to Samples/data/bdtsdata/NN/vnn folder. Files need to be present in the project if VNN algorithm is used. For more information, please see VisageTracker documentation.

Projects using older versions of these files should be updated to contain the newest data files from the bdtsdata folder.

### Samples changes:

OpenCV library which is used in sample applications is no longer distributed within visage|SDK package. Instructions for prerequisites to building sample projects have changed and can be seen here for VisageTrackerDemo and here for VisageDetectorDemo.

## visage|SDK 8.5

### Changes in configuration file:

- smoothing_factors - due to the implementation of new smoothing algorithms in VisageTracker, default values and optimal ranges for this parameter have been changed in all configuration

Please refer to the VisageTracker Configuration Manual, section 2.1. for additional information.

If you want to update your existing configuration files, it is recommended to copy the parameters values from Facial Features Tracker - High.cfg configuration file supplied in this package.

### Data files changes:

visage|SDK data files located in Samples/data/bdtsdata folder have been updated. Copy all files located in the bdtsdata folder to appropriate folders in any existing applications.

## visage|SDK 8.4

### API changes:

VisageFaceAnalyser:
Method estimateAge() now accepts only RGB input image; estimateEmotion() and estimateGender() expect RGB, RGBA or grayscale input image.

### Licensing changes:

visage|SDK can no longer be used without license - FaceTrack, FaceAnalysis and FaceRecognition will not return results without valid license. More information on how to obtain license key and include it in the application can be found in Licensing section of the documentation.
In order to try visage|SDK on Linux, prebuilt applications are provided in bin folder.

### Data files changes:

visage|SDK data files located in Samples/data/bdtsdata folder have been updated. Copy all files located in the bdtsdata folder to appropriate folders in any existing applications.

## visage|SDK 8.3.5959

### Landmark detection changes:

- Eyebrows (group 4) detection locations have been changed to the upper contour of the eyebrow to conform more closely to MPEG-4 standard
- Nose (group 9) facial landmarks 9.1 and 9.2 are no longer detected. Instead, facial landmarks 9.5 and 9.4 are detected and 9.1 and 9.2 are estimated from the fitted 3D model.
- Nose contour has been added (group 14, points 21 - 25)

For detailed illustration see MPEG-4 FBA.

### API changes:

    VisageFeaturesDetector:

- VisageFeaturesDetector initialization has been modified to conform to the documentation. To be more specific, to initialize the detector absolute or relative path to the data folder containing "bdtsdata" subfolder must be passed, e.g. if the working directory is Samples/data instead of:

      bool detectorInit = visageFeaturesDetector->Initialize("bdtsdata");

  to:

      bool detectorInit = visageFeaturesDetector->Initialize(".");

  For more details see VisageFeaturesDetector API documentation.

    VisageFaceRecognition:

- VisageFaceRecognition constructor takes a path to the data file itself instead of a path to the data file folder, e.g. :

      VisageFaceRecognition *m_VFR = new VisageFaceRecognition("bdtsdata/NN");

  to:

      VisageFaceRecognition *m_VFR = new VisageFaceRecognition("bdtsdata/NN/fr.bin");

### Changes in configuration file:

Configuration file format had stayed the same.

jk_300 model has been set as a default model for pose and action unit estimation instead of candide3 model.

If you want to update your existing configuration files, it is recommended to copy the parameters values from Facial Features Tracker - High.cfg configuration file supplied in this package.

### Data files changes:

visage|SDK data files located in Samples/data/bdtsdata folder have been updated. Copy all files located in the bdtsdata folder to appropriate folders in any existing applications.

## visage|SDK 8.2.5477 for Raspberry PI

### New platform supported

     We now support Raspberry PI platform. Actually tested with NOOBS v2.4.0., which is Raspbian GNU/Linux 8 (jessie).

## visage|SDK 8.2.5684

### API changes:

    VisageTracker:

Due to the introduction of multitracking prototype of following methods has been changed:

-     virtual int VisageTracker::track(int frameWidth,
                         int frameHeight,
                         const char* p_imageData,
                         FaceData* facedata,
                         int format = VISAGE_FRAMEGRABBER_FMT_RGB,
                         int origin = VISAGE_FRAMEGRABBER_ORIGIN_TL,
                         int widthStep = 0,
                         long timeStamp = -1);

  to:

      virtual int* VisageTracker::track(int frameWidth,
                         int frameHeight,
                         const char* p_imageData,
                         FaceData* facedata,
                         int format = VISAGE_FRAMEGRABBER_FMT_RGB,
                         int origin = VISAGE_FRAMEGRABBER_ORIGIN_TL,
                         int widthStep = 0,
                         long timeStamp = -1,
                         int maxFaces = 1);

    VisageFaceRecognition:

- New function added to VisageFaceRecognition class for determining descriptor size:

      int VisageFaceRecognition::getDescriptorSize();

- Descriptor data type was changed from float to short. Following function are affected:

      int VisageFaceRecognition::extractDescriptor(FaceData *facedata, VsImage *image, short *descriptor);
      int VisageFaceRecognition::descriptorsSimilarity(short *first_descriptor, short *second_descriptor);
      int VisageFaceRecognition::addDescriptor(short *descriptor, const char *name);

    VisageFeaturesDetector:

Following methods has been changed:

-     int VisageFeaturesDetector::detectFacialFeatures(VsImage* frame,
                                                       FaceData* output,
                                                       int maxFaces = 1,
                                                       float minFaceScale = 0.1f,
                                                       float maxFaceScale = 1.0f);

  to:

      int VisageFeaturesDetector::detectFacialFeatures(VsImage* frame,
                                                       FaceData* output,
                                                       int maxFaces = 1,
                                                       float minFaceScale = 0.1f,
                                                       float maxFaceScale = 1.0f,
                                                       bool outputOnly2DFeatures = false);

### Changes in configuration file format:

- face_detector_sensitivity parameter added. Controls face detector sensitivity (TPR - true positive rate) for VisageFeaturesDetector and for initialization phase of the Visage Tracker.

- lbf_nperturb_threads parameter added. Controls the number of threads that will be used for perturbation parallelization (default value is 1).

- Pose fitting model sensitivity for z translation(pose_fitting_pose_sensitivity) increased from 0.001 to 0.1

For detailed description of these changes consult VisageTracker Configuration Manual.

If you want to update your existing configuration files, it is recommended to copy the values for these new parameters from the Facial Features Tracker - High.cfg configuration file supplied in this package. In all other cases, simply use the provided configuration files.

### Data files changes:

visage|SDK data files located in Samples/data/bdtsdata folder have been updated. Copy all files located in the bdtsdata folder to appropriate folders in any existing applications.

### Other changes:

libVisageAnalyser library dynamically links and is dependent on OpenBLAS library. For more information see samples documentation.

## visage|SDK 8.1.4407

### API changes:

Prototype of following methods has been changed:

-     void VisageTracker::setTrackerConfigurationFileName(const char* trackerConfigFile)

  to:

      void VisageTracker::setTrackerConfigurationFile(const char* trackerConfigFile, bool au_fitting_disabled = false, bool mesh_fitting_disabled = false)

-     int VisageFeaturesDetector::detectFacialFeatures(VsImage* frame, FaceData* output, int maxFaces = 1, float minFaceScale = 0.1f)

  to:

      int VisageFeaturesDetector::detectFacialFeatures(VsImage* frame, FaceData* output, int maxFaces = 1, float minFaceScale = 0.1f, float maxFaceScale = 1.0f)

Following class members have been removed:

-     VisageSDK::FaceData::frame

Following class methods have been removed:

-     int VisageTracker::getTrackingData(FaceData *data)

-     void VisageTracker::attach(VisageTrackerObserver *_obs)

-     void VisageTracker::detach()

Following interfaces have been removed:

-     VisageTrackerObserver

VisageFaceAnalysers' emotions model augmented with neutral emotion. The function:

    int VisageSDK::VisageFaceAnalyser::estimateEmotion(VsImage * frame, FaceData * facedata, float *prob_estimates)

now returns 7 values in following order: anger, disgust, fear, happiness, sadness, surprise and neutral

### Changes in configuration file format:

- process_eyes configuration parameter changed to bit-flag type parameter. Controls gaze vector calculation and pupil points refinement. Setting the parameter to 1 enables the gaze calculations, setting it to 2 enables the pupil refinement and setting it to 3 enables both functionalities.

- Configuration parameters min_face_scale and max_face_scale added. If they are not listed in the configuration file default values will be used (0.15,1.0).

- Smoothing factor groups have been updated.

  - New group for face contour smoothing has been added - contour.

  - Mouth and chin group has been renamed to mouth and now covers only mouth smoothing. Chin smoothing is moved to contour smoothing group.

- Instead of one model three new separate models have been added: pose fitting, au fitting and mesh fitting model. Old parameters have been modified and new parameters have been added. Changes in the configuration parameters related to the model are reflected in the table below:

  OLD PARAMETER NAME | POSE FITTING MODEL | AU FITTING MODEL | MESH FITTING MODEL
  model_filename | pose_fitting_model | au_fitting_model | mesh_fitting_model
  fdp_filename | pose_fitting_fdp | au_fitting_fdp | mesh_fitting_fdp
  au_use | pose_fitting_au_use | au_fitting_au_use | mesh_fitting_au_use
  ekf_sensitivity | pose_fitting_au_sensitivity | au_fitting_au_sensitivity | mesh_fitting_au_sensitivity
  - | pose_fitting_su_use | au_fitting_su_use | mesh_fitting_su_use
  - | pose_fitting_su_sensitivity | au_fitting_su_sensitivity | mesh_fitting_su_sensitivity

  For detailed description of these changes consult VisageTracker Configuration Manual.

  If you want to update your existing configuration files, it is recommended to copy the values for these new parameters from the Facial Features Tracker - High.cfg configuration file supplied in this package. In all other cases, simply use the provided configuration files.

### Data files changes:

visage|SDK data files located in Samples/data/bdtsdata folder have been updated. Copy all files located in the bdtsdata folder to appropriate folders in any existing applications.
New model has been added - jk_300, in two additional files: jk_300.wfm and jk_300.fdp. For detailed information on how the new model is used inside the visage|SDK consult VisageTracker Configuration Manual section 2.3.

## visage|SDK 8.0.3444

### API changes:

1. VisageTracker2 class has been renamed to VisageTracker.

2. The following methods have been removed:

-     VisageTracker::trackFromCam()

  (example on how to replicate this functionality with VisageTracker::track() method is available in VisageTrackerDemo sample)

-     VisageTracker::trackFromVideo()

  (example on how to replicate this functionality with VisageTracker::track() method is available in VisageTrackerDemo sample)

-     VisageTracker::trackFromRawImages()

-     VisageTracker::getNormalizedFaceImage()

  If you require this function please contact our technical support.

-     VisageFeaturesDetector::getNormalizedFaceImage()

-     VisageFeaturesDetector::detectFacialFeatures(const char* imageFileName, FaceData* output, int maxFaces = 1, float minFaceScale = 0.1f)

3. VisageTrackerFrameGrabber class has been removed.

4. DetectStrip API has been removed.

5. visage|SDK libraries have been split in three libraries, based on the functionality:

- libVisageVision - face detection, alignment and face tracking

- libVisageGaze - screen space gaze tracking (requires libVisageVision)

- libVisageAnalyser - face analysis (requires libVisageVision)

6. Prototype of method:

    void initializeLicenseManager(char *licenseKeyFileName)

changed to

    void initializeLicenseManager(const char *licenseKeyFileName)

### Changes in configuration files:

- Smoothing factors groups and their default values have been changed (translation and rotation groups removed, new groups include eyebrows, mouth_and_chin, pupils, eyelids and nose).

- Some parameters have been removed from configuration files. Please consult VisageTracker Configuration Manual to see complete list of parameters in configuration files.

If you want to update your existing configuration files, it is recommended to copy the values for these new parameters from the Facial Features Tracker - High.cfg configuration file supplied in this package. In all other cases, simply use the provided configuration files.

### Data files changes:

visage|SDK data files located in Samples/data/bdtsdata folder have been updated. Copy all files located in the bdtsdata folder to appropriate folders in any existing applications.

### Sample changes:

Drawing of feature points in VisageDetectorDemo sample application has been moved from visage|SDK library to a separate source file VisageDrawing.cpp

### Licensing changes:

Unlicensed VisageFeaturesDetector will return complete results but has a delay of 2 seconds for each call of detectFacialFeatures method.

Unlicensed VisageFaceAnalyser has a delay of 2 seconds for each call of estimate function.

## visage|SDK 7.4.2500

### API changes:

1. Rendering has been moved from the visage|SDK library to samples, thus following optional interfaces for VisageTracker2 have been removed:

    class TrackerGUIInterface

    class TrackerOpenGLInterface

2. VisageTracker2 constructor has been removed

    VisageTracker2(TrackerOpenGLInterface *oglInterface, TrackerGUIInterface *guiInterface, const char *trackerConfigFile)

use

    VisageTracker2(const char* trackerConfigFile);

3. Method for tracking from a digital camera is changed to accept additional optional parameters for picking camera device and setting camera width and height:

    bool trackFromCam(const char* outFbaFileName = NULL, int orientation = VISAGE_CAMERA_UP, int frameGrabberImageFormat = VISAGE_FRAMEGRABBER_FMT_RGB, bool startThread = true, int pickCamDevice = -1, int camWidth = -1, int camHeight = -1);

### Changes in configuration files:

Configuration file Facial Features Tracker - Asymmetric.cfg has been removed. Two new configurations have been added to the Samples/data folder:

- Facial Features Tracker - High.cfg - for use with newer and faster processors (e.g. Intel i7, iPhone 6, ... ).
- Facial Features Tracker - Low.cfg - for use with older and slower processors (e.g. iPhone 4, iPhone 4S, ... ).

### Changes in configuration file format:

- New configuration optional parameters high_prec_addition and tracking_preproc added. If they are not listed in the configuration file default values will be used (1,1).

- Smoothing factor groups have been updated. Default values of smoothing factors have been changed in configuration files.
  For detailed description of these changes consult VisageTracker Configuration Manual.

- All configuration now use candide3.wfm model file. It is recommended to set the model_filename parameter in all existing configurations so it points to candide3.wfm.

If you want to update your existing configuration files, it is recommended to copy the values for these new parameters from the Facial Features Tracker - High.cfg configuration file supplied in this package. In all other cases, simply use the provided configuration files.

### Data files changes:

Data files location has been changed from Samples\Linux\data folder to Samples\data folder. Copy all files located in the bdtsdata folder to appropriate folders in any existing applications.

Symmetrical Candide3 face model (old candide3.wfm) has been removed and replaced with asymmetric Candide3 face model, formerly candide3-exp.wfm now candide3.wfm.

## visage|SDK 7.3.1860

### API changes:

1. Old method for tracking from raw images and the respective interface class are deprecated:

    bool trackFromRawImages(VisageTrackerFrameGrabber *frameGrabber,
                            int width,
                            int height,
                            int format,
                            int origin,
                            const char *outFbaFileName=NULL);

and

    class VisageTrackerFrameGrabber

New method is introduced:

    virtual int track(int frameWidth,
                      int frameHeight,
                      const char *p_imageData,
                      FaceData *facedata,
                      int format=VISAGE_FRAMEGRABBER_FMT_RGB,
                      int origin=VISAGE_FRAMEGRABBER_ORIGIN_TL,
                      int widthStep=0);

2. Screen space gaze API has been separated from the VisageTracker2 class. Specialized VisageGazeTracker class added. There have been no changes in screen space gaze API methods.

3. Additional functionality has been added to the API:

- Reset tracker functionality added.

      void VisageTracker2::reset();

- Get normalized face in an image functionality added.

      void getNormalizedFaceImage(IplImage* frame,
                                  IplImage* normFace,
                                  FaceData* face_data,
                                  FDP* normFDP,
                                  int norm_type = VS_NORM_POSE);

### Changes in configuration file format:

- New configuration optional parameters lbf_stage_modifier, lbf_nperturb added. If they are not listed in the configuration file default values will be used (0, 5 in the order listed).
- New configuration optional parameter max_work_size added. If the parameter is not listed in the configuration file or if the supplied value is less than 100 or greater than 1080, default value 320 is used.

For detailed description of new parameters consult VisageTracker Configuration Manual. If you want to update your existing configuration files, it is recommended to copy the values for these new parameters from the Facial Features Tracker - Asymmetric.cfg configuration file supplied in this package. In all other cases, simply use the provided configuration files.

Many parameters are now obsolete and not used in the tracker (e.g. template matching parameters). Tracker will work with configurations containing the old parameters but it is recommended to use the provided configuration files.

### Data files changes:

Data files are located in the folder Visage Technologies\visageSDK\Samples\Linux\data\bdtsdata. Copy all files located in bdtsdata folder to appropriate folders in any existing applications.

## visage|SDK 7.2.1286

This section covers all changes introduced in all releases since 7.1b6.730.

### API changes:

Screen space gaze tracking API introduced.

1. Screen space gaze tracking API methods added to the VisageTracker2 class:

    void VisageTracker2::InitOnlineGazeCalibration();

    void AddGazeCalibrationPoint(float x, float y);

    float FinalizeOnlineGazeCalibration();

    void InitOfflineGazeCalibration(ScreenSpaceGazeRepository *calibrator);

    float getGazeEstimations(ScreenSpaceGazeRepository *repository);

2. Screen space gaze data container ScreenSpaceGazeData is introduced.

3. Screen space gaze data repository ScreenSpaceGazeRepository is introduced.

4. Added gazeData member to FaceData container class.

5. VisageFeaturesDetector functionally is extended to be able to specify minimal detected face size in an image. Therefore interface of detectFacialFeatures functions is changed from:

    VisageFeaturesDetector::detectFacialFeatures(const char* imageFileName, FaceData* output, int maxFaces = 1);

    VisageFeaturesDetector::detectFacialFeatures(IplImage *frame, FaceData* output, int maxFaces = 1)

to:

    VisageFeaturesDetector::detectFacialFeatures(const char* imageFileName, FaceData* output, int maxFaces = 1, int minFaceSize = 0);

    VisageFeaturesDetector::detectFacialFeatures(IplImage* frame, FaceData* output, int maxFaces = 1, int minFaceSize = 0);

### Changes in configuration file format:

- New configuration optional parameters max_work_eye_dist, work_buffer_width, work_buffer_height added. If they are not listed in the configuration file default values will be used (60, 1024, 1024 in the order listed). For detailed description of these parameters consult VisageTracker Configuration Manual
- max_work_image_width parameter is now obsolete
- screen_space_gaze smoothing factor modifier added to the smoothing_factors parameter
- Four eyelids detections added to the bdts_points_use and bdts_points_angle parameters
- ekf_sensitivity value for AU13(au_leye_closed) and AU23(au_reye_closed) set to 100

If you want to update your existing configuration files, it is recommended to copy the values for these new parameters from the Facial Features Tracker - Asymmetric.cfg configuration file supplied in this package. In all other cases, simply use the provided configuration files.

### Other:

Enabled fitting while mouth is moderately open during initialization.

Action Units for eye closure now return continuous results.

### Bug fixes:

Tracking bug on high in-plane rotations (z axis) fixed.

Tracker crashing when VisageTracker2 object is deleted after calling stop() method fixed.

Tracker crashing when wrong path to the data files is given to VisageDetector::Initialize() method fixed.

# visage|SDK 7.1b6.730

This is a first release of visage|SDK for Linux.