|
visageSDK
|
VisageFaceAnalyser contains face analysis algorithms capable of estimating age, gender and emotion from facial images. More...
#include <VisageFaceAnalyser.h>
Public Member Functions | |
| VisageFaceAnalyser () | |
| Constructor. | |
| ~VisageFaceAnalyser () | |
| Destructor. | |
| int | init (const char *dataPath) |
| Initialise VisageFaceAnalyser. More... | |
| VFAReturnCode | analyseImage (const VsImage *image, const FaceData &faceData, const int options, AnalysisData &results) |
Performs face analysis tasks specified by options parameter on a given image and outputs results to an AnalysisData object instance. More... | |
| VFAReturnCode | analyseStream (const VsImage *frame, const FaceData &faceData, const int options, AnalysisData &results, const int faceIndex=0) |
Performs face analysis tasks specified by options parameter on a given frame and outputs results to an AnalysisData object instance. More... | |
| void | resetStreamAnalysis (const int faceIndex=-1) |
| Resets collected face analysis data. More... | |
VisageFaceAnalyser contains face analysis algorithms capable of estimating age, gender and emotion from facial images.
Before using VisageFaceAnalyser, it must be initialized using the function init(). After the initialization the following types of analysis can be used:
Face analysis may be performed on an individual image, or on a sequential stream of images (such as a video or camera feed). The two corresponding functions are:
| analyseImage() | Perform face analysis on a single image |
| analyseStream() | Perform face analysis on a sequential stream (utilizes score-based selection of ideal candidate frames to deliver a high-precision averaged result) |
VisageFaceAnalyser uses VsImage structure as a container for the input image. Please refer to the VsImage structure documentation for details of accessing its data members; the basic members are the size of the image (frame->width, frame->height) and the pointer to the actual pixel data of the image (frame->imageData). All of the estimation methods expect grayscale, RGB or RGBA image. Please note that for the most efficient usage, the grayscale image format should be used. Grayscale format is a default image format for the estimation methods and conversion from other valid image formats is done internally.
The following is an example of how to create an input image using methods provided by visage|SDK:
Definition at line 163 of file VisageFaceAnalyser.h.
| VFAReturnCode VisageSDK::VisageFaceAnalyser::analyseImage | ( | const VsImage * | image, |
| const FaceData & | faceData, | ||
| const int | options, | ||
| AnalysisData & | results | ||
| ) |
Performs face analysis tasks specified by options parameter on a given image and outputs results to an AnalysisData object instance.
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.
An example of usage with OpenCV, estimate gender and age on all the faces detected in an image file:
| image | VsImage container that contains the input grayscale, RGB or RGBA image. |
| faceData | FaceData obtained by a previous successful tracking (TRACK_STAT_OK) or detection operation with VisageTracker or VisageFeaturesDetector. |
| options | Bitwise combination of VFAFlags which determines the analysis operations to be performed. |
| results | AnalysisData struct containing success flags for individual operations and their assorted results. |
| VFAReturnCode VisageSDK::VisageFaceAnalyser::analyseStream | ( | const VsImage * | frame, |
| const FaceData & | faceData, | ||
| const int | options, | ||
| AnalysisData & | results, | ||
| const int | faceIndex = 0 |
||
| ) |
Performs face analysis tasks specified by options parameter on a given frame and outputs results to an AnalysisData object instance.
This function is primarily intended for performing face analysis on a continuous stream of related frames containing the same person, 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.
Important notes:
This method should only be called with FaceData obtained from a successful tracking operation that returned TRACK_STAT_OK tracking status.
If options parameter is changed between subsequent calls to analyseStream(), the internal state will be reset and previously collected analysis data will be lost. For optimal results options parameter should remain constant during single stream analysis session.
If a new person in the continuous stream replaces the old one, it is neccessary to call resetStreamAnalysis() method otherwise results will not be correct as analyseStream() method has no capability of differentiating faces.
An example of usage with OpenCV, estimate gender and age on all the faces tracked in a video file:
| frame | VsImage container that contains the input grayscale, RGB or RGBA frame. |
| faceData | FaceData obtained by a previous successful tracking operation with VisageTracker (TRACK_STAT_OK). |
| options | Bitwise combination of VFAFlags which determines the analysis operations to be performed. |
| results | AnalysisData struct containing success flags for individual operations and their assorted results. |
| faceIndex | Index of the face for which analysis should be performed. |
| int VisageSDK::VisageFaceAnalyser::init | ( | const char * | dataPath | ) |
Initialise VisageFaceAnalyser.
This function must be called before using VisageFaceAnalyser by passing it a path to the folder containing the VisageFaceAnalyser data files. Within the visage|SDK package, this folder is Samples/data/vfa*. When implementing applications, developers may copy this folder as part of their application. The path is given relative to the current working directory at the time of calling the init() function.
The VisageFaceAnalyser data folder contains the following subfolders corresponding to the various types of analysis that can be performed:
Note that it is not neccessary for all subfolders to be present, only the ones needed by the types of analysis that will be performed. For example, if only gender estimation will be performed, then only the gd folder is required.
The return value of the init() function indicates which types of analysis have been successfully initialised. Subsequent attempt to use a type of analysis that was not initialized shall fail; for example, if only gd folder was present at initialization, attempt to estimate emotions shall fail.
The return value is a bitwise combination of flags indicating which types of analysis are successfully initialized.
| dataPath | relative path from the working directory to the directory that contains VisageFaceAnalyser data files. |
| void VisageSDK::VisageFaceAnalyser::resetStreamAnalysis | ( | const int | faceIndex = -1 | ) |
Resets collected face analysis data.
Erases age, gender and emotion data collected up to this point.
This is intended to be used in cases when a new person replaces the old one in the same continous input stream.
If an index parameter is specified, only data for that specific face is erased. If no parameter is specified, data for all faces is erased.
| faceIndex | Index of the face for which analysis data should be reset |
1.8.13