CompreFace Python SDK makes face recognition into your application even easier.

• Requirements
• Installation
• Usage
  • Initialization
  • Example Add an Example of a Subject
  • Example Recognize Faces from a Given Image
  • Example List of All Saved Subjects
  • Example Delete All Examples of the Subject by Name
  • Example Delete an Example of the Subject by ID
  • Example Compare Faces from a Given Image
  • Example Detect Faces from a Given Image
  • Example Verify Face from a Given Images
• Reference
  • CompreFace Global Object
  • Options structure
  • Face Recognition Service
    • Add an Example of a Subject
    • Recognize Faces from a Given Image
    • List of All Saved Subjects
    • Delete All Examples of the Subject by Name
    • Delete an Example of the Subject by ID
    • Verify Faces from a Given Image
  • Face Detection Service
  • Face Verification Service

Before using our SDK make sure you have installed CompreFace and Python on your machine.

1. CompreFace
2. Python (Version 3.7+)

It can be installed through pip:

pip install compreface-sdk

All these examples you can find in repository inside examples folder.

To start using Python SDK you need to import CompreFace object from 'compreface-sdk' dependency.

Then you need to init it with url and port. By default, if you run CompreFace on your local machine, it's http://localhost and 8000 respectively. You can pass optional options object when call method to set default parameters, see reference for more information.

After you initialized CompreFace object you need to init the service object with the api key of your face service. You can use this service object to recognize faces.

However, before recognizing you need first to add faces into the face collection. To do this, get the face collection object from the service object.

from compreface import CompreFace from compreface.service import RecognitionService from compreface.collections import FaceCollection DOMAIN: str = 'http://localhost' PORT: str = '8000' API_KEY: str = 'your_face_recognition_key' compre_face: CompreFace = CompreFace(DOMAIN, PORT) recognition: RecognitionService = compre_face.init_face_recognition(API_KEY) face_collection: FaceCollection = recognition.get_face_collection()

Here is example that shows how to add an image to your face collection from your file system:

image_path: str = 'examples/common/jonathan-petit-unsplash.jpg' subject: str = 'Jonathan Petit' face_collection.add(image_path=image_path, subject=subject)

This code snippet shows how to recognize unknown face.

image_path: "str or bytes" recognition.recognize(image_path=image_path)

This code shows how to retrieve a list of subject examples saved in a Face Collection:

face_collection.list()

This code shows how to delete all image examples of the subject:

subject: str = 'Jonathan Petit' print(face_collection.delete_all(subject))

This example to delete an image by ID:

faces: list = face_collection.list().get('faces') if(len(faces) != 0): last_face: dict = faces[len(faces) - 1] print(face_collection.delete(last_face.get('image_id'))) else: print('No subject found')

This example shows how to compare unknown face with existing face in face collection:

image_path: "str or bytes" face: dict = next(item for item in face_collection.list().get('faces') if item['subject'] == 'Jonathan Petit') image_id = face.get('image_id') face_collection.verify(image_path=image_path, image_id=image_id)

Here is example to detect faces from a given image.

from compreface import CompreFace from compreface.service import DetectionService DOMAIN: str = 'http://localhost' PORT: str = '8000' DETECTION_API_KEY: str = 'your_face_detection_key' compre_face: CompreFace = CompreFace(DOMAIN, PORT) detection: DetectionService = compre_face.init_face_detection(DETECTION_API_KEY) image_path: str = 'examples/common/jonathan-petit-unsplash.jpg' detection.detect(image_path=image_path)

Here is example to verify face from a given images.

from compreface import CompreFace from compreface.service import VerificationService DOMAIN: str = 'http://localhost' PORT: str = '8000' VERIFICATION_API_KEY: str = 'your_face_verification_key' compre_face: CompreFace = CompreFace(DOMAIN, PORT) verify: VerificationService = compre_face.init_face_verification(VERIFICATION_API_KEY) image_path: str = 'examples/common/jonathan-petit-unsplash.jpg' verify.verify(source_image_path=image_path, target_image_path=image_path)

Global CompreFace Object is used for initializing connection to CompreFace and setting default values for options. Default values will be used in every service method if applicable. If the option’s value is set in the global object and passed as a function argument then the function argument value will be used.

Constructor:

CompreFace(domain, port, options)

Possible options:

Example:

from compreface import CompreFace DOMAIN: str = 'http://localhost' PORT: str = '8000' compre_face: CompreFace = CompreFace(domain=DOMAIN, port=PORT, options={ "limit": 0, "det_prob_threshold": 0.8, "prediction_count": 1, "face_plugins": "calculator,age,gender,landmarks", "status": "true" })

Methods:

1. CompreFace.init_face_recognition(api_key)

Inits face recognition service object.

Example:

from compreface.service import RecognitionService API_KEY: str = 'your_face_recognition_key' recognition: RecognitionService = compre_face.init_face_recognition(API_KEY)

2. CompreFace.init_face_detection(api_key)

Inits face detection service object.

Example:

from compreface.service import DetectionService DETECTION_API_KEY: str = 'your_face_detection_key' detection: DetectionService = compre_face.init_face_detection(DETECTION_API_KEY)

3. CompreFace.init_face_verification(api_key)

Inits face verification service object.

Example:

from compreface.service import VerificationService VERIFICATION_API_KEY: str = 'your_face_verification_key' verify: VerificationService = compre_face.init_face_verification(VERIFICATION_API_KEY)

Options is optional field in every request that contains an image. If the option’s value is set in the global object and passed as a function argument then the function argument value will be used.

class DetProbOptionsDict(TypedDict): det_prob_threshold: float class ExpandedOptionsDict(DetProbOptionsDict): limit: int status: bool face_plugins: str class AllOptionsDict(ExpandedOptionsDict): prediction_count: int

Example of face recognition with object:

recognition.recognize(image_path=image_path, options={ "limit": 0, "det_prob_threshold": 0.8, "prediction_count": 1, "face_plugins": "calculator,age,gender,landmarks", "status": "true" })

Face recognition service is used for face identification. This means that you first need to upload known faces to face collection and then recognize unknown faces among them. When you upload an unknown face, the service returns the most similar faces to it. Also, face recognition service supports verify endpoint to check if this person from face collection is the correct one. For more information, see CompreFace page.

This creates an example of the subject by saving images. You can add as many images as you want to train the system.

FaceCollection.add(image_path, subject, options)

Response body on success:

{ "image_id": "6b135f5b-a365-4522-b1f1-4c9ac2dd0728", "subject": "subject1" }

Recognizes faces from the uploaded image.

RecognitionService.recognize(image_path, options)

Response body on success:

{ "result": [ { "age": [25, 32], "gender": "female", "embedding": [9.424854069948196e-4, "...", -0.011415496468544006], "box": { "probability": 1.0, "x_max": 1420, "y_max": 1368, "x_min": 548, "y_min": 295 }, "landmarks": [ [814, 713], [1104, 829], [832, 937], [704, 1030], [1017, 1133] ], "subjects": [ { "similarity": 0.97858, "subject": "subject1" } ], "execution_time": { "age": 28.0, "gender": 26.0, "detector": 117.0, "calculator": 45.0 } } ], "plugins_versions": { "age": "agegender.AgeDetector", "gender": "agegender.GenderDetector", "detector": "facenet.FaceDetector", "calculator": "facenet.Calculator" } }

To retrieve a list of subjects saved in a Face Collection:

FaceCollection.list()

Response body on success:

{ "faces": [ { "image_id": <image_id>, "subject": <subject> }, ... ] } 

To delete all image examples of the :

FaceCollection.delete_all(subject)

Response body on success:

[ { "image_id": <image_id>, "subject": <subject> }, ... ] 

To delete an image by ID:

FaceCollection.delete(image_id)

Response body on success:

{ "image_id": <image_id>, "subject": <subject> } 

FaceCollection.verify(image_path, image_id, options)

Compares similarities of given image with image from your face collection.

Response body on success:

{ "result": [ { "box": { "probability": <probability>, "x_max": <integer>, "y_max": <integer>, "x_min": <integer>, "y_min": <integer> }, "similarity": <similarity1> }, ... ] } 

Face detection service is used for detecting faces in the image.

Methods:

DetectionService.detect(image_path, options)

Finds all faces on the image.

Response body on success:

{ "result": [ { "age": [25, 32], "gender": "female", "embedding": [-0.03027934394776821, "...", -0.05117142200469971], "box": { "probability": 0.9987509250640869, "x_max": 376, "y_max": 479, "x_min": 68, "y_min": 77 }, "landmarks": [ [156, 245], [277, 253], [202, 311], [148, 358], [274, 365] ], "execution_time": { "age": 30.0, "gender": 26.0, "detector": 130.0, "calculator": 49.0 } } ], "plugins_versions": { "age": "agegender.AgeDetector", "gender": "agegender.GenderDetector", "detector": "facenet.FaceDetector", "calculator": "facenet.Calculator" } }

Face verification service is used for comparing two images. A source image should contain only one face which will be compared to all faces on the target image.

Methods:

VerificationService.verify(source_image_path, target_image_path, options)

Compares two images provided in arguments. Source image should contain only one face, it will be compared to all faces in the target image.

Response body on success:

{ "source_image_face" : { "age" : [ 25, 32 ], "gender" : "female", "embedding" : [ -0.0010271212086081505, "...", -0.008746841922402382 ], "box" : { "probability" : 0.9997453093528748, "x_max" : 205, "y_max" : 167, "x_min" : 48, "y_min" : 0 }, "landmarks" : [ [ 92, 44 ], [ 130, 68 ], [ 71, 76 ], [ 60, 104 ], [ 95, 125 ] ], "execution_time" : {}, "face_matches": [ { "age" : [ 25, 32 ], "gender" : "female", "embedding" : [ -0.049007344990968704, "...", -0.01753818802535534 ], "box" : { "probability" : 0.99975, "x_max" : 308, "y_max" : 180, "x_min" : 235, "y_min" : 98 }, "landmarks" : [ [ 260, 129 ], [ 273, 127 ], [ 258, 136 ], [ 257, 150 ], [ 269, 148 ] ], "similarity" : 0.97858, "execution_time" : { "age" : 59.0, "gender" : 30.0, "detector" : 177.0, "calculator" : 70.0 } }], "plugins_versions" : { "age" : "agegender.AgeDetector", "gender" : "agegender.GenderDetector", "detector" : "facenet.FaceDetector", "calculator" : "facenet.Calculator" } } }

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

After creating your first contributing pull request, you will receive a request to sign our Contributor License Agreement by commenting your pull request with a special message.

Please report any bugs here.

If you are reporting a bug, please specify:

• Your operating system name and version
• Any details about your local setup that might be helpful in troubleshooting
• Detailed steps to reproduce the bug

The best way to send us feedback is to file an issue at https://github.com/exadel-inc/compreface-python-sdk/issues.

If you are proposing a feature, please:

• Explain in detail how it should work.
• Keep the scope as narrow as possible to make it easier to implement.

CompreFace Python SDK is open-source facial recognition SDK released under the Apache 2.0 license.