Outline 2

web/packages/new/photos/services/ml/cluster-new.ts

@@ -23,12 +23,23 @@ export interface Cluster {
  *
  * The person is the user visible concept. It consists of a set of clusters,
  * each of which itself is a set of faces.
+ *
+ * For ease of transportation, the Person entity on remote looks like
+ *
+ *     { name, clusters: { cluster_id, face_ids }}
+ *
+ * That is, it has the clusters embedded within itself.
  */
 export interface Person {
     /** A unique nanoid to identify this person. */
     id: string;
+    /**
+     * An optional name assigned by the user to this person.
+     */
+    name: string | undefined;
     /**
      * An unordered set of ids of the clusters that belong to this person.
+     *
      * For ergonomics of transportation and persistence this is an array but it
      * should conceptually be thought of as a set.
      */
@@ -40,9 +51,19 @@ export interface Person {
  *
  * [Note: Face clustering algorithm]
  *
- * 1. clusters = []
- * 2. For each face, find its nearest neighbour in the embedding space. If no
- *    such neighbour is found within our threshold, create a new c
+ * 1.  clusters = []
+ * 2.  For each face, find its nearest neighbour in the embedding space. If no
+ *     such neighbour is found within our threshold, create a new cluster.
+ * 3.  Otherwise assign this face to the same cluster as its nearest neighbour.
+ *
+ * [Note: Face clustering feedback]
+ *
+ * This user can tweak the output of the algorithm by providing feedback. They
+ * can perform the following actions:
+ *
+ * 1.  Move a cluster from one person to another.
+ * 2.  Break a cluster.
+ *
  */
 export const clusterFaces = (faceIndices: FaceIndex[]) => {
     log.debug(() => ["Clustering", faceIndices]);