Face Detection

class Facechip

Class which is used to manage a face chip image. A face chip represents and aligned and cropped face image. A Facechip can be in CPU memory or GPU memory.

Example of a Facechip:

../_images/chip.jpg
Trueface::Facechip::Facechip() = default

Default constructor.

void Trueface::Facechip::saveImage(const std::string &filepath)

Save the face chip to disk.

Parameters:

filepath – [in] The filepath where the face chip should be saved, including the image extension.

ErrorCode Trueface::Facechip::loadImage(const std::string &filepath, bool gpuMemory = false, int gpuIndex = 0)

Load the face chip from disk.

Parameters:

  • filepath – [in] The filepath of the facechip to load.

  • gpuMemory – [in] Read the image into GPU memory. This should be set to true when running GPU inference.

  • gpuIndex – [in] The GPU index.

unsigned int Trueface::Facechip::getHeight() const

Get the face chip height in pixels.

Returns:

Returns the face chip height in pixels.

unsigned int Trueface::Facechip::getWidth() const

Get the face chip width in pixels.

Returns:

Returns the face chip width in pixels.

unsigned int Trueface::Facechip::getStride() const

Get the GPU stride for GPU images.

Returns:

Returns the GPU stride for the Facechip.

bool Trueface::Facechip::isGPUImage() const

Is the face chip in GPU memory.

Returns:

Returns true if the face chip is in GPU memory.

uint8_t *Trueface::Facechip::getData() const

Get the decoded image buffer.

Returns:

Returns the decoded image buffer.

using Trueface::TFFacechip = std::shared_ptr<Facechip>
ErrorCode Trueface::SDK::detectFaces(const TFImage &tfImage, std::vector<FaceBoxAndLandmarks> &faceBoxAndLandmarks)

Detect all the faces in the image. Use the ConfigurationOptions::fdFilter to filter the detected faces.

Refer to our FAQ page to understand the impact of face height on similarity score.

The face detector is able to detect faces in the following dynamic height range. Smallest detectable face = ((the larger of your image dimensions) / 640 * 20) pixels. Largest detectable face = (your image height) pixels.

Parameters:

  • tfImage – [in] The input image returned by preprocessImage().

  • faceBoxAndLandmarks – [out] A vector of FaceBoxAndLandmarks representing each of the detected faces. If not faces are found, the vector will be empty. The detected faces are sorted in order of descending face score.

Returns:

Error code, see ErrorCode.

ErrorCode Trueface::SDK::detectLargestFace(const TFImage &tfImage, FaceBoxAndLandmarks &faceBoxAndLandmarks, bool &found)

Detect the largest face in the image by area. Use the ConfigurationOptions::fdFilter to filter the detected faces.

Refer to our FAQ page to understand the impact of face height on similarity score.

The face detector is able to detect faces in the following dynamic height range. Smallest detectable face = ((the larger of your image dimensions) / 640 * 20) pixels. Largest detectable face = (your image height) pixels.

Parameters:

  • tfImage – [in] The input image returned by preprocessImage().

  • faceBoxAndLandmarks – [out] The FaceBoxAndLandmarks containing the landmarks and bounding box of the largest detected face in the image.

  • found – [out] Whether a face was found in the image.

Returns:

Error code, see ErrorCode.

ErrorCode Trueface::SDK::getFaceLandmarks(const TFImage &tfImage, const FaceBoxAndLandmarks &faceBoxAndLandmarks, Landmarks &landmarks)

Obtain the 106 face landmarks.

Parameters:
Returns:

Error code, see ErrorCode.

ErrorCode Trueface::SDK::getFaceLandmarks(const std::vector<TFImage> &tfImages, const std::vector<FaceBoxAndLandmarks> &faceBoxAndLandmarksVec, std::vector<Landmarks> &landmarksVec)

Obtain the 106 face landmarks. his batch processing method increases throughput when using GPU inference.T

Parameters:

  • tfImages – [in] A vector of input images.

  • faceBoxAndLandmarksVec – [in] A vector of the FaceBoxAndLandmarks.

  • landmarksVec – [out] A vector of arrays representing the 106 face landmark points in each face image.

Returns:

Error code, see ErrorCode.

The order of the face landmarks:

../_images/landmarks.png
ErrorCode Trueface::SDK::extractAlignedFace(const TFImage &tfImage, const FaceBoxAndLandmarks &faceBoxAndLandmarks, TFFacechip &tfFacechip, int marginLeft = 0, int marginTop = 0, int marginRight = 0, int marginBottom = 0, float scale = 1.0)

Align the the detected face to be optimized for passing to feature extraction. If using the face chip with Trueface algorithms (ex face recognition), do not change the default margin and scale values.

Parameters:

  • tfImage – [in] The input image returned by preprocessImage().

  • faceBoxAndLandmarks – [in] The FaceBoxAndLandmarks returned by detectLargestFace() or detectFaces().

  • tfFacechip – [out] A TFFacechip to store the output facechip.

  • marginLeft – [in] Adds a margin to the left side of the face chip.

  • marginTop – [in] Adds a margin to the top side of the face chip.

  • marginRight – [in] Adds a margin to the right side of the face chip.

  • marginBottom – [in] Adds a margin to the bottom side of the face chip.

  • scale – [in] Changes the scale of the face chip.

Returns:

Error code, see ErrorCode.

ErrorCode Trueface::SDK::estimateHeadOrientation(const TFImage &tfImage, const FaceBoxAndLandmarks &faceBoxAndLandmarks, const Landmarks &landmarks, HeadOrientation &headOrientation)

Estimate the head orientation. Refer to our FAQ page to understand the impact of face orientation on similarity score.

Parameters:

  • tfImage – [in] The input image returned by preprocessImage().

  • faceBoxAndLandmarks – [in] The face box and landmarks, returned by detectLargestFace().

  • landmarks – [in] The detailed face landmarks, returned by getFaceLandmarks().

  • headOrientation – [out] The predicted head orientation.

Returns:

Error code, see ErrorCode.

template<typename T>
struct Point

Public Members

T x

Coordinate along the horizontal axis, or pixel column.

T y

Coordinate along the vertical axis, or pixel row.

struct FaceBoxAndLandmarks

Public Functions

float getHeight() const

Returns the height of the face box in pixels.

float getArea() const

Returns the area of the face box in pixels squared.

Public Members

Point<float> topLeft

The top left corner Point of the bounding box.

Point<float> bottomRight

The bottom right corner Point of the bounding box.

std::vector<Point<float>> landmarks

A vector of Point representing the facial landmarks: subject right eye, subject left eye, nose, subject right mouth corner, subject left mouth corner.

float score

Likelihood of this being a true positive.

The order of the face landmarks:

../_images/landmarks2.jpg
using Trueface::Landmarks = std::array<Point<float>, 106>

Array of 106 face points.

struct HeadOrientation

Used to describe the orientation of a head.

Public Members

float yaw

The rotation angle around the image’s vertical axis, in radians.

float pitch

The rotation angle around the image’s transverse axis, in radians.

float roll

The rotation angle around the image’s longitudinal axis, in radians.

std::array<double, 3> rotationVec

The rotation vector, can be passed to drawHeadOrientationBox() method.

std::array<double, 3> translationVec

The translation vector, can be passed to drawHeadOrientationBox() method.