Outline

web/apps/photos/src/services/face/db.ts

@@ -0,0 +1,27 @@
+/**
+ * The faces in a file (and an embedding for each of them).
+ *
+ * This interface describes the format of both local and remote face data.
+ *
+ * - 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), stored in the local
+ *   IndexedDB ("face/db") and also uploaded (E2EE) to remote.
+ *
+ * - Remote embeddings are 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 FaceIndex} interface.
+ *
+ * It has a top level envelope with information about the client (in particular
+ * the primary key {@link fileID}), an inner envelope {@link faceEmbedding} with
+ * metadata about the indexing, and an array of {@link faces} each containing
+ * the result of a face detection and an embedding for that detected face.
+ *
+ * This 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) like a "clipEmbedding".
+ */
+export interface FaceIndex {}