This article explains how to add more than one face image to an existing identity.


Method 1 - Merging Identities

To add a new face image to existing identity, use following two properties:

  • URL Param: mergeWith=<person ID to add face image to>
  • Header: X-RPC-FACES-GROUPING-THRESHOLD=0


You must first find an identity that matches the face image you want to upload and get the person Id of that existing identity.  Then you will call POST /people API with the new face image and specify both query parameters above in order to add the new face image as a new identity and then merge the two identities.  This is the method used by SAFR Desktop.


Note: This behavior creates TWO DIFFERENT identities and then links to two into a parent/child relationship.  In the SAFR People Window, it will appear as one identity with faces nested underneath it.  One of the identities is set as the "root" identity with the rootPersonId.  This is the face that appears at the top of the list.


It is also possible to merge two already existing identities.  Use the PUT /merge or PUT /mergerecursive APIs to perform this action.  You will need the list of personIds to be merged and the rootPersonId to merge them into.


Note: COVI REST API has a merge query parameter.   This query parameter provides a method to automatically merge identities but was developed specifically for the RealTimes photo grouping consumer service and is not supported in SAFR.  This query parameter should be ignored for SAFR use cases

 

Method 2 - Adding or updating faces to existing identity

Merge Identities vs. Adding Faces to Identity


As mentioned, the mergeWith query parameter above can combine two identities into a single.  To the merged Identities appear as a single entry in the Person Window but are returned as 2 separate records in the REST APIs, each having their own metadata (all but the root person record is ignored).


An alternative is to have a single person identity with multiple face images.  This technique stores a single person record and multiple face images within that record.  REST APIs will only return a single rootPersonId.  The Person window still displays multiple faces in the person record just like with separate merged faces.


Number of face images per person

By default, SAFR stores only 1 face image per person.  Any updates to the person's face image will replace the existing image. You can instruct SAFR to store more face images and control if SAFR users those face images for recognition using the following properties.


  • person.max.representative.face.candidates - How many faces SAFR will keep for each identity.
  • person.max.representative.face.count - How many faces SAFR will use for recognition for each identity.


By default, both of these is 1.  These are set in application.properties for covi configuration.  The files are located in C:\Program Files\RealNetworks\SAFR\covi\app\config\covi or /opt/RealNetworks/SAFR/covi/app/config/covi.


As an example, lets say you have the following set:

  • person.max.representative.face.candidates - How many faces SAFR will keep for each identity.
  • person.max.representative.face.count - How many faces SAFR will use for recognition for each identity.  If more face images are present, only the best quality will be used for matching.


Adding or Updating Faces on Identity

A new query parameter (update-person-id) was added with SAFR release 3.9 in Feb 2022.  It can be used for SAFR use cases to add faces to an existing identity.


update-person-id with just one face in identity

If a person.max.representative.face.candidates=1, then update-person-id will result in replacing the face image for that identity if the new face image meets the minimum image quality thresholds (min-cpq, min-fsq, etc).  


Note: When using the update-person-id, the update-if-lower-quality is ignored and the new images is always added even if it is lower quality than one of the existing images.  The minimum image quality thresholds are still respected though and the new face image will be reject if it does not meet the minimum quality thresholds.

update-person-id with just one face in identity

If a person.max.representative.face.candidate


update-person-id with multiple faces in identity

If a person.max.representative.face.candidate > 1, the update-person-id will result in replacing the lowest quality image from the existing face images.  The new face image must still pass the minimum quality thresholds but the image will be added even if it is lower quality than the lowest quality face image already in the identity.


Use case:

Your company maintains a watchlist outside of SAFR and you want to use SAFR REST APis to synchronize that watchlist into SAFR identity database. Because you are using REST APIs, you cannot benefit from the merge options provided in the import face workflow with SAFR Desktop.


Solution: 

  1. In application.properties in covi set the following:
    person.max.representative.face.candidates=3
  2. Use update-person-id query parameter


The update-person-id will add faces until it reaches the max representative faces.  Then it will replace the lowest quality face with the new face if the new face (as long as new face is above quality thresholds)


Note: SAFR Clients may still add faces above the person.max.representative.face.candidates setting.  The server-side setting is only meant for use for automatic server-side merging.


Replace Face Image

A special case of above is to call POST /people?update-person-id=<pseron_id> with default value for person.max.representative.face.candidates of 1.    In this case the update-person-id will result in either replacing the image (if better quality) or ignoring the request.  Response to the API should indicate if changes were made through the accountUpdated JSON property to know which action was taken.