1 SAFR-Genetec SDK Integration Guide

1.1 Introduction

Integrated SAFR Genetec is only available on Windows.

Integrating SAFR’s facial recognition and analysis capabilities into Genetec enables you to use SAFR’s video feed information overlays within Genetec camera video feeds, thus making it much easier to quickly and accurately separate unknown people from authorized people from known threats. You’ll also have immediate access to additional infomation such as age, gender, sentiment, name, company, known associates, or any other configurable information you want to create.

Note: SAFR has the native capability to detect age, gender, and sentiment, while other information needs to be manually entered by an operator.

Integrating the two systems also allows SAFR’s information about individuals to trigger Genetec alerts and other actions within the Genetec system. Genetec’s metadata within bookmarks are enriched with SAFR’s additional information, allowing you to more easily find relevant bookmarks.

1.2 Integration Overview and Requirements

A typical deployment requires the following:

• A machine running Genetec Security Center.
• A machine running Genetec Security Desk and Genetec Config Tool.
• One or more machines running the SAFR Desktop Client to process videos.
• If you’re doing a SAFR on-premises deployment, you’ll also need a machine running SAFR Server. SAFR Server can run on the same machine as one of the Desktop Clients, provided the host machine meets the system requirements.

Cameras are connected to the Genetec Security Center. The SAFR Desktop Client(s) can then connect to the Genetec Security Center to perform analysis of the video and add overlays. Depending on the number of cameras you need, one or more machines may be required to run the SAFR Desktop Client, each processing multiple video feeds. The Desktop Client processes the video and returns information to Genetic to overlay the video feeds and generate events. The Desktop is also used to perform various management activities.

1.2.1 System Requirements

Genetec has the following system requirements:

• One machine running Genetec Security Center Version 5.7 or later.
• One machine running Genetec Security Desk and Genetec Config Tool.
• Each machine running a Genetec product must meet the following system requirements:
• Windows 10.
• Additional system requirements as described in the Genetec documentation.

SAFR has the following system requirements:

• Each machine running the SAFR Desktop Client must meet the following requirements:
• Windows 10.
• The Desktop Client must be version 1.3.228 or later.
• Genetec Security Center SDK for your version of Genetec Security Center must be installed.
• Additional system requirements as described on the SAFR system requirements page.
• Local SAFR deployments require at least one machine running SAFR Platform 1.3 or later.
• Each machine running SAFR Server must meet the following requirements:
• Windows 10.
• Additional system requirements as described on the SAFR system requirements page.

1.2.2 Licensing and the Genetec Part Number

An accompanying Genetec part number must be added to your Genetec connection license. Do the following to discover and add the Genetec part number:

1. Go to the Genetec Portal and sign in using your Genetec credentials.
2. In the applications section, search for SAFR. From the results, click SAFR Facial Recognition.
3. On the SAFR Facial Recognition Solution Details page, in the right column, the Genetec Part Number is displayed.
4. Contact Genetec and have them add the part number to your license. You need a quantity of the part number equal to the number of cameras SAFR will be processing plus one additional license for the metadata channel SAFR creates. In other words, if SAFR will be processing cameras, then you need quantity of the part number added to your license.

You’ll need the following licenses: each Genetec camera where SAFR face detection and recognition is used, you’ll need:

• A Genetec connection license with the accompanying Genetec part number is required for each connected Genetec camera.
• One additional Genetec connection license for the metadata channel SAFR creates.
• A SAFR license for each camera is required

For example, if you have 300 cameras but only need face detection on 30 cameras at a time, then you would obtain a 31 connection license from Genetec and a 30 camera license from RealNetworks. Having a 31 connection Genetec license does not mean you are limited to face detection on a fixed set of 30 cameras. At any time, you can choose to connect the SAFR Desktop Client to a different camera. You may have cameras in your parking garage that you were not previously monitoring with SAFR recognition. You can use a few of your licenses that are connected to other cameras to connect to garage cameras instead.

1.3 Install and Configure the Genetec Security Center

1. Download the latest version of Genetec Security Center from the Genetec Portal.
2. Run the installer. For details about which install options to select, see the Security Center Installation and Upgrade Guide.

1.3.1 Create a SAFR User

To create a user with the permissions that SAFR will require, do the following:

1. Open the Genetec Config Tool.
2. Click Tasks > User Management.

3. Create a new user (with a username of, for example, SAFR) with the following permissions:

All privileges

• Application privileges

• Log on using the SDK

Administrative privileges

• Physical entities

• View camera properties

Access control management

• View cardholder group properties

• View cardholder properties

• View visitor properties

System management

• View general settings

• Modify custom events

Action Privileges

• Cameras

• View live video

• Add bookmarks

1.3.2 Add Permissions for Event-to-Archive Actions

In order to create Event-to-Actions in the Genetec Config Tool, one or more of the following Action permissions must also be added to the SAFR user created in the previous section. Only those actions you want to trigger with SAFR events are needed:

All privileges

• Action privileges
• Set threat level
• Cameras
• Protect video from deletion
• Save/modify/print snapshots
• Access control
• Doors
• Explicitly unlock doors
• Override unlock schedules
• Elevators
• Override elevator schedules
• Alarms
• Trigger alarms
• Users
• Send a message • Send an email
• Send/clear task
• Macros
• Execute macros
• Zones
• Arm/disarm zones
• Areas
• Modify people count

1.3.3 Set Minimum Cardholder Image Size

Do the following:

1. Open the Genetec Config Tool.
2. Open Tasks > Administration > Access Control > General Settings.
3. Set Maximum Picture File Size to 128k or larger.

1.3.4 Configure the Media Gateway

Do the following:

1. Open the Genetec Config Tool.

2. Open Tasks > Administration > Video.

3. Click the arrow next to the Video Unit button in the bottom left corner, and select Media Gateway.

4. Click Next, and in the Create Media Gateway wizard, click Create. Accept the default values; no changes are needed.

5. Select Media Gateway, and click the Properties task.

• This adds a Media Gateway entry in the list on left side.

6. Determine the user to be granted access to the media gateway.

• This can be the SAFR user or a different user; we recommend using the same SAFR user unless you already have one configured to use the Media Gateway.

• This user does not need to have specific permissions. The permissions for media gateway are granted to this user in the next step.

7. To add this user to the Accessible To section, click the + icon. In the bottom right, click Apply to save the changes.

8. When prompted, enter a password for the user you are adding.

• This password can be the same as the user’s normal password or it can be different.

9. Save the username and password.

• This is the password that must be used in the Media Gateway credentials fields in the SAFR preferences window.

1.4 Install and Configure SAFR

1. On the machine(s) where you plan to install the SAFR Desktop Client, install the Genetec SDK from the Genetec Portal.
2. Go to the SAFR Download Portal.
3. If you’re doing a cloud deployment, download and install Windows SAFR Desktop. Make sure to select the Genetec Security Center install option.
4. If you’re doing an on-premises deployment, download and install Windows SAFR Platform. Make sure to select the Genetec Security Center install option.

• When installing the SAFR Platform, the default SAFR port assignments sometimes conflict with other software port assignments. If a port conflict occurs, the error message shown below will pop up in the middle of your installation.

If this happens, do the following:

1. Click OK to edit port configurations.
2. Notepad will open, displaying the safrports.conf file.
3. Edit any conflicting ports to new values. (e.g. CoviHTTP=18080)
4. Save and exit Notepad.

The Platform installer will then restart and the new port values will be used. You can find the modified safrports.conf file at C:\Program Files\RealNetworks\SAFR\.

After the installation finishes, two icons will appear on your desktop: one labeled SAFRActions and another labeled SAFR. SAFRActions launches SAFR Actions, while SAFR launches the Desktop Client. The SAFR Server (when installed as part of a local deployment) automatically runs as a collection of background services.

Immediately following installation, the installer opens the Desktop Client and prompts you to log in with your SAFR Account credentials. Make sure to log in; it’s important in acquiring the SAFR license.

1.4.1 Connect SAFR to Genetec

1. Within your SAFR Desktop Client, select Tools->Preferences->Genetec.

Note: If the Genetec preference tab is not showing, it means that the Genetec SDK was not properly installed on your machine.

2. Enter the following information in the Genetec preferences tab.

• Username: Enter the SAFR user you created earlier.

• Password: Enter the Password you created for the SAFR user.

• Directory: IP address of the server running the Genetec Security Center server.

• Media Gateway: Used for acquiring video streams.

• Username: Enter the SAFR user you created earlier.

• Password: Enter the Password you created for the SAFR user.

• Port: Enter the port on which to connect to the Media Gateway. You can use the default value of 654 unless that would create a port conflict.

This should cause your SAFR system to establish a connection with the Genetec system.

To verify that your SAFR system successfully connected to the Genetec system, do the following:

1. On the SAFR Desktop Client, open Tools -> Preferences -> Camera.
2. Cameras connected to Genetec system should be visible.
3. All cameras connected to Genetec have the Genetec prefix in their names.

1.5 Troubleshooting

1.5.1 How do I Resolve a Certificate Registration Error when Logging in from SAFR to Genetec?

This error is caused by a mismatch between the SAFR Genetec certificate and the Genetec Security Center license. SAFR builds have either a Genetec production certificate or a development certificate. The production certificate can be used only with Security Center installations that use a production or demonstration license. The development certificate can be used only with Security Center installations that use a development license.

Here are some steps you can take to try to diagnose the issue:

1. Use the Genetec Config Tool to connect to the Genetec Security Center server.
2. Click About on the left side.
3. Click the Certificates tab.
4. If you see a line that says, "Generic certificate for developers" then the Security Center server is using a developer license. You must use a SAFR build that uses a developer certificate. Builds with developer certificate are available only from SAFR build farm and should be used only by developers.
5. If that line is not present, then Security Center is using a production or demonstration license. You must use a SAFR build that uses a production certificate. Download SAFR build with production certificate from the SAFR Download Portal.

• Click on the Purchase Order tab. Production or demonstration licenses must also have a license for SAFR attached to it. There should be a line with Part #GSC-1SDK-RealN- FaceRec. The quantity must be equal to or greater than the number of cameras that SAFR will be processing.

1.5.2 How do I Resolve a Connection Error when Logging in from SAFR to Genetec?

There can be many different causes for a Connection Timeout error from SAFR. However, if you are in a situation where this consistently happens and no cameras are connecting, then doing the following will most likely resolve the error:

1. Connect to the Security Center server using the Genetec Config Tool.
2. Go to the Video task.
3. In the left pane, right-click on the Media Gateway role.
4. Select the Maintenance->Deactivate role.
5. After the role turns gray, right-click on it again.
6. Select the Maintenance->Activate role.
7. The Media Gateway will go through a startup routine. It will turn red, yellow, and eventually white.
8. After it turns white, try connecting again.

2 SAFR Genetec Operation Guide

2.1 SAFR Genetec Preferences

You can set several Genetec-specific preferences by opening the SAFR Desktop Client and clicking on Tools -> Preferences -> Genetec.

• Username: Person with the credentials to connect the SAFR system to the Genetec Security Center Server.
• Password: Password of a person with credentials to connect the SAFR system to a Genetec Security Center Server.
• Directory: IP address or hostname of the Genetec server.
• Media Gateway: Used for acquiring video streams.
• Username: Person with the credentials to connect the SAFR system to a Genetec Security Center
  • Server.
• Password: Password of a person with credentials to connect the SAFR system to a Genetec Security Center Server.
• Port: The port at which SAFR will connect to the Genetec Security Center Server. The default is 654.
• Draw Overlays: Enables the drawing of ovals, names, and other details within Genetec camera video stream. The overlays match what would be shown in the SAFR Desktop Client, so SAFR settings affecting SAFR overlays also affect what is drawn in Genetec.
• Report Events: Enables reporting SAFR events to Genetec. If this setting isn’t checked, Include Event Details is automatically greyed out.
• Include Event Details: When enabled, all of the technical details of the event are attached to events. This option is especially useful if an operator uses macros to handle events for decision making.
• Insert Bookmarks: When enabled, bookmarks are added to camera video streams events. This allows operators to search videos for events or recognized people names. Care should be taken as to what to include since encountering many faces can cause numerous bookmarks to be created. When this box isn’t checked, the 4 children settings below are all greyed out.
• Include Unrecognizable Faces: When enabled, adds bookmarks when a face is detected but SAFR does not have enough information to determine if they are a stranger or a known person. This can result in an overwhelming number of bookmarks, so it’s disabled by default. However, this setting can be useful when monitoring areas with very few people.
• Include Strangers: When enabled, adds bookmarks when a face is recognized and determined to be a stranger. This option is generally useful for secured areas where only known people should be.
• Include Enrolled: When enabled, adds bookmarks when a face is recognized and determined to be a known person.
• Include Concerns and Threats: When enabled, adds bookmarks when a face is recognized and determined to be a known concern or threat.
• Cardholders
• Import Every 24 Hours: When enabled, all the Genetec cardholders not already in SAFR’s Person Directory are imported and registered to SAFR every 24 hours.
• Import now... : Clicking this causes all the Genetec cardholders not already in SAFR’s Person Directory to be imported and registered to SAFR.

2.2 Connect and Use Cameras and Video Feeds

To connect cameras to Genetec, you need to add the cameras to the Genetec Video Archiver using the Genetec Config Tool. For details, please see the Genetec Security Center Administrator Guide. After a camera has been added to the Video Archiver, it should be displayed as a Genetec camera in SAFR. If it’s not, try closing and re-opening the SAFR Desktop Client.

2.2.1 Genetec Cameras are listed in SAFR in one of three places:

• Preferences > Cameras
  
• SAFR Camera Feed Analyzer tool in "Cameras" dropdown list
  
• Video Feeds > Add Feed
  

2.2.2 Adding Cameras from Camera Feed Analyzer

This method is useful to allow for configuring feed before setting it to run as a background Windows Service or leave the feed running in Windows for logged in users.

1. Open SAFR Desktop
2. Select File > Camera Feed Analyzer
3. Select one of the Genetec cameras from the camera dropdown list
4. Make any configuration changes desired in Tools > Preferences
5. Optionally, run the feed as a background Windows Service using the button shown by red arrow below.
   

2.2.3 Adding Feeds from Video Feeds Window

This method is useful to allow for adding feeds directly as a background Windows Service.

1. Open SAFR Desktop
2. Select Tools > Video Feeds
3. Chose "…" menu and select "Add Feed"
4. Optionally pre-type part of the camera name in Camera entry field to show only those cameras
   
5. Select desired camera and click "Add" button.

2.2.4 Using Direct RTSP URL

VMS Integration supports pulling video feed directly from the camera using an RTSP URL instead of from the VMS. This allows for lower latency and reduces load on the Media Gateway. To leverage this feature, enter the RTSP URL to the camera through the "Direct URL" entry field as shown below for any of the VMS Cameras.

2.2.5 To connect additional cameras

1. Open another instance of the Desktop Client by selecting File > New on the client.
2. Repeat steps 2-6 above.
3. You can keep repeat this procedure to add overlays to as many video feeds as desired.

Note: Most machines can only support up to 16 video feeds. If you want to connect more feeds than that, you’ll need to install the SAFR Desktop Client on additional machines.

By default, the SAFR Desktop Client operates in the Enrolled and Stranger Monitoring video processing mode and generates events and bookmarks into the Genetec system for every registered person or stranger. If you want a different mode for a given camera, choose a different mode from that camera’s Camera window Mode Selector menu.

2.3 Bookmarks

SAFR enhances Genetec’s bookmarks so that they provide readily accessible additional information, making the bookmarks much more useful. Bookmarked video contains the video feed overlays and enhanced peoplerelated data described above. In addition, the bookmarks themselves are populated with the attributes for each person in the camera view so that searching bookmarks is more fruitful. All bookmarks automatically contain the Person Type, ID Class, and Name of each recognized person, and additional attributes such as Age and Gender will be included within the bookmarks, if such additional attributes are known. The image below shows how bookmarks can be used to review important events. The yellow overlay indicates that the person is a concern.

2.4 Genetec Cardholders and SAFR Identities

Genetec cardholders can be registered to SAFR by doing the following:

1. Increase the Genetec Security Center setting for thumbnail size to make sure SAFR has access to high quality images to use for face recognition.

2. On the SAFR Desktop Client, click Tools > Preferences > Genetec.

3. In the Cardholders section click Import Now... . Pressing this button causes the following to occur:

• Each imported cardholder is given a Person Type based on their assigned group.

• If a cardholder has multiple group memberships, the cardholder group with the highest access privilege is used to define the group.

• After import, SAFR updates the events in Genetec to make sure Genetec has one event for each Person Type.

4. You can configure SAFR to import new cardholders every 24 hours by selecting the Import Every 24 Hours check box.

You can also register people to SAFR by using SAFR’s native functionality. For more information, see Importing and Registering People. Although people registered with SAFR are never synchronized to Genetec, you may want to register people to SAFR anyways when you want to add threats, concerns, or other registered people who may not be suitable as Genetec cardholders.

2.4.1 Edit Cardholder Data

You may want to edit people’s properties to better manage which events get triggered when that person is recognized, For example, setting a person’s ID Class to Concern or Threat triggers the corresponding alarms, while changing a cardholder group can allow you to trigger a VIP alert for specific cardholder groups. The most important people attributes are the Name, Image, Person Type, and ID Class.

Attributes should be edited through Genetec Security Center whenever possible. Person Type defines a person’s role (for example, staff or visitor) while the ID Class defines the risk level (No-Concern, Stranger, Concern, or Threat). Person Type and Image can be edited in Security Center by changing the cardholder group a person belongs to.

To edit these attributes, open Cardholder Management in Genetec Config Tool and update the desired users. After making changes, make sure to either manually synchronize users or set automatic synchronization as described previously in the "Register Cardholders".

ID Class and any other attributes of a person must be edited in SAFR’s People dialog accessed through the Desktop Client > Tools menu. All cardholders imported from Genetec Security Center are assigned an ID Class of Normal. To edit the ID Class of a person, click Tools > People in the Desktop Client. The following window is displayed:

The Person Type and Name attributes can be edited by clicking their respective fields in the People window. To edit ID Class, in the People Edit dialog, double-click the user and choose the desired value from the ID Class menu as shown in the following image:

2.5 SAFR Events

You can use SAFR to generate events. When enabled on the Events Preferences page, events occur when a person appears in the view of a connected camera. When a person appears in the camera’s view, they’re immediately assigned an ID Class attribute, although that ID Class may change if the system successfully recognizes them and assigns them a more appropriate ID Class. The types of ID Classes are listed below.

• Unrecognizable: A face was detected but it wasn’t of sufficient quality to attempt recognition.
• Stranger: The person’s face is of sufficient quality to recognize them, but they’re not in Genetec’s cardholder database, nor are they registered in SAFR’s Identity Database.
• No-Concern: Registered person.
• Concern: Registered person who has been marked as a person of concern.
• Threat: Registered person who has been marked as a known threat.

There are several different combinations of the conditions that are triggered. The following image shows multiple events populated in the Genetec alerts panel. Clicking any of the events allows the video from that event to be replayed:

The following table lists the available events that SAFR makes available to Genetec.

Event Message	Id Class	Named	Person Type	Condition
Unrecognizable face detected	N/A	N/A	N/A	Face detected but insufficient information for recognition
Stranger detected	Stranger	N/A	N/A	Face detected but not found in registered people
Known person detected without a name.	Normal	No	None	Registered person without name or person type assigned
Known person detected with name <name>	Normal	Yes	None	Registered person with name but no person type
Known person detected of type <personType>	Normal	No	Defined	Registered person with person type but no name
Known person detected of type <personType> with name <name>	Normal	Yes	Defined	Registered person with person type and name
Concern person detected without a name	Concern	No	None	Same as above for Concern
Concern person detected with name <name>	Concern	Yes	None	Same as above for Concern
Concern person detected of type <personType>	Concern	No	Defined	Same as above for Concern
Concern person detected of type <personType> with name <name>	Concern	Yes	Defined	Same as above for Concern
Threat person detected without a name	Threat	No	None	Same as above for Threat
Threat person detected with name <name>	Threat	Yes	None	Same as above for Threat
Threat person detected of type <personType>	Threat	No	Defined	Same as above for Threat
Threat person detected of type <personType> with name <name>	Threat	Yes	Defined	Same as above for Threat

2.5.1 SAFR Operator Modes

SAFR has different operator modes that control what events are generated. Below is a short summary of the modes most relevant to Genetec Security Center integration. For a complete description, see the Operator Modes documentation.

• Secure Access: Only triggers events when cardholders and people registered in SAFR’s Person Directory are identified with a high degree of certainty. This mode is useful when the system is being used to manage physical access. (i.e. when the system is responsible for unlocking doors for authenticated people)
• Secure Access with Smile: Similar to Secure Access mode, except that registered people must smile in order to cause the system to grant them access.
• Enrolled Monitoring: Similar to Secure Access mode, but events are triggered at a lower recognition confidence level.
• Enrolled and Stranger Monitoring: Similar to Enrolled Monitoring mode, but events are also triggered for strangers.

2.5.2 Add and Configure Alerts

To trigger the alert as a result of a SAFR-generated event, do the following:

1. Open the Genetec Config Tool, and go to the System Panel.

2. Click the + icon to add a new alarm, and click the When menu. Type SAFR and press Enter to see the list of SAFR-enabled alarms.

3. Choose the desired entry from the list.
4. Under From, choose the camera you want to use to trigger the event. Under Action, choose a desired action. (e.g. Trigger Alarm)

5. Click Save when done.

SAFR Events can be tied to Actions which can then trigger an Alarm. Initially create an alarm you want to trigger, and then use Genetec Event-to-Action dialog to tie SAFR Events to any action that can be defined in the Genetec system (for example, Trigger Alarm).

2.5.3 Add an Alarm

An alarm can be used to make sure an important event is noticed. In this example, we show how to create an alarm that is triggered when someone who has been marked as a threat is recognized on one of the cameras.

For more information on triggering events, refer to Genetec support documentation.

To create an alarm, do the following:

1. Open the Genetec Config Tool, and open the Alarms screen.

2. Click Add Alarm, and type a Name as shown in the following image:

3. Click Save to save the alarm.

2.5.4 Recommended Settings for Alarms

Properties task

Choose priorities based on circumstances and your organization guidelines (1=high, 255=low) • Stranger: 100 (If infrequent, set high) • Concern: 50 • Threat: 10 Video display option Set to Live to see the live view when alarm loads video Playback may be useful for short events where the subject may have walked off the screen by the time the video loads • If playback mode, set to at least 4 seconds to avoid buffering

Advanced task

Auto-Acknowledge: Good for stranger events; enter the number of seconds to stay in the view before returning to the view you were on prior to the event Choose color to match the SAFR colors (add ref to section in manual that describes colors) Reactivate threshold: Suppresses additional alarm if another similar alarm triggered within this time • Adjust as needed for use case.

2.5.5 Trigger Macros

When SAFR is configured to Include Event Details in reported events, highly customized actions can be programmed using macros in the Genetec system. Event details include all information associated with the detected face (e.g. Name, Person Type, Age, Gender, Sentiment, etc.). For more information on macros, refer to the Genetec support documentation.

2.6 Troubleshooting Tips

• If detection or recognition is poor (not many faces found or recognized)

o Make sure the Genetec video feeds are set for a sufficiently large frame size

o Ensure face images are well lit and at least 80 pixels from ear to ear

o Ensure SAFR is set to correct processing mode (Enrolled and Stranger Monitoring is a good default)

• If overlays are not well aligned to face

o Ensure system clock on both Genetec server and SAFR Desktop are aligned to within 100 ms. Check “your clock is off by” on time.gov for each computer.

• If events not appearing in Genetec for background SAFR Video Feeds, ensure that events are enabled as follows:

• Ensure events for the cameras connected to SAFR

1