Skip to content

Exadel CompreFace

This adapter hub service can be used to deploy CompreFace, a free and open source facial recognition service developed by Exadel. It can be used to do things such as face identification, face verification, and landmark detection.

This service is intended to be used for demonstrations and solutions where the rate of requests is low and the submitted images are relatively clear and free of defects or artifacts. It should not be used if multiple requests per second are expected or in medium-high security solutions that require a more sophisticated face matching system.

Refer to Exadel's official CompreFace documentation site for detailed instructions on how to configure and use this service.

https://github.com/exadel-inc/CompreFace/tree/master/docs

Requirements

  • Requires a working UIP Adapter Hub
  • Requires a valid TLS server certificate and its private key
  • This adapter hub service requires approximately 4GB of free memory to operate

Warning

CompreFace service requests is a resource intensive operation. If frequent requests are expected the service should be deployed on an adapter hub machine that is not shared with other workloads and has sufficient CPU and memory for your expected workload.

Install HTTPS/TLS Certificate

CompreFace should be configured with an HTTPS/TLS certificate and corresponding private key in order to provide a secure connection for its clients.

Important

Certificates issued by widely-trusted certificate authorities expire after 397 days (13 months) so they must be updated annually. UIP administrators should plan to repeat this procedure as part of their annual maintenance for the UIP system.

The client access system name must be listed within the Subject Alternative Name (SAN) X.509 extension of the HTTPS Certificate explicitly or by wildcard. Run the following OpenSSL command to display the SAN extension of the certificate.

# Display the x.509 Subject Alternative Name of certificate
openssl x509 -noout -ext subjectAltName -in server-cert.pem

Tip

If UIP and Adapter Hub are installed on the same machine you can use the same server certificate and private key that are being used for UIP Client Access. This reduces the number of certificates that must be maintained.

The server certificate file should be placed in the location /etc/wfadapterhub/compreface/cert.pem. The folder can be created by running the command sudo mkdir -p /etc/wfadapterhub/compreface/. (Requires sudo access)

The cert.pem file should contain the server certificate, its private key, and any intermediate CA certificates.

The first and last lines of the host certificate and CA certificates will be the following:

-----BEGIN CERTIFICATE-----

-----END CERTIFICATE-----

The first and last lines of the private key file will be the following:

-----BEGIN PRIVATE KEY-----

-----END PRIVATE KEY-----

If the certificate authority provided a PFX format certificate file it can be converted into a PEM format file compatible with UIP using the following OpenSSL command.

# Extract certificate, private key, and CA chain from PFX (requires password used to create PFX)
openssl pkcs12 -in certificate.pfx -nocerts -nodes -chain -out certificate.pem

If the certificate authority provided a PKCS8 format encrypted private key it will need to be converted to PKCS1 format. It can be converted using the following OpenSSL command.

# Convert PKCS8 private key to PKCS1 (requires password used to encrypt source file)
openssl pkcs8 -in private-pkcs8.key -traditional -out private.key

Install Nginx Config File

In order to configure the CompreFace service's Nginx web server component for secure HTTPS/TLS access you must override its builtin default configuration file.

Right-Click Here and Save link as to download an Nginx configuration file with modifications to use HTTPS/TLS.

  1. Open the downloaded compreface-nginx.conf file in a text editor
  2. Scroll to file section marked NEC change start and locate the line that says server_name <YOUR ADAPTER HUB SERVER>;
  3. Replace the text <YOUR ADAPTER HUB SERVER> with the hostname of your adapter hub server. This name should be included in your certificates Subject Alternative Names (SAN) property.
  4. Save changes, the copy the file to /etc/wfadapterhub/compreface/compreface-nginx.conf (Requires sudo access) .

Add Adapter Hub Service

  1. Navigate to the Adapter Hubs > Adapter Hub Services > Add Adapter Hub Service page
  2. Enter a name for the service (e.g., facematch)
  3. Enable Deploy at create
  4. Select the desired adapter Hub
  5. Within the Template json paste the following...
{
  "name": "Exadel CompreFace",
  "version": "1.2.0",
  "description": "Exadel CompreFace - This application is not sold or supported by NEC.  Please contact Exadel or your SI for support. ",
  "documentation": "https://exadel.com/accelerator-showcase/compreface/",
  "properties": {},
  "services": {
    "compreface": {
      "image": "exadel/compreface",
      "ports": [
        {
          "protocol": "tcp",
          "hostPort": 8000,
          "containerPort": 443
        }
      ],
      "volumes": [
        {
          "type": "volume",
          "source": "compreface-db",
          "target": "/var/lib/postgresql/data"
        },
        {
          "type": "bind",
          "source": "/etc/wfadapterhub/compreface/compreface-nginx.conf",
          "target": "/etc/nginx/conf.d/nginx.conf"
        },
        {
          "type": "bind",
          "source": "/etc/wfadapterhub/compreface/cert.pem",
          "target": "/etc/nginx/cert.pem"
        }
      ]
    }
  },
  "volumes": {
    "compreface-db": {}
  }
}
  1. Modify the hostPort TCP port that the service should listen on if needed (Default: 8000) within the Template json.
  2. Save the adapter hub service to save and deploy the face match service.

Getting Started Using Exadel CompreFace

After the CompreFace service has finished deploying the next step is to browse to its web application and create a login account.

Browse to https://your-adapter-hub:8000/login, select Create an account, and complete the account creation process to log into CompreFace.

The next steps are to Create Application, select the created application to access its services page, and then select Create New to add services to your application.

Choose the desired CompreFace service that you would like to use, such as verification, then select Create Service. This will generate an API access key that can be used to submit requests to the chosen CompreFace service API.

Using CompreFace Face Verification API To Match Faces Between Two Images

This API will evaluate two base64 images and return information regarding the face(s) in those images and a score estimating how much they match.

Sample Workflow

Right-Click Here and Save link as to download a sample workflow that uses this API. It can be loaded into UIP using the UIP > Workflows > Import feature.

Edit the Start step of the imported workflow and modify the compreface_base_url and verification_api_key workflow properties to match your deployment.

Face Verification Base64 Request Format (application/json)

Important

Requests must include an "x-api-key" header with a valid API key value. 401 - Unauthorized will be returned for API authentication failures.

{
    "source_image": "string",
    "target_image": "string"
}

source_image string - Base64 representation of image to match

target_image string - Base64 representation of image to match

Response Format (application/json)

Code 400 - Invalid Request

Code 401 - Unauthorized

Code 429 - Too Many Requests Outstanding

Code 200 - Match results

{
    "result": [
        {
            "source_image_face": {
                "box": {
                    "probability": 0.99989,
                    "x_max": 123,
                    "y_max": 133,
                    "x_min": 21,
                    "y_min": 16
                }
            },
            "face_matches": [
                {
                    "box": {
                        "probability": 0.99995,
                        "x_max": 190,
                        "y_max": 284,
                        "x_min": 38,
                        "y_min": 117
                    },
                    "similarity": 0.98311
                }
            ]
        }
    ]
}

source_image_face array - Information regarding the submitted source_image

face_matches array - Information regarding potential face matches in the submitted target_image

box array - A face found in an image

probability float - The probability that the detected object is a face

x_max, y_max, x_min, y_min integers - The bounding box pixel coordinates of a face

similarity float - The match score of how similar the faces from the two images are. The expected value is between 0 to 1 - higher is better.