Skip to main content
Version: 1.3.1


Deployment 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 FileDescription
./cfg/image-api.values.yamlA configuration file of Image API instance deployment
./cfg/package.settings.cfgA configuration file of dependencies for installation of Kubernetes cluster
./cfg/smc.settings.cfgA 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_address is the internal IP address of the machine for deployment.
  • external_ip_address is 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:

  • is a domain name used in ingress to route requests to Kubernetes services.

IP address for domain name <> should be configured at DNS server.

Install Dependencies

If the system has no Docker, Kubernetes or Helm, run the command below:

$ ./ package install

Upload Images

Upload docker-images image-api to local registry:

$ ./ image-api load-images

Upload the smc docker images to your local registry:

$ ./ 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:

$ ./ smc install

This command performs the following actions:

  1. Setting of docker and host network
  2. Cluster installation
  3. Ingress-controller installation
  4. Flannel installation

To use GPU, install nvidia-device-plugin using the command below:

$ ./ smc nvidia install

To use Horizontal Pod Autoscaler, install metric-server:

$ ./ smc metric-server install

To create image-api secrets in a cluster, run the command below:

$ ./ 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


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 NameFunctions
image_pull_policyThe parameter affects pulling (downloading) container images from registry to deploy an Image API deployment instance. The following field values are available:
  • Always - kubelet (node agent in Kubernetes) pulls an image from registry.
  • Never - image pulling from registry is not applicable. If the image is already present locally, kubelet attempts to launch a container, otherwise, startup fails.
  • IfNotPresent - image is pulled only if it isn’t present locally.[*].configs[*].capturer.nameThe 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 capturer_config field:

  • common_capturer_uld_fda.xml (Configuration file for ULD detector)
  • common_capturer_refa_fda_a.xml (Configuration file for REFA detector)

For more information about configuration files, see the 3DiVi Face SDK documentation.[*].configs[*].recognizer.nameThe 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:

  • method11v1000_recognizer.xml
  • method12v30_recognizer.xml
  • method12v50_recognizer.xml
  • method12v100_recognizer.xml
  • method12v1000_recognizer.xml

For more information about recognizers, identification methods, and recognizer configuration files, see the 3DiVi Face SDK documentation.[*].configs[*].use_avx2Using the AVX2 instructions allows to speed up the recognizers.[*].configs[*].use_cudaThe field value indicates the graphics card usage by the service. This option is available for face-detector-template-extractor.[*].replicasValue of service replicas.[*].configs[*].downscale_ rawsamples_to_preferred_sizeWhen 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_ingressThis parameter enables proxying to image-api services via ingress.
processing.enable_resource_managementThis parameter enables the use of pod resource management in the cluster.
processing.enable_hpaThis parameter enables Horizontal Pod Autoscaler for deployments. Needs metric-server to be installed.
processing.enable_node_selectorThis parameter activates the use of designated nodeSelectors in pods. The labels must be assigned to cluster nodes using the command:
kubectl label nodes <node_name> type=<type>
  • "type": "processing" - node for calculations
  • "type": "generic" - generic node

Install Image API to the Cluster

Launch the script below to install Image API to the cluster:

$ ./ 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-57581/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


To make sure that the system works properly, use the command below:

$ ./ 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 ✓


To delete Image API, run the command below:

$ ./ image-api uninstall


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

  1. Reinstall the secrets.
$ ./ image-api install-secrets
  1. Delete Image API release from the cluster.
$ ./ image-api uninstall
  1. Install Image API release into the cluster.
$ ./ image-api install