Documentation

.NET API Reference

Namespace

Realeyes.FaceVerification

Classes

FaceVerifier

Main entry point for face detection, embedding, and verification operations. Implements IDisposable.

Constructor

public FaceVerifier(string modelPath, int maxConcurrency = 0)

Creates a new FaceVerifier instance.

Parameter Type Description Default
modelPath string Path to the .realZ model file —
maxConcurrency int Maximum concurrency. 0 for automatic (all cores) 0

Throws:

  • ArgumentNullException — when modelPath is null
  • FaceVerificationException — when model loading fails

Properties

Property Type Description
ConcurrentCalculations int Number of calculations currently running concurrently (read-only)
ModelName string Name/version of the loaded model (read-only)
SdkVersion Version SDK version (read-only, static)
SdkVersionString string SDK version as a string (read-only, static)

Methods

DetectFacesAsync
public Task<FaceList> DetectFacesAsync(ImageHeader imageHeader)

Detects faces in an image asynchronously.

Parameter Type Description
imageHeader ImageHeader Image to process

Returns: Task<FaceList> — disposable collection of detected faces.

Throws: FaceVerificationException — when detection fails.

EmbedFaceAsync
public Task<float[]> EmbedFaceAsync(Face face)

Computes the embedding vector for a detected face asynchronously.

Parameter Type Description
face Face Previously detected face

Returns: Task<float[]> — embedding vector.

Throws:

  • ArgumentNullException — when face is null
  • FaceVerificationException — when embedding fails
CompareFaces
public Match CompareFaces(float[] embedding1, float[] embedding2)

Compares two face embeddings and returns a similarity score.

Parameter Type Description
embedding1 float[] First face embedding
embedding2 float[] Second face embedding

Returns: Match — match result with similarity score.

Throws:

  • ArgumentNullException — when either embedding is null
  • ArgumentException — when embeddings have different lengths
Dispose
public void Dispose()

Disposes the FaceVerifier and releases native resources.

FaceList

A disposable collection of Face objects that automatically disposes all faces when disposed. Inherits from List<Face> and implements IDisposable and IAsyncDisposable.

Methods

Dispose
public void Dispose()

Disposes all Face objects in the collection synchronously.

DisposeAsync
public ValueTask DisposeAsync()

Disposes all Face objects in the collection asynchronously.

Face

Represents a detected face with landmarks, bounding box, and quality information. Implements IDisposable.

Constructor

public Face(ImageHeader imageHeader, Point2d[] landmarks, BoundingBox boundingBox, float confidence)

Creates a Face object from a third-party face detector.

Parameter Type Description
imageHeader ImageHeader Image containing the face
landmarks Point2d[] Face landmarks (exactly 5 points)
boundingBox BoundingBox Bounding box of the face
confidence float Detection confidence score

Throws:

  • ArgumentNullException — when imageHeader or landmarks is null
  • ArgumentException — when landmarks count is not exactly 5
  • FaceVerificationException — when face creation fails

Properties

Property Type Description
DetectionQuality DetectionQuality Detection quality of this face (read-only)
BoundingBox BoundingBox Bounding box of this face (read-only)
Confidence float Detection confidence score (read-only)

Methods

GetLandmarks
public Point2d[] GetLandmarks()

Gets the facial landmarks.

Returns: Point2d[] — array of 5 landmark points.

Clone
public Face Clone()

Creates a copy of this face.

Returns: Face — a new Face instance with the same data.

Dispose
public void Dispose()

Disposes the face and releases native resources.

Data Types

ImageHeader

Image descriptor for passing image data to the Face Verification Library. (readonly record struct)

Constructor

public ImageHeader(byte[] Data, int Width, int Height, int Stride, ImageFormat Format)
Parameter Type Description
Data byte[] Image data bytes
Width int Width in pixels
Height int Height in pixels
Stride int Length of one row in bytes (e.g., 3 * width + padding)
Format ImageFormat Pixel format

Throws:

  • ArgumentNullException — when Data is null
  • ArgumentOutOfRangeException — when Width, Height, or Stride is not positive

Properties

Property Type Description
Data byte[] Image data bytes (read-only)
Width int Width of the image in pixels (read-only)
Height int Height of the image in pixels (read-only)
Stride int Length of one row of pixels in bytes (read-only)
Format ImageFormat Image pixel format (read-only)

BoundingBox

Bounding box representing a rectangular region. (readonly record struct)

Constructor

public BoundingBox(int X, int Y, int Width, int Height)
Parameter Type Description
X int X coordinate of the top-left corner
Y int Y coordinate of the top-left corner
Width int Width of the bounding box
Height int Height of the bounding box

Properties

Property Type Description
X int X coordinate of the top-left corner (read-only)
Y int Y coordinate of the top-left corner (read-only)
Width int Width of the bounding box (read-only)
Height int Height of the bounding box (read-only)
Right int Right edge X coordinate (X + Width) (read-only)
Bottom int Bottom edge Y coordinate (Y + Height) (read-only)
Area int Area of the bounding box (Width * Height) (read-only)

Point2d

2D point representing a landmark coordinate. (readonly record struct)

Constructor

public Point2d(float X, float Y)
Parameter Type Description
X float X coordinate
Y float Y coordinate

Properties

Property Type Description
X float X coordinate (read-only)
Y float Y coordinate (read-only)

Match

Result of face comparison indicating similarity. (readonly record struct)

Constructor

public Match(float Similarity)
Parameter Type Description
Similarity float Similarity score

Properties

Property Type Description
Similarity float Similarity score (read-only)

Methods

ExceedsThreshold
public bool ExceedsThreshold(float threshold)

Checks if the similarity score exceeds a threshold.

Parameter Type Description
threshold float Similarity threshold

Returns: bool — true if Similarity >= threshold.

Version

Semantic version number. (readonly record struct)

Constructor

public Version(int Major, int Minor, int Patch)
Parameter Type Description
Major int Major version number
Minor int Minor version number
Patch int Patch version number

Properties

Property Type Description
Major int Major version number (read-only)
Minor int Minor version number (read-only)
Patch int Patch version number (read-only)

Methods

ToString
public override string ToString()

Returns: string — version in "Major.Minor.Patch" format.

Enumerations

ImageFormat

Image pixel format.

Value Int Description
Grayscale 0 8-bit grayscale
RGB 1 24-bit RGB
RGBA 2 32-bit RGBA or RGB with padding
BGR 3 24-bit BGR
BGRA 4 32-bit BGRA or BGR with padding

DetectionQuality

Detection quality indicator.

Value Int Description
Good 0 No issues detected
BadQuality 1 Bad quality detected
MaybeRolled 2 Face may be rolled; embeddings could be incorrect

Exceptions

FaceVerificationException

Exception thrown when Face Verification Library operations fail. Inherits from Exception.

Constructors

public FaceVerificationException()
public FaceVerificationException(string message)
public FaceVerificationException(string message, Exception innerException)
Parameter Type Description
message string Error message
innerException Exception Inner exception