API client

Our system works with the gRPC service developed by Google. It allows data transferring to the server quickly and safely, with no need to worry if someone intercepts your requests. You can read more about the gRPC service on the official website: grpc.io Before using the API, you have to register and create a new key, or download a free trial key in case you want to test the service. You can choose as many modules as you want.

Show setup for: Ubuntu: 16 18 + Python: 2,7 3,7

Installation

1. First, you have to install the requirements and the system core:

• 1.1 Clone the GitHub repository:
  

  git clone https://github.com/NeurodataLab/api-service

• 1.2 Go to the Python folder:
  

  cd api-service/python

• 1.3 Install requirements:
  

  python2 [python3] -m pip install -r -requirements.txt

• 1.4 Create proto files for the gRPC:
  

  source ./make_proto_python2.sh [make_proto_python3.sh]

  
  1.5 All generated files will be placed into
  

  api-service/python/pyproto

2. After successful installation you will have to add the keys to the system:

• 2.1 Download each key from your personal account. There will be 4 files. Read more about them at grpc.io
• 2.2 Create a subfolder under

  api-service/cert

  with any name you want, for example my_key
• 2.3 Put the 4 files to this subfolder

  api-service/cert/my_key/

Usage

Before use, don’t forget to add api-service/python and api-service/python/pyproto to PYTHONPATH environment variable. First, you will have to authorize in the service:

import api.auth.Auth as Auth
import os.path as osp

cert_home = osp.join(osp.dirname(osp.abspath(__file__)), '../cert/my_key')

ssl_auth = Auth.SslCredential(osp.join(cert_home, 'client.key'),
                              osp.join(cert_home, 'client.crt'),
                              osp.join(cert_home, 'ca.crt'))

key_auth = Auth.AuthCredential('emotionsdemo.com:50051', osp.join(cert_home, 'root.json'), ssl_auth)

After successful authorization, you can use the modules supported by your key. For detailed information about the modules see Modules Info. Also, you can see an example on our GitHub page api-service/python/demo.py

Classes

Image

To process an image, you will first have to prepare it.

from api.utils.image import Image

You can initialize Image instance from the path

image = Image.from_file('some_image.jpg')

Or you can initialize Image instance from a cv2-like image

image = Image.from_bgr(bgr_image)

After initialization, you can process this image via the module which supports image processing, for example: Face Detector

See example on the GitHub page.

Face Detector

Face Detector module supports image processing. See how to initialize Image instance

Initialization

Import FaceDetector module to your project

import api.recognition.FaceDetection as FD

Create FaceDetector instance with your authentication key (see ClientApi/Usage)

face_detector = FD.FaceDetector(key_auth)

Image processing

To process an image, you will first need to create Image instance (see ClienAPI/Classes/Image). Then, you can process the image via Face Detector. Note, that this is a blocking operation.

image_result, status, error_msg = face_detector.on_image(image)

If status==2, some errors occurred. You can see a detailed error description in error_msg. Otherwise, Face Detector processed the image correctly, and the result will appear in the image_result variable.

Face Detector result type is dict, contains one field ‘FaceDetector’, and

image_result[‘FaceDetector’]

contains a list-like array of detected faces. Each face is a dict with ‘x’, ‘y’, ‘w’ and ‘h’ fields in cv-like coordinates.

Sample result:

[{‘x’: 10, ‘y’: 20, ‘w’: 40, ‘h’: 45},
{‘x’: 100, ‘y’: 30, ‘w’: 45, ‘h’: 45}]

You can see more examples on the GitHub page.

Emotion Recognition

Emotion Recognition module supports image processing. See how to initialize Image instance

Initialization

Import EmotionRecognition module to your project

import api.recognition.EmotionRecognition as ER

Create EmotionRecognition instance with your authentication key (see ClientApi/Usage)

emo_recognizer = ER.EmotionRecognition(key_auth)

Image processing

To process an image, you need first create Image instance (see ClienAPI/Classes/Image). Then, you can process the image via Emotion Recognition. Note, that this is a blocking operation.

image_result, status, error_msg = emo_recognizer.on_image(image)

If status==2, some errors occurred. You can see a detailed error description in error_msg. Otherwise, Emotion Recognition processed the image correctly, and the result will appear in the image_result variable.

Emotion Recognition result type is dict, contains two fields: ‘FaceDetector’ and ‘EmotionRecognition’. Data in ‘FaceDetector’ field is identical to Face Detector result APIModules/FaceDetector/ImageProcessing

Sample result:

[{‘x’: 10, ‘y’: 20, ‘w’: 40, ‘h’: 45, "emotions": [
	[0.9151450991630554, "Surprise"],
	[0.07965227961540222, "Happiness"],
	[0.004168621730059385, "Anxiety"],
	[0.0005960435955785215, "Anger"],
	[0.00035987311275675893, "Neutral"],
	[7.289356290129945e-05, "Sadness"],
	[5.118385161040351e-06, "Disgust"]
]}]

You can see more examples on the GitHub page.