Installation
Deployment Preparation
Preparation
Replace a license file face_sdk.lic to the setup folder of the unpacked distribution kit. Further commands should be performed relative to the setup directory.
Configuration
| Configuration File | Description |
| ./cfg/image-api.values.yaml | A configuration file of Image API instance deployment |
| ./cfg/package.settings.cfg | A configuration file of dependencies for installation of Kubernetes cluster |
| ./cfg/smc.settings.cfg | A configuration file of Kubernetes cluster |
1. Open a deployment configuration file ./cfg/smc.settings.cfg in a text editor and set values for the following variables:
apiserver_advertise_addressis the internal IP address of the machine for deployment.external_ip_addressis the public IP address of the machine which DNS will be configured to.
If there is no public IP address, use the internal IP address.
2. Open a deployment configuration file ./cfg/image-api.values.yaml in a text editor and set values for the following variables:
ingress.hostis a domain name used in ingress to route requests to Kubernetes services.
IP address for domain name <ingress.host> should be configured at DNS server.
Install Dependencies
If the system has no Docker, Kubernetes or Helm, run the command below:
$ ./cli.sh package install
Upload Images
Upload docker-images image-api to local registry:
$ ./cli.sh image-api load-images
Upload the smc docker images to your local registry:
$ ./cli.sh smc load-images
Uploading can last for about 5 minutes.
Install and Configure a Cluster
To create and configure the cluster, run the following command:
$ ./cli.sh smc install
This command performs the following actions:
- Setting of docker and host network
- Cluster installation
- Ingress-controller installation
- Flannel installation
To use GPU, install nvidia-device-plugin using the command below:
$ ./cli.sh smc nvidia install
To use Horizontal Pod Autoscaler, install metric-server:
$ ./cli.sh smc metric-server install
To create image-api secrets in a cluster, run the command below:
$ ./cli.sh image-api install-secrets
Cluster Health Check
After initializing the master node, make sure that all nodes are ready for operation. You can check this by running the command below:
$ kubectl get nodes
As a result, the following output will be displayed in the terminal:
NAME STATUS ROLES AGE VERSION
master-node Ready control-plane,master 1d v1.23.8
Deployment
Configuration File Settings (optionally)
Optionally, before installing Image API to a cluster, you can set values for the following fields in the ./cfg/image-api.values.yaml configuration file:
| Field Name | Functions |
| image_pull_policy | The parameter affects pulling (downloading) container images from registry to deploy an Image API deployment instance. The following field values are available:
|
| processing.services[*].configs[*].capturer.name | The field value indicates the name of the configuration file of the selected face detector. Image API uses face detectors from Face SDK - a set of code libraries for development of face recognition solutions. This version of Image API works with two detectors: ULD and REFA. ULD detector allows you to detect faces of different sizes, including masked faces (detection speed is higher than that of REFA). REFA detector provides higher coverage of head rotation angles and maximum quality, including detection of masked faces (detection quality is higher than that of ULD). The following configuration files can be specified as values for the
For more information about configuration files, see the 3DiVi Face SDK documentation. |
| processing.services[*].configs[*].recognizer.name | The field value indicates the name of the face recognizer configuration file. Image API uses a set of recognizers from Face SDK. Each recognizer uses a specific recognition method (algorithm). Generally, Face SDK provides several recognition methods that differ in recognition quality and operating time. For this version of Image API you can specify the following recognizer configuration files:
For more information about recognizers, identification methods, and recognizer configuration files, see the 3DiVi Face SDK documentation. |
| processing.services[*].configs[*].use_avx2 | Using the AVX2 instructions allows to speed up the recognizers. |
| processing.services[*].configs[*].use_cuda | The field value indicates the graphics card usage by the service. This option is available for face-detector-template-extractor. |
| processing.services.[*].replicas | Value of service replicas. |
| processing.services[*].configs[*].downscale_ rawsamples_to_preferred_size | When field is enabled, each sample is downscaled to the suitable size to reduce memory consumption. However, the system performance decreases. It is recommended to leave this field disabled. |
| processing.enable_ingress | This parameter enables proxying to image-api services via ingress. |
| processing.enable_resource_management | This parameter enables the use of pod resource management in the cluster. |
| processing.enable_hpa | This parameter enables Horizontal Pod Autoscaler for deployments. Needs metric-server to be installed. |
| processing.enable_node_selector | This parameter activates the use of designated nodeSelectors in pods. The labels must be assigned to cluster nodes using the command:
|
Install Image API to the Cluster
Launch the script below to install Image API to the cluster:
$ ./cli.sh image-api install
Then run the following command to get the deployment status:
$ kubectl get pods
As a result, the console will display a list of pods (deployment instances), their statuses, the number of restarts, and the pod age. The example of console output:
NAME READY STATUS RESTARTS AGE
image-api-age-estimator-dep-5bf7889dcd-jm46h 1/1 Running 0 1h
image-api-body-detector-dep-6778495696-4zkpm 1/1 Running 0 1h
image-api-emotion-estimator-dep-7c8cdd7c6b-z4vlv 1/1 Running 0 1h
image-api-face-detector-face-fitter-dep-5fb48dcb5… 1/1 Running 0 1h
image-api-gateway-dep-65d4846c59-g2nfj 1/1 Running 0 1h
image-api-gender-estimator-dep-86b9457f9b-2464q 1/1 Running 0 1h
image-api-face-detector-liveness-estimator-dep-7bd… 1/1 Running 0 1h
image-api-mask-estimator-dep-76b958b84b-w7pss 1/1 Running 0 1h
image-api-quality-assessment-estimator-dep-fbf8bc4… 1/1 Running 0 1h
image-api-face-detector-template-extractor-dep-5758… 1/1 Running 0 1h
image-api-verify-matcher-dep-6d66dc4948-lx8j7 1/1 Running 0 1h
Status Running for all pods means that all containers are successfully launched.
Overview of the deployments is given below:
- image-api-gateway-dep: reverse proxy, responsible for unified access to processing services;
- image-api-face-detector-face-fitter-dep: face detection and calculation of anthropometric points and head rotation angles (roll, pitch, yaw);
- image-api-body-detector-dep: body detection;
- image-api-emotion-estimator-dep: estimation of emotions;
- image-api-age-estimator-dep: age estimation;
- image-api-gender-estimator-dep: gender estimation;
- image-api-face-detector-liveness-estimator-dep: the service detects faces and checks if a person in the image is real or fake;
- image-api-mask-estimator-dep: the service checks if a person in the image is wearing a medical face mask;
- image-api-quality–assessment-estimator-dep: image quality assessment;
- image-api-verify-matcher-dep: the service compares two biometric templates to verify whether they belong to the same person;
- image-api-template-extractor-dep: the service detects faces and extracts a biometric template from a face image.
Configure DNS
To allow DNS access, your network server should contain a record that <domain> is available at <external_ip_address>. Variable values can be obtained from the ./cfg/smc.settings.cfg and ./cfg/image-api.values.yaml files filled in in para. Configuration. To perform this configuration, contact your network administrator.
For testing you can specify the IP address and domain in the /etc/hosts file on Linux or C:\Windows\System32\drivers\etc\hosts on Windows. To do this, add a new line <external_ip_address> <host> with the values of the corresponding variables to the end of this file. Please note that you must have administrator rights to edit the hosts file.
To use Image API at the same machine where it is deployed, you can use a script that will automatically add the necessary record to the /etc/hosts file.
$ echo "<external_ip_address> <host>" | sudo tee -a /etc/hosts
Testing
To make sure that the system works properly, use the command below:
$ ./cli.sh image-api test - http://<host>
Test output should be the following:
face-detector-face-fitter ✓
age-estimator ✓
emotion-estimator ✓
gender-estimator ✓
face-detector-liveness-estimator ✓
mask-estimator ✓
quality-assessment-estimator ✓
face-detector-template-extractor ✓
body-detector ✓
face-detector-template-extractor ✓
face-detector-template-extractor ✓
verify-matcher ✓
Deletion
To delete Image API, run the command below:
$ ./cli.sh image-api uninstall
Licensing
Install a license
Unpack Image API distribution kit and move a license file face_sdk.lic (the file is attached to the e-mail) to setup directory.
Update a license
- Reinstall the secrets.
$ ./cli.sh image-api install-secrets
- Delete Image API release from the cluster.
$ ./cli.sh image-api uninstall
- Install Image API release into the cluster.
$ ./cli.sh image-api install