visageSDK
Instance Methods | List of all members
VisageFaceAnalyser Class Reference

Objective-C wrapper of the native VisageSDK::VisageFaceAnalyser class. More...

#import <objc_VisageFaceAnalyser.h>

Inherits NSObject.

Instance Methods

(VisageFaceAnalyser *) - initWithDataPath:
 Constructor. More...
 
(VFAReturnCode) - analyseImage:withFaceData:withOptions:withAnalysisData:
 Performs the specified face analysis tasks on a given image and outputs results to an AnalysisData object instance. More...
 
(VFAReturnCode) - analyseStream:withFaceData:withOptions:withAnalysisData:withFaceIndex:
 Performs the specified face analysis tasks on a given frame and outputs results to an AnalysisData object instance. More...
 
(void) - resetStreamAnalysis:
 Resets age, gender and emotion data for the specified face index. More...
 
(void) - resetStreamAnalysis
 Resets age, gender and emotion data for all faces. More...
 

Detailed Description

Objective-C wrapper of the native VisageSDK::VisageFaceAnalyser class.

Definition at line 67 of file objc_VisageFaceAnalyser.h.

Method Documentation

◆ analyseImage:withFaceData:withOptions:withAnalysisData:()

- (VFAReturnCode) analyseImage: (VisageImage *)  image
withFaceData: (FaceData *)  faceData
withOptions: (VFAFlags)  options
withAnalysisData: (AnalysisData *)  results 

Performs the specified face analysis tasks 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.

Prior to using this function it is necessary to process the facial image using VisageTracker or VisageFeaturesDetector and pass the frame and obtained data to this function. When using data from VisageTracker, only data obtained when tracking status was TRACK_STAT_OK should be passed.

Usage example:

let detector = VisageFeaturesDetector("Face Detector.cfg")
let maxFaces = Int32(4)
let minFaceScale = Float(0.05)
let maxFaceScale = Float(0.95)
let faceData = FaceDataCollection(maxFaces: maxFaces)
detector!.detectFacialFeatures(image, withFaceData: faceData, withMaxFaces: maxFaces, withMinFaceScale: minFaceScale, withMaxFaceScale: *maxFaceScale, ithOutputOnly2DFeatures: false)
let analysisData = AnalysisData()
let options = VFAFlags(arrayLiteral: .AGE, .EMOTION, .GENDER)
analyser!.analyze(image, withFaceData: faceData, withOptions: options, with: analysisData);
Parameters
imageThe input grayscale, RGB or RGBA image.
faceDataFaceData obtained by a previous successful tracking (TRACK_STAT_OK) or detection operation with VisageTracker or VisageFeaturesDetector.
optionsBitwise combination of VFAFlags which determines the analysis operations to be performed
resultsAnalysisData interface containing success flags for individual operations and their assorted results
Returns
VFAReturnCode value indicating the status of the performed analysis.

◆ analyseStream:withFaceData:withOptions:withAnalysisData:withFaceIndex:()

- (VFAReturnCode) analyseStream: (VisageImage *)  frame
withFaceData: (FaceData *)  faceData
withOptions: (VFAFlags)  options
withAnalysisData: (AnalysisData *)  results
withFaceIndex: (int)  faceIndex 

Performs the specified face analysis tasks 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.

Note
Prior to using this function it is necessary to process the facial image using VisageTracker and pass the frame and obtained data to this function.
Parameters
frameThe input grayscale, RGB or RGBA frame.
faceDataFaceData obtained by a previous successful tracking operation with VisageTracker (TRACK_STAT_OK).
optionsBitwise combination of VFAFlags which determines the analysis operations to be performed
resultsAnalysisData interface containing success flags for individual operations and their assorted results
faceIndexIndex of the face for which analysis should be performed
Returns
VFAReturnCode value indicating the status of the performed analysis.

◆ initWithDataPath:()

- (VisageFaceAnalyser *) initWithDataPath: (NSString *)  dataPath

Constructor.

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:

  • ad: age estimation
  • gd: gender estimation
  • ed: emotion estimation

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. Subsqeuent 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.

Parameters
dataPathrelative path from the working directory to the directory that contains VisageFaceAnalyser data files.
Returns
The return value of 0 indicates that no data files are found and no analysis will be possible. In such case, the placement of data files should be verified. A non-zero value indicates that one or more types of analysis are successfully initialized. The specific types of analysis that have been initialized are indicated by a bitwise combination of the following flags: VFA_GENDER, VFA_GENDER, VFA_EMOTION.

◆ resetStreamAnalysis()

- (void) resetStreamAnalysis

Resets age, gender and emotion data for all faces.

This is intended to be used in cases when a new person replaces the old one in the same continous input stream.

◆ resetStreamAnalysis:()

- (void) resetStreamAnalysis: (int)  faceIndex

Resets age, gender and emotion data for the specified face index.

This is intended to be used in cases when a new person replaces the old one in the same continous input stream.


The documentation for this class was generated from the following file: