Hitachi Live Face Matching connector
The Hitachi Live Face Matching (LFM) connector integrates alerts that are generated by Live Face Matching with Hitachi Visualization Suite (HVS). This integration enables you to view and manage facial recognition alerts as events.
Features
Manageable
The connector can be installed and uninstalled.
Configurable
Names (entity and entity type name), wait timer, and camera coordinates are configurable.
Alert wait time
During the wait time, all matches for the candidate are accumulated and at the end of the wait time only the match with the highest confidence is sent. Default is 5 seconds.
Log files
The connector generates two types of log files, info.log and warning.log. These files are not listed in the Windows Event viewer, but output to C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.XX\pkgs\logs. The log files can be viewed using a text editor.
System diagram
The following diagram illustrates how the Visualization Suite Live Face Matching connector integrates Live Face Matching alerts with Visualization Suite.
Prerequisites and configuration considerations
- The Live Face Matching Client "Alert Notice Destination Configuration" is configured to send alerts to the connector. See the Live Face Matching Operations Guide.
- The Live Face Matching Server and Client is supported in version 2.0.3. See Live Face Matching.
- The connector runs on a Windows machine (64 bit). Visualization Suite has been qualified with Windows 10.
- The connector is supported in Visualization Suite v6.0.0 and above.
- The connector is supported in Live Face Matching v2.0.3.
Configuration steps
Procedure
Configure the Live Face Matching server.
Configure the Live Face Matching client server.
Configure the identify server to send alert notifications to Visualization Suite (Alert Notice Destination Configuration).
Install the Live Face Matching connector.
Edit the connector configuration file (Config.json).
Start the Windows Service.
Next steps
After completing these steps, Visualization Suite should start receiving Live Face Matching alerts.
See the Live Face Matching documentation for the instructions for installing and configuring the application.
See Installation Guide for the instructions for installing and configuring the connector. For the download instructions, go to Navigating TISC.
Alert entity type properties
Key | Label | Attribute type |
alert_id | Alert ID | text |
camera_name | Camera Name | text |
similarity | Similarity | numeric |
last_name | Last Name | text |
middle_name | Middle Name | text |
first_name | First Name | text |
person_id | Person ID | text |
alert_image_original | Alert Image | image |
facial_thumbnail | Person Image | image |
birthday | Birthday | date and time |
age | Age | numeric |
gender | Gender | numeric |
nationality | Nationality | numeric |
street | Street | text |
city | City | text |
state | State | text |
zip | Zip | numeric |
group | Group | text |
notes_string | Notes (String) | text |
notes_number | Notes (Number) | numeric |
notes_date | Notes (Date) | date and time |
Config.json example for cloud production
{ "app": { "alert_wait_time": 5, "entity_name_template": "{camera_name} ({similarity}%) - name: {first_name} {last_name}" }, "hvs_settings": { "host": "https://api.hitachismartcamera.com", "username": "EMAIL_ADDRESS", "password": "****", "domain": "YOUR_DOMAIN_NAME" }, "lfm_settings": { "host": "http://LFM_SERVER_IP_ADDRESS/DBAccess.cgi", "password": "***" }, "web_api": { "host": "127.0.0.1", (Or IP of the Server where HVS LFM Connector is installed) "port": 9091 (PORT that configured on LFM client Alert Notice Destination Configuration) }, "local_folders": { "cache": "./alerts_cache", "logs": "./logs", "images": "./images" }, "camera_locations": { "sample_camera_name": { "lon": -79.859619, "lat": 40.108013 }, "default": { "lon": -77.05599310876786, "lat": 38.870921500751344 } }, "person_info_key_map": { "opt_str_01": "last_name", "opt_str_02": "first_name", "opt_str_03": "middle_name", "opt_str_04": "street", "opt_str_05": "state", "opt_str_06": "city", "opt_str_07": "group", "opt_str_08": "notes_string", "opt_int_01": "birthday", "opt_int_02": "age", "opt_int_03": "gender", "opt_int_04": "nationality", "opt_int_05": "zip", "opt_int_06": "notes_number", "opt_int_07": "notes_date" }, "alert_entity_type": { "appearance": { "background_color": "#fe9200", "cluster_marker": { "custom": "", "icon": "camera", "icon_type": "fontawesome", "shape": "" }, "color": "#fe9200", "domain_panel_location": "EVENTS", "has_detail_page": true, "has_preview_panel": true, "icon": "camera", "icon_type": "fontawesome", "location_render_mode": "POINT" }, "attributes": { "camera_name": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Camera Name", "type": "Text" }, "alert_id": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Alert ID", "type": "Text" }, "last_name": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Last Name", "type": "Text" }, "middle_name": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Middle Name", "type": "Text" }, "similarity": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Similarity", "type": "numeric" }, "person_id": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Person ID", "type": "text" }, "first_name": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "First Name", "type": "Text" }, "alert_image_original": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Alert Image", "type": "image" }, "facial_thumbnail": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Person Image", "type": "image" }, "birthday": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Birthday", "type": "date and time" }, "age": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": false }, "label": "Age", "type": "numeric" }, "gender": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": false }, "label": "Gender", "type": "numeric" }, "nationality": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": false }, "label": "Nationality", "type": "numeric" }, "street": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Street", "type": "text" }, "city": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "City", "type": "text" }, "state": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "State", "type": "text" }, "zip": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Zip", "type": "numeric" }, "group": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Group", "type": "text" }, "notes_string": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Notes", "type": "text" }, "notes_number": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Notes", "type": "numeric" }, "notes_date": { "appearance": { "visible": true, "show_in_detail_page": true, "show_in_preview_panel": true }, "label": "Notes", "type": "date and time" } }, "can_not_survive_without_parent": false, "description": "Description of the LFM Alert", "display_name": "LFM Alert", "enabled": true, "entity_creation_notification": { "enabled": true, "message_format": "" }, "has_area": false, "has_timeline": true, "name": "LFM Alert", (Entity Type name is editable, you can change the name) "persistence_on_map": 1800, "refresh_intervals": 10, "visible": true, "visible_on_entities_management": true, "visible_on_nav_panel": true }, "logging": { "version": 1, "disable_existing_loggers": false, "formatters": { "simple": { "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s" } }, "handlers": { "console": { "class": "logging.StreamHandler", "level": "INFO", "formatter": "simple", "stream": "ext://sys.stdout" }, "info_file_handler": { "class": "logging.handlers.RotatingFileHandler", "level": "INFO", "formatter": "simple", "filename": "logs/info.log", "maxBytes": 1000000, "backupCount": 10, "encoding": "utf8" }, "error_file_handler": { "class": "logging.handlers.RotatingFileHandler", "level": "WARNING", "formatter": "simple", "filename": "logs/warning.log", "maxBytes": 1000000, "backupCount": 10, "encoding": "utf8" } }, "root": { "level": "INFO", "handlers": [ "console", "info_file_handler", "error_file_handler" ] } }, "internal": { "entity_type_id": "" (Can be existing LFM Alert Entity Type ID or empty string "") } }
app: alert_wait_time
The time period, in seconds, Visualization Suite waits before creating an entity after it receives an alert. During the wait period, if the application receives more than one alert for the same person and camera combination, it checks the similarity for all alerts and only creates one entity for the alert with the highest similarity score. All other low-scoring alerts are ignored.
Default: 5 seconds
app: entity_name_template
The name template for the alert entities. The values between the curly brackets, "{similarity}", for example, are directly pulled from the alert entity values. All parameters for the "Person Info Key Map" attributes as well as the following are variable:
- similarity
- camera_name
- person_id
- alert_id
Default: "{camera_name} ({similarity}%) - name: {person_name} {last_name}"
Example: Cam 123 (75%) - Jon Doe
As with any JSON file, the special characters need to be escaped. Check the following:
- \b Backspace (ascii code 08)
- \f Form feed (ascii code 0C)
- \n New line
- \r Carriage return
- \t Tab
- \" Double quote
- \\ Backslash character
Also, the bracket system supports additional properties. For more information, please refer to: https://docs.python.org/3.4/library/string.html#format-specification-mini-language
hvs_settings: host
The Visualization Suite API address:
- Cloud Staging URL: https://api.hitachismartcam.com/
- Cloud Production URL: https://api.hitachismartcamera.com/
hvs_settings: domain
The name of the Visualization Suite domain name
lfm_settings: host
The Live Face Matching (LFM) server address, http://<LFM_SERVER_URL>/DBAccess.cgi
Note:
- The Live Face Matching server must be reachable from the server where the connector is installed.
- HTTPS is not supported by Live Face Matching.
To test connectivity, open a browser on the server where the connector is installed, and go to the Live Face Matching server. If the server is not accessible, the following error message is returned: CGI Error.Request Message URI[/DBAccess.cgi].'cmd=' : Parameter is not found.
lfm_settings: password
The credentials to access to the Live Face Matching server
web_api: host
The host server where the connector is installed. You can use 127.0.0.1 or the IP address of the system.
The Live Face Matching client must be configured to send Live Face Matching alerts to the system. For details, see the "Alert Notice Destination Configuration" topic of the Live Face Matching Operations Guide.
The application exposes a web API endpoint for the Live Face Matching server to send the alerts. Make sure the IP address and port match the alert destination configuration in the Live Face Matching Client.
web_api: port
The port value that is configured in the Alert Notice Destination Configuration section in the Live Face Matching Client. For details, see the Live Face Matching Operations Guide.
In order to receive alerts, the alert destination for the Live Face Matching client must configured. Make sure that the port is available and can be used from the Live Face Matching Client.
camera_locations
Each key refers to a camera name. The default key is used for any unmatched camera names.
For example:
"CAMERA_NAME": { "lon": -79.859619, "lat": 40.108013 },
Note: The "CAMERA_NAME" is case sensitive, and must match with the camera name in LFM.
"Camera_001": {"lon": 101.6872215270996, "lat": 3.108291736889529}
person_info_key_map
The key values in this dictionary refer to the fields received from the person details API call from the Live Face Matching server. The values refer to the attribute names that will be used in the Visualization Suite entity. For example:
hvs_entity["attributes"]["personname"] = lfm_person_details["opt_str_02"].
In most cases, the defaults should be correct.
alert_entity_type
This is the entire Visualization Suite entity type definition for the Live Face Matching alert. This will be used when creating an entity type. For details, refer to the Visualization Suite API documentation.
alert_entity_type: name
The name of the Visualization Suite entity type for Live Face Matching alerts. Default is LFM Alert. You can specify a different name as long as the entity type is not already taken.
alert_entity_type: persistence_on_map
See Persistence on Map in Entity Management.
alert_entity_type:refresh_intervals
See Refresh Interval in in Entity Management.
logging
The logging configuration. Typically, keeping the default settings is fine.
Supported Log Level
- CRITICAL
- ERROR
- WARNING
- INFO
- DEBUG
- NOTSET
internal: entity_type_id
This field hosts the entity_type_id used to create new entities in Visualization Suite.
Do not change this field while the application is running:
- If this field is null or contains an empty string, the application attempts to create the entity type during startup and update the config file with the ID.
Otherwise, if you manually populate the field and if the entity type ID does not exist, the application generates an error during entity creation.
Make sure this field is either empty when running the application for the first time, or if you manually populate the field, verify that it contains correct data (for example, it specifies an entity type that exists in the target Visualization Suite).
- The default should be an empty string when running the application for the first time. The application should create the entity type and update the ID. After that, subsequent restarts off the application should use the newly populated ID.
- If this field is null or contains an empty string, the application attempts to create the entity type during startup and update the config file with the ID.
Installing multiple Live Face Matching connector service instances
- Install a single instance of the Live Face Matching connector service on as many separate systems as you need using the installer.
- Install multiple Live Face Matching connector services on one system. This has fewer infrastructure requirements, but you need to create a Window service manually by following the steps below.
Before you begin
Procedure
Copy the Hitachi Visualization Suite Live Face Matching Connector folder.
Example: C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.X.Paste the folder in C:\Program Files\Hitachi Vantara\
Rename the copied folder.
Example: C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.X-2Delete the pkgs\logs folder.
Launch the Command Prompt as an Administrator.
Navigate to the folder you duplicated in the step 3, then run the commands.
Before running the following commands, replace the following italicized values accordingly. You can check the Windows Service Manager for the current Live Face Matching connector service name.- ${SERVICE_NAME}
- ${PRODUCT_NAME}/
- ${PRODUCT_VERSION}
"nssm.exe" install "${SERVICE_NAME}" "$INSTDIR\Python\python.exe" "nssm.exe" set "${SERVICE_NAME}" AppDirectory "$INSTDIR\pkgs" "nssm.exe" set "${SERVICE_NAME}" DisplayName "${PRODUCT_NAME} ${PRODUCT_VERSION}" "nssm.exe" set "${SERVICE_NAME}" Description "${PRODUCT_NAME} ${PRODUCT_VERSION}" "nssm.exe" set "${SERVICE_NAME}" AppParameters web_api.py "nssm.exe" set "${SERVICE_NAME}" AppStdout "output.log" "nssm.exe" set "${SERVICE_NAME}" AppNoConsole 1
The following shows example command lines:"nssm.exe" install "HVSLFMConnector2" "C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.1-2\Python\python.exe" "nssm.exe" set "HVSLFMConnector2" AppDirectory "C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.1-2\pkgs" "nssm.exe" set "HVSLFMConnector2" DisplayName "HVS LFM Connector 6.0.0.1-2" "nssm.exe" set "HVSLFMConnector2" Description "HVS LFM Connector 6.0.0.1-2" "nssm.exe" set "HVSLFMConnector2" AppParameters web_api.py "nssm.exe" set "HVSLFMConnector2" AppStdout "output.log" "nssm.exe" set "HVSLFMConnector2" AppNoConsole 1
Open Windows Services.
Verify that a new HVS LFM Connector window service is created.
Open the services properties.
Click Log On.
Check Allow service to interact with desktop.
Click Apply.
Click OK.
If necessary, update the Hitachi Visualization Suite Live Face Matching connector configuration file, such as the Live Face Matching server address and port.
Save your changes.
Start Window Services.
Check the pkgs\logs folder and verify that files are created.
Uninstalling the Live Face Matching connector
Stop the HVS LFM Service from the Windows Service.
Close all File Explore windows.
Open
.Select HVS LFM Connector.
Click and select uninstall.
After the uninstall has completed, open or refresh the Windows Service and the Control Panel and confirm that HVS LFM connector is removed.
Manually removing a service
Launch the Command Prompt as an Administrator.
Navigate to the \pkgs folder where the Hitachi Visualization Suite Live Face Matching connector is installed.
For example: C:\Program Files\Hitachi Vantara\HVS LFM Connector VERSION\pkgsType the following: nssm remove <servicename>
Frequently asked questions
If the log file does not reflect the error details, use the command prompt to check for the error information, according to the following procedure:
- Open the Command prompt as an administrator.
- Navigate to where the Hitachi Visualization Suite Live Face Matching connector is installed. For example: C:\Program Files\Hitachi Vantara\HVS LFM Connector X.X.X.X (cd "C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.2")
- Navigate to the pkgs folder (cd pkgs).
- Type the following: "C:\Program Files\Hitachi Vantara\HVS LFM Connector X.X.X.X\Python\python.exe" web_api.py
- Press Enter.
Either the service will run or information about the service start error will be displayed, as shown in the following example.
C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.2\pkgs>"C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0. 0.2\Python\python.exe" web_api.py Traceback (most recent call last): File "web_api.py", line 5, in <module> import cv2 File "C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.2\pkgs\cv2\__init__.py", line 3, in <module> from .cv2 import * ImportError: DLL load failed: The specified module could not be found.
Default location: C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.XX\pkgs\logs
Hitachi Visualization Suite Live Face Matching Connector logs are not available on windows event viewer.
HTTPS is not supported.
Check the Live Face Matching Client "Alert Notice Destination Configuration" and make sure that the Hitachi Visualization Suite Live Face Matching connector specifies the port that is configured on the Live Face Matching Client. See the Live Face Matching Operations Guide. You can first test to make sure whether the Live Face Matching Client can receive alerts on the Live Face Matching Client. Once you verify that Live Face Matching Clients can receive alerts, then check that ports are not blocked.
Check the log files at C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.XX\pkgs\logs to find the error message. When you do not see Entity Type on Hitachi Visualization Suite, issue likely having wrong endpoints, wrong credential, the entity type name already exist on the system (entity type name must be unique within domain).
Check the "Persistence on Map" value on the entity type management page to see how long the marker stays on the Map:
. Check that the entity exists using either search or page.Check the "Persistence on Map" value on the entity type management page to see how long the marker stays on the Map:
. You can shorten the length of time to reduce the number of the map markers on the Map.You can uninstall from HVS LFM connector to uninstall. Before uninstalling, backup the config.json file and close all open files.
and selectComplete the following procedure:
- Stop Hitachi Visualization Suite Live Face Matching connector from the window services: Log in to HVS, delete the LFM Alert entity type from Map >> Settings >> Entity Types >> Select LFM Alert Type and click delete.
- Log in to Hitachi Visualization Suite.
- Navigate to
- Select LFM Alert Type.
- Click delete.
- Open C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.XX\pkgs\config.json file.
- Remove entity_type_id and replace with
""
, then restart the Hitachi Visualization Suite Live Face Matching connector to create a new Entity Type.