SAFR : Solution Guide - Threat Detection

Table of Contents


This tutorial describes how to use SAFR to detect and create an alert if a person who is recorded as a known threat appears at an entrance monitored by video cameras. It describes how to use SAFR to perform threat detection and take action, such as alerting authorities or locking doors to prevent access.

You are the head of security for a small school district. The schools in this district are designed with two entrances in order to ensure all traffic into the school can be tightly managed. The goal is to detect and send an alert for anyone entering the courtyard and to prevent anyone who is banned from the school from entering the buildings.

In this tutorial, you will learn how to setup SAFR to perform the following useful functions:

  • Train the system to recognize a specific person
  • Register a person as a concern or threat
  • Set up cameras to detect any registered persons under a wide range of lighting conditions
  • Configure the system to send an alert should a person of concern enter the courtyard
  • If cameras are located outside the entrance, configure the system to lock doors if a person of concern is detected as approaching

About cameras

When performing facial recognition, the best results are achieved when faces are clearly visible and have sufficient contrast (the visual difference between the darkest and lightest areas) and sharpness (the amount of relative focus of an image) to allow the recognition system to distinguish the facial features. This can be a challenge with bright backlighting or low light conditions. Cameras need to handle a wide range of challenging environmental conditions, such as direct sunlight during the day and poor lighting conditions at night. So, one of the most important components of a successful facial recognition system for threat detection is the camera. While SAFR works with almost any IP based or USB camera, selection of a high-quality camera is critical for threat detection. Review the Appendix for recommendations on environmental assessment and camera selection.

About SAFR applications

The SAFR Desktop and SAFR Recognition mobile app allow you to connect to a video feed and process video to perform face detection and recognition. The SAFR Desktop and SAFR Recognition mobile app only perform the face detection portion; recognition is done in the SAFR Cloud or SAFR Platform. Face detection involves locating faces within an image. Information about the face is determined, such as its orientation (the direction in which the face is pointed, often referred to in SAFR as Center Pose Quality or CPQ), the sharpness, contrast, and size. This information is used to determine if a suitable face has been found. If so, the face is submitted to SAFR Cloud or Local Server for recognition. 

The SAFR Actions application is designed to allow one or more actions to be taken when a recognition event occurs. For example, SAFR Actions can be used to send an email if a stranger is observed at a particular camera. SAFR Actions can be installed on any computer and connects to the SAFR Cloud or Server to monitor for recognition events. Actions can be triggered based upon a wide range of attributes associated with each recognition event, such as person type, ID Class (threat, concern, stranger), site (building), and source (camera). Actions can include sending an email, unlocking a door, or triggering an alarm.

Plan your system

Before you get started, think about how you want to install SAFR. The following components are needed for threat detection:

  • SAFR Cloud or Server can be used in the cloud or installed with the server on site; for this tutorial, the SAFR Cloud is used
  • SAFR Desktop, SAFR Recognition mobile app, or Virgo for processing video feeds from cameras
  • SAFR Actions for processing events
  • One or more cameras
  • Optionally, one or more door locks to control

The following illustration provides an example of how the components can be laid out:

The SAFR Desktop, SAFR Recognition mobile app, or Virgo and SAFR Actions can run on a single computer, but here they are shown separately. If you have many cameras, you may need to install more than one machine to process the video feeds. Typically one machine can handle up to eight (8) cameras.

In this tutorial, we assume one might want to lock doors and prevent access if a threat is detected.

System requirements

SAFR Desktop and SAFR Server require a fast computer to analyze the video feeds. SAFR Desktop is optimized to work with NVIDIA GPU cards and will support more cameras on a system with an NVIDIA GPU. See the download page for information on system requirements. When planning a system with more than ten cameras, speak to your sales associate for guidance on sizing your SAFR system.

Install and configure SAFR

The following activities need to take place:

  • Install cameras
  • Install and configure SAFR Edge
  • Connect cameras
  • Install and configure SAFR Actions

Install your cameras

Before you start, you should have your IP cameras installed and connected to your network. See the Appendix for information on camera selection and location for best performance. Later we'll describe how to get the information for how to connect SAFR to your camera.

Install and configure SAFR Edge

 If you have not already done so, from SAFR download portal, download and install SAFR Edge for your operating system.

  • For Windows machines, the full version is intended for machines with NVIDIA video cards. With an NVIDIA card installed, you can realize significantly improved performance.
  • The SAFR Edge installer includes both SAFR Desktop and SAFR Actions apps.

After installation, do the following:

  1. Open SAFR Desktop from the Windows Start menu or Mac Applications folder.
  2. From the menu in the top-right corner of the main window, choose Secure Access or Secure Access with Smile. The modes associated with these menu items have default actions triggered when a user is recognized or smiles.
  3. In Windows, open SAFR > Tools > Preferences. On Mac, use SAFR > Preferences. Configure the following:
    • On the Account tab, update the User Site and User Source fields to a suitable value for your environment. By default, the fields are shown with globally unique IDs.
    • (Optional) On the Events tab:
      • Check the event types you want to be triggered, or, under the Positive, Neutral and Negative Reply sections, select a voice that sounds when an event is triggered.
    • On the Recognition Tab, if there are issues with recognition, adjust the following:
      • Minimum required face size / To allow identification: set to 120 (this allows recognition when face image is <220 default)
      • Minimum required center pose quality / To allow recognition: Decrease to allow non-frontal recognition
      • Minimum required face contrast quality / To allow recognition: Increase if you have a very bright background
      • Identify recognition threshold / Camera: Increase value to allow more lenient recognition

Choose a camera

On the SAFR Desktop, from the menu in the top left of the main window, select a camera. By default, the local camera is selected. At any time, you can select another camera from the menu to display its view. 


Configure for a threat


Learn/register a person

From photos

To learn a person from a photo of that person, do the following:

  1. Open SAFR Desktop.
  2. Choose File > Import Faces.
  3. Open one or more photos.
    1. Any photo that has sufficient quality for recognition will show a purple oval around the face with option to click and add a name.
  4. In each learned photo, type a name if desired.

From video

To learn one or more people from a video, perform the following steps.

  1. Open SAFR Desktop.
  2. Choose File > Open.
  3. Open a video.
    1. Any face within the video that has sufficient quality for recognition be added to the database.
  4. Add Names as follows if desired:
    1. Choose Tools > People (or SAFR > People on Mac).
    2. Sort by Enrollment Data and set sort order to Descending in order to see the newly-added entries.
    3. Type names for each.

From SAFR Recognition mobile app

For testing, you can use the SAFR Mobile App to register a person who will act as a test subject:

  1. Go to the SAFR Download Portal and click on the link for SAFR Mobile App to install.
  2. After installing the SAFR Mobile app, launch the application. The app will show the front facing camera by default.
  3. Hold the camera so your face fills the screen and wait for the screen to display "Tap face to register."
  4. Tap the face and enter your name. You are now registered.

Configure person as threat

Take following steps to configure a person as a threat or concern:

  1. Choose Tools > People (or SAFR > People on Mac).
  2. If you want to see most recently added people, sort by Enrollment Data, and set sort order to Descending in order to see the newly added entries.
    1. You can remove people already marked as Threat or Concern by filtering on ID Class of No Concern.
  3. For each user you want to change:
    1. Double-click user.
    2. Choose Threat or Concern from the ID Class menu list.
  4. In the SAFR Desktop app, that person should now be marked with a red oval overlay to indicate a Threat or an amber oval overlay to indicate a Concern.

Adjust SAFR recognition preferences

At a high level, optimizing recognition involves the following steps:

  1. Adjust image quality for the image being produced by the camera to get the best possible image of a face
    1. Configure the camera to increase face size, sharpness, and contract
  2. Adjust image quality thresholds in SAFR for face recognition
    1. When it is not possible to improve image quality from camera beyond a certain point, adjust adjust SAFR thresholds for face size, center pose, sharpness, and contrast
    2. This may not be necessary if the image quality from the camera is already above the minimum thresholds set by default in SAFR
  3. Adjust Identity Recognition Threshold to optimize matching against existing faces

Test recognition results and optimize

The easiest way to determine the quality of the face images is to use the recognition details panel inside the SAFR Desktop application

  • On Windows enable "Recognition Candidates" and "Recognition Details" via View menu
  • On Mac enable "Recognition Candidates" via the View menu

Enabling this will display a cut-out of each face found in the video as follows:


You can use the information above for two purposes:

  • Initially, configure the camera to increase face size, center pose quality, sharpness, and contract (larger values are better)
  • Then, if necessary, adjust SAFR Thresholds so that SAFR will attempt to perform recognition for face images that do not meet minimum thresholds

The section below describe these two steps.

Optimize camera image

Using the face size, sharpness, and contrast in the previous display, try adjusting camera settings to improve the values reported by SAFR Desktop. See Camera Selection for information on optimizing camera settings.  The important settings consider on the camera are:

  • Backlight control (BLC)
  • Wide (or High) Dynamic Range (WDR) mode
  • Focus (typically let camera autofocus - you may want to set a region to focus thru the camera administration interface
  • In extreme cases of lighting, you may need to set manual modes such as Shutter priority.  
    • For example, you may use manual Iris Priority to let more light in and allow the background to be "washed out" as long as face illumination is good

Adjust SAFR preferences

SAFR settings for face size, center pose quality, sharpness, and contrast are used to filter out certain images from attempting recognition. This is useful when you want to avoid spending processing time on faces that will not lead to satisfactory recognition results or if you want to recognize on people only with a certain range of the camera. These settings should be adjusted if needed to ensure SAFR is attempting to perform recognition. 

In addition, there are settings that determine how close two face images need to be before SAFR will consider them matching.   These settings are adjusted as described below.

The values reported in the Recognition Candidates panel as described above can be directly compared to the values in the Detection and Recognition Tabs of the SAFR Preferences.  The following describes the most important settings to adjust in order to improve recognition results.


The section below describes adjusting these settings.  Tuning for best results takes time. Modify settings methodically and note the results with each change. If results go far off track, reset to defaults and start over.  Please keep in mind the following as you make these adjustments.

(lightbulb) Most defaults are set intelligently for the mode selected. Change as few settings as you need to accomplish the goal.

(lightbulb) Don't hesitate to click the Reset to Defaults button if things get too convoluted.

(lightbulb) If the quality or size values are too small, the accuracy will suffer. In some cases, it is better to improve image quality by adjusting or upgrading camera than to lower the quality bar for recognition.

(lightbulb) SAFR Allows detection and recognition settings to be customized per mode.  There are several different modes in SAFR Desktop.  The mode is selected in the upper right of the main window of SAFR Desktop (See below).  Make sure you are adjusting settings for the mode you are currently using.





Before changing settings, Set SAFR Desktop to correct mode; in this case, Enrolled and Stranger Monitoring.

Camera Preferences

These settings are specific to each camera input used by SAFR.

Go to the Tools menu. Click Preferences and click the Cameras tab.  Enter the following:

  • Source: Name for camera (this is what appears in events Source attribute).
  • URL: rasp://<username>:<password>@<ipaddress>/h264.
  • Check Lens Correction.  This straitens video warped due to fish eye distortion.  This will improving recognition though usually only slightly.
    • If there is not already warp in the video or only very slight warp, do not use this setting.
    • Adjust K1 and K2 until straight edges appear straight.
    • This is a trial and error process.

Note: These settings are camera-specific and are not available on webcams.

Detection Preferences

These settings that affect how SAFR behaves when searching for a face within each frame of the video.

Go to the Tools menu. Click Preferences and click the Detection tab. Enter the following:

  • Reduce vertical input image size to: 1080 - Increasing this can improve ability to detect faces within the image but increases CPU usage. This increases CPU usage and if too large slows down time to detection. Set this to as large as possible w/o making CPU or GPU hit 100%. If your subject is moving through the video field of view too quickly this may give insufficient time for recognition to succeed.
  • Minimum searched face size: 50 - Set to slightly smaller than Minimum required face size (e.g. 50) to avoid flipping between showing overlay and not when face in video is exactly same as Min required face size. 
  • Minimum required face size: 60 - The smallest face that recognition will be attempted on. 60 is typically as small as you want to go in most cases.
    • Use this to avoid trying to recognize until a face is close enough thus avoiding false unrecognized events for known users.
    • The smaller the value the more processing time to scan a frame for faces.

(lightbulb) If you enable "Recognition candidates" from View Menu, SAFR Desktop will display the cropped face with the cropped face size to help in choosing a value.

Tracking Preferences

These settings affect how closely SAFR tracks a face in the video.

Go to the Tools menu. Click Preferences and click the Tracking tab. Enter the following:

  • Position: Left default value of 115%. Increase if motion high or frame rate low to improve tracking.
  • Size: Left default value of 50%. Increase if motion high or frame rate low to improve tracking.
  • Failed recognition back-off interval: Set to .2 (default .34)
Recognition Preferences

These settings that affect when SAFR will attempt to recognize a face and how aggressively it will try to match:

Go to the Tools menu. Click Preferences and click the Recognition tab. Enter the following:

  • Minimum required center pose quality: To allow recognition: 0
  • Minimum required face sharpness quality: To allow recognition: 0
  • Minimum required face contrast quality: To allow recognition: 0
  • Proximity Threshold Allowance: 0.13 (increase to 0.2 or 0.3 if matching % is too low).

Settings for Center Pose Quality, Sharpness and Contrast:


Settings for Recognition (Matching):


User Interface Preferences

These settings that affect display in SAFR.  For this tutorial the most relevant settings are making it easier to read overlays on the screen.

Go to the Tools menu. Click Preferences and click the User Interface tab. Enter the following:

  • Video > Highlight border thickness (all modes): 19 (larger the value the larger the text thus making it easier to read from a distance).
  • Video > Overlay text size (all modes): 6 (larger the value the larger the text thus making it easier to read from a distance).
  • Video > Speak name display message: Checked (useful to hear when recognition occurs).


Note about validation during tuning

It is important to test each modification. This helps to know effect of each setting change. To do this, its helpful to have one person walk in front of the camera(s) while another person monitors the screen to confirm results. In this case, we are looking for location when person res recognized.

If you do not have a 2nd person to act as a subject, another good option is to use a web conferencing solution or screen capture software to record the SAFR Desktop application and then review. This also provides a nice record between each change.


Edit the SAFR Actions config file

These instructions assume you are creating a brand new SAFR Actions configuration file. If you already have modified SAFR Actions configuration file to perform other actions, you must add the Rules section to the file. Simply, these instructions also assume you are editing the configuration file instead of editing through the application GUI. 

(warning) Make sure the SAFR Actions application is not running before editing the configuration file.

On the machine where SAFR Actions is installed:

  1. Open SAFRActions.config which can be found in following locations:
    • Windows: C:\ProgramData\RealNetworks\SAFR\ares\config\
    • Linux: /Library/RealNetworks/SAFR/ares/
  2. Replace the contents with the following sample config contents.
  3. Save and close the file.
  4. Start SAFR Actions app; ensure the new config is loaded. If not, close SAFR and copy the config again.
  5. Set the following in SAFR Actions application (so the application performs encoding of the password for you).
  6. Change environment to your environment:
  7. Set userId, userPwd to your SAFR account
  8. Choose File > Save to load and save changes. Changes should take effect immediately.

SAFR Actions sample config file

SAFRActions.config File
  "directory": "main",
  "emailDef": [
      "attachments": [
      "label": "threatDetected",
      "message": "<h1>Threat Detected</h1>Classification: #a<br\/>Site: #I<br\/>Camera: #S<br\/>",
      "recipients": [
      "subject": "Threat Detected"
  "environment": "INT2",
  "rules": [
      "event": {
        "hasPersonId": true,
        "idClass": [
      "triggers": [
          "actions": [
            "@emailSend threatDetected"
          "daysOfWeek": [
          "reply": {
            "message": "Threat Detected!"
          "timesOfDay": [
              "end": "24:00",
              "start": "00:00"
  "userId": "USER",
  "userPwd": "PWD"

(warning) Notes:

  • Make sure the system clock on SAFR Desktop and SAFR Actions is within a few seconds of each other or events may not trigger. If needed, adjust the date/time.
  • SAFR Action Service:
    • On Windows, the SAFR Actions app runs as a service and you can exit the application and service continues to listen for and react to events.
      • Because it runs as a Windows Service, you can log out the user but do not let the computer sleep.
    • On Mac, the SAFR Actions app must be kept running. You can close the window, but do not quit the application or log out the user.
      • Alternatively, you can run SAFR Actions on Mac via command line. See App Documentation for .details.
  • Keep SAFR Desktop, Mobile, or Virgo running:
    • The SAFR Desktop, Mobile, or Virgo connected to the camera must remain running for events to be generated. The app may be minimized, but do not quit the application or recognition stops.

Configure the outbound email server

Configure credentials to allow SAFR to send email through your email server:

  1. Obtain a SMTP server account you can use for sending emails. 
    • Important: It is recommended you create a new account with only its default settings, and avoid using an established or personal account. If you are using Gmail, avoid setting 2-step verification (also known as two-factor authentication). 
  2. Open SAFR Actions > Tools > Configure Email Server.
    • You are prompted to log into SAFR Cloud if you have not already:
      • Choose SAFR Partner Cloud.
      • Enter your SAFR cloud account username and password.
      • Click Connect.
    • In the Configure Email Server dialog, enter all requested info, read from your SAFR cloud account if previously filled out elsewhere:
      • Sender Email - Email username for SMTP account, for example,
      • Email Password - Password for the SMTP account
      • Sender Name - Display name for the From line
      • From Email Address - Email for the From line; this does not work with all email servers; if not supported, the Sender Email is populated
      • Email Server Address - for example,
      • Email Server Port - 587 for SMTP default

Note: If using Gmail, you may need to change settings to use Less Secure App Access. In the SAFRActions log, if you receive an EMAIL SEND ERROR: <date> 500 Report server internal error, do the following:

      • To confirm, log into your Gmail account you have configured to send SMTP. Look for an email with title Critical Security Alert, with a message body that states, Someone just used your password to try to sign in to your account from a non-Google app.
      • When you click Check Activity and choose Yes to Were You Recently Prevented from Signing in to your Google Account? a message is displayed saying, Less Secure App Was Blocked.

To resolve this:

      • Log into your Google Account. Click your avatar in upper-right, and choose Google Account.
      • Go to Security > Less Secure App Access, and change Allow Less Secure Apps to On.

Test alerts

The easiest way to test your SAFR Actions is to use the mobile app to trigger an alert. You can install the application as described previously under From SAFR Mobile App. Register one or more test subjects, and mark the persons as a threat as described previously in Configure Threat Alerts

Test the alert as follows:

  1. Open SAFR Mobile app.
  2. Hide your face from the camera, and then unhide and wait for face to be recognized.
  3. Upon recognition:
    1. A red oval should be drawn around your face if the event is triggered.
    2. You should see the message Threat Detected flash on the screen.
    3. You should see an email appear in your inbox.

If you do not get a message displayed, check the SAFR Actions log to see if there are any clues there. You can find the log here:

  1. Windows: C:\ProgramData\RealNetworks\SAFR\ares\logs
  2. Mac: /Library/RealNetworks/SAFR/ares

Possible issues and resolutions:

  1. If you see errors with login, correct account info
  2. If you see Too Late, the machine running the SAFR app and the machine running SAFR Actions may not be set to same time. Correct this and try again.
  3. If you see other errors, check the message and attempt to make corrections, or contact RealNetworks technical support.


Camera selection

The goal is to detect a threat and perform alerting when a threat or concern is detected. In some cases, you may want automatic actions to take place upon detection of a threat; in particular, you may want doors to lock where detection occurred or potentially locking down the entire facility in addition to alerting authorities.

In this tutorial, cameras are positioned either inside the building pointed at external doors or mounted just outside external entrances pointed at approaching subjects. The major challenge here is lighting. Conditions can vary from rainy to sunny. You can face the following challenges in both conditions:

  1. Very high contrast - The subjects are incredibly dark with very bright background.
  2. Backlight conditions change when doors open.
    1. Opening doors can change lighting conditions right at the time the subject is walking past. The camera is still trying to adjust to the lighting conditions while the subject is walking past. This is especially true with automatic doors that open very wide and remain open for a period of time.

The application is for threat detection. It is important to have a camera attempt recognition on anyone entering the door.

The following are best practices for how to handle outside doors specifically in these conditions:
  1. Camera recognition accuracy should be maintained under following conditions:
    1. Bright sunny daytime conditions.
    2. Cloudy daytime conditions.
    3. Nighttime conditions (inside of building well-lighted).
  1. Automatic sliding door:
    1. Double door slides open as person approaches door.
Are there specific cameras recommended to perform well in these conditions?
Would the best option be counting cameras outside facing out? Either one above the door, or two - one on each side of the door. This would be ideal for this tutorial since you would be recognizing the person before entering. Cameras located inside the building do not allow the option to lock down in the event that a serious threat has been identified.

Camera recommendations

Camera positioning:

  1. If inside building, place camera 20-30 feet in front of door about 10-12 feet high.
  2. Subject should be facing nearly straight on.
  3. Camera resolution should be such that faces are at least 120 pixels high when at door, larger if possible.

Backlighting conditions can be typically overcome with appropriate adjustments to camera settings. The camera in use needs to be advanced enough to offer standard camera adjustments:

  1. Shutter Priority mode.
  2. Exposer Compensation.
  3. Manual Mode with full Shutter Speed, Iris (Aperture), and Gain adjustment.

The Sony 772R is an example of such a camera. In addition to these settings, the 772R also offers various digital tools to enhance the image:

  1. Visibility Enhancer.
  2. Backlight compensation.
  3. Highlight compensation.
  4. NR (Noise Reduction).

The basic steps in handling a backlight situation are as follows:

  1. Angle the camera slightly toward the floor to eliminate as much direct light as possible into the cameras sensor.
  2. Place the bound on the slowest shutter speed allowed. As people are moving through the field of view (FOV), maintaining high shutter speed is important to obtain blur-free images.
    1. Set the slowest shutter speed to at least 1/90 second.
    2. In some cameras, if the shutter speed lower bound is not settable for auto mode, you may need to use shutter priority mode.
    3. Sony 772R camera has both options available.
  3. Turn on Backlight compensation if available (it is on 772R), and adjust level.
  4. If faces are still dark, adjust Exposure compensation to brighten the faces. The background becomes overexposed, but that works for FR [What is FR? - sg].
  5. If there are specular reflections or faces are still too dark, turn on Highlight Compensation.

The previous approach is appropriate for the situation where varying outdoor conditions also vary the amount of light reflected from the face. Light intensity is simply boosted above what the cameras would choose automatically and enhancing the image to reduce exposer variance.

In cases where outdoor conditions only generate backlight (light from behind the subject's face) and there is minimal variation in lighting from inside (few windows so indoor illuminating on the face is mostly constant), it is more appropriate to place the camera in fully manual mode and set Shutter Speed, Iris, and Gain values manually to properly expose the face while allowing the background to be overexposed. In this mode, the camera makes no auto-adjustments and is not be thrown off by momentary bursts of light due to door opening or other momentary reflections. To do this:

  1. Set shutter speed to 1/90 or higher.
  2. Open the iris, increasing the f-stop for the iris (aperture) until the face is bright enough.
  3. Focus the camera on the sweet spot of the recognition where people are most likely to face towards the camera. [Not sure I understand the phrase "sweet spot of the recognition"; are you saying to adjust the camera focus until the facial image is sharpest (clearest?) at the place where most people are going to be directly facing toward the camera? - sg]

Increasing the iris [add "f-stop"? - sg] reduces the depth of field (distance during which face is in focus). Increasing the iris [add "f-stop"? - sg] increases the quality of the image but reduces the amount of time the image is in focus and viability for recognition. In either case, focus the camera on the sweet spot of the recognition [Same as previously noted - sg] where people are most likely to face toward the camera.

Anyone setting up cameras for facial recognition should be fully familiar with digital photography concepts described in the following video (15 minutes duration):

Specifics on backlight compensation:

SONY 772R User Guide:

Experimenting in a similar test environment is important to successfully overcome backlight situations.

Lighting considerations

Success with recognition indoors or outdoors depends on lighting conditions (amount of light being reflected from the face).

The light source:

  1. Should have a light source that hits the front of the face.
  2. Outdoors:
    1. Typically always has more light during daytime unless there is an awning blocking the light from above and front as the person approaches.
    2. At nighttime needs to have a light source behind the camera to illuminate the front of the face.
  3. Indoors:
    1. Still need to contend with the backlight illumination.
    2. Should have ample ambient lighting conditions and relatively uniform light on the face for best results.

Handling other light sources:

  1. Avoid a direct line between the sun and camera lens.
  2. Camera lens should have sun/rain shade for effective operation.