SmartFace Station

Please see below advanced guides for the SmartFace Station. The guides are split into few categories:

• Configuration
• Personalization

Configuration#

These guides are focusing at advanced configuration, actions and settings that are not covered in the SmartFace Station manuals.

Mounting a video as a camera source#

In the SmartFace Station you can mount a video file instead of the RTSP stream if needed. To mount a video the video needs to be accessible to the browser accessing both the SmartFace Station and the video.

The easiest way to achieve availability of a video is to upload it into the SmartFace’s S3 bucket in the Min.IO object database.

Uploading a Video into Min.IO#

To upload a video into the Min.IO please visit your Min.IO’s on the port 9000, if you are using the same machine as it is installed on the URL would look like: http://localhost:9000. You will be redirected to http://localhost:9001/login. Here you can log in using the default username minioadmin and password minioadmin. It is recommended to change this for security reasons.

Once you are logged in, you can click on the Create Bucket + button to create a new bucket. We will use this bucket to separate our additional videos from the internally managed data from the SmartFace platform.

In the Create Bucket page pick a name. For the example purposes we will use the name videos.

The newly created bucket will be now available in the list of buckets. Click the Browse -> button.

To upload a video, click on the click the Upload button. Uploaded files are visible.

To ensure we can use the videos for our intended purposes we need to adjust the access policy. The Default private policy might be the right one for us. Please click on the Manage button for the bucket. Then click on the Access Policy.

Pick the right policy. In our example we will use public.

Adding a Video as a RTSP camera source#

To use the video in a new camera, click on REGISTER CAMERA button. In the camera configuration in the SmartFace Station. As a RTSP / VIDEO SOURCE use the full path to the uploaded video. Unless configured differently, for the URL please use the http://minio:9000/ then the name of the bucket and the name of the file. In such a case the full URL to be used will be http://minio:9000/videos/facetest.mp4.

How to disable video looping on video as a camera source#

When you use a video as an input source, per default the video will be repeating on a loop. To avoid infinite looping we can set the video to run only once.

To disable looping, set ProcessVideoOnlyOnce parameter of a camera to true. It can be done via the REST API. This parameter is hidden and it will be not be visible as an option in the swagger. To change specific camera configuration, use PUT command of Camera endpoint.

A sample of an incomplete put command is below:

{
    "spoofDetectorResourceIds": [
      "none"
    ],
    "id": "53519cb1-c75e-4ad2-44cd-08da8fde8bfe",
    "name": "Video Input Camera",
    "source": "http://minio:9000/videos/facetest.mp4",
    "enabled": true,
    "ProcessVideoOnlyOnce": true,
    "faceDetectorConfig": {
      "minFaceSize": 20,
      "maxFaceSize": 300,
      "maxFaces": 20,
      "confidenceThreshold": 600
    },
    "pedestrianDetectorConfig": {
      "minPedestrianSize": 80,
      "maxPedestrianSize": 2000,
      "maxPedestrians": 20,
      "confidenceThreshold": 2500
    },
    "faceDetectorResourceId": "cpu",
    "templateGeneratorResourceId": "cpu",
    "pedestrianDetectorResourceId": "none",
    .
    .
    }
  }

How to use an USB Camera in the SmartFace#

You can use USB cameras, such as web cameras with the SmartFace. The configuration does differ between the Windows and the Docker environments.

Windows Environment#

In the Windows environment as long as the USB camera is recognized and the drivers are up to date, you can simply use the number of the camera in the Device Manager on Windows. Please note the count starts from 0. When registering a new camera, in our example we will put 0 as an RTSP/VIDEO SOURCE.

Linux Docker Environment#

In the Linux Docker environment we are using gstreamer configuration string. If the camera is up and running correctly then we use the device’s mount point from the /dev/ directory. As an example we will use the device video0.

Update the docker-compose.yml#

In the Linux Docker environment we need to allow the camera service to access the device. Please add these lines under the camera service:

devices:
      - /dev/video0:/dev/video0

For a sample camera SFCam2, the docker-compose.yml setup would look like this:

sf-cam-2:
    image: ${REGISTRY}sf-cam:${SF_VERSION}
    container_name: SFCam2
    command: --serviceName SFCam2
    ports:
      - 30002:${CameraDefaults__PreviewPort}
    restart: unless-stopped
    devices:
      - /dev/video0:/dev/video0
    environment:
      - RabbitMQ__Hostname
      - RabbitMQ__Username
      - RabbitMQ__Password
      - RabbitMQ__Port
      - RabbitMQ__VirtualHost
      - RabbitMQ__UseSsl
      - ConnectionStrings__CoreDbContext
      - Database__DbEngine
      - AppSettings__Log_RollingFile_Enabled=false
      - AppSettings__USE_JAEGER_APP_SETTINGS
      - JAEGER_AGENT_HOST
      - S3Bucket__Endpoint
      - S3Bucket__BucketName
      - S3Bucket__AccessKey
      - S3Bucket__SecretKey
    volumes:
      - "./iengine.lic:/etc/innovatrics/iengine.lic"

To apply changes use docker-compose up -d command.

Set source using the gstreamer string#

Then a sample gstreamer string will be v4l2src device=/dev/video0 ! video/x-raw, format=YUY2, pixel-aspect-ratio=1/1, width=1280, height=720, framerate=10/1 ! videoconvert ! appsink.

Please add this string as an RTSP/VIDEO SOURCE for a camera.

How to enable video uploading for Rapid Video Investigation#

The SmartFace Station is managing the interaction between the SmartFace Platform and the user web browser. During the installation the run.sh script sets the paths for the S3/Min.IO endpoint. This is set to your hostname. If the hostnames are not correcly set for the network and the machines on it, it is possible that in some cases the hostname set for the machine where the SmartFace Platform is running is not accesible to the machine running the browser. This means that the user’s browser can not see the Min.IO path correctly. In this case the upload of a video is not possible.

This situation was updated in the SmartFace Platform version 5.4.22. If you are using and older version and this happens to you, or you are using a newer version and this issue occurs to you, please adjust the S3_ENDPOINT to match your ip, that is accessible for both the SmartFace Station container and the user via a web browser.

To fix the issue for your installation please edit .env.sfstation and update the S3_ENDPOINT to match your ip address as below:

# Setup for S3 / MinIO API
S3_ENDPOINT=http://your-ip-address:9000

How to enable Identification tab#

To enable the Identification tab, you need to enable it in the docker configuration and you need to have https certificate on your server.

Enablement in the docker configuration#

Open the directory where your SmartFace Platform’s docker-compose.yml is located. Edit the file .env.sfstation and locate the lines below:

#Enabled Identification page
IDENTIFICATION_ENABLED=false

Adjust the IDENTIFICATION_ENABLED line to be true:

#Enabled Identification page
IDENTIFICATION_ENABLED=true

Restart the SFStation service. An easiest way to achieve it is to use this command in the same directory:

docker-compose up -d

Enabling of the HTTPS Certification#

To enable the HTTP Certification please read the guide in here.

Testing the results of the enablement#

Once you access the SF Station on the port 8000 again, then an additional tab is available:

How to enable local Camera usage#

To enable camera usage in the Identification Dashboard and in the Watchlist Management tab, please ensure the secure https connection is enabled or your Chrome web browser considers your SmartFace Station to be trusted.

Then you can proceed with enabling the Camera usage in the .env.sfstation environment variables configuration file for the docker installation. Please find the configuration below and set the DOT_FACE_CAMERA_ENABLED to be true.

# DOT camera parameters (HTTPS is required)
DOT_FACE_CAMERA_ENABLED=true
DOT_FACE_CAMERA_FACE_CENTER_LIMIT=0.2
DOT_FACE_CAMERA_FACE_CONFIDENCE=0.06

Enabling HTTPS (Certification)#

You can can enable and configure the HTTPS Certificate in the .env file. If it is enabled, the Smartface Station would run on https://your-domain. Please note that backend services behind the SmartFace Station server can still use http://.

Configuring the .env file#

Please adjust (and add if necessary) values listed in the table below

Please put your server.key and server.cert files next to .env file or specify a full path.

To apply the changes, please run the command:

docker compose up -d

Generating your own local certificate#

Certificate have to be obtained from verified certificate authority or generated on local machine. For local testing and development purposes it is possible to generate your own certificate. If it is generated on local machine it can be considered by Internet browser as untrusted.

Become local certificate authority#

To obtain myCA.key (your private key) and myCA.pem (your root certificate) use the terminal commands below.

mkdir ~/certs
cd ~/certs

//generate the private key to become a local CA
openssl genrsa -des3 -out myCA.key 2048

//generate a root certificate
openssl req -x509 -new -nodes -key myCA.key -sha256 -days 1825 -out myCA.pem -reqexts v3_req -extensions v3_ca

Apply the local certificates#

The locally generated certificates can be applied to browsers. The steps differ depending on the device/OS you are using

Mac#

Please run the command below using the myCa.pem file generated:

sudo security add-trusted-cert -d -r trustRoot -k "/Library/Keychains/System.keychain" myCA.pem

Windows#

Please follow the below steps for adding the Root Certificate to Windows 10:

1. Open the “Microsoft Management Console” by using the Windows + R keyboard combination, typing mmc and clicking Open
2. Go to File > Add/Remove Snap-in
3. Click Certificates and Add
4. Select Computer Account and click Next
5. Select Local Computer then click Finish
6. Click OK to go back to the MMC window
7. Double-click Certificates (local computer) to expand the view
8. Select Trusted Root Certification Authorities, right-click on Certificates in the middle column under “Object Type” and select All Tasks then Import
9. Click Next then Browse. Change the certificate extension dropdown next to the filename field to All Files (.) and locate the myCA.pem file, click Open, then Next
10. Select Place all certificates in the following store. “Trusted Root Certification Authorities store” is the default. Click Next then click Finish to complete the wizard.

Linux#

For Linux you can install certificate to google chrome (setting → security → manage certificates → add certificate authority → select myCA.pem) or you can add the root certificate. This guide is focusing on Ubuntu Linux distribution.

1. If it isn’t already installed, install the ca-certificates package.

sudo apt-get install -y ca-certificates

2. Copy the myCA.pem file to the /usr/local/share/ca-certificates directory as a myCA.crt file.

sudo cp ~/certs/myCA.pem /usr/local/share/ca-certificates/myCA.crt

3. Update the certificate store.

sudo update-ca-certificates

iOS#

Adding the Root Certificate to iOS 14 can be done by following these steps:

1. Email the root certificate to yourself, so you can access it on your iOS device. Make sure to use the default Mail app to access the email.
2. Tap on the attachment in the email on your iOS device. It will prompt you to review the profile in the Settings app.
3. Open the Settings app and click Profile Downloaded near the top.
4. Click Install in the top right, and then Install again on the Warning screen.
5. Once installed, hit Close and go back to the main Settings page.
6. Go to General > About.
7. Scroll to the bottom and click on Certificate Trust Settings.
8. Enable your root certificate under “ENABLE FULL TRUST FOR ROOT CERTIFICATES”.

Android#

On Android devices, if you move the file manually via USB tether, you can go to Lock screen and security > Other security settings > Install from device storage, then navigate to the certificate file to install it. On older Android devices, the path might be Settings > Security & Screen Lock > Install from storage.

Creating CA-Signed Certificates for Smartface#

As an alternative to locally generate and supply the certificates on the device/browser level you can also generate your own certificates that will be used directly by the SmartFace Station. To do so, please follow the steps below:

openssl genrsa -out smartface.test.key 2048

//create a CSR
openssl req -new -key smartface.test.key -out smartface.test.csr

Create smartface.test.ext (X509 V3 certificate extension config file, which is used to define the Subject Alternative Name (SAN) for the certificate)

smartface.test.ext should contain

authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names

[alt_names]
DNS.1 = your-hostname

Now we run the command to create the certificate: using our CSR, the CA private key, the CA certificate, and the config file:

openssl x509 -req -in smartface.test.csr -CA myCA.pem -CAkey myCA.key -CAcreateserial -out smartface.test.crt -days 825 -sha256 -extfile smartface.test.ext

We now have two files: smartface.test.key (the private key) and smartface.test.crt (the signed certificate) which we can use in smartface (copy them next to .env and set HTTPS_KEY_FILE=smartface.test.key and HTTPS_CERT_FILE=smartface.test.crt)

Making SmartFace Station trusted for Chrome#

For local development and for testing purposes it might be useful to make the SmartFace Station trusted for the Google Chrome web browser. For production environments we recommend to enable secure https connection. This would allow you to use the local computer’s camera functionality, such as the Identification Dashboard or to allow Watchlist member registration in the Watchlist Management Dashboard directly from the web browser using the web camera.

To make the SmartFace Station trusted in Chrome please follow these steps:

1. Enter the following URL using your Google Chrome: chrome://flags/#unsafely-treat-insecure-origin-as-secure
2. Find the section Insecure origins treated as secure. Add your URL including the port (default is port 8000). For example: http://smartface-installation:8000 or http://192.168.0.100:8000
3. Change the dropdown button to Enabled
4. Click Relaunch to apply changes

5. You can check if the Camera Preview option is available in the Identification Dashboard. Please ensure the DOT_FACE_CAMERA_ENABLED is true as explained in the How to enable local Camera usage guide.

Logging in SmartFace Station#

IYou can configure and enable loging in the .env file . By default Logging is enabled and logging to file is disabled.

Windows The location of the env file is C:\Program Files (x86)\SmartFace Station\.env.

Docker The location of the env file is .env.sfstation.

Personalization#

These guides are focusing at personalizing the experience with the SmartFace Station

How to apply branding to the SmartFace Station’s Feedback Display#

The Feedback Display can be branded so it has it’s own layout, texts and animations.

In a Windows installation there is a branding folder located within the SmartFace Station installation folder. The default path is C:\Program Files (x86)\SmartFace Station\branding. In Docker installation you need to add such folder into you file system and bind it in your docker-compose.yml file:

  sf-station:
    image: ${REGISTRY}sf-station:${SFS_VERSION}
    container_name: SFStation
    restart: unless-stopped
    ports:
      - 8000:8000
    volumes:
      - "./branding:/build/branding"
    env_file: .env.sfstation

The branding folder has these files:

naming-product.json
logo-product.svg
logo-product-without-text.svg
logo-company.svg
feedback-display-top-image.svg
feedback-display-error.svg
feedback-display-bottom-image.svg
feedback-display-access-denied-not-identified.svg
feedback-display-access-denied-block-or-spoof.svg
favicon-product.ico
empty-display.gif

The files can be changed, updated and replaced to match your needs. This includes the empty-display.gif file that can show an animation during the time that noone is in front of the camera.

In the naming-product.json file you can adjust the texts provided by the Feedback Display. This includes the strings being shown when you have an access granted, when you are being denied, or when you are requested to put on a mask.

{
  "windowTitle": "SmartFace Station",
  "configSection": "SmartFace Platform",
  "feedbackDisplayErrorMessage": "Error",
  "feedbackDisplayAccessGrantedWelcomeMessage": "Welcome",
  "feedbackDisplayDeniedNotIdentifiedMessage": "Passage is not allowed",
  "feedbackDisplayDeniedBlockedOrSpoofMessage": "Passage is not allowed",
  "feedbackDisplayPutOnYourMaskMessage": "Put on your mask please"
}

To apply the changes, please restart the SmartFace Station service. The easiest way would be to run the following code:

docker compose up -d

How to apply and manage labels#

The SmartFace Station allow to enable labels for each watchlist member. It is a set of key/value pairs that can be shown in the SmartFace Station. To present such labels you need to enable them and then you need to add this information to watchlist members.

In an example below you can see “Date of birth”, “Tax number” and “Phone number” labels.

Enabling labels in the SmartFace Station#

Please edit .env.sfstation in your installation folder with a text editor.

Uncomment/apply changes to the section below:

# Add optional labels to watclist member (key is used in API requests, label is visual representation of key and used only in station frontend)
WATCHLIST_MEMBER_KEY_0=date
WATCHLIST_MEMBER_LABEL_0=Date of birth
WATCHLIST_MEMBER_KEY_1=tax_number
WATCHLIST_MEMBER_LABEL_1=Tax number
WATCHLIST_MEMBER_KEY_2=phone
WATCHLIST_MEMBER_LABEL_2=Phone number

Apply changes to the SmartFace Station, so the configuration reloads. The easiest way to achieve this is to run the command below:

docker compose up -d

Please observe any match notification in the SmartFace station to ensure the labels are shown for any watchlist member.

Adding label data to watchlist members#

You can change the values for each label either directly in the SmartFace Station, or via the RESP API on the port 8098.

To update the values, please run a REST API request, such as below:

{
	"displayName": "Juraj",
	"fullName": null,
	"note": "",
	"labels": [],
	"id": "88866909-54ea-4c09-8673-2a95aa370180",
	"createdAt": "2023-10-25T10:16:56.899082Z",
	"updatedAt": "2023-10-25T10:17:05.337245Z",
	"labels": 
	[
		{
		  "key": "date",
		  "value": "11/01/2023"
		},
		{
		  "key": "tax_number",
		  "value": "123456789"
		},
		{
		  "key": "phone",
		  "value": "004219123456789"
		}
	]
}

Once applied, the values are visible together with the keys in the SmartFace Station.

How to setup SmartFace Station Presets#

The SmartFace allows to use several presets meant for different users, who have different roles. The preset’s lock out options and the user is not allowing to do certain actions.

Available SmartFace Station roles#

The default role is the admin (administrator) of the whole SmartFace Station - can see/change everything. There are 3 specific roles Access, Investigation and Security with 3 levels each - Operator, Supervisor and Administrator

Access#

SmartFace Station Functionality Per Role Level for the Access. The Starting Page is http://localhost:8000/access-control

Investigation#

SmartFace Station Functionality Per Role Level for the Investigation. The Starting Page is http://localhost:8000/investigation/

Security SmartFace Station Functionality Per Role Level for the Security. The Starting Page is http://localhost:8000/security

How to Setup the Roles#

The file .env.sfstation is located in the same folder as the main docker-compose.yml. There is a section in this file that allows you to configure what role is to be used in the SmartFace Station. This allows you to focus on the functionality related to the role and to hide functionality that should not be related to the role of the user.

The section of the file .env.sfstation is listed below:

# Optional roles are used for locking specified part of frontend for given roles
# Claim name is "Group mapper name" specified in Keycloak or "cognito:groups" in Cognito
# ROLES_CLAIM_NAME=sf_roles
# ROLE_KEY_ADMIN=/admin
# ROLE_KEY_SECURITY_SUPERVISOR=/security_supervisor
# ROLE_KEY_SECURITY_OPERATOR=/security_operator
# ROLE_KEY_ACCESS_SUPERVISOR=/access_supervisor
# ROLE_KEY_ACCESS_OPERATOR=/access_operator
# ROLE_KEY_INVESTIGATION_SUPERVISOR=/investigation_supervisor
# ROLE_KEY_INVESTIGATION_OPERATOR=/investigation_operator
# ROLE_KEY_SECURITY_ADMIN=/security_admin
# ROLE_KEY_ACCESS_ADMIN=/access_admin
# ROLE_KEY_INVESTIGATION_ADMIN=/investigation_admin
# FORCED_ROLE_NAME_0=/admin

By adjusting the line # FORCED_ROLE_NAME_0=/admin you can adjust the role to be used. So to change the role to access operator instead of the `admin role, you can set the line as this:

FORCED_ROLE_NAME_0=/access_supervisor

Please do not forget to remove the # symbol as only then is the new configuration applied. Once the role is applied please save the configuration file and restart the SmartFace Station docker container. It easiest way to achieve this is to run the commands below in the same folder as is the docker-compose.yml file.

docker-compose stop;docker-compose down;docker-compose up -d

Please note that the roles can also be applied dynamically to specific users. Together with restricting access to specific ports this can be done via Keycloak setup.