Face search

In addition to real-time matching of detected face against faces stored in watchlists, SmartFace is also capable to search in all detected faces stored by SmartFace from all real-time camera streams or all offline video files processed by Rapid Video Processing.

The SmartFace Face Search feature is provided by SmartFace Face Matcher service. This service keeps all available face templates in the memory for the best search performance. The list of face templates is constantly updated with new face templates from camera streams and offline video processing.

Face search processing#

Face search request#

To perform Face Search on all detected faces you need to make a face matching request through REST API via endpoint: /api/v1/Faces/Search

Example of search request:

{
  "image": {
    "data": "base64 encoded image"
  },
  "threshold": 40,
  "faceDetectorConfig": {
    "minFaceSize": 30,
    "maxFaceSize": 500,
    "confidenceThreshold": 600
  },
  "faceDetectorResourceId": "cpu", 			// "cpu" or "gpu" or "accurate_cpu" or "accurate_gpu"
  "templateGeneratorResourceId": "cpu" 		// "cpu" or "gpu"
}

Example of search response:

{
  "searchSessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

The response contains SearchSessionId which can be used to query data via GraphQL API.

All match results are stored in the database, and each search request will create:

• SearchSession object in database, which identifies each search by its searchSessionId.

• SearchSessionObject for each matched face above requested threshold

Querying face search results#

Only GraphQL can be used to query for results of face search functionality. You can either traverse SearchSessionObjects and its linked Faces or vice versa.

Example of GraphQL query:

query {
  faces (where: { searchSessionObjects: { some: { searchSessionId: { eq:"3fa85f64-5717-4562-b3fc-2c963f66afa6"}}}}) {
    items {
      imageDataId
      age      
      gender
      createdAt
    }
  }
}

Deleting face search results data#

The face search feature can produce large amounts of SearchSessionObjects data, which can lead to reduced performance when querying data.

You can setup cleanup process of this data by making request through REST API via endpoint: /api/v1/Setup/SearchSessionsCleanup

Example of search results cleanup process configuration request:

{
  "enabled": true,
  "maxItemsCount": 100000000,
  "maxSessionAge": "7.00:00:00",
  "interval": "01:00:00"
}

Face search HW requirements#

The Face Matcher service keeps all available face templates in the memory for the best search performance. If you have a long history of detected faces in the database from many high-traffic cameras, you need to consider allocating special HW resources just to run this service.

Memory footprint of Face Matcher#

Reference measurements:

Example: If your face database contains e.g. 10,000,000 faces, you have to count with 15 GB of memory for loaded templates and +20% increase in memory during search requests.

Initial loading time#

It will take approximately 3.5 minutes to initially load 1 million face templates from the database into Face Matcher if the database is on the same server as the service itself. Increase of the loading time is linear with increasing number of faces.

Example: If your face database contains e.g. 10,000,000 faces, initial load time will be 35 minutes.

Search time#

Final duration of the face search consist from two times:

• matching time - in memory match of all loaded templates with uploaded face

• results insert time - time of inserting SearchSessionObjects into the database

Matching time on 1 million face templates in memory is approximately 500 ms.

Results insert time depend on number of results what need to be inserted, database access speed and available HW.

Reference measurements:

Example: If your face database contains e.g. 10,000,000 faces, and you will have 1% matches (~ 100,000) you can calculate the search time:
Search Time = Matching time + Result Insert Time = 0.5s * 10 + 2s = approx. 7 seconds

Cleanup process time#

Reference measurements: