Integration with Remote Facial Recognition Systems

You can integrate your FindFace CIBR instance with remote facial recognition systems. In this case, the server known as a puppeteer will be pushing records designated for remote alerting to remote servers known as puppets. In return, it will be receiving recognition events matching with those records. You can set up a daily search that allows the puppeteer to receive scheduled events.

This functionality has a large scope of possible applications. One course is tracking offenders’ location and routes and detecting alleged accomplices. Another one is finding missing people. The results are especially great if applied to Public and Transport Safety systems with thousands of cameras.

The current version supports only integration with facial recognition systems from the FindFace family.

In this section:

Sync Schedule
Configure Puppeteer
Configure Puppet

Sync Schedule 

The data between a puppeteer and a puppet are synced in the following way:

The puppeteer delivers designated records to the puppet with an interval specified in the REMOTE_MONITORING_SYNC_INTERVAL parameter (see configuration below).
The puppet delivers matching recognition events to the puppeteer as soon as they appear.

Configure Puppeteer 

To configure your FindFace CIBR instance to be a puppeteer, do the following:

Open the /opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py configuration file. Make sure that the EXTERNAL_ADDRESS parameter is filled.
```
sudo vi /opt/findface-cibr/configs/findface-multi-legacy/findface-multi-legacy.py

EXTERNAL_ADDRESS = 'http://192.168.0.4'
```
Note

The value of EXTERNAL_ADDRESS is defined during deployment.

Find the Puppeteer section.

# ============== Puppeteer ===============
# INSTALLED_APPS.append('ffsecurity_puppeteer')

# PUPPETEER_CONFIG = {
#     'UNSAVED_RESULTS_DELETION_TIMEOUT': 3600,        # maximum lifetime of search results not saved involuntarily
#     'REMOTE_MONITORING_SYNC_INTERVAL': 600,          # monitoring data synchronization interval, seconds
#     'REMOTE_MONITORING_EVENTS_MAX_AGE': 30*24*60*60, # monitoring events older than this number of seconds will be
#                                                      # automatically deleted (every night at 1:17 am by default)
#     'ENABLE_WATCH_LISTS_MONITORING': False,
#     'DAILY_SEARCH_PUSH_HOUR': 2,                     # daily search cards synchronization hour
#     'DAILY_SEARCH_PULL_HOUR': 6,                     # hour in which results of daily search will be obtained
#     'DAILY_SEARCH_EVENTS_MAX_AGE': 0,                # daily search events older than this number of seconds will be
#                                                      # automatically deleted (every night at 1:17 am by default)
#     'DAILY_SEARCH_EVENTS_FULLFRAME_MAX_AGE': 30*24*60*60,  # daily search events fullframes
#                                                      # older than this number of seconds will be
#                                                      # automatically deleted (every night at 1:17 am by default)
#     'puppets': [
#         {
#             'id': 'first_puppet',                    # puppet ID
#             'url': 'http://1.1.1.1:8010/',           # puppet URL
#             'token': 'first_puppet_token',           # use pwgen -s 64 1 (should match the token in puppet)
#             'facen_model': 'mango_320'           # face model in puppet
#         },
#         {
#             'id': 'second_puppet',
#             'url': 'http://1.1.1.1:8010/',
#             'token': 'second_puppet_token',
#
#              # if remote installation has a different face model than the one used in FFSecurity -
#              # you need to specify its name and ExtractionAPI URL where the corresponding face model is specified
#              # other settings like detector, normalizer and other should be set as puppeteer's ExtractionAPI
#              # contact support for details
#             'facen_model': 'grapefruit_480',
#             'extractor': 'http://127.0.0.1:18667',
#         },
#     ]
# }
#

Uncomment the section as shown in the example below and specify the following parameters:

REMOTE_MONITORING_SYNC_INTERVAL: interval in seconds with which the puppeteer sends designated records to a puppet.
REMOTE_MONITORING_EVENTS_MAX_AGE: remote alerts older than this number of days will be automatically deleted on the puppeteer (every night at 1:17 a.m. by default).
puppets → id: a puppet ID.
puppets → url: IP address and port of a puppet’s principal server.

Specify the port as follows:
- Leave the default port as is if the puppet represents a public or transport safety system (i.e., it has the public-security service at its core).
- Switch the default port to 80 or do not specify it at all if the puppet is based on the findface-security service (i.e., with FindFace Security or FindFace Multi installed).
puppets → token: token for mutual authentication between the puppeteer and a puppet.
Tip

Use the following command to generate a random token.
```
pwgen -s 64 1
```
puppets → facen_model: neural network model used on a puppet for face recognition.
puppets → extractor: IP address and port of the biometric data extraction service on a puppet if the neural network model for face recognition on the puppet differs from that on the puppeteer.

Leave other parameters in the section commented out.

# ============== Puppeteer ===============
INSTALLED_APPS.append('ffsecurity_puppeteer')

PUPPETEER_CONFIG = {
#     'UNSAVED_RESULTS_DELETION_TIMEOUT': 3600,        # maximum lifetime of search results not saved involuntarily
     'REMOTE_MONITORING_SYNC_INTERVAL': 600,          # monitoring data synchronization interval, seconds
     'REMOTE_MONITORING_EVENTS_MAX_AGE': 30*24*60*60, # monitoring events older than this number of seconds will be
#                                                      # automatically deleted (every night at 1:17 am by default)
#     'ENABLE_WATCH_LISTS_MONITORING': False,
#     'DAILY_SEARCH_PUSH_HOUR': 2,                     # daily search cards synchronization hour
#     'DAILY_SEARCH_PULL_HOUR': 6,                     # hour in which results of daily search will be obtained
#     'DAILY_SEARCH_EVENTS_MAX_AGE': 0,                # daily search events older than this number of seconds will be
#                                                      # automatically deleted (every night at 1:17 am by default)
#     'DAILY_SEARCH_EVENTS_FULLFRAME_MAX_AGE': 30*24*60*60,  # daily search events fullframes
#                                                      # older than this number of seconds will be
#                                                      # automatically deleted (every night at 1:17 am by default)
     'puppets': [
         {
             'id': 'first_puppet',                    # puppet ID
             'url': 'http://1.1.1.1:8010/',           # puppet URL
             'token': 'first_puppet_token',           # use pwgen -s 64 1 (should match the token in puppet)
             'facen_model': 'mango_320'           # face model in puppet
         },
         {
             'id': 'second_puppet',
             'url': 'http://1.1.1.1:8010/',
             'token': 'second_puppet_token',

#              # if remote installation has a different face model than the one used in FFSecurity -
#              # you need to specify its name and ExtractionAPI URL where the corresponding face model is specified
#              # other settings like detector, normalizer and other should be set as puppeteer's ExtractionAPI
#              # contact support for details
             'facen_model': 'grapefruit_480',
             'extractor': 'http://127.0.0.1:18667',
         },
     ]
 }

The daily search is enabled in FindFace CIBR 2.1.2.1 by default. If necessary, set the schedule for sending records to the puppet and receiving events that matched the records that have been sent by uncommenting and setting the following parameters:
```
PUPPETEER_CONFIG = {
    ...
    'DAILY_SEARCH_PUSH_HOUR': 2,                     # daily search cards synchronization hour
    'DAILY_SEARCH_PULL_HOUR': 6,                     # hour in which results of daily search will be obtained
    ...
```
Navigate to the Watch list tab and check Collect location data for the watch list of your interest.

If necessary, enable daily search cleanup by uncommenting the following parameters:

PUPPETEER_CONFIG = {
    ...
    'DAILY_SEARCH_EVENTS_MAX_AGE': 0,                # daily search events older than this number of seconds will be
                                                     # automatically deleted (every night at 1:17 am by default)
    'DAILY_SEARCH_EVENTS_FULLFRAME_MAX_AGE': 30*24*60*60,  # daily search events fullframes
                                                     # older than this number of seconds will be
                                                     # automatically deleted (every night at 1:17 am by default)
    ...

'DAILY_SEARCH_EVENTS_MAX_AGE': 0: the duration (in seconds) of storing location data of the object of interest. By default, 0, permanent storage.
'DAILY_SEARCH_EVENTS_FULLFRAME_MAX_AGE': 30*24*60*60: the storage duration (in seconds) of full frames of daily search events obtained from the puppets. By default, 30*24*60*60 seconds (30 days). Change 30 to the desired number of days. if needed.

Note

You can manually remove location data of the object and full frames of daily search events older than the given number of seconds by executing the commands below.

To set the number of seconds to remove location data of the object, use the --daily-search-events-max-age argument.

sudo docker exec findface-cibr-findface-multi-legacy-1 /opt/findface-security/bin/python3 /tigre_prototype/manage.py cleanup --daily-search-events-max-age 1

To remove full frames of daily search events obtained from the puppets older than 5 days (5*24*60*60 = 432000 seconds), use --daily-search-events-fullframe-max-age argument.

sudo docker exec findface-cibr-findface-multi-legacy-1 /opt/findface-security/bin/python3 /tigre_prototype/manage.py cleanup --daily-search-events-fullframe-max-age 432000

Restart the findface-cibr-findface-multi-legacy-singleton-services-1 and findface-cibr-findface-multi-legacy-1 containers.

sudo docker container restart findface-cibr-findface-multi-legacy-singleton-services-1 findface-cibr-findface-multi-legacy-1

Configure Puppet 

To configure a remote FindFace Multi 2.0+ instance to be a puppet, do the following:

Open the /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py configuration file. Make sure that the EXTERNAL_ADDRESS parameter is filled.
```
sudo vi /opt/findface-multi/configs/findface-multi-legacy/findface-multi-legacy.py

EXTERNAL_ADDRESS = 'http://192.168.0.5'
```

Find the Vns section.

# ================= Vns ==================
# A plugin for using FindFace Security as a puppeteer server
# increasing CONCURRENCY might speedup remote monitoring
# INSTALLED_APPS.append('ffsecurity_vns')

# VNS_CONFIG = {
#     'USERS': {
#         'user1': 'token1',
#         'user2': 'token2'
#     },
#     'MONITORING_THRESHOLD': 0.75,
#     'DAILY': {
#         'ENABLED': False,
#         'THRESHOLD': 0.75,
#         'START_TIME': "00:00:00"
#     },
#     'CONCURRENCY': 5,
# }

Uncomment the section as shown in the example below and specify the following parameters:

token: token for mutual authentication between the puppet and a puppeteer. You can specify several users and tokens if the puppet is communicating with several puppeteers. You can leave the user names as is.
MONITORING_THRESHOLD: confidence threshold in face recognition events sent to a puppeteer.

Leave other parameters in the section commented out.

# ================= Vns ==================
# A plugin for using FindFace Security as a puppeteer server
# increasing CONCURRENCY might speedup remote monitoring
INSTALLED_APPS.append('ffsecurity_vns')

VNS_CONFIG = {
     'USERS': {
         'user1': 'token1',
         'user2': 'token2'
     },
     'MONITORING_THRESHOLD': 0.75,
#     'DAILY': {
#         'ENABLED': False,
#         'THRESHOLD': 0.75,
#         'START_TIME': "00:00:00"
#     },
#     'CONCURRENCY': 5,
 }

If you have enabled the daily search in the Puppeteer (see step #4 above), uncomment and enable 'DAILY' parameters. Specify the time for matching the events with the records that were received from the puppeteer.

# ================= Vns ==================
# A plugin for using FindFace Security as a puppeteer server
# increasing CONCURRENCY might speedup remote monitoring
INSTALLED_APPS.append('ffsecurity_vns')

VNS_CONFIG = {
...
     'DAILY': {
         'ENABLED': True,
         'THRESHOLD': 0.75,
         'START_TIME': "00:00:00"
     },
#     'CONCURRENCY': 5,
 }

If the event stream of the puppet is too large, you could increase the CONCURRENCY value, which will speed up remote monitoring.
- CONCURRENCY: this is the number of asynchronous tasks that will perform event matching to the monitoring gallery on the puppet. The default value is 5.

Restart all FindFace Multi containers.

cd /opt/findface-multi/

sudo docker-compose restart

To configure a remote FindFace Multi instance version 1.2 and early to be a puppet, do the following:

Open the /etc/findface-security/config.py configuration file. Make sure that the EXTERNAL_ADDRESS parameter is filled.
```
sudo vi /etc/findface-security/config.py

EXTERNAL_ADDRESS = 'http://192.168.0.5'
```
Find the Vns section.
Uncomment the section as shown in the example and specify token and MONITORING_THRESHOLD parameters.
If you have enabled the daily search in the Puppeteer, uncomment and enable 'DAILY' parameters. Specify the time for matching the events with the records that were received from the puppeteer.

Restart the findface-security service.

sudo systemctl restart findface-security.service

Perform migration to sync with puppeteers.
```
sudo findface-security migrate
```

Integration with Remote Facial Recognition Systems

Sync Schedule

Configure Puppeteer

Configure Puppet

Sync Schedule 

Configure Puppeteer 

Configure Puppet 