Class: FDP

FDP

new FDP()

Feature points of a face.

This class is a container for facial feature points as defined by MPEG-4 FBA standard, as well as some additional feature points. Feature points are identified by their group (for example, feature points of the nose constitute their own group) and index. So, for example, the tip of the chin belongs to group 2 and has index 1, so it is identified as point 2.1. The identification of all MPEG-4 feature points is illustrated in the image below:



Groups 2 - 11 contain feature points defined according to the MPEG-4 FBA standard, and groups 12 and 14 contain additional feature points that are not part of the MPEG-4 standard (12.1, 12.5, 12.6, 12.7, 12.8, 12.9, 12.10, 12.11, 12.12, 14.1, 14.2, 14.3, 14.4, 14.21, 14.22, 14.23, 14.24, 14.25).

Face contour - group 13 and group 15



Face contour is available in two versions: the visible contour (points 13.1 - 13.17) and the physical contour (points 15.1 - 15.17). The physical contour is the set of 16 equally spaced points running from one ear to another, following the outer edge of cheeks and the jaw. Depending on face rotation, points on the physical contour may not always be visible; however, our algorithm maps them on the 3D model of the face and estimates the invisible points. Therefore all points of the physical contour are always available, regardless of their visibility, in both 3D and 2D (featurePoints2D, featurePoints3D, featurePoints3DRelative). The 2D points are obtained by projection from the 3D points, and they may not correspond to the points on the visible contour.

The visible contour is the set of 16 equally spaced points running along the edges of the visible part of the face in the image, starting at the height of ears. Thus, in a frontal face the visible contour runs from one ear, along the jaw and chin, to the other ear; in a semi-profile face it runs from the visible ear, along the jaw and chin, then along the cheek on the far side of the face; in full profile it runs from the ear, along the jaw, then up along the mouth and nose. The points on the visible contour are obtained directly by detection/tracking, and they are available only in 2D (featurePoints2D). Please note that point 13.17 is exactly identical to point 2.1 (2.1 point exists for MPEG-4 compatibility purposes).

Stability and accuracy of the contours



The points on the visible contour are among the most difficult to detect/track, and their accuracy is lower than that of eyes or mouth points; they are also more noisy (jittery). The points on the physical contour are obtained from the fitted 3D model of the face. This stabilises them so there is considerably less jitter. In general, it is recommended to use the physical contour.

FDP class stores feature point information. It also provides functions for reading and writing the feature point data as files, as well as certain auxiliary members that deal with normalisation of feature points and their classification according to facial region.

The actual data for each feature point is stored in the structure FeaturePoint. One such structure is allocated for each feature point. To access a feature point, use one of the functions getFP() that access a feature point by its group and index expressed either as integer values, or as a string (e.g. "2.1"). Functions getFPPos() are available as a convenience, to access the feature point coordinates directly, without first accessing the FeaturePoint structure.

The feature points may relate to a particular 3D model. In such a case it is interesting to know, for each feature point, to which vertex it belongs. For this purpose, the FeaturePoint structure contains the mesh identifier and vertex index that correspond to the feature point and the FDP class provides functions to access this data.

Left-right convention

References to left and right in feature point definitions are given from the perspective of the face itself so "right eye" can be imagined as "my right eye". When referring to feature points in an image, it is assumed that image is taken by camera and not mirrored so "right eye" is on the left in the image, as shown in feature points illustration above.

See:

Methods

getFP(group, n) → {FeaturePoint}

Get a feature point by its group and index.
Note: After the end of use, obtained FeaturePoint needs to be deleted to release the allocated memory. Example:

var left_eye_fp = faceData.getFeaturePoints2D().getFP(3,5);
var right_eye_fp = faceData.getFeaturePoints2D().getFP(3,6);

... 

left_eye_fp.delete();
right_eye_fp.delete();



Parameters:
Name Type Description
group number Feature point group. Valid range is from 2 to 15.
n number Feature point index. Valid range is from 1 to the size of particular group. Group sizes can be obtained using groupSize().

Returns:
Feature point object corresponding to the group and index
Type
FeaturePoint

setFP(group, n, featurePoint)

Set a feature specified by its group and index.

Parameters:
Name Type Description
group number Feature point group. Valid range is from 2 to 15.
n number Feature point index. Valid range is from 1 to the size of particular group. Group sizes can be obtained using groupSize().
featurePoint FeaturePoint The feature point object to set.

setFP(name, featurePoint)

Set a feature specified by its name.

Parameters:
Name Type Description
name string Feature point name (e.g. "7.1").
featurePoint FeaturePoint The feature point object to set.

getFPPos(group, n) → {Float32Array}

Get the position of a feature point specified by its group and index.

Parameters:
Name Type Description
group number Feature point group. Valid range is from 2 to 15.
n number Feature point index. Valid range is from 1 to the size of particular group. Group sizes can be obtained using groupSize().

Returns:
Vertex position (array of 3 numbers).
Type
Float32Array

setFPPos(group, n, x, y, z)

Set the position of a feature point specified by its group and index.

Parameters:
Name Type Description
group number Feature point group. Valid range is from 2 to 15.
n number Feature point index. Valid range is from 1 to the size of particular group. Group sizes can be obtained using groupSize().
x number Vertex x position.
y number Vertex y position.
z number Vertex z position.

getFPQuality(group, n)

Get the quality of a feature point specified by its group and index.

Parameters:
Name Type Description
group number Feature point group. Valid range is from 2 to 15.
n number Feature point index. Valid range is from 1 to the size of particular group. Group sizes can be obtained using groupSize().

setFPQuality(group, n, quality)

Set the quality of a feature point specified by its group and index.

Parameters:
Name Type Description
group number Feature point group. Valid range is from 2 to 15.
n number Feature point index. Valid range is from 1 to the size of particular group. Group sizes can be obtained using groupSize().
quality number quality value.

setFPPos(name, x, y, z)

Set the position of a feature point specified by its name.

Parameters:
Name Type Description
name string Feature point name (e.g. "7.1").
x number Vertex x position.
y number Vertex y position.
z number Vertex z position.

reset()

Resets all feature points.

The value of all feature points is set to "undefined".

FPIsDefined(group, n) → {boolean}

Returns true if the feature point is defined.

Parameters:
Name Type Description
group number Feature point group. Valid range is from 2 to 15.
n number Feature point index. Valid range is from 1 to the size of particular group. Group sizes can be obtained using groupSize().

Returns:
True if the feature point is defined, false otherwise.
Type
boolean

FPIsDetected(group, n) → {boolean}

Returns true if the feature point is detected.

Parameters:
Name Type Description
group number Feature point group. Valid range is from 2 to 15.
n number Feature point index. Valid range is from 1 to the size of particular group. Group sizes can be obtained using groupSize().

Returns:
True if the feature point is detected, false otherwise.
Type
boolean

FPIsValid(group, n) → {boolean}

Returns true if specified feature point identifier is valid.

Parameters:
Name Type Description
group number Feature point group. Valid range is from 2 to 15.
n number Feature point index. Valid range is from 1 to the size of particular group. Group sizes can be obtained using groupSize().

Returns:
True if specified feature point identifier is valid, false otherwise.
Type
boolean

FPIsValid(name) → {boolean}

Returns true if specified feature point identifier is valid.

Parameters:
Name Type Description
name string Feature point name (e.g. "7.1").

Returns:
True if specified feature point identifier is valid, false otherwise.
Type
boolean

getFPName(group, n) → {string}

Get feature point name from group and index.

Parameters:
Name Type Description
group number Feature point group. Valid range is from 2 to 15.
n number Feature point index. Valid range is from 1 to the size of particular group. Group sizes can be obtained using groupSize().

Returns:
Feature point name.
Type
string

groupSize(group) → {number}

Get the size of the specified feature point group. Valid range for group is from 2 to 15.

Parameters:
Name Type Description
group number Feature point group. Valid range is from 2 to 15.

Returns:
Size of the specified feature point group.
Type
number

getMirrorPointIndex(group, index) → {number}

Get the mirror point index for the point defined by given group and index.

Parameters:
Name Type Description
group number Feature point group. Valid range is from 2 to 15.
index number Feature point index. Valid range is from 1 to the size of particular group. Group sizes can be obtained using groupSize().

Returns:
Index of the mirror point (group is the same).
Type
number