diff --git a/web/packages/new/photos/services/ml/face.ts b/web/packages/new/photos/services/ml/face.ts index 8e944b3980..463a217fb5 100644 --- a/web/packages/new/photos/services/ml/face.ts +++ b/web/packages/new/photos/services/ml/face.ts @@ -36,34 +36,37 @@ export const faceIndexingVersion = 1; /** * The faces in a file (and an embedding for each of them). * - * This interface describes the format of remote face related data (aka "face - * index") for a file. See {@link LocalFaceIndex} for the subset of the fields - * that we also persist locally. + * This interface describes the format of face related data (aka "face index") + * for a file. This is the common subset that is present in both the fields that + * are persisted on remote ({@link RemoteFaceIndex}) and locally + * ({@link LocalFaceIndex}). * - * - Local face detections and embeddings (collectively called as the face - * index) are generated by the current client when uploading a file, or when - * noticing a file which doesn't yet have a face index. They are then uploaded - * (E2EE) to remote, and the relevant bits also saved locally in the ML DB for + * - Face detections and embeddings (collectively called as the face index) are + * generated by the current client when uploading a file, or when noticing a + * file which doesn't yet have a face index. They are then uploaded (E2EE) to + * remote, and the relevant bits also saved locally in the ML DB for * subsequent lookup or clustering. * - * - Remote embeddings are fetched by subsequent clients to avoid them having to - * reindex (indexing faces is a costly operation, esp. for mobile clients). + * - This face index is then fetched by subsequent clients to avoid them having + * to reindex (indexing faces is a costly operation, esp. for mobile clients). * * In both these scenarios (whether generated locally or fetched from remote), - * we end up with an face index described by this {@link RemoteFaceIndex} - * interface. We slightly prune this when saving it to the local DB, and code - * that runs locally only has access to the {@link LocalFaceIndex}. - * - * It has a top level envelope with information about the file (in particular - * the primary key {@link fileID}), an inner envelope {@link faceEmbedding} with - * metadata about the indexing, and an . - * - * The word embedding is used to refer two things: The last one (faceEmbedding > - * faces > embedding) is the "actual" embedding, but sometimes we colloquially - * refer to the inner envelope (the "faceEmbedding") also an embedding since a - * file can have other types of embedding (envelopes), e.g. a "clipEmbedding". + * we end up with an some data described by this {@link FaceIndex} interface. We + * modify it slightly, adding envelopes, when saving them locally or uploading + * them to remote - those variations are described by the {@link LocalFaceIndex} + * and {@link RemoteFaceIndex} types respectively. */ -export interface RemoteFaceIndex { +export interface FaceIndex { + /** + * The list of faces (and their embeddings) detected in the file. + * + * Each of the items is a {@link Face}, containing the result of a face + * detection, and an embedding for that detected face. + */ + faces: Face[]; +} + +export type RemoteFaceIndex = FaceIndex & { /** * An integral version number of the indexing algorithm / pipeline. * @@ -76,20 +79,9 @@ export interface RemoteFaceIndex { * The UA for the client which generated this embedding. */ client: string; - /** - * The list of faces (and their embeddings) detected in the file. - * - * Each of the items is a {@link Face}, containing the result of a face - * detection, and an embedding for that detected face. - */ - faces: Face[]; -} +}; -/** - * A pruned version of {@link RemoteFaceIndex} with data and shape that are - * suitable for local persistence and usage. - */ -export type LocalFaceIndex = Omit & { +export type LocalFaceIndex = FaceIndex & { /** * The ID of the {@link EnteFile} whose index this is. *