visageSDK
Public Member Functions | List of all members
VisageCSWrapper.VisageFeaturesDetector Class Reference

Faces and facial features detector implementation. More...

Public Member Functions

 VisageFeaturesDetector (string detectorConfigFile)
 Constructor that receives detector configuration file and initializes the features detector. More...
 
 ~VisageFeaturesDetector ()
 Destructor. More...
 
int DetectFacialFeatures (VSImage frame, FaceData[] output, float minFaceScale=0.1f, float maxFaceScale=1.0f, bool outputOnly2DFeatures=false)
 
int DetectFaces (VSImage frame, VSRect[] faces, float minFaceScale=0.1f, float maxFaceScale=1.0f, bool useRefinementStep=true)
 

Detailed Description

Faces and facial features detector implementation.

This class detects one or more faces and their facial features in an image. The input is an image bitmap or an image file in one of the supported file formats: JPEG, PNG, BMP or PPM. The results are, for each detected face, the 3D head pose, gaze direction, eye closure, the coordinates of facial feature points, e.g. chin tip, nose tip, lip corners etc. and 3D face model fitted to the face.

The results are returned in one or more FaceData objects, one for each detected face. Please refer to the FaceData documentation for detailed description of returned data.

To use the detector, pass the detector configuration file to the Visage Features Detector constructor. The name of the configuration file should be relative to the current working directory. Then, call the function DetectFacialFeatures() to perform facial features detection on the image.

Example:

gVisageFeaturesDetector = new VisageFeaturesDetector(@"..\Samples\data\Face Detector.cfg");
numFaces = gVisageFeaturesDetector.DetectFacialFeatures(frame, dataArray);

Please note that vft folder and the configuration file must be distributed with an application using VisageFeaturesDetector.

Definition at line 29 of file VisageFeaturesDetector.cs.

Constructor & Destructor Documentation

VisageCSWrapper.VisageFeaturesDetector.VisageFeaturesDetector ( string  detectorConfigFile)

Constructor that receives detector configuration file and initializes the features detector.

Several data files are needed for facial features detection. In the current distribution these files are contained within the Samples/data folder.

To successfully initialize VisageFeaturesDetector, provide path to the folder with the following folder structure and data files:

  • vft folder that contains algorithm and features specific files. NOTE: The subfolder structure and names must be retained.
    • Required algorithm data files:
      • ff/*
      • fa/*
        • NOTE: If landmarks refinement (configuration parameter refine_landmarks [0]) is disabled, d2.vino.* is not needed.
      • fm/* containing .fdp and .wfm files corresponding to the 3D model (configuration parameters *_fitting_model, *_fitting_fdp)
Parameters
detectorConfigFileThe name of the detector configuration file (.cfg) relative to the current working directory, e.g. "Samples/data/Face Detector.cfg", considering visageSDK as a working directory.
VisageCSWrapper.VisageFeaturesDetector.~VisageFeaturesDetector ( )

Destructor.

Member Function Documentation

int VisageCSWrapper.VisageFeaturesDetector.DetectFaces ( VSImage  frame,
VSRect[]  faces,
float  minFaceScale = 0.1f,
float  maxFaceScale = 1.0f,
bool  useRefinementStep = true 
)

Performs face detection in a still image.

The algorithm detects one or more faces. For each detected face a square facial bounding box is returned.

The results are returned in form of VsRect objects. An array of VsRect objects passed to this method as output parameter should be allocated to maxFaces size. For example:

boundingBoxArray = new VSRect[MAX_FACES];
for (int i = 0; i < MAX_FACES; ++i)
{
boundingBoxArray[i] = new VSRect();
}
if (gVisageFeaturesDetector.Initialized)
{
numFaces = gVisageFeaturesDetector.DetectFaces(frame, boundingBoxArray);
}

After this call, n contains the number of detected faces. The first n members of the faces array are filled with resulting bounding boxes for each detected face.

VsImage is the image storage class similar to IplImage from OpenCV, it has the same structure and members so it can be used like IplImage. Please refer to OpenCV documentation for details of accessing IplImage 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).

Following image formats are supported:

  • VISAGE_FORMAT.RGB: each pixel of the image is represented by three bytes representing red, green and blue channels, respectively.
  • VISAGE_FORMAT.RGBA: each pixel of the image is represented by four bytes representing red, green, blue and alpha (ignored) channels, respectively.
  • VISAGE_FORMAT.LUMINANCE: each pixel of the image is represented by one byte representing the luminance (gray level) of the image. Origin must be:
  • VISAGE_ORIGIN.TL: Origin is the top left pixel of the image. Pixels are ordered row-by-row starting from top left.

Note that the input image is internally converted to grayscale.

Parameters
frameThe input image.
facesPointer to an array of VSRect objects in which the results will be returned.
minFaceScaleScale of smallest face to be searched for, defined as decimal fraction [0.0 - 1.0] of input image size (min(width, height)).
maxFaceScaleScale of largest face to be searched for, defined as decimal fraction [0.0 - 1.0] of input image size (min(width, height)).
useRefinementStepIf set to true, additional refinement algorithm will be used resulting with more precise facial bounding boxes and lower FPR, but higher detection time.
Returns
Number of detected faces (0 or more).
int VisageCSWrapper.VisageFeaturesDetector.DetectFacialFeatures ( VSImage  frame,
FaceData[]  output,
float  minFaceScale = 0.1f,
float  maxFaceScale = 1.0f,
bool  outputOnly2DFeatures = false 
)

Performs faces and facial features detection in a still image.

The algorithm detects one or more faces and their features. The results are, for each detected face, the 3D head pose, gaze direction, eye closure, the coordinates of facial feature points (e.g. chin tip, nose tip, lip corners etc.) and 3D face model fitted to the face.

The results are returned in form of FaceData objects. An array of FaceData objects passed to this method as output parameter should be allocated to maxFaces size. For example:

dataArray = new FaceData[MAX_FACES];
for (int i = 0; i < MAX_FACES; ++i)
{
dataArray[i] = new FaceData();
}
if (gVisageFeaturesDetector.Initialized)
{
numFaces = gVisageFeaturesDetector.DetectFacialFeatures(frame, dataArray);
}

After this call, n contains the number of faces actually detected. The first n members of the data array are filled with resulting data for each detected face. Please refer to the FaceData documentation for detailed description of returned parameters.

Following image formats are supported:

  • VISAGE_FORMAT.RGB: each pixel of the image is represented by three bytes representing red, green and blue channels, respectively.
  • VISAGE_FORMAT.RGBA: each pixel of the image is represented by four bytes representing red, green, blue and alpha (ignored) channels, respectively.
  • VISAGE_FORMAT.LUMINANCE: each pixel of the image is represented by one byte representing the luminance (gray level) of the image. Origin must be:
  • VISAGE_ORIGIN.TL: Origin is the top left pixel of the image. Pixels are ordered row-by-row starting from top left.

Note that the input image is internally converted to grayscale.

See also
FaceData
Parameters
frameThe input image.
outputPointer to an array of FaceData objects in which the results will be returned.
minFaceScaleScale of smallest face to be searched for, defined as decimal fraction [0.0 - 1.0] of input image size (min(width, height)).
maxFaceScaleScale of smallest face to be searched for, defined as decimal fraction [0.0 - 1.0] of input image size (min(width, height)).
outputOnly2DFeaturesIf set, detection time will be reduced and only featurePoints2D will be returned.
Returns
Number of detected faces (0 or more).

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