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 Additional eyes landmarks Additional lips landmarks For more details please see FDP documentation.

Changes in configuration file:

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: Introducing new functions for getting and setting temporally_denoise_input parameter: Introducing major changes in fitting related parameters API.
The following API methods have been replaced: The following API methods have been removed: Introducing new functions for getting and setting pose_fitting_model_configuration, au_fitting_model_configuration, mesh_fitting_model_configuration parameters respectively:

FDP class:

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

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:

VisageFaceAnalyser API

VisageFaceAnalyser API was refactored to optimise usage and to include newly introduced multi-frame analysis feature.

Old face analysis functions were removed: and replaced with new ones: 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: For more details please see VisageFeaturesDetector API documentation.

VisageConfiguration API

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

VisageGazeTracker API

Prototype of following method has been changed:

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

Added

Modified

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

Liveness API

Parameter *frame is now mandatory for the following method:

Changes in configuration file:

Removed

Added

Renamed

Modified

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

Modified

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.

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:

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:

Changes in configuration file:

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

Added

Modified

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:

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:

used in conjunction with new VisageTracker methods: For more details and usage code examples please refer to Detailed Description section of VisageConfiguration and VsCfgArr.


FDP class:


Deprecated API:


Licensing:

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:

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:

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:

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:

For detailed illustration see MPEG-4 FBA.

API changes:

VisageFeaturesDetector:
VisageFaceRecognition:

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:
VisageFaceRecognition:
VisageFeaturesDetector:
Following methods has been changed:

Changes in configuration file format:


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: Following class members have been removed: Following class methods have been removed: Following interfaces have been removed: 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:

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:

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:

6. Prototype of method:

void initializeLicenseManager(char *licenseKeyFileName)
changed to
void initializeLicenseManager(const char *licenseKeyFileName)

Changes 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:

Changes in configuration file format:

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:

Changes in configuration file format:

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:

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.