Table of Contents

Class FrameEmbeddingIndex

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

An in-memory index of per-frame CLIP embeddings used for semantic video search. Each entry stores a frame's presentation timestamp, the source tag it came from, and the embedding vector produced by a VideoEmbeddingBlock. A query embedding (for example the CLIP text embedding of a natural-language phrase) is matched by cosine similarity and the closest frames are returned. The index is thread-safe and can be persisted to and loaded from disk.

public sealed class FrameEmbeddingIndex

Inheritance

Inherited Members

Remarks

All embeddings in one index must share the same dimension (the same CLIP model); adding a vector of a different length throws. Cosine similarity is computed by normalizing both the stored vector and the query, so raw (unnormalized) vectors are matched correctly as well; embeddings produced by the block are already L2-normalized. The on-disk format is a compact binary layout with a 'VFEI' magic header and a version number so a future format change is detectable.

Properties

Count

Gets the number of indexed frame embeddings.

public int Count { get; }

Property Value

int

Dimension

Gets the embedding dimension shared by every vector in the index, or 0 when the index is empty.

public int Dimension { get; }

Property Value

int

Methods

Add(TimeSpan, string, float[])

Adds a frame embedding to the index. The first embedding added fixes the index dimension; every later embedding must match it.

public void Add(TimeSpan timestamp, string sourceTag, float[] embedding)

Parameters

timestamp TimeSpan

The presentation timestamp of the frame within its source.

sourceTag string

The source tag to associate with the frame (for example a file name). May be null.

embedding float[]

The frame embedding vector. Must not be null or empty. A copy is stored.

Exceptions

ArgumentException

Thrown when embedding is null/empty or its length differs from the index dimension.

Clear()

Removes all indexed embeddings and resets the index dimension.

public void Clear()

Load(string)

Loads the index 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 index file.

Save(string)

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

public void Save(string path)

Parameters

path string

The destination file path.

Exceptions

ArgumentException

Thrown when path is null or empty.

Search(float[], int)

Finds the frames whose embeddings are most similar to a query embedding by cosine similarity, highest first.

public FrameEmbeddingSearchResult[] Search(float[] query, int topK)

Parameters

query float[]

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

topK int

The maximum number of results to return. Values > the entry count return every entry.

Returns

FrameEmbeddingSearchResult[]

The top matches sorted by descending cosine similarity; an empty array when the index is empty, the query is null/empty or its length differs from the index dimension, or topK is not positive.