Class FaceRecognition

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

Inheritance

System.Object

DisposableObject

FaceRecognition

Implements

System.IDisposable

Inherited Members

DisposableObject.IsDisposed

DisposableObject.ThrowIfDisposed()

DisposableObject.DisposeManaged()

DisposableObject.Dispose()

System.Object.ToString()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

Namespace: FaceRecognitionDotNet

Assembly: FaceRecognitionDotNet.dll

Syntax

public sealed class FaceRecognition : DisposableObject, IDisposable

Properties

CustomAgeEstimator

Gets or sets the custom age estimator that user defined.

Declaration

public AgeEstimator CustomAgeEstimator { get; set; }

Property Value

Type	Description
AgeEstimator

CustomEmotionEstimator

Gets or sets the custom emotion estimator that user defined.

Declaration

public EmotionEstimator CustomEmotionEstimator { get; set; }

Property Value

Type	Description
EmotionEstimator

CustomEyeBlinkDetector

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

Declaration

public EyeBlinkDetector CustomEyeBlinkDetector { get; set; }

Property Value

Type	Description
EyeBlinkDetector

CustomFaceDetector

Gets or sets the custom face detector that user defined.

Declaration

public FaceDetector CustomFaceDetector { get; set; }

Property Value

Type	Description
FaceDetector

CustomFaceLandmarkDetector

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

Declaration

public FaceLandmarkDetector CustomFaceLandmarkDetector { get; set; }

Property Value

Type	Description
FaceLandmarkDetector

CustomGenderEstimator

Gets or sets the custom gender estimator that user defined.

Declaration

public GenderEstimator CustomGenderEstimator { get; set; }

Property Value

Type	Description
GenderEstimator

CustomHeadPoseEstimator

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

Declaration

public HeadPoseEstimator CustomHeadPoseEstimator { get; set; }

Property Value

Type	Description
HeadPoseEstimator

InternalEncoding

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

Declaration

public static Encoding InternalEncoding { get; set; }

Property Value

Type	Description
System.Text.Encoding

Methods

BatchFaceLocations(IEnumerable<Image>, Int32, Int32)

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

Declaration

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

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<Image>	images	An enumerable collection of images.
System.Int32	numberOfTimesToUpsample	The number of image looking for faces. Higher numbers find smaller faces.
System.Int32	batchSize	The number of images to include in each GPU processing batch.

Returns

Type	Description
System.Collections.Generic.IEnumerable<Location[]>	An enumerable collection of array of found face locations.

Exceptions

Type	Condition
System.ArgumentNullException	images is null.

CompareFace(FaceEncoding, FaceEncoding, Double)

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

Declaration

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

Parameters

Type	Name	Description
FaceEncoding	knownFaceEncoding	A known face encodings.
FaceEncoding	faceEncodingToCheck	A single face encoding to compare against a known face encoding.
System.Double	tolerance	The distance between faces to consider it a match. Lower is more strict. The default value is 0.6.

Returns

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

Exceptions

Type	Condition
System.ArgumentNullException	knownFaceEncoding or faceEncodingToCheck is null.
System.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.

Declaration

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

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<FaceEncoding>	knownFaceEncodings	An enumerable collection of known face encodings.
FaceEncoding	faceEncodingToCheck	A single face encoding to compare against the enumerable collection.
System.Double	tolerance	The distance between faces to consider it a match. Lower is more strict. The default value is 0.6.

Returns

Type	Description
System.Collections.Generic.IEnumerable<System.Boolean>	An enumerable collection of True/False values indicating which known face encodings match the face encoding to check.

Exceptions

Type	Condition
System.ArgumentNullException	knownFaceEncodings or faceEncodingToCheck is null.
System.ObjectDisposedException	faceEncodingToCheck is disposed. Or knownFaceEncodings contains disposed object.

Create(ModelParameter)

Create a new instance of the FaceRecognition class.

Declaration

public static FaceRecognition Create(ModelParameter parameter)

Parameters

Type	Name	Description
ModelParameter	parameter	The instance that contains model binary datum.

Returns

Type	Description
FaceRecognition

Exceptions

Type	Condition
System.ArgumentNullException	parameter is null.
System.NullReferenceException	The model data is null.

Create(String)

Create a new instance of the FaceRecognition class.

Declaration

public static FaceRecognition Create(string directory)

Parameters

Type	Name	Description
System.String	directory	The directory path that stores model files.

Returns

Type	Description
FaceRecognition

Exceptions

Type	Condition
System.IO.FileNotFoundException	The model file is not found.
System.IO.DirectoryNotFoundException	The specified directory path is not found.

CropFaces(Image, IEnumerable<Location>)

Crop a specified image with enumerable collection of face locations.

Declaration

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

Parameters

Type	Name	Description
Image	image	The image contains a face.
System.Collections.Generic.IEnumerable<Location>	locations	The enumerable collection of location rectangle for faces.

Returns

Type	Description
System.Collections.Generic.IEnumerable<Image>

Exceptions

Type	Condition
System.ArgumentNullException	image or locations is null.
System.ObjectDisposedException	image is disposed.

DisposeUnmanaged()

Releases all unmanaged resources.

Declaration

protected override void DisposeUnmanaged()

Overrides

DisposableObject.DisposeUnmanaged()

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

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

Declaration

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

Parameters

Type	Name	Description
System.Collections.Generic.IDictionary<FacePart, System.Collections.Generic.IEnumerable<FacePoint>>	landmark	The dictionary of face parts locations (eyes, nose, etc).
System.Boolean	leftBlink	When this method returns, contains true, if the left eye blinks; otherwise, false.
System.Boolean	rightBlink	When this method returns, contains true, if the right eye blinks; otherwise, false.

Exceptions

Type	Condition
System.ArgumentNullException	landmark is null.
System.ArgumentException	landmark does not contain LeftEye or RightEye.
System.NotSupportedException	The custom eye blink detector is not ready.
System.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.

Declaration

public static double FaceDistance(FaceEncoding faceEncoding, FaceEncoding faceToCompare)

Parameters

Type	Name	Description
FaceEncoding	faceEncoding	The face encoding to compare.
FaceEncoding	faceToCompare	The face encoding to compare against.

Returns

Type	Description
System.Double	The euclidean distance for comparison face. If 0, faces are completely equal.

Exceptions

Type	Condition
System.ArgumentNullException	faceEncoding or faceToCompare is null.
System.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.

Declaration

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

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<FaceEncoding>	faceEncodings	The enumerable collection of face encoding to compare.
FaceEncoding	faceToCompare	The face encoding to compare against.

Returns

Type	Description
System.Collections.Generic.IEnumerable<System.Double>	The enumerable collection of euclidean distance for comparison face. If 0, faces are completely equal.

Exceptions

Type	Condition
System.ArgumentNullException	faceEncodings or faceToCompare is null.
System.ObjectDisposedException	faceToCompare is disposed. Or faceEncodings contains disposed object.

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

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

Declaration

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

Parameters

Type	Name	Description
Image	image	The image contains faces. The image can contain multiple faces.
System.Collections.Generic.IEnumerable<Location>	knownFaceLocation	The enumerable collection of location rectangle for faces. If specified null, method will find face locations.
System.Int32	numJitters	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

Type	Description
System.Collections.Generic.IEnumerable<FaceEncoding>	An enumerable collection of face feature data corresponds to all faces in specified image.

Exceptions

Type	Condition
System.ArgumentNullException	image is null.
System.InvalidOperationException	knownFaceLocation contains no elements.
System.ObjectDisposedException	image or this object or custom face landmark detector is disposed.
System.NotSupportedException	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.

Declaration

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

Parameters

Type	Name	Description
Image	faceImage	The image contains faces. The image can contain multiple faces.
System.Collections.Generic.IEnumerable<Location>	faceLocations	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

Type	Description
System.Collections.Generic.IEnumerable<System.Collections.Generic.IDictionary<FacePart, System.Collections.Generic.IEnumerable<FacePoint>>>	An enumerable collection of dictionary of face parts locations (eyes, nose, etc).

Exceptions

Type	Condition
System.ArgumentNullException	faceImage is null.
System.InvalidOperationException	faceLocations contains no elements.
System.ObjectDisposedException	faceImage or this object or custom face landmark detector is disposed.
System.NotSupportedException	The custom face landmark detector is not ready.

FaceLocations(Image, Int32, Model)

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

Declaration

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

Parameters

Type	Name	Description
Image	image	The image contains faces. The image can contain multiple faces.
System.Int32	numberOfTimesToUpsample	The number of times to up-sample the image when finding faces.
Model	model	The model of face detector to detect in image.

Returns

Type	Description
System.Collections.Generic.IEnumerable<Location>	An enumerable collection of face location correspond to all faces in specified image.

Exceptions

Type	Condition
System.ArgumentNullException	image is null.
System.ObjectDisposedException	image or this object is disposed.

LoadFaceEncoding(Double[])

Creates an FaceEncoding from the System.Double array.

Declaration

public static FaceEncoding LoadFaceEncoding(double[] encoding)

Parameters

Type	Name	Description
System.Double[]	encoding	The System.Double array contains face encoding data.

Returns

Type	Description
FaceEncoding	The FaceEncoding this method creates.

Exceptions

Type	Condition
System.ArgumentNullException	encoding is null.
System.ArgumentOutOfRangeException	encoding must be 128.

LoadImage(Byte[], Int32, Int32, Int32, Mode)

Creates an Image from the System.Byte array.

Declaration

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

Parameters

Type	Name	Description
System.Byte[]	array	The System.Byte array contains image data.
System.Int32	row	The number of rows in a image data.
System.Int32	column	The number of columns in a image data.
System.Int32	stride	The stride width in bytes.
Mode	mode	A image color mode.

Returns

Type	Description
Image	The Image this method creates.

Exceptions

Type	Condition
System.ArgumentNullException	array is null.
System.ArgumentOutOfRangeException	row is less than 0.
System.ArgumentOutOfRangeException	column is less than 0.
System.ArgumentOutOfRangeException	stride is less than 0.
System.ArgumentOutOfRangeException	stride is less than column.
System.ArgumentOutOfRangeException	row x stride is less than System.Array.Length.

LoadImage(Bitmap)

Creates an Image from the specified existing bitmap image.

Declaration

public static Image LoadImage(Bitmap bitmap)

Parameters

Type	Name	Description
System.Drawing.Bitmap	bitmap	The System.Drawing.Bitmap from which to create the new Image.

Returns

Type	Description
Image	The Image this method creates.

Exceptions

Type	Condition
System.ArgumentNullException	bitmap is null.
System.ArgumentOutOfRangeException	The specified System.Drawing.Imaging.PixelFormat is not supported.

LoadImage(IntPtr, Int32, Int32, Int32, Mode)

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

Declaration

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

Parameters

Type	Name	Description
System.IntPtr	array	The unmanaged memory pointer indicates System.Byte array image data.
System.Int32	row	The number of rows in a image data.
System.Int32	column	The number of columns in a image data.
System.Int32	stride	The stride width in bytes.
Mode	mode	A image color mode.

Returns

Type	Description
Image	The Image this method creates.

Exceptions

Type	Condition
System.ArgumentException	array is System.IntPtr.Zero.
System.ArgumentOutOfRangeException	row is less than 0.
System.ArgumentOutOfRangeException	column is less than 0.
System.ArgumentOutOfRangeException	stride is less than 0.
System.ArgumentOutOfRangeException	stride is less than column.

LoadImageFile(String, Mode)

Creates an Image from the specified path.

Declaration

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

Parameters

Type	Name	Description
System.String	file	A string that contains the path of the file from which to create the Image.
Mode	mode	A image color mode.

Returns

Type	Description
Image	The Image this method creates.

Exceptions

Type	Condition
System.IO.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.

Declaration

public uint PredictAge(Image image, Location location)

Parameters

Type	Name	Description
Image	image	The image contains a face.
Location	location	The location rectangle for a face.

Returns

Type	Description
System.UInt32	An index of age group of face image correspond to specified location in specified image.

Exceptions

Type	Condition
System.ArgumentNullException	image or location is null.
System.ObjectDisposedException	image or this object or custom age estimator is disposed.
System.NotSupportedException	The custom age estimator is not ready.

PredictEmotion(Image, Location)

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

Declaration

public string PredictEmotion(Image image, Location location)

Parameters

Type	Name	Description
Image	image	The image contains a face.
Location	location	The location rectangle for a face.

Returns

Type	Description
System.String	An emotion of face image correspond to specified location in specified image.

Exceptions

Type	Condition
System.ArgumentNullException	image or location is null.
System.ObjectDisposedException	image or this object or custom emotion estimator is disposed.
System.NotSupportedException	The custom emotion estimator is not ready.

PredictGender(Image, Location)

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

Declaration

public Gender PredictGender(Image image, Location location)

Parameters

Type	Name	Description
Image	image	The image contains a face.
Location	location	The location rectangle for a face.

Returns

Type	Description
Gender	An gender of face image correspond to specified location in specified image.

Exceptions

Type	Condition
System.ArgumentNullException	image or location is null.
System.ObjectDisposedException	image or this object or custom gender estimator is disposed.
System.NotSupportedException	The custom gender estimator is not ready.

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

Returns a head pose estimated from face parts locations.

Declaration

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

Parameters

Type	Name	Description
System.Collections.Generic.IDictionary<FacePart, System.Collections.Generic.IEnumerable<FacePoint>>	landmark	The dictionary of face parts locations (eyes, nose, etc).

Returns

Type	Description
HeadPose	A head pose estimated from face parts locations.

Exceptions

Type	Condition
System.ArgumentNullException	landmark is null.
System.ObjectDisposedException	This object or custom head pose estimator is disposed.
System.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.

Declaration

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

Parameters

Type	Name	Description
Image	image	The image contains a face.
Location	location	The location rectangle for a face.

Returns

Type	Description
System.Collections.Generic.IDictionary<System.UInt32, System.Single>	Probabilities of age group of face image correspond to specified location in specified image.

Exceptions

Type	Condition
System.ArgumentNullException	image or location is null.
System.ObjectDisposedException	image or this object or custom age estimator is disposed.
System.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.

Declaration

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

Parameters

Type	Name	Description
Image	image	The image contains a face.
Location	location	The location rectangle for a face.

Returns

Type	Description
System.Collections.Generic.IDictionary<System.String, System.Single>	Probabilities of emotion of face image correspond to specified location in specified image.

Exceptions

Type	Condition
System.ArgumentNullException	image or location is null.
System.ObjectDisposedException	image or this object or custom emotion estimator is disposed.
System.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.

Declaration

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

Parameters

Type	Name	Description
Image	image	The image contains a face.
Location	location	The location rectangle for a face.

Returns

Type	Description
System.Collections.Generic.IDictionary<Gender, System.Single>	Probabilities of gender of face image correspond to specified location in specified image.

Exceptions

Type	Condition
System.ArgumentNullException	image or location is null.
System.ObjectDisposedException	image or this object or custom gender estimator is disposed.
System.NotSupportedException	The custom gender estimator is not ready.

Implements

System.IDisposable