Table of Contents

Class FaceRecognition

Namespace
FaceRecognitionDotNet
Assembly
VisioForge.Core.FaceAI.dll

Provides the method to find and recognize face methods. This class cannot be inherited.

public sealed class FaceRecognition : DisposableObject, IDisposable

Inheritance

Implements

Inherited Members

Properties

CustomAgeEstimator

Gets or sets the custom age estimator that user defined.

public AgeEstimator CustomAgeEstimator { get; set; }

Property Value

AgeEstimator

CustomEmotionEstimator

Gets or sets the custom emotion estimator that user defined.

public EmotionEstimator CustomEmotionEstimator { get; set; }

Property Value

EmotionEstimator

CustomEyeBlinkDetector

Gets or sets the custom eye blink detector that user defined.

public EyeBlinkDetector CustomEyeBlinkDetector { get; set; }

Property Value

EyeBlinkDetector

CustomFaceDetector

Gets or sets the custom face detector that user defined.

public FaceDetector CustomFaceDetector { get; set; }

Property Value

FaceDetector

CustomFaceLandmarkDetector

Gets or sets the custom face landmark detector that user defined.

public FaceLandmarkDetector CustomFaceLandmarkDetector { get; set; }

Property Value

FaceLandmarkDetector

CustomGenderEstimator

Gets or sets the custom gender estimator that user defined.

public GenderEstimator CustomGenderEstimator { get; set; }

Property Value

GenderEstimator

CustomHeadPoseEstimator

Gets or sets the custom head pose estimator that user defined.

public HeadPoseEstimator CustomHeadPoseEstimator { get; set; }

Property Value

HeadPoseEstimator

InternalEncoding

Gets or sets the character encoding to convert String to array of Byte for internal library.

public static Encoding InternalEncoding { get; set; }

Property Value

Encoding

Methods

BatchFaceLocations(IEnumerable<Image>, int, int)

Returns an enumerable collection of array of bounding boxes of human faces in a image using the cnn face detector.

public IEnumerable<Location[]> BatchFaceLocations(IEnumerable<Image> images, int numberOfTimesToUpsample = 1, int batchSize = 128)

Parameters

images IEnumerable<Image>

An enumerable collection of images.

numberOfTimesToUpsample int

The number of image looking for faces. Higher numbers find smaller faces.

batchSize int

The number of images to include in each GPU processing batch.

Returns

IEnumerable<Location[]>

An enumerable collection of array of found face locations.

Exceptions

ArgumentNullException

images is null.

CompareFace(FaceEncoding, FaceEncoding, double)

Compare a known face encoding against a candidate encoding to see if they match.

public static bool CompareFace(FaceEncoding knownFaceEncoding, FaceEncoding faceEncodingToCheck, double tolerance = 0.6)

Parameters

knownFaceEncoding FaceEncoding

A known face encodings.

faceEncodingToCheck FaceEncoding

A single face encoding to compare against a known face encoding.

tolerance double

The distance between faces to consider it a match. Lower is more strict. The default value is 0.6.

Returns

bool

A True/False value indicating which known a face encoding matches the face encoding to check.

Exceptions

ArgumentNullException

knownFaceEncoding or faceEncodingToCheck is null.

ObjectDisposedException

knownFaceEncoding or faceEncodingToCheck.

CompareFace(FaceInfo, FaceInfo, double)

Compare a known face encoding against a candidate encoding to see if they match.

public static bool CompareFace(FaceInfo knownFaceEncoding, FaceInfo faceEncodingToCheck, double tolerance = 0.6)

Parameters

knownFaceEncoding FaceInfo

A known face encodings.

faceEncodingToCheck FaceInfo

A single face encoding to compare against a known face encoding.

tolerance double

The distance between faces to consider it a match. Lower is more strict. The default value is 0.6.

Returns

bool

A True/False value indicating which known a face encoding matches the face encoding to check.

Exceptions

ArgumentNullException

knownFaceEncoding or faceEncodingToCheck is null.

ObjectDisposedException

knownFaceEncoding or faceEncodingToCheck.

CompareFaces(IEnumerable<FaceEncoding>, FaceEncoding, double)

Compare an enumerable collection of face encodings against a candidate encoding to see if they match.

public static List<bool> CompareFaces(IEnumerable<FaceEncoding> knownFaceEncodings, FaceEncoding faceEncodingToCheck, double tolerance = 0.6)

Parameters

knownFaceEncodings IEnumerable<FaceEncoding>

An enumerable collection of known face encodings.

faceEncodingToCheck FaceEncoding

A single face encoding to compare against the enumerable collection.

tolerance double

The distance between faces to consider it a match. Lower is more strict. The default value is 0.6.

Returns

List<bool>

An enumerable collection of True/False values indicating which known face encodings match the face encoding to check.

Exceptions

ArgumentNullException

knownFaceEncodings or faceEncodingToCheck is null.

ObjectDisposedException

faceEncodingToCheck is disposed. Or knownFaceEncodings contains disposed object.

CompareFaces(IEnumerable<FaceInfo>, FaceInfo, double)

Compare an enumerable collection of face encodings against a candidate encoding to see if they match.

public static List<bool> CompareFaces(IEnumerable<FaceInfo> knownFaceEncodings, FaceInfo faceEncodingToCheck, double tolerance = 0.6)

Parameters

knownFaceEncodings IEnumerable<FaceInfo>

An enumerable collection of known face encodings.

faceEncodingToCheck FaceInfo

A single face encoding to compare against the enumerable collection.

tolerance double

The distance between faces to consider it a match. Lower is more strict. The default value is 0.6.

Returns

List<bool>

An enumerable collection of True/False values indicating which known face encodings match the face encoding to check.

Exceptions

ArgumentNullException

knownFaceEncodings or faceEncodingToCheck is null.

ObjectDisposedException

faceEncodingToCheck is disposed. Or knownFaceEncodings contains disposed object.

CompareFaces(IEnumerable<FaceEncoding>, IEnumerable<FaceEncoding>, double)

Compare an enumerable collection of face encodings against a candidate encoding to see if they match.

public static List<bool> CompareFaces(IEnumerable<FaceEncoding> knownFaceEncodings, IEnumerable<FaceEncoding> faceEncodingsToCheck, double tolerance = 0.6)

Parameters

knownFaceEncodings IEnumerable<FaceEncoding>

An enumerable collection of known face encodings.

faceEncodingsToCheck IEnumerable<FaceEncoding>

A enumerable collection of face encoding to compare against the enumerable collection.

tolerance double

The distance between faces to consider it a match. Lower is more strict. The default value is 0.6.

Returns

List<bool>

An enumerable collection of True/False values indicating which known face encodings match the face encoding to check.

Exceptions

ArgumentNullException

knownFaceEncodings or faceEncodingToCheck is null.

ObjectDisposedException

faceEncodingToCheck is disposed. Or knownFaceEncodings contains disposed object.

CompareFaces(IEnumerable<FaceInfo>, IEnumerable<FaceInfo>, double)

Compare an enumerable collection of face encodings against a candidate encoding to see if they match.

public static List<bool> CompareFaces(IEnumerable<FaceInfo> knownFaceEncodings, IEnumerable<FaceInfo> faceEncodingsToCheck, double tolerance = 0.6)

Parameters

knownFaceEncodings IEnumerable<FaceInfo>

An enumerable collection of known face encodings.

faceEncodingsToCheck IEnumerable<FaceInfo>

A enumerable collection of face encoding to compare against the enumerable collection.

tolerance double

The distance between faces to consider it a match. Lower is more strict. The default value is 0.6.

Returns

List<bool>

An enumerable collection of True/False values indicating which known face encodings match the face encoding to check.

Exceptions

ArgumentNullException

knownFaceEncodings or faceEncodingToCheck is null.

ObjectDisposedException

faceEncodingToCheck is disposed. Or knownFaceEncodings contains disposed object.

Create(string)

Create a new instance of the FaceRecognitionDotNet.FaceRecognition class.

public static FaceRecognition Create(string directory)

Parameters

directory string

The directory path that stores model files.

Returns

FaceRecognition

Exceptions

FileNotFoundException

The model file is not found.

DirectoryNotFoundException

The specified directory path is not found.

Create(ModelParameter)

Create a new instance of the FaceRecognitionDotNet.FaceRecognition class.

public static FaceRecognition Create(ModelParameter parameter)

Parameters

parameter ModelParameter

The instance that contains model binary datum.

Returns

FaceRecognition

Exceptions

ArgumentNullException

parameter is null.

NullReferenceException

The model data is null.

CropFaces(Image, IEnumerable<Location>)

Crop a specified image with enumerable collection of face locations.

public static IEnumerable<Image> CropFaces(Image image, IEnumerable<Location> locations)

Parameters

image Image

The image contains a face.

locations IEnumerable<Location>

The enumerable collection of location rectangle for faces.

Returns

IEnumerable<Image>

Exceptions

ArgumentNullException

image or locations is null.

ObjectDisposedException

image is disposed.

DisposeUnmanaged()

Releases all unmanaged resources.

protected override void DisposeUnmanaged()

EyeBlinkDetect(IDictionary<FacePart, IEnumerable<FacePoint>>, out bool, out bool)

Detects the values whether human eye's blink or not from face landmark.

public void EyeBlinkDetect(IDictionary<FacePart, IEnumerable<FacePoint>> landmark, out bool leftBlink, out bool rightBlink)

Parameters

landmark IDictionary<FacePart, IEnumerable<FacePoint>>

The dictionary of face parts locations (eyes, nose, etc).

leftBlink bool

When this method returns, contains true, if the left eye blinks; otherwise, false.

rightBlink bool

When this method returns, contains true, if the right eye blinks; otherwise, false.

Exceptions

ArgumentNullException

landmark is null.

ArgumentException

landmark does not contain FaceRecognitionDotNet.FacePart.LeftEye or FaceRecognitionDotNet.FacePart.RightEye.

NotSupportedException

The custom eye blink detector is not ready.

ObjectDisposedException

This object or custom eye blink detector is disposed.

FaceDistance(FaceEncoding, FaceEncoding)

Compare a face encoding to a known face encoding and get a euclidean distance for comparison face.

public static double FaceDistance(FaceEncoding faceEncoding, FaceEncoding faceToCompare)

Parameters

faceEncoding FaceEncoding

The face encoding to compare.

faceToCompare FaceEncoding

The face encoding to compare against.

Returns

double

The euclidean distance for comparison face. If 0, faces are completely equal.

Exceptions

ArgumentNullException

faceEncoding or faceToCompare is null.

ObjectDisposedException

faceEncoding or faceToCompare is disposed.

FaceDistances(IEnumerable<FaceEncoding>, FaceEncoding)

Compare an enumerable collection of face encoding to a known face encoding and get an enumerable collection of euclidean distance for comparison face.

public static IEnumerable<double> FaceDistances(IEnumerable<FaceEncoding> faceEncodings, FaceEncoding faceToCompare)

Parameters

faceEncodings IEnumerable<FaceEncoding>

The enumerable collection of face encoding to compare.

faceToCompare FaceEncoding

The face encoding to compare against.

Returns

IEnumerable<double>

The enumerable collection of euclidean distance for comparison face. If 0, faces are completely equal.

Exceptions

ArgumentNullException

faceEncodings or faceToCompare is null.

ObjectDisposedException

faceToCompare is disposed. Or faceEncodings contains disposed object.

FaceEncodings(Image, IEnumerable<Location>, int, PredictorModel, Model)

Returns an enumerable collection of face feature data corresponds to all faces in specified image.

public IEnumerable<FaceEncoding> FaceEncodings(Image image, IEnumerable<Location> knownFaceLocation = null, int numJitters = 1, PredictorModel predictorModel = PredictorModel.Small, Model model = Model.Hog)

Parameters

image Image

The image contains faces. The image can contain multiple faces.

knownFaceLocation IEnumerable<Location>

The enumerable collection of location rectangle for faces. If specified null, method will find face locations.

numJitters int

The number of times to re-sample the face when calculating encoding.

predictorModel PredictorModel

The dimension of vector which be returned from detector.

model Model

The model of face detector to detect in image. If knownFaceLocation is not null, this value is ignored.

Returns

IEnumerable<FaceEncoding>

An enumerable collection of face feature data corresponds to all faces in specified image.

Exceptions

ArgumentNullException

image is null.

InvalidOperationException

knownFaceLocation contains no elements.

ObjectDisposedException

image or this object or custom face landmark detector is disposed.

NotSupportedException

FaceRecognitionDotNet.PredictorModel.Custom is not supported.

FaceLandmark(Image, IEnumerable<Location>, PredictorModel, Model)

Returns an enumerable collection of dictionary of face parts locations (eyes, nose, etc) for each face in the image.

public IEnumerable<IDictionary<FacePart, IEnumerable<FacePoint>>> FaceLandmark(Image faceImage, IEnumerable<Location> faceLocations = null, PredictorModel predictorModel = PredictorModel.Large, Model model = Model.Hog)

Parameters

faceImage Image

The image contains faces. The image can contain multiple faces.

faceLocations IEnumerable<Location>

The enumerable collection of location rectangle for faces. If specified null, method will find face locations.

predictorModel PredictorModel

The dimension of vector which be returned from detector.

model Model

The model of face detector to detect in image. If faceLocations is not null, this value is ignored.

Returns

IEnumerable<IDictionary<FacePart, IEnumerable<FacePoint>>>

An enumerable collection of dictionary of face parts locations (eyes, nose, etc).

Exceptions

ArgumentNullException

faceImage is null.

InvalidOperationException

faceLocations contains no elements.

ObjectDisposedException

faceImage or this object or custom face landmark detector is disposed.

NotSupportedException

The custom face landmark detector is not ready.

FaceLocations(Image, int, Model)

Returns an enumerable collection of face location correspond to all faces in specified image.

public IEnumerable<Location> FaceLocations(Image image, int numberOfTimesToUpsample = 1, Model model = Model.Hog)

Parameters

image Image

The image contains faces. The image can contain multiple faces.

numberOfTimesToUpsample int

The number of times to up-sample the image when finding faces.

model Model

The model of face detector to detect in image.

Returns

IEnumerable<Location>

An enumerable collection of face location correspond to all faces in specified image.

Exceptions

ArgumentNullException

image is null.

ObjectDisposedException

image or this object is disposed.

LoadFaceEncoding(double[])

Creates an FaceRecognitionDotNet.FaceEncoding from the Double array.

public static FaceEncoding LoadFaceEncoding(double[] encoding)

Parameters

encoding double[]

The Double array contains face encoding data.

Returns

FaceEncoding

The FaceRecognitionDotNet.FaceEncoding this method creates.

Exceptions

ArgumentNullException

encoding is null.

ArgumentOutOfRangeException

encoding must be 128.

LoadImage(Bitmap)

Creates an FaceRecognitionDotNet.Image from the specified existing bitmap image.

public static Image LoadImage(Bitmap bitmap)

Parameters

bitmap Bitmap

The Bitmap from which to create the new FaceRecognitionDotNet.Image.

Returns

Image

The FaceRecognitionDotNet.Image this method creates.

Exceptions

ArgumentNullException

bitmap is null.

ArgumentOutOfRangeException

The specified PixelFormat is not supported.

LoadImage(byte[], int, int, int, Mode)

Creates an FaceRecognitionDotNet.Image from the Byte array.

public static Image LoadImage(byte[] array, int row, int column, int stride, Mode mode)

Parameters

array byte[]

The Byte array contains image data.

row int

The number of rows in a image data.

column int

The number of columns in a image data.

stride int

The stride width in bytes.

mode Mode

A image color mode.

Returns

Image

The FaceRecognitionDotNet.Image this method creates.

Exceptions

ArgumentNullException

array is null.

ArgumentOutOfRangeException

row is less than 0.

ArgumentOutOfRangeException

column is less than 0.

ArgumentOutOfRangeException

stride is less than 0.

ArgumentOutOfRangeException

stride is less than column.

ArgumentOutOfRangeException

row x stride is less than Length.

LoadImage(nint, int, int, int, Mode)

Creates an FaceRecognitionDotNet.Image from the unmanaged memory pointer indicates Byte array image data.

public static Image LoadImage(nint array, int row, int column, int stride, Mode mode)

Parameters

array nint

The unmanaged memory pointer indicates Byte array image data.

row int

The number of rows in a image data.

column int

The number of columns in a image data.

stride int

The stride width in bytes.

mode Mode

A image color mode.

Returns

Image

The FaceRecognitionDotNet.Image this method creates.

Exceptions

ArgumentException

array is Zero.

ArgumentOutOfRangeException

row is less than 0.

ArgumentOutOfRangeException

column is less than 0.

ArgumentOutOfRangeException

stride is less than 0.

ArgumentOutOfRangeException

stride is less than column.

LoadImageFile(string, Mode)

Creates an FaceRecognitionDotNet.Image from the specified path.

public static Image LoadImageFile(string file, Mode mode = Mode.Rgb)

Parameters

file string

A string that contains the path of the file from which to create the FaceRecognitionDotNet.Image.

mode Mode

A image color mode.

Returns

Image

The FaceRecognitionDotNet.Image this method creates.

Exceptions

FileNotFoundException

The specified path does not exist.

PredictAge(Image, Location)

Returns an index of age group of face image correspond to specified location in specified image.

public uint PredictAge(Image image, Location location)

Parameters

image Image

The image contains a face.

location Location

The location rectangle for a face.

Returns

uint

An index of age group of face image correspond to specified location in specified image.

Exceptions

ArgumentNullException

image or location is null.

ObjectDisposedException

image or this object or custom age estimator is disposed.

NotSupportedException

The custom age estimator is not ready.

PredictEmotion(Image, Location)

Returns an emotion of face image correspond to specified location in specified image.

public string PredictEmotion(Image image, Location location)

Parameters

image Image

The image contains a face.

location Location

The location rectangle for a face.

Returns

string

An emotion of face image correspond to specified location in specified image.

Exceptions

ArgumentNullException

image or location is null.

ObjectDisposedException

image or this object or custom emotion estimator is disposed.

NotSupportedException

The custom emotion estimator is not ready.

PredictGender(Image, Location)

Returns an gender of face image correspond to specified location in specified image.

public Gender PredictGender(Image image, Location location)

Parameters

image Image

The image contains a face.

location Location

The location rectangle for a face.

Returns

Gender

An gender of face image correspond to specified location in specified image.

Exceptions

ArgumentNullException

image or location is null.

ObjectDisposedException

image or this object or custom gender estimator is disposed.

NotSupportedException

The custom gender estimator is not ready.

PredictHeadPose(IDictionary<FacePart, IEnumerable<FacePoint>>)

Returns a head pose estimated from face parts locations.

public HeadPose PredictHeadPose(IDictionary<FacePart, IEnumerable<FacePoint>> landmark)

Parameters

landmark IDictionary<FacePart, IEnumerable<FacePoint>>

The dictionary of face parts locations (eyes, nose, etc).

Returns

HeadPose

A head pose estimated from face parts locations.

Exceptions

ArgumentNullException

landmark is null.

ObjectDisposedException

This object or custom head pose estimator is disposed.

NotSupportedException

The custom head pose estimator is not ready.

PredictProbabilityAge(Image, Location)

Returns probabilities of age group of face image correspond to specified location in specified image.

public IDictionary<uint, float> PredictProbabilityAge(Image image, Location location)

Parameters

image Image

The image contains a face.

location Location

The location rectangle for a face.

Returns

IDictionary<uint, float>

Probabilities of age group of face image correspond to specified location in specified image.

Exceptions

ArgumentNullException

image or location is null.

ObjectDisposedException

image or this object or custom age estimator is disposed.

NotSupportedException

The custom age estimator is not ready.

PredictProbabilityEmotion(Image, Location)

Returns probabilities of emotion of face image correspond to specified location in specified image.

public IDictionary<string, float> PredictProbabilityEmotion(Image image, Location location)

Parameters

image Image

The image contains a face.

location Location

The location rectangle for a face.

Returns

IDictionary<string, float>

Probabilities of emotion of face image correspond to specified location in specified image.

Exceptions

ArgumentNullException

image or location is null.

ObjectDisposedException

image or this object or custom emotion estimator is disposed.

NotSupportedException

The custom emotion estimator is not ready.

PredictProbabilityGender(Image, Location)

Returns probabilities of gender of face image correspond to specified location in specified image.

public IDictionary<Gender, float> PredictProbabilityGender(Image image, Location location)

Parameters

image Image

The image contains a face.

location Location

The location rectangle for a face.

Returns

IDictionary<Gender, float>

Probabilities of gender of face image correspond to specified location in specified image.

Exceptions

ArgumentNullException

image or location is null.

ObjectDisposedException

image or this object or custom gender estimator is disposed.

NotSupportedException

The custom gender estimator is not ready.