Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

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.

GUID-6E8C58DB-A5F1-461D-9F75-3EF858AB8581-low.png

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

The connector for enables you to view Live Face Matching alerts in the Visualization Suite interface. Configuring Live Face Matching alerts to be ingested to Visualization Suite as events involves the following steps:

Procedure

  1. Configure the Live Face Matching server.

  2. Configure the Live Face Matching client server.

  3. Configure the identify server to send alert notifications to Visualization Suite (Alert Notice Destination Configuration).

  4. Install the Live Face Matching connector.

  5. Edit the connector configuration file (Config.json).

  6. 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.

NoteSome links are restricted to users with certain permissions. Not all links will be available for all users.

Alert entity type properties

KeyLabelAttribute type
alert_idAlert IDtext
camera_nameCamera Nametext
similaritySimilaritynumeric
last_nameLast Nametext
middle_nameMiddle Nametext
first_nameFirst Nametext
person_idPerson IDtext
alert_image_originalAlert Imageimage
facial_thumbnailPerson Imageimage
birthdayBirthdaydate and time
ageAgenumeric
genderGendernumeric
nationalityNationalitynumeric
streetStreettext
cityCitytext
stateStatetext
zipZipnumeric
groupGrouptext
notes_stringNotes (String)text
notes_numberNotes (Number)numeric
notes_dateNotes (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:

  • 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.

Installing multiple Live Face Matching connector service instances

The Live Face Matching connector installer can install only one instance of a Window service for the Hitachi Visualization Suite Live Face Matching connector. If you have multiple Live Face Matching servers and require multiple connector services, you have two options:
  • 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

If you have not already installed the Live Face Matching connector for Visualization Suite, install and configure it first, and then test it to ensure it is working properly.

Procedure

  1. Copy the Hitachi Visualization Suite Live Face Matching Connector folder.

    Example: C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.X.
  2. Paste the folder in C:\Program Files\Hitachi Vantara\

  3. Rename the copied folder.

    Example: C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.X-2
  4. Delete the pkgs\logs folder.

  5. Launch the Command Prompt as an Administrator.

  6. 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
  7. Open Windows Services.

  8. Verify that a new HVS LFM Connector window service is created.

  9. Open the services properties.

  10. Click Log On.

  11. Check Allow service to interact with desktop.

  12. Click Apply.

  13. Click OK.

  14. If necessary, update the Hitachi Visualization Suite Live Face Matching connector configuration file, such as the Live Face Matching server address and port.

  15. Save your changes.

  16. Start Window Services.

  17. Check the pkgs\logs folder and verify that files are created.

Uninstalling the Live Face Matching connector

  1. Stop the HVS LFM Service from the Windows Service.

  2. Close all File Explore windows.

  3. Open Control Panel Programs and Features.

  4. Select HVS LFM Connector.

  5. Click and select uninstall.

  6. 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

  1. Launch the Command Prompt as an Administrator.

  2. 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\pkgs
  3. Type the following: nssm remove <servicename>

Frequently asked questions

The Hitachi Visualization Suite Live Face Matching Connector window service does not start and an error message displays. GUID-04EC7745-E199-4B01-95D4-3777D3B2EADF-low.png

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:

  1. Open the Command prompt as an administrator.
  2. 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")
  3. Navigate to the pkgs folder (cd pkgs).
  4. Type the following: "C:\Program Files\Hitachi Vantara\HVS LFM Connector X.X.X.X\Python\python.exe" web_api.py
  5. 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.
Where can I see the log files?

Default location: C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.XX\pkgs\logs

I cannot find Hitachi Visualization Suite Live Face Matching Connector logs in the windows event viewer.

Hitachi Visualization Suite Live Face Matching Connector logs are not available on windows event viewer.

Does Live Face Matching support HTTPS?

HTTPS is not supported.

I don't receive any alerts from Live Face Matching.

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.

An Live Face Matching Alert entity type is not created on Hitachi Visualization Suite.

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).

No Live Face Matching Alerts are populated on the Hitachi Visualization Suite Map.

Check the "Persistence on Map" value on the entity type management page to see how long the marker stays on the Map: Map settings Entity type click the gear icon. Check that the entity exists using either search or Map settings Entity typepage.

Too many Live Face Matching Alerts are shown on the Hitachi Visualization Suite Map.

Check the "Persistence on Map" value on the entity type management page to see how long the marker stays on the Map: Map settings Entity type click the gear icon. You can shorten the length of time to reduce the number of the map markers on the Map.

How can I uninstall the Live Face Matching connector

You can uninstall from Control Panel All Control Panel Items Programs and Features and select HVS LFM connector to uninstall. Before uninstalling, backup the config.json file and close all open files.

How do I delete previously generated Live Face Matching Alerts on Hitachi Visualization Suite?

Complete the following procedure:

  1. 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.
    1. Log in to Hitachi Visualization Suite.
    2. Navigate to Map Settings Entity Types
    3. Select LFM Alert Type.
    4. Click delete.
  2. Open C:\Program Files\Hitachi Vantara\HVS LFM Connector 6.0.0.XX\pkgs\config.json file.
  3. Remove entity_type_id and replace with "", then restart the Hitachi Visualization Suite Live Face Matching connector to create a new Entity Type.