findface-security

The findface-security component serves as a gateway to the FindFace core. It provides interaction between the FindFace Core and the web interface, the system functioning as a whole, HTTP and web socket (along with Django), database update, and webhooks.

The findface-security component also performs the functions of findface-facerouter (part of the FindFace Core), setting processing directives for detected faces. It accepts a face bbox and normalized image along with the original image and other data (for example, the detection date and time) from the findface-video-worker service and redirect them to findface-sf-api for further processing.

The findface-security configuration is done through the /etc/findface-security/config.py configuration file.

sudo vi /etc/findface-security/config.py

# ==============================================================================
# FindFace Security configuration file
# ==============================================================================
#
# This config file is written in Python's syntax and interpreted at FindFace Security
# service startup. You have to restart the service in order to apply changes.
#
# If you have any questions or suggestions, please contact us at [email protected]


# ==============================================================================
# GENERAL SETTINGS
# ==============================================================================

# enables additional logs
DEBUG = False

# media files directory
MEDIA_ROOT = "/var/lib/findface-security/uploads"

# static files directory
STATIC_ROOT = "/var/lib/findface-security/static"

# language code
LANGUAGE_CODE = 'en-us'

# time zone
TIME_ZONE = 'UTC'

# Database is used by FindFace Security to store cameras,
# camera groups, watchlists and so on. Only PostgreSQL is supported.
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'DISABLE_SERVER_SIDE_CURSORS': True,
        'NAME': 'ffsecurity',
        'PORT': 5439, 'USER': 'ntech', 'PASSWORD': 'g3PNKWnh6EABpxiYqWp9Lsw9hmPLwknQ'
    }
}

# Signature key for session encryption
# Use pwgen -sncy 50 1|tr "'" "." to generate your own unique key
SECRET_KEY = '2d294d1fbc7c0bf76e26e718b5f2eacf'

# ==============================================================================
# FINDFACE SECURITY SETTINGS
# ==============================================================================

# SERVICE_EXTERNAL_ADDRESS is prioritized for FFSecurity webhooks and Genetec plugin.
# EXTERNAL_ADDRESS is used instead if SERVICE_EXTERNAL_ADDRESS is not provided.
# You must provide either SERVICE_EXTERNAL_ADDRESS or EXTERNAL_ADDRESS in order
# to be able to work with FFSecurity webhooks and Genetec plugin.
SERVICE_EXTERNAL_ADDRESS = 'http://172.20.77.117'

# EXTERNAL_ADDRESS is used to access objects created inside FFSecurity via external links.
EXTERNAL_ADDRESS = ''

# - Base FFSecurity settings -

# enable permissions system
ENABLE_ACL = True

FFSECURITY = {
    # findface-video-worker authorization token
    'VIDEO_DETECTOR_TOKEN': '0b600a94fe39c73e681a5f0da917efd0',

    # base face matching confidence threshold
    'CONFIDENCE_THRESHOLD': 0.739,

    # episodes specific matching threshold that is used to join faces in an episode
    'EPISODES_THRESHOLD': 0.689,

    # minimum face quality sufficient to add it to a dossier
    'MINIMUM_DOSSIER_QUALITY': 0.45,

    # do not save unmatched events (GDPR support)
    'IGNORE_UNMATCHED': False,

    # blur all unmatched faces on the full frame of the matched event (GDPR support)
    'BLUR_UNMATCHED_FACES': False,

    # full frame jpeg quality when `BLUR_UNMATCHED_FACES` is enabled
    'BLURRED_FULLFRAME_JPEG_QUALITY': 85,

    # matched events older than EVENTS_MAX_MATCHED_AGE will be automatically
    # deleted (every night at 1:17 am by default)
    'EVENTS_MAX_MATCHED_AGE': 0,

    # same as above but for unmatched events
    'EVENTS_MAX_UNMATCHED_AGE': 30,

    # same as EVENTS_MAX_MATCHED_AGE but for matched full frame images only (thumbnails won't be deleted)
    'EVENTS_MAX_FULLFRAME_UNMATCHED_AGE': 30,

    # same as above but for unmatched full frame images only (thumbnails won't be deleted)
    'EVENTS_MAX_FULLFRAME_MATCHED_AGE': 30,

    # same as above but for counter records
    'COUNTER_RECORDS_MAX_AGE': 30,

    # same as above but for person events (if no person events left in person, it is deleted too)
    'PERSON_EVENTS_MAX_AGE': 90,

    # when closing episode, delete all events except the best episode event
    'EPISODE_KEEP_ONLY_BEST_EVENT': False,

    # NTLS licence server url
    'NTLS_HTTP_URL': 'http://127.0.0.1:3185',

    # findface-video-worker face posting address,
    # it must be set to either FFSecurity EXTERNAL_ADDRESS (by default)
    # or findface-facerouter url (in some specific cases)
    'ROUTER_URL': 'http://127.0.0.1',

    # send serialized dossiers, dossier-lists, camera and camera groups in webhooks
    'VERBOSE_WEBHOOKS': False,

    # jpeg quality used when saving thumbnails
    'THUMBNAIL_JPEG_QUALITY': 75,

    # FFServer services urls
    'VIDEO_MANAGER_ADDRESS': 'http://127.0.0.1:18810',
    'SF_API_ADDRESS': 'http://127.0.0.1:18411',
    'FFCOUNTER_ADDRESS': 'http://127.0.0.1:18300',

    # upload video archives to this path, it differs from media root and
    # you have to change alias in corresponding nginx location also (/videos/)
    'VIDEO_ARCHIVE_UPLOAD_PATH': '/var/lib/findface-security/uploads/videos/',

    # additional events features.
    # make sure that corresponding extractors
    # are licensed and enabled at findface-extraction-api config file.
    # available features are: gender, age, emotions, beard, glasses, medmask.
    'EVENTS_FEATURES': [],

    # feature specific confidence thresholds
    'LIVENESS_THRESHOLD': 0.75,
    'EMOTIONS_THRESHOLD': 0.25,
    'BEARD_THRESHOLD': 0.7,

    # counters full frame saving options:
    # `always` - save always
    # `detect` - save only if faces or silhouettes have been detected
    # `never` - never save full frames
    'COUNTERS_SAVE_FULLFRAME': 'always',
    'COUNTERS_FULLFRAME_JPEG_QUALITY': 75,
    'COUNTERS_THUMBNAIL_JPEG_QUALITY': 75,

    # max camera frames_dropped percent
    'MAX_CAMERA_DROPPED_FRAMES': {'yellow': 0.1, 'red': 0.3},
    # max camera faces_failed percent
    'MAX_CAMERA_FAILED_FACES': {'yellow': 0.1, 'red': 0.3},

    # -- Persons configuration --

    # rrule (recurrence rule) for scheduling persons clusterization
    # WARNING: all scheduling works with UTC time and NOT aware of any timezone
    'PERSONS_CLUSTERIZATION_SCHEDULE': 'RRULE:FREQ=DAILY;INTERVAL=1;WKST=MO;BYHOUR=0;BYMINUTE=0',

    # face to person matching confidence threshold
    'PERSONS_CONFIDENCE_THRESHOLD': 0.739,

    # minimum required face quality for person creation
    'PERSON_EVENT_MIN_QUALITY': 0.45,
    # minimum required number events in episode for person creation
    'PERSON_EVENT_MIN_EPISODE_EVENTS': 1,

    # maximum concurrent video manager jobs for video archives processing
    'MAX_VIDEO_ARCHIVE_JOBS': 3,

    # reports image saving options
    'REPORT_THUMBNAIL_JPEG_QUALITY': 75,
    'REPORT_THUMBNAIL_MAX_HEIGHT': 100,
    'REPORT_FULLFRAME_JPEG_QUALITY': 75,
    'REPORT_FULLFRAME_MAX_HEIGHT': 250,

    # -- Optional parameters --

    # Edit CUSTOM_FIELDS->dossier_meta section to customize dossier content.
    # Below is an example for integration FindFace Security with Sigur.

    # Edit CUSTOM_FIELDS->dossier_face section to customize dossier face content.
    # Below is an example with every field type possible.

    # 'CUSTOM_FIELDS': {
    #     'dossier_meta': {
    #         'items': [
    #             {
    #                 'name': 'personid',
    #                 'default': '',
    #                 'label': 'PersonID',
    #                 'display': ['list', 'form'],
    #                 'description': 'Sigur person ID'
    #             },
    #             {
    #                 'name': 'firstname',
    #                 'default': '',
    #                 'label': 'First Name',
    #                 'display': ['list', 'form'],
    #                 'description': 'Sigur first name'
    #             },
    #             {
    #                 'name': 'lastname',
    #                 'default': '',
    #                 'label': 'Last Name',
    #                 'display': ['list', 'form'],
    #                 'description': 'Sigur last name'
    #             },
    #             {
    #                 'name': 'version',
    #                 'default': '',
    #                 'label': 'Version',
    #                 'display': ['list', 'form'],
    #                 'description': 'Sigur photo version'
    #             }
    #         ],
    #         'filters': [
    #             {
    #                 'name': 'personid',
    #                 'label': 'Sigur person ID filter',
    #                 'field': 'personid'
    #             }
    #         ]
    #     },
    #     'dossier_face': {
    #         'items': [
    #             {
    #                 "field_name": "tag_name_1",
    #                 "type": "string",
    #                 "default": "change_me"
    #             },
    #             {
    #                 "field_name": "tag_name_2",
    #                 "type": "uint",
    #                 "default": 123
    #             },
    #             {
    #                 "field_name": "tag_name_3",
    #                 "type": "bool",
    #                 "default": True
    #             },
    #         ]
    #     }
    # },

    # maximum event age in seconds than could be added to an episode.
    # 'EPISODE_SEARCH_INTERVAL': 60,
    # If none of these events matched, new episode is created.

    # maximum episode duration (episode is closed after)
    # 'EPISODE_MAX_DURATION': 300,

    # if no new event added to an episode during this timeout, episode will be closed.
    # 'EPISODE_EVENT_TIMEOUT': 30,

    # maximum created thumbnail width
    # 'THUMBNAIL_MAX_WIDTH': 320,

    # url of the backend which is used for social network search.
    # contact support for additional information.
    # 'SOCIAL_BACKEND': None,

    # additional social backend headers.
    # 'SOCIAL_HEADERS': {},

    # unacknowledged events notification interval
    # 'UNACKNOWLEDGED_NOTIFY_INTERVAL': 1,

    # set to True to run all media requests (photos, attachments) through the
    # django application for acl checks.
    # enabling this setting slightly increases security but
    # has severe negative effects on performance.
    # you will also have to mark /uploads/ location as 'internal' in nginx config
    #
    # 'OVERPROTECT_MEDIA': False,
}

# - FindFace Security user interface configuration dictionary -

FFSECURITY_UI_CONFIG = {
    "event": {
        "features": {
            "f_gender_class": ["male", "female"],
            "age": {
                "f_age_gte": "",
                "f_age_lte": ""
            },
            "f_emotions_class": ["angry", "disgust", "fear", "happy", "sad", "surprise", "neutral"],
            "f_glasses_class": ["none", "eye", "sun"],
            "f_beard_class": ["none", "beard"],
            "f_liveness_class": ["real", "fake"],
            "f_medmask_class": ["none", "incorrect", "correct"],
        }
    },

    # Adjustable confidence threshold presets for face matching.
    # Please consult with our support before changing.
    "confidence_display": [
        {"confidence": 0.00, "color": "#000000", "label": {"ru": "Очень низкий", "en": "Very Low"}},
        {"confidence": 0.65, "color": "#FF0300", "label": {"ru": "Низкий", "en": "Low"}},
        {"confidence": 0.70, "color": "#FFB700", "label": {"ru": "Пониженный", "en": "Slightly Low"}},
        {"confidence": 0.72, "color": "#B8FA00", "label": {"ru": "Нормальный", "en": "Moderate"}},
        {"confidence": 0.75, "color": "#7EFF2B", "label": {"ru": "Повышенный", "en": "Slightly High"}},
        {"confidence": 0.80, "color": "#4DFF60", "label": {"ru": "Высокий", "en": "High"}},
        {"confidence": 0.85, "color": "#1DFF96", "label": {"ru": "Очень высокий", "en": "Very High"}},
    ]
}

# -- ASGI-server configuration --
# consult support before changing these settings.

# per worker thread pool size.
ASGI_THREADS = 32

UVICORN_SETTINGS = {
    # worker processes count, 'auto' sets it to logical cpu count
    'workers': 'auto',
    'host': 'localhost',
    'port': 8002,
    # websocket worker processes count,
    # 'auto' sets it to logical cpu count, but not more than 8.
    'ws-workers': 'auto',
    'ws-host': 'localhost',
    'ws-port': 8003,
}

# disable unused services to increase
# overall system performance in some cases.
SERVICES = {
    "ffsecurity": {
        "episodes": True,
        "webhooks": True,
        # use queue manager to prevent drops of video archive events
        "video_archive_events_manager": True,
        "persons": False,
    }
}

# -- Other settings --

# The number of threads in the night clusterization.
# Not recommended values are greater than the number of cores in the processor.
# Consult with support before changing this value.
NUMPY_OMP_NUM_THREADS = 'auto'


# ==============================================================================
# FINDFACE SECURITY PLUGINS
# ==============================================================================
# Uncomment lines below to enable plugins. Please consult documentation for
# a plugin specific settings.

# =============== Axxon ================
# INSTALLED_APPS.append('ffsecurity_axxon')

# AXXON = [
#     {
#         'name': 'server_name',
#         'api': 'http://example.com/',
#         'rtsp': 'rtsp://example.com:554/',
#         'user': 'user',
#         'password': 'password',
#     }
# ]

# FFSECURITY_UI_CONFIG['dossier'] = {
#    'video': True,
# }


# =============== Genetec ================
# INSTALLED_APPS.append('ffsecurity_genetec')


# ================ Sova ==================
# INSTALLED_APPS.append('ffsecurity_sova')


# ================ Sigur =================
# keep in mind, that SIGUR plugin also uses CUSTOM_FIELDS and THUMBNAIL_MAX_WIDTH settings
# INSTALLED_APPS.append('ffsecurity_sigur')
# SIGUR = {
#     'LOGIN': 'admin',
#     'PASSWORD': 'admin',
#     'MF_SELECTOR': 'biggest',  # what to do with several faces in sigur person photo; allowed ['biggest', 'reject']
#     'ONLY_RT_EVENTS': True,  # only events with bs_type == realtime,
#     'EVENT_DELAY': 0.004 # minimum time between two events of same person in seconds. If interval between two events with same person is less, than this value, second event will be dropped
# }


# ======= CryptoPRO authentication =======
# INSTALLED_APPS.append('ffsecurity_cproauth')
# REST_FRAMEWORK['DEFAULT_AUTHENTICATION_CLASSES'] = [
#     'ffsecurity.auth.TokenAuthentication',
#     'ffsecurity_cproauth.auth.CryptoProOrTokenAuthentication'
# ]


# ========== DossierLists sync ===========
# INSTALLED_APPS.append('ffsecurity_sync')

# token must be identical on master and slave
# use pwgen -s 64 1
# SYNC_TOKEN = 'change_me'

# SYNC_TIME = {
#     # 24 hour format
#     'hour': 3,
#     'minute': 0,
# }


# ============== 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
#     'ENABLE_DAILY_SEARCH': True,                     # daily search activation (default False)
#     'DAILY_SEARCH_PUSH_HOUR': 2,                     # daily search dossiers synchronization hour
#     'DAILY_SEARCH_PULL_HOUR': 6,                     # hour in which results of daily search will be obtained
#     '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': 'ifruit_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
#             'facen_model': 'grapefruit_480',
#             'extractor': 'http://127.0.0.1:18667',
#         },
#     ]
# }

When configuring findface-security, refer to the following parameters:

Parameter Description
BEARD_THRESHOLD The presence of a beard on a face is determined with a certain level of confidence. Depending on the confidence threshold, the system returns a binary result none or beard.
CONFIDENCE_THRESHOLD Face similarity threshold for verification in events.
COUNTERS_FULLFRAME_JPEG_QUALITY JPEG quality of full frames in counters.
COUNTER_RECORDS_MAX_AGE The age of counter records at which they are automatically purged from the database.
COUNTERS_SAVE_FULLFRAME Saving options of full frames in counters: always, detect - only save if faces or silhouettes have been detected, never.
COUNTERS_THUMBNAIL_JPEG_QUALITY JPEG quality of thumbnails in counters.
CUSTOM_FIELDS Uncomment and modify this section to customize dossier content. See Dossier Custom Tabs, Fields, and Filters for details.
DATABASES (section) Database settings. Fill in as such: 'PORT': 5439, 'USER': 'ntech', 'PASSWORD': '<password from /etc/pgbouncer/userlist.txt>'
EMOTIONS_THRESHOLD Emotions are determined with a certain level of confidence. Depending on the confidence threshold, the system distinguishes emotional faces from neutral ones.
EPISODE_EVENT_TIMEOUT The maximum time in seconds since the last event has been added to an episode. After this time, an episode automatically closes.
EPISODE_KEEP_ONLY_BEST_EVENT When closing an episode, delete all events in it except the best event.
EPISODE_MAX_DURATION The maximum episode duration in seconds. After this time, an episode automatically closes.
EPISODE_SEARCH_INTERVAL The period of time preceding an event, within which the system searches the biometric database for events with similar faces. If no such an event is found, the system creates a new episode. Otherwise, it picks up the most relevant event from a LIVE episode after sorting out the 100 most recent similar faces. See Organize Events with Episodes.
EPISODES_THRESHOLD Face similarity threshold for verification in episodes.
EVENTS_FEATURES If you enabled recognition models in the findface-extraction-api configuration file, list them here.
EVENTS_MAX_FULLFRAME_MATCHED_AGE Same as EVENTS_MAX_MATCHED_AGE but only for full frames.
EVENTS_MAX_FULLFRAME_UNMATCHED_AGE Same as EVENTS_MAX_UNMATCHED_AGE but only for full frames.
EVENTS_MAX_MATCHED_AGE The age of matched events at which they are automatically purged from the database.
EVENTS_MAX_UNMATCHED_AGE The age of unmatched events at which they are automatically purged from the database.
EXTERNAL_ADDRESS External IP address or URL that will be used to access the FindFace Security web interface.
EXTRACTION_API IP address of the findface-extraction-api host.
IGNORE_UNMATCHED Disable logging events for faces which have no match in the dossiers (negative verification result). Set true if the system has to process a large number of faces.
LIVENESS_THRESHOLD The liveness detector will estimate a face liveness with a certain level of confidence. Depending on the confidence threshold, it will return a binary result real or fake.
MAX_CAMERA_DROPPED_FRAMES Color representation of camera statuses (yellow and red), based on the percentage of dropped frames.
MAX_CAMERA_FAILED_FACES Color representation of camera statuses (yellow and red), based on the percentage of failed postings.
MAX_VIDEO_ARCHIVE_JOBS Maximum concurrent findface-video-manager jobs for video archive processing.
MINIMUM_DOSSIER_QUALITY Minimum quality of a face in a dossier photo. Photos containing faces of worse quality will be rejected when uploading to a dossier. Upright faces in frontal position are considered the best quality.
NTLS_HTTP_URL IP address of the findface-ntls host.
PERSONS_CLUSTERIZATION_SCHEDULE Recurrence rule (RRULE) for scheduling person clusterization.
PERSONS_CONFIDENCE_THRESHOLD Confidence threshold to match a face to a person.
PERSON_EVENT_MIN_EPISODE_EVENTS Minimum number of events in episodes used in person clusterization.
PERSON_EVENT_MIN_QUALITY Minimum quality of faces used in person clusterization. Do not modify the default value without consulting with our experts (support@ntechlab.com)
PERSON_EVENTS_MAX_AGE The age of person events at which they are automatically purged from the database.
ROUTER_URL IP address of the findface-security host that will receive detected faces from the findface-video-worker instance(s). Specify either external or internal IP address, subject to the network through which findface-video-worker interacts with findface-security.
SERVICE_EXTERNAL_ADDRESS (Optional) IP address prioritized for webhooks and Genetec integration.
SF_API_ADDRESS IP address of the findface-sf-api host.
THUMBNAIL_JPEG_QUALITY Thumbnail JPEG quality.
THUMBNAIL_MAX_WIDTH Maximum thumbnail width.
VERBOSE_WEBHOOKS Send serialized dossiers, watch lists, cameras, and camera groups in webhooks.
VIDEO_DETECTOR_TOKEN To authorize the video face detection module, come up with a token and specify it here.
VIDEO_MANAGER_ADDRESS IP address of the findface-video-manager host.