{"id":18925138,"url":"https://github.com/exadel-inc/compreface-python-sdk","last_synced_at":"2025-04-07T11:03:55.099Z","repository":{"id":46677689,"uuid":"341595166","full_name":"exadel-inc/compreface-python-sdk","owner":"exadel-inc","description":"Python SDK for CompreFace - free and open-source face recognition system from Exadel","archived":false,"fork":false,"pushed_at":"2023-04-05T08:59:39.000Z","size":3574,"stargazers_count":130,"open_issues_count":9,"forks_count":43,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-31T10:04:14.515Z","etag":null,"topics":["compreface","compreface-sdk","computer-vision","face-detection","face-recognition","face-recognition-python","face-verification","facenet","insightface","python","sdk"],"latest_commit_sha":null,"homepage":"https://exadel.com/solutions/compreface/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/exadel-inc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-23T15:13:48.000Z","updated_at":"2025-03-20T12:02:16.000Z","dependencies_parsed_at":"2025-01-15T23:17:17.346Z","dependency_job_id":"868d351f-8b7a-4039-ba9d-e64b0e6a4ea5","html_url":"https://github.com/exadel-inc/compreface-python-sdk","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exadel-inc%2Fcompreface-python-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exadel-inc%2Fcompreface-python-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exadel-inc%2Fcompreface-python-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exadel-inc%2Fcompreface-python-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/exadel-inc","download_url":"https://codeload.github.com/exadel-inc/compreface-python-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247640460,"owners_count":20971557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compreface","compreface-sdk","computer-vision","face-detection","face-recognition","face-recognition-python","face-verification","facenet","insightface","python","sdk"],"created_at":"2024-11-08T11:09:43.199Z","updated_at":"2025-04-07T11:03:55.072Z","avatar_url":"https://github.com/exadel-inc.png","language":"Python","readme":"# CompreFace Python SDK\n\nCompreFace Python SDK makes face recognition into your application even easier.\n\n# Table of content\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Initialization](#initialization)\n  - [Adding faces into a face collection](#adding-faces-into-a-face-collection)\n  - [Recognition](#recognition)\n  - [Webcam demo](#webcam-demo)\n- [Reference](#reference)\n  - [CompreFace Global Object](#compreFace-global-object)\n    - [Methods](#methods)\n  - [Options structure](#options-structure)\n  - [Face Recognition Service](#face-recognition-service)\n    - [Recognize Faces from a Given Image](#recognize-faces-from-a-given-image)\n    - [Get Face Collection](#get-face-collection)\n      - [Add an Example of a Subject](#add-an-example-of-a-subject)\n      - [List of All Saved Examples of the Subject](#list-of-all-saved-examples-of-the-subject)\n      - [Delete All Examples of the Subject by Name](#delete-all-examples-of-the-subject-by-name)\n      - [Delete an Example of the Subject by ID](#delete-an-example-of-the-subject-by-id)\n      - [Verify Faces from a Given Image](#verify-faces-from-a-given-image)\n    - [Get Subjects](#get-subjects)\n      - [Add a Subject](#add-a-subject)\n      - [List Subjects](#list-subjects)\n      - [Rename a Subject](#rename-a-subject)\n      - [Delete a Subject](#delete-a-subject)\n      - [Delete All Subjects](#delete-all-subjects)\n    - [Face Detection Service](#face-detection-service)\n      - [Detect](#detect)\n    - [Face Verification Service](#face-verification-service)\n      - [Verify](#verify)\n- [Contributing](#contributing)\n    - [Report Bugs](#report-bugs)\n    - [Submit Feedback](#submit-feedback)\n- [License info](#license-info)\n\n# Requirements\n\nBefore using our SDK make sure you have installed CompreFace and Python on your machine.\n\n1. [CompreFace](https://github.com/exadel-inc/CompreFace#getting-started-with-compreface)\n2. [Python](https://www.python.org/downloads/) (Version 3.7+)\n\n## CompreFace compatibility matrix\n\n| CompreFace Python SDK version | CompreFace 0.5.x | CompreFace 0.6.x |\n| ------------------------------| ---------------- | ---------------- | \n| 0.1.0                         | ✔                | :yellow_circle:  | \n| 0.6.x                         | :yellow_circle:  | ✔                | \n\nExplanation:\n\n* ✔  SDK supports all functionality from CompreFace. \n* :yellow_circle:  SDK works with this CompreFace version. \nIn case if CompreFace version is newer - SDK won't support new features of CompreFace. In case if CompreFace version is older - new SDK features will fail.\n* ✘ There are major backward compatibility issues. It is not recommended to use these versions together\n\n\n# Installation\n\nIt can be installed through pip:\n\n```shell\npip install compreface-sdk\n```\n\n# Usage\n\nAll these examples you can find in repository inside [examples](/examples) folder.\n\n## Initialization\n\nTo start using Python SDK you need to import `CompreFace` object from 'compreface-sdk' dependency.  \n\nThen 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.\nYou can pass optional `options` object when call method to set default parameters, see reference for [more information](#options-structure).\n\nAfter 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.\n\nHowever, before recognizing you need first to add faces into the face collection. To do this, get the face collection object from the service object.\n\n```python\nfrom compreface import CompreFace\nfrom compreface.service import RecognitionService\nfrom compreface.collections import FaceCollection\nfrom compreface.collections.face_collections import Subjects\n\nDOMAIN: str = 'http://localhost'\nPORT: str = '8000'\nAPI_KEY: str = 'your_face_recognition_key'\n\ncompre_face: CompreFace = CompreFace(DOMAIN, PORT)\n\nrecognition: RecognitionService = compre_face.init_face_recognition(API_KEY)\n\nface_collection: FaceCollection = recognition.get_face_collection()\n\nsubjects: Subjects = recognition.get_subjects()\n```\n\n## Adding faces into a face collection\n\nHere is example that shows how to add an image to your face collection from your file system:\n\n```python\nimage_path: str = 'examples/common/jonathan-petit-unsplash.jpg'\nsubject: str = 'Jonathan Petit'\n\nface_collection.add(image_path=image_path, subject=subject)\n```\n\n## Recognition\n\nThis code snippet shows how to recognize unknown face.\n\n```python\nimage_path: str = 'examples/common/jonathan-petit-unsplash.jpg'\n\nrecognition.recognize(image_path=image_path)\n```\n\n## Webcam demo\nWebcam demo shows how to use CompreFace Recognition and Detection services using Python SDK.\nIn both cases, age, gender and mask plugins are applied.\n\nFollow this [link](/webcam_demo) to see the instructions.\n\n# Reference\n\n## CompreFace Global Object\n\nGlobal CompreFace Object is used for initializing connection to CompreFace and setting default values for options.\nDefault values will be used in every service method if applicable.\nIf the option’s value is set in the global object and passed as a function argument then the function argument value will be used.\n\n**Constructor:**\n\n```CompreFace(domain, port, options)```\n\n| Argument | Type   | Required | Notes                                     | \n| ---------| ------ | -------- | ----------------------------------------- | \n| url      | string | required | URL with protocol where CompreFace is located. E.g. `http://localhost` |\n| port     | string | required | CompreFace port. E.g. `8000` |\n| options  | object | optional | Default values for face recognition services. See more [here](#options-structure). `AllOptionsDict` object can be used in this method   |\n\nPossible options:\n\n| Option              | Type    | Notes                                     |\n| --------------------| ------  | ----------------------------------------- |\n| det_prob_threshold  | float   | minimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0 |\n| limit               | integer | maximum number of faces on the image to be recognized. It recognizes the biggest faces first. Value of 0 represents no limit. Default value: 0       |\n| prediction_count    | integer | maximum number of subject predictions per face. It returns the most similar subjects. Default value: 1    |\n| face_plugins        | string  | comma-separated slugs of face plugins. If empty, no additional information is returned. [Learn more](https://github.com/exadel-inc/CompreFace/tree/master/docs/Face-services-and-plugins.md)    |\n| status              | boolean | if true includes system information like execution_time and plugin_version fields. Default value is false    |\n\nExample:\n\n```python\nfrom compreface import CompreFace\n\nDOMAIN: str = 'http://localhost'\nPORT: str = '8000'\n\ncompre_face: CompreFace = CompreFace(domain=DOMAIN, port=PORT, options={\n    \"limit\": 0,\n    \"det_prob_threshold\": 0.8,\n    \"prediction_count\": 1,\n    \"face_plugins\": \"calculator,age,gender,landmarks\",\n    \"status\": \"true\"\n})\n```\n\n### Methods\n\n1. ```CompreFace.init_face_recognition(api_key)```\n\nInits face recognition service object.\n\n| Argument | Type   | Required | Notes                                     |\n| ---------| ------ | -------- | ----------------------------------------- |\n| api_key  | string | required | Face Recognition Api Key in UUID format    |\n\nExample:\n\n```python\nfrom compreface.service import RecognitionService\n\nAPI_KEY: str = 'your_face_recognition_key'\n\nrecognition: RecognitionService = compre_face.init_face_recognition(API_KEY)\n```\n\n2. ```CompreFace.init_face_detection(api_key)```\n\nInits face detection service object.\n\n| Argument | Type   | Required | Notes                                     |\n| ---------| ------ | -------- | ----------------------------------------- |\n| api_key  | string | required | Face Detection Api Key in UUID format    |\n\nExample:\n\n```python\nfrom compreface.service import DetectionService\n\nDETECTION_API_KEY: str = 'your_face_detection_key'\n\ndetection: DetectionService = compre_face.init_face_detection(DETECTION_API_KEY)\n```\n\n3. ```CompreFace.init_face_verification(api_key)```\n\nInits face verification service object.\n\n| Argument | Type   | Required | Notes                                     |\n| ---------| ------ | -------- | ----------------------------------------- |\n| api_key  | string | required | Face Verification Api Key in UUID format    |\n\nExample:\n\n```python\nfrom compreface.service import VerificationService\n\nVERIFICATION_API_KEY: str = 'your_face_verification_key'\n\nverify: VerificationService = compre_face.init_face_verification(VERIFICATION_API_KEY)\n```\n\n## Options structure\n\nOptions is optional field in every request that contains an image.\nIf the option’s value is set in the global object and passed as a function argument then the function argument value will be used.\n\n```python \n\nclass DetProbOptionsDict(TypedDict):\n    det_prob_threshold: float\n\n\nclass ExpandedOptionsDict(DetProbOptionsDict):\n    limit: int\n    status: bool\n    face_plugins: str\n\n\nclass AllOptionsDict(ExpandedOptionsDict):\n    prediction_count: int\n\n```\n| Option              | Type    | Notes                                     |\n| --------------------| ------  | ----------------------------------------- |\n| det_prob_threshold  | float   | minimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0 |\n| limit               | integer | maximum number of faces on the image to be recognized. It recognizes the biggest faces first. Value of 0 represents no limit. Default value: 0       |\n| prediction_count    | integer | maximum number of subject predictions per face. It returns the most similar subjects. Default value: 1    |\n| face_plugins        | string  | comma-separated slugs of face plugins. If empty, no additional information is returned. [Learn more](https://github.com/exadel-inc/CompreFace/tree/master/docs/Face-services-and-plugins.md)    |\n| status              | boolean | if true includes system information like execution_time and plugin_version fields. Default value is false    |\n\nExample of face recognition with object:\n\n```python\nrecognition.recognize(image_path=image_path, options={\n    \"limit\": 0,\n    \"det_prob_threshold\": 0.8,\n    \"prediction_count\": 1,\n    \"face_plugins\": \"calculator,age,gender,landmarks\",\n    \"status\": \"true\"\n})\n```\n\n## Face Recognition Service\n\nFace recognition service is used for face identification.\nThis means that you first need to upload known faces to face collection and then recognize unknown faces among them.\nWhen you upload an unknown face, the service returns the most similar faces to it.\nAlso, face recognition service supports verify endpoint to check if this person from face collection is the correct one.\nFor more information, see [CompreFace page](https://github.com/exadel-inc/CompreFace).\n\n### Recognize Faces from a Given Image\n\n*[Example](examples/recognize_face_from_image.py)*\n\nRecognizes all faces from the image.\nThe first argument is the image location, it can be an url, local path or bytes.\n\n```python\nrecognition.recognize(image_path, options)\n```\n\n| Argument           | Type    | Required | Notes                                                                                                                                          |\n| ------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| image_path         | image   | required | Image can pass from url, local path or bytes. Max size is 5Mb                                                         |\n| options            | object  | optional | `AllOptionsDict` object can be used in this method. See more [here](#options-structure).  |\n\nResponse:\n\n```json\n{\n  \"result\" : [ {\n    \"age\" : {\n      \"probability\": 0.9308982491493225,\n      \"high\": 32,\n      \"low\": 25\n    },\n    \"gender\" : {\n      \"probability\": 0.9898611307144165,\n      \"value\": \"female\"\n    },\n    \"mask\" : {\n      \"probability\": 0.9999470710754395,\n      \"value\": \"without_mask\"\n    },\n    \"embedding\" : [ 9.424854069948196E-4, \"...\", -0.011415496468544006 ],\n    \"box\" : {\n      \"probability\" : 1.0,\n      \"x_max\" : 1420,\n      \"y_max\" : 1368,\n      \"x_min\" : 548,\n      \"y_min\" : 295\n    },\n    \"landmarks\" : [ [ 814, 713 ], [ 1104, 829 ], [ 832, 937 ], [ 704, 1030 ], [ 1017, 1133 ] ],\n    \"subjects\" : [ {\n      \"similarity\" : 0.97858,\n      \"subject\" : \"subject1\"\n    } ],\n    \"execution_time\" : {\n      \"age\" : 28.0,\n      \"gender\" : 26.0,\n      \"detector\" : 117.0,\n      \"calculator\" : 45.0,\n      \"mask\": 36.0\n    }\n  } ],\n  \"plugins_versions\" : {\n    \"age\" : \"agegender.AgeDetector\",\n    \"gender\" : \"agegender.GenderDetector\",\n    \"detector\" : \"facenet.FaceDetector\",\n    \"calculator\" : \"facenet.Calculator\",\n    \"mask\": \"facemask.MaskDetector\"\n  }\n}\n```\n\n| Element                    | Type    | Description                                                                                                                                                 |\n| -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| age                        | object  | detected age range. Return only if [age plugin](https://github.com/exadel-inc/CompreFace/blob/master/docs/Face-services-and-plugins.md) is enabled                                                       |\n| gender                     | object  | detected gender. Return only if [gender plugin](https://github.com/exadel-inc/CompreFace/blob/master/docs/Face-services-and-plugins.md) is enabled                                                       |\n| mask                       | object  | detected mask. Return only if [face mask plugin](https://github.com/exadel-inc/CompreFace/blob/master/docs/Face-services-and-plugins.md) is enabled.          |\n| embedding                  | array   | face embeddings. Return only if [calculator plugin](https://github.com/exadel-inc/CompreFace/blob/master/docs/Face-services-and-plugins.md) is enabled                                                   |\n| box                        | object  | list of parameters of the bounding box for this face                                                                                                        |\n| probability                | float   | probability that a found face is actually a face                                                                                                            |\n| x_max, y_max, x_min, y_min | integer | coordinates of the frame containing the face                                                                                                                |\n| landmarks                  | array   | list of the coordinates of the frame containing the face-landmarks.|\n| subjects                   | list    | list of similar subjects with size of \u003cprediction_count\u003e order by similarity                                                                                |\n| similarity                 | float   | similarity that on that image predicted person                                                                                                              |\n| subject                    | string  | name of the subject in Face Collection                                                                                                                      |\n| execution_time             | object  | execution time of all plugins                                                                                                                               |\n| plugins_versions           | object  | contains information about plugin versions                                                                                                                  |\n\n### Get Face Collection\n\n```python\nrecognition.get_face_collection()\n```\n\nReturns Face collection object\n\nFace collection could be used to manage known faces, e.g. add, list, or delete them.\n\nFace recognition is performed for the saved known faces in face collection, so before using the `recognize` method you need to save at least one face into the face collection.\n\nMore information about face collection and managing examples [here](https://github.com/exadel-inc/CompreFace/blob/master/docs/Rest-API-description.md#managing-subject-examples)\n\n**Methods:**\n\n#### Add an Example of a Subject\n\n*[Example](examples/add_example_of_a_subject.py)*\n\nThis creates an example of the subject by saving images. You can add as many images as you want to train the system. Image should\ncontain only one face.\n\n```python\nface_collection.add(image_path, subject, options)\n```\n\n| Argument           | Type   | Required | Notes                                                                                                |\n| ------------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------- |\n| image_path         | image  | required | Image can pass from url, local path or bytes. Max size is 5Mb               |\n| subject            | string | required | is the name you assign to the image you save                                                         |\n| options            | object | optional | `DetProbOptionsDict` object can be used in this method. See more [here](#options-structure).  |\n\nResponse:\n\n```json\n{\n  \"image_id\": \"6b135f5b-a365-4522-b1f1-4c9ac2dd0728\",\n  \"subject\": \"subject1\"\n}\n```\n\n| Element  | Type   | Description                |\n| -------- | ------ | -------------------------- |\n| image_id | UUID   | UUID of uploaded image     |\n| subject  | string | Subject of the saved image |\n\n#### List of All Saved Examples of the Subject\n\nTo retrieve a list of subjects saved in a Face Collection:\n\n```python\nface_collection.list()\n```\n\nResponse:\n\n```\n{\n  \"faces\": [\n    {\n      \"image_id\": \u003cimage_id\u003e,\n      \"subject\": \u003csubject\u003e\n    },\n    ...\n  ]\n}\n```\n\n| Element  | Type   | Description                                                       |\n| -------- | ------ | ----------------------------------------------------------------- |\n| image_id | UUID   | UUID of the face                                                  |\n| subject  | string | \u003csubject\u003e of the person, whose picture was saved for this api key |\n\n#### Delete All Examples of the Subject by Name\n\n*[Example](examples/delete_all_examples_of_subject.py)*\n\nTo delete all image examples of the \u003csubject\u003e:\n\n```python\nface_collection.delete_all(subject)\n```\n\n| Argument  | Type   | Required | Notes                                                                                                                                |\n| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |\n| subject   | string | optional | is the name you assign to the image you save. If this parameter is absent, all faces in Face Collection will be removed |\n\nResponse:\n\n```\n{\n    \"deleted\": \u003ccount\u003e\n}\n```\n\n| Element  | Type    | Description              |\n| -------- | ------- | ------------------------ |\n| deleted  | integer | Number of deleted faces  |\n\n#### Delete an Example of the Subject by ID\n\n*[Example](examples/delete_example_by_id.py)*\n\nTo delete an image by ID:\n\n```python\nface_collection.delete(image_id)\n```\n| Argument  | Type   | Required | Notes                                                        |\n| --------- | ------ | -------- | ------------------------------------------------------------ \n| image_id  | UUID   | required | UUID of the removing face                                    |\n\nResponse:\n\n```\n{\n  \"image_id\": \u003cimage_id\u003e,\n  \"subject\": \u003csubject\u003e\n}\n```\n\n| Element  | Type   | Description                                                       |\n| -------- | ------ | ----------------------------------------------------------------- |\n| image_id | UUID   | UUID of the removed face                                          |\n| subject  | string | \u003csubject\u003e of the person, whose picture was saved for this api key |\n\n#### Verify Faces from a Given Image\n\n*[Example](examples/verification_face_from_image.py)*\n\n```python\nface_collection.verify(image_path, image_id, options)\n```\n\nCompares similarities of given image with image from your face collection.\n\n\n| Argument           | Type    | Required | Notes                                                                                                                                                 |\n| ------------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |\n| image_path         | image   | required | Image can pass from url, local path or bytes. Max size is 5Mb                                                                |\n| image_id           | UUID    | required | UUID of the verifying face                                                                                                                            |\n| options            | string  | Object   | `ExpandedOptionsDict` object can be used in this method. See more [here](#options-structure).  |\n\nResponse:\n\n```json\n{\n  \"result\" : [ {\n    \"age\" : {\n      \"probability\": 0.9308982491493225,\n      \"high\": 32,\n      \"low\": 25\n    },\n    \"gender\" : {\n      \"probability\": 0.9898611307144165,\n      \"value\": \"female\"\n    },\n    \"mask\" : {\n      \"probability\": 0.9999470710754395,\n      \"value\": \"without_mask\"\n    },\n    \"embedding\" : [ 9.424854069948196E-4, \"...\", -0.011415496468544006 ],\n    \"box\" : {\n      \"probability\" : 1.0,\n      \"x_max\" : 1420,\n      \"y_max\" : 1368,\n      \"x_min\" : 548,\n      \"y_min\" : 295\n    },\n    \"landmarks\" : [ [ 814, 713 ], [ 1104, 829 ], [ 832, 937 ], [ 704, 1030 ], [ 1017, 1133 ] ],\n    \"subjects\" : [ {\n      \"similarity\" : 0.97858,\n      \"subject\" : \"subject1\"\n    } ],\n    \"execution_time\" : {\n      \"age\" : 28.0,\n      \"gender\" : 26.0,\n      \"detector\" : 117.0,\n      \"calculator\" : 45.0,\n      \"mask\": 36.0\n    }\n  } ],\n  \"plugins_versions\" : {\n    \"age\" : \"agegender.AgeDetector\",\n    \"gender\" : \"agegender.GenderDetector\",\n    \"detector\" : \"facenet.FaceDetector\",\n    \"calculator\" : \"facenet.Calculator\",\n    \"mask\": \"facemask.MaskDetector\"\n  }\n}\n```\n\n| Element                        | Type    | Description                                                  |\n| ------------------------------ | ------- | ------------------------------------------------------------ |\n| age                            | object  | detected age range. Return only if [age plugin](https://github.com/exadel-inc/CompreFace/tree/master/docs/Face-services-and-plugins.md#face-plugins) is enabled         |\n| gender                         | object  | detected gender. Return only if [gender plugin](https://github.com/exadel-inc/CompreFace/tree/master/docs/Face-services-and-plugins.md#face-plugins) is enabled         |\n| mask                           | object  | detected mask. Return only if [face mask plugin](https://github.com/exadel-inc/CompreFace/blob/master/docs/Face-services-and-plugins.md) is enabled.          |\n| embedding                      | array   | face embeddings. Return only if [calculator plugin](https://github.com/exadel-inc/CompreFace/tree/master/docs/Face-services-and-plugins.md#face-plugins) is enabled      |\n| box                            | object  | list of parameters of the bounding box for this face         |\n| probability                    | float   | probability that a found face is actually a face             |\n| x_max, y_max, x_min, y_min     | integer | coordinates of the frame containing the face                 |\n| landmarks                      | array   | list of the coordinates of the frame containing the face-landmarks. Return only if [landmarks plugin](https://github.com/exadel-inc/CompreFace/tree/master/docs/Face-services-and-plugins.md#face-plugins) is enabled      |\n| similarity                     | float   | similarity that on that image predicted person               |\n| execution_time                 | object  | execution time of all plugins                       |\n| plugins_versions               | object  | contains information about plugin versions                       |\n\n### Get Subjects\n\n```python\nrecognition.get_subjects()\n```\n\nReturns subjects object\n\nSubjects object allows working with subjects directly (not via subject examples).\n\nMore information about subjects [here](https://github.com/exadel-inc/CompreFace/blob/master/docs/Rest-API-description.md#managing-subjects)\n\n**Methods:**\n\n#### Add a Subject\n\n*[Example](examples/add_subject.py)*\n\nCreate a new subject in Face Collection.\n```python\nsubjects.add(subject)\n```\n\n| Argument           | Type   | Required | Notes                                                                   |\n| ------------------ | ------ | -------- | ------------------------------------------------------------------------|\n| subject            | string | required | is the name of the subject. It can be any string                        |\n\nResponse:\n\n```json\n{\n  \"subject\": \"subject1\"\n}\n```\n\n| Element  | Type   | Description                |\n| -------- | ------ | -------------------------- |\n| subject  | string | is the name of the subject |\n\n#### List Subjects\n\n*[Example](examples/get_list_of_all_subjects.py)*\n\nReturns all subject related to Face Collection.\n```python\nsubjects.list()\n```\n\nResponse:\n\n```json\n{\n  \"subjects\": [\n    \"\u003csubject_name1\u003e\",\n    \"\u003csubject_name2\u003e\"\n  ]\n}\n```\n\n| Element  | Type   | Description                |\n| -------- | ------ | -------------------------- |\n| subjects | array  | the list of subjects in Face Collection |\n\n#### Rename a Subject\n\n*[Example](examples/update_existing_subject.py)*\n\nRename existing subject. If a new subject name already exists, subjects are merged - all faces from the old subject name are reassigned to the subject with the new name, old subject removed.\n\n```python\nsubjects.rename(subject, new_name)\n```\n\n| Argument            | Type   | Required | Notes                                                                   |\n| ------------------  | ------ | -------- | ------------------------------------------------------------------------|\n| subject             | string | required | is the name of the subject that will be updated                         |\n| new_name            | string | required | is the name of the subject. It can be any string                        |\n\nResponse:\n\n```json\n{\n  \"updated\": \"true|false\"\n}\n```\n\n| Element  | Type    | Description                |\n| -------- | ------  | -------------------------- |\n| updated  | boolean | failed or success          |\n\n#### Delete a Subject\n\n*[Example](examples/delete_subject_by_name.py)*\n\nDelete existing subject and all saved faces.\n```python\nsubjects.delete(subject)\n```\n\n| Argument           | Type   | Required | Notes                                                                   |\n| ------------------ | ------ | -------- | ------------------------------------------------------------------------|\n| subject            | string | required | is the name of the subject.                                             |\n\nResponse:\n\n```json\n{\n  \"subject\": \"subject1\"\n}\n```\n\n| Element  | Type   | Description                |\n| -------- | ------ | -------------------------- |\n| subject  | string | is the name of the subject |\n\n#### Delete All Subjects\n\n*[Example](examples/delete_all_subjects.py)*\n\nDelete all existing subjects and all saved faces.\n```python\nsubjects.delete_all()\n```\n\nResponse:\n\n```json\n{\n  \"deleted\": \"\u003ccount\u003e\"\n}\n```\n\n| Element  | Type    | Description                |\n| -------- | ------  | -------------------------- |\n| deleted  | integer | number of deleted subjects |\n\n\n## Face Detection Service\n\nFace detection service is used for detecting faces in the image.\n\n**Methods:**\n\n### Detect\n\n*[Example](examples/detect_face_from_image.py)*\n\n```python\ndetection.detect(image_path, options)\n```\n\nFinds all faces on the image.\n\n| Argument          | Type    | Required | Notes                                                                                                                                          |\n| ----------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| image_path        | image   | required | image where to detect faces. Image can pass from url, local path or bytes. Max size is 5Mb                            |\n| options           | string  | Object   | `ExpandedOptionsDict` object can be used in this method. See more [here](#options-structure).  |\n\nResponse:\n\n```json\n{\n  \"result\" : [ {\n    \"age\" : {\n      \"probability\": 0.9308982491493225,\n      \"high\": 32,\n      \"low\": 25\n    },\n    \"gender\" : {\n      \"probability\": 0.9898611307144165,\n      \"value\": \"female\"\n    },\n    \"mask\" : {\n      \"probability\": 0.9999470710754395,\n      \"value\": \"without_mask\"\n    },\n    \"embedding\" : [ -0.03027934394776821, \"...\", -0.05117142200469971 ],\n    \"box\" : {\n      \"probability\" : 0.9987509250640869,\n      \"x_max\" : 376,\n      \"y_max\" : 479,\n      \"x_min\" : 68,\n      \"y_min\" : 77\n    },\n    \"landmarks\" : [ [ 156, 245 ], [ 277, 253 ], [ 202, 311 ], [ 148, 358 ], [ 274, 365 ] ],\n    \"execution_time\" : {\n      \"age\" : 30.0,\n      \"gender\" : 26.0,\n      \"detector\" : 130.0,\n      \"calculator\" : 49.0,\n      \"mask\": 36.0\n    }\n  } ],\n  \"plugins_versions\" : {\n    \"age\" : \"agegender.AgeDetector\",\n    \"gender\" : \"agegender.GenderDetector\",\n    \"detector\" : \"facenet.FaceDetector\",\n    \"calculator\" : \"facenet.Calculator\",\n    \"mask\": \"facemask.MaskDetector\"\n  }\n}\n```\n\n| Element                        | Type    | Description                                                  |\n| ------------------------------ | ------- | ------------------------------------------------------------ |\n| age                            | object  | detected age range. Return only if [age plugin](https://github.com/exadel-inc/CompreFace/tree/master/docs/Face-services-and-plugins.md#face-plugins) is enabled         |\n| gender                         | object  | detected gender. Return only if [gender plugin](https://github.com/exadel-inc/CompreFace/tree/master/docs/Face-services-and-plugins.md#face-plugins) is enabled         |\n| mask                           | object  | detected mask. Return only if [face mask plugin](https://github.com/exadel-inc/CompreFace/blob/master/docs/Face-services-and-plugins.md) is enabled.          |\n| embedding                      | array   | face embeddings. Return only if [calculator plugin](https://github.com/exadel-inc/CompreFace/tree/master/docs/Face-services-and-plugins.md#face-plugins) is enabled      |\n| box                            | object  | list of parameters of the bounding box for this face (on processedImage) |\n| probability                    | float   | probability that a found face is actually a face (on processedImage)     |\n| x_max, y_max, x_min, y_min     | integer | coordinates of the frame containing the face (on processedImage)         |\n| landmarks                      | array   | list of the coordinates of the frame containing the face-landmarks. Return only if [landmarks plugin](https://github.com/exadel-inc/CompreFace/tree/master/docs/Face-services-and-plugins.md#face-plugins) is enabled      |\n| execution_time                 | object  | execution time of all plugins                       |\n| plugins_versions               | object  | contains information about plugin versions                       |\n\n\n## Face Verification Service\n\n*[Example](examples/verify_face_from_image.py)*\n\nFace verification service is used for comparing two images.\nA source image should contain only one face which will be compared to all faces on the target image.\n\n**Methods:**\n\n### Verify\n\n```python\nverify.verify(source_image_path, target_image_path, options)\n```\n\nCompares two images provided in arguments. Source image should contain only one face, it will be compared to all faces in the target image.\n\n| Argument            | Type    | Required | Notes                                                                                                                                                 |\n| ------------------  | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |\n| image_id            | UUID    | required | UUID of the verifying face                                                                                                                            |\n| source_image_path   | image   | required | file to be verified. Image can pass from url, local path or bytes. Max size is 5Mb                                           |\n| target_image_path   | image   | required | reference file to check the source file. Image can pass from url, local path or bytes. Max size is 5Mb                       |\n| options             | string  | Object   | `ExpandedOptionsDict` object can be used in this method. See more [here](#options-structure).  |\n\nResponse:\n\n```json\n{\n  \"result\" : [{\n    \"source_image_face\" : {\n      \"age\" : {\n        \"probability\": 0.9308982491493225,\n        \"high\": 32,\n        \"low\": 25\n      },\n      \"gender\" : {\n        \"probability\": 0.9898611307144165,\n        \"value\": \"female\"\n      },\n      \"mask\" : {\n        \"probability\": 0.9999470710754395,\n        \"value\": \"without_mask\"\n      },\n      \"embedding\" : [ -0.0010271212086081505, \"...\", -0.008746841922402382 ],\n      \"box\" : {\n        \"probability\" : 0.9997453093528748,\n        \"x_max\" : 205,\n        \"y_max\" : 167,\n        \"x_min\" : 48,\n        \"y_min\" : 0\n      },\n      \"landmarks\" : [ [ 92, 44 ], [ 130, 68 ], [ 71, 76 ], [ 60, 104 ], [ 95, 125 ] ],\n      \"execution_time\" : {\n        \"age\" : 85.0,\n        \"gender\" : 51.0,\n        \"detector\" : 67.0,\n        \"calculator\" : 116.0,\n        \"mask\": 36.0\n      }\n    },\n    \"face_matches\": [\n      {\n        \"age\" : {\n          \"probability\": 0.9308982491493225,\n          \"high\": 32,\n          \"low\": 25\n        },\n        \"gender\" : {\n          \"probability\": 0.9898611307144165,\n          \"value\": \"female\"\n        },\n        \"mask\" : {\n          \"probability\": 0.9999470710754395,\n          \"value\": \"without_mask\"\n        },\n        \"embedding\" : [ -0.049007344990968704, \"...\", -0.01753818802535534 ],\n        \"box\" : {\n          \"probability\" : 0.99975,\n          \"x_max\" : 308,\n          \"y_max\" : 180,\n          \"x_min\" : 235,\n          \"y_min\" : 98\n        },\n        \"landmarks\" : [ [ 260, 129 ], [ 273, 127 ], [ 258, 136 ], [ 257, 150 ], [ 269, 148 ] ],\n        \"similarity\" : 0.97858,\n        \"execution_time\" : {\n          \"age\" : 59.0,\n          \"gender\" : 30.0,\n          \"detector\" : 177.0,\n          \"calculator\" : 70.0,\n          \"mask\": 36.0\n        }\n      }],\n    \"plugins_versions\" : {\n      \"age\" : \"agegender.AgeDetector\",\n      \"gender\" : \"agegender.GenderDetector\",\n      \"detector\" : \"facenet.FaceDetector\",\n      \"calculator\" : \"facenet.Calculator\",\n      \"mask\": \"facemask.MaskDetector\"\n    }\n  }]\n}\n```\n\n| Element                        | Type    | Description                                                  |\n| ------------------------------ | ------- | ------------------------------------------------------------ |\n| source_image_face              | object  | additional info about source image face |\n| face_matches                   | array   | result of face verification |\n| age                            | object  | detected age range. Return only if [age plugin](https://github.com/exadel-inc/CompreFace/tree/master/docs/Face-services-and-plugins.md#face-plugins) is enabled         |\n| gender                         | object  | detected gender. Return only if [gender plugin](https://github.com/exadel-inc/CompreFace/tree/master/docs/Face-services-and-plugins.md#face-plugins) is enabled         |\n| mask                           | object  | detected mask. Return only if [face mask plugin](https://github.com/exadel-inc/CompreFace/blob/master/docs/Face-services-and-plugins.md) is enabled.          |\n| embedding                      | array   | face embeddings. Return only if [calculator plugin](https://github.com/exadel-inc/CompreFace/tree/master/docs/Face-services-and-plugins.md#face-plugins) is enabled      |\n| box                            | object  | list of parameters of the bounding box for this face         |\n| probability                    | float   | probability that a found face is actually a face             |\n| x_max, y_max, x_min, y_min     | integer | coordinates of the frame containing the face                 |\n| landmarks                      | array   | list of the coordinates of the frame containing the face-landmarks. Return only if [landmarks plugin](https://github.com/exadel-inc/CompreFace/tree/master/docs/Face-services-and-plugins.md#face-plugins) is enabled      |\n| similarity                     | float   | similarity between this face and the face on the source image               |\n| execution_time                 | object  | execution time of all plugins                       |\n| plugins_versions               | object  | contains information about plugin versions                       |\n\n# Contributing\n\nContributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\nAfter 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.\n\n## Report Bugs\n\nPlease report any bugs [here](https://github.com/exadel-inc/compreface-python-sdk/issues).\n\nIf you are reporting a bug, please specify:\n\n- Your operating system name and version\n- Any details about your local setup that might be helpful in troubleshooting\n- Detailed steps to reproduce the bug\n\n## Submit Feedback\n\nThe best way to send us feedback is to file an issue at https://github.com/exadel-inc/compreface-python-sdk/issues.\n\nIf you are proposing a feature, please:\n\n- Explain in detail how it should work.\n- Keep the scope as narrow as possible to make it easier to implement.\n\n# License info\n\nCompreFace Python SDK is open-source facial recognition SDK released under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.html).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexadel-inc%2Fcompreface-python-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexadel-inc%2Fcompreface-python-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexadel-inc%2Fcompreface-python-sdk/lists"}