Table of Contents

Class FaceGallery

Namespace
VisioForge.Core.Types.X.AI
Assembly
VisioForge.Core.dll

An in-memory gallery of enrolled face identities used for 1:N face recognition. Each identity holds one or more L2-normalized face embeddings; a query embedding is matched by cosine similarity (the maximum over all stored embeddings of all identities). The gallery is thread-safe and can be persisted to and loaded from disk.

public sealed class FaceGallery

Inheritance

Inherited Members

Remarks

Embeddings are produced by a face recognizer; use a recognition block's enrollment API (for example FaceRecognitionBlock.Enroll), which computes and stores the embedding for you. All embeddings in one gallery must share the same dimension (the same embedding model); enrolling a vector of a different length throws. Switching the embedding model requires a separate gallery.

Properties

Count

Gets the number of enrolled identities.

public int Count { get; }

Property Value

int

Methods

Add(string, float[])

Adds an embedding for the given identity. Multiple embeddings can be enrolled per identity (for example from several photos) to improve robustness. The embedding is L2-normalized before storage.

public void Add(string name, float[] embedding)

Parameters

name string

The identity name. Must not be null or empty.

embedding float[]

The face embedding vector. Must not be null or empty and must have a non-zero magnitude.

Exceptions

ArgumentException

Thrown when name is null/empty, embedding is null/empty or has zero magnitude, or its length differs from the embeddings already in the gallery (a different embedding model).

Clear()

Removes all enrolled identities.

public void Clear()

GetNames()

Gets the names of the enrolled identities.

public string[] GetNames()

Returns

string[]

A snapshot array of the enrolled identity names.

Identify(float[], float, out float)

Finds the best-matching identity for a query embedding by cosine similarity.

public string Identify(float[] embedding, float threshold, out float score)

Parameters

embedding float[]

The query embedding (any magnitude; it is normalized internally).

threshold float

The minimum cosine similarity to report a match.

score float

Receives the best cosine similarity found (even if below the threshold), or 0 when the gallery is empty.

Returns

string

The best-matching identity name when its score meets threshold; otherwise null.

Load(string)

Loads the gallery from a binary file, replacing the current contents.

public void Load(string path)

Parameters

path string

The source file path.

Exceptions

FileNotFoundException

Thrown when the file does not exist.

InvalidDataException

Thrown when the file is not a valid gallery file.

Remove(string)

Removes all embeddings of the given identity.

public bool Remove(string name)

Parameters

name string

The identity name.

Returns

bool

true if the identity existed and was removed; otherwise, false.

Save(string)

Saves the gallery to a binary file. Overwrites an existing file.

public void Save(string path)

Parameters

path string

The destination file path.