CompreFace is a free face recognition solution that can be easily integrated into
any IT system without prior machine learning skills
Contributing
·
Submit an Issue
·
Blog
·
Community chat
CompreFace is a face detection and recognition GitHub project. Essentially, it is a docker-based application that can be used as a standalone server or deployed in the cloud. You don’t need prior machine learning skills to set up and use CompreFace.
Our approach to face detection and recognition is based on FaceNet and InsightFace libraries that use deep neural networks. CompreFace provides a convenient REST API for training algorithms to detect and recognize faces from your collection of images (aka Face Collection). The solution also features a role management system that allows you to easily control who has access to your Face Collection.
We need your help to better understand which features we should add to the service and how we can improve it further! Our feedback form is totally anonymous, and answering the questions will take just 2 minutes of your time: https://forms.gle/ybAEPc3XmzEcpv4M8
The system can accurately identify people even when it has only “seen” their photo once. Technology-wise, CompreFace has several advantages over similar free face recognition solutions: CompreFace:
docker-compose up -d
cmd
in windows search bar)cd path_of_the_folder
, press enter).docker-compose up -d
docker-compose up --build
git config --global core.autocrlf false
docker ps
docker-compose down
docker system prune --volumes
/dev/start.sh
file to docker-compose -f docker-compose.yml up --remove-orphans --build
cd dev
docker-compose stop
sh start--dev.sh
and make sure http://localhost:4200/ startsStep 1. You need to sign up for the system and log in into the account you’ve just created or use the one you already have. After that, the system redirects you to the main page.
Step 2. Create an application (left section) using the "Create" link at the bottom of the page. An application is where you can create and manage your Face Collections.
Step 3. Enter your application by clicking on its name. Here you will have two options: you can either add new users and manage their access roles or create new Face Collections.
Step 4. After creating a new collection, you will see it in the Face Collections List with an appropriate name and API key. To add known faces to your Face Collection, you can use REST API. Once you’ve uploaded all known faces, you can test the collection using REST API or the TEST page. We recommend that you use an image size no higher than 5MB, as it could slow down the request process. The supported image formats include JPEG/PNG/JPG/ICO/BMP/GIF/TIF/TIFF.
Step 5. Upload your photo and let our open-source face recognition system match the image against the Face Collection. If you use a UI for face recognition, you will see the original picture with marks near every face. If you use REST API, you will receive a response in JSON format.
JSON contains an array of objects that represent each recognized face. Each object has the following fields:
subject
- person identificatorsimilarity
- gives the confidence that this is the found subjectprobability
- gives the confidence that this is a facex_min
, x_max
, y_min
, y_max
are coordinates of the face in the image{
"result": [
{
"box": {
"probability": 0.99583,
"x_max": 551,
"y_max": 364,
"x_min": 319,
"y_min": 55
},
"faces": [
{
"similarity": 0.99593,
"face_name": "lisan"
}
]
}
]
}
Here is a JavaScript code snippet that loads a new image to your Face Collection:
async function saveNewImageToFaceCollection() {
let name = encodeURIComponent('John');
let formData = new FormData();
let photo = document.getElementById("fileDropRef").files[0];
formData.append("photo", photo);
try {
let r = await fetch('http://localhost:8000/api/v1/faces/?subject=`${name}`', {method: "POST", body: formData});
} catch (e) {
console.log('Houston, we have a problem...:', e);
}
}
This function sends the image to our server and shows results in a text area:
function recognizeFace(input) {
async function getData() {
let response = await fetch('http://localhost:8000/api/v1/recognize')
let data = await response.json()
return data
}
let result = Promise.resolve(response)
result.then(data => {
document.getElementById("result-textarea-request").innerHTML = JSON.stringify(data);
});
}
By using the created API key, the user can add an image as an example of a particular face, retrieve a list of saved images, recognize a face from the image uploaded to the Face Collection, and delete all examples of the face by the name.
This creates an example of the subject by saving images. You can add as many images as you want to train the system.
curl -X POST "http://localhost:8000/api/v1/faces?subject=<subject>&det_prob_threshold=<det_prob_threshold>" \
-H "Content-Type: multipart/form-data" \
-H "x-api-key: <faces_collection_api_key>" \
-F file=@<local_file>
Element | Description | Type | Required | Notes |
---|---|---|---|---|
Content-Type | header | string | required | multipart/form-data |
x-api-key | header | string | required | api key of the Face Collection, created by the user |
subject | param | string | required | is the name you assign to the image you save |
det_prob_threshold | param | string | optional | minimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0. |
file | body | image | required | allowed image formats: jpeg, jpg, ico, png, bmp, gif, tif, tiff, webp. Max size is 5Mb |
Response body on success:
{
"image_id": "<UUID>",
"subject": "<subject>"
}
Element | Type | Description |
---|---|---|
image_id | UUID | UUID of uploaded image |
subject | string | of saved image |
Recognizes faces from the uploaded image.
curl -X POST "http://localhost:8000/api/v1/faces/recognize?limit=<limit>&prediction_count=<prediction_count>&det_prob_threshold=<det_prob_threshold>" \
-H "Content-Type: multipart/form-data" \
-H "x-api-key: <faces_collection_api_key>" \
-F file=<local_file>
Element | Description | Type | Required | Notes |
---|---|---|---|---|
Content-Type | header | string | required | multipart/form-data |
x-api-key | header | string | required | api key of the Face Collection, created by the user |
file | body | image | required | allowed image formats: jpeg, jpg, ico, png, bmp, gif, tif, tiff, webp. Max size is 5Mb |
limit | param | integer | optional | maximum number of faces with best similarity in result. Value of 0 represents no limit. Default value: 0 |
det_prob_ threshold | param | string | optional | minimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0. |
prediction_count | param | integer | optional | maximum number of predictions per faces. Default value: 1 |
Response body on success:
{
"result": [
{
"box": {
"probability": <probability>,
"x_max": <integer>,
"y_max": <integer>,
"x_min": <integer>,
"y_min": <integer>
},
"faces": [
{
"similarity": <similarity1>,
"subject": <subject1>
},
...
]
}
]
}
Element | Type | Description |
---|---|---|
box | object | list of parameters of the bounding box for this face |
probability | float | probability that a found face is actually a face |
x_max, y_max, x_min, y_min | integer | coordinates of the frame containing the face |
faces | list | list of similar faces with size of <prediction_count> order by similarity |
similarity | float | similarity that on that image predicted person |
subject | string | name of the subject in Face Collection |
To retrieve a list of subjects saved in a Face Collection:
curl -X GET "http://localhost:8000/api/v1/faces" \
-H "x-api-key: <faces_collection_api_key>" \
Element | Description | Type | Required | Notes |
---|---|---|---|---|
x-api-key | header | string | required | api key of the Face Collection, created by the user |
Response body on success:
{
"faces": [
{
"image_id": <image_id>,
"subject": <subject>
},
...
]
}
Element | Type | Description |
---|---|---|
image_id | UUID | UUID of the face |
subject | string | of the person, whose picture was saved for this api key |
To delete all image examples of the :
curl -X DELETE "http://localhost:8000/api/v1/faces?subject=<subject>" \
-H "x-api-key: <faces_collection_api_key>"
Element | Description | Type | Required | Notes |
---|---|---|---|---|
x-api-key | header | string | required | api key of the Face Collection, created by the user |
subject | param | string | optional | is the name you assign to the image you save. Caution! If this parameter is absent, all faces in Face Collection will be removed |
Response body on success:
[
{
"image_id": <image_id>,
"subject": <subject>
},
...
]
Element | Type | Description |
---|---|---|
image_id | UUID | UUID of the removed face |
subject | string | of the person, whose picture was saved for this api key |
To delete an image by ID:
curl -X DELETE "http://localhost:8000/api/v1/faces/<image_id>" \
-H "x-api-key: <faces_collection_api_key>"
Element | Description | Type | Required | Notes |
---|---|---|---|---|
x-api-key | header | string | required | api key of the Face Collection, created by the user |
image_id | variable | UUID | required | UUID of the removing face |
Response body on success:
{
"image_id": <image_id>,
"subject": <subject>
}
Element | Type | Description |
---|---|---|
image_id | UUID | UUID of the removed face |
subject | string | of the person, whose picture was saved for this api key |
To compare faces from the uploaded images with the face in saved image ID:
curl -X POST "http://localhost:8000/api/v1/faces/<image_id>/verify?limit=<limit>&det_prob_threshold=<det_prob_threshold>" \
-H "Content-Type: multipart/form-data" \
-H "x-api-key: <faces_collection_api_key>" \
-F file=<local_file>
Element | Description | Type | Required | Notes |
---|---|---|---|---|
Content-Type | header | string | required | multipart/form-data |
x-api-key | header | string | required | api key of the Face Collection, created by the user |
image_id | variable | UUID | required | UUID of the verifying face |
file | body | image | required | allowed image formats: jpeg, jpg, ico, png, bmp, gif, tif, tiff, webp. Max size is 5Mb |
limit | param | integer | optional | maximum number of faces with best similarity in result. Value of 0 represents no limit. Default value: 0 |
det_prob_ threshold | param | string | optional | minimum required confidence that a recognized face is actually a face. Value is between 0.0 and 1.0. |
Response body on success:
{
"result": [
{
"box": {
"probability": <probability>,
"x_max": <integer>,
"y_max": <integer>,
"x_min": <integer>,
"y_min": <integer>
},
"similarity": <similarity1>
},
...
]
}
Element | Type | Description |
---|---|---|
box | object | list of parameters of the bounding box for this face |
probability | float | probability that a found face is actually a face |
x_max, y_max, x_min, y_min | integer | coordinates of the frame containing the face |
similarity | float | similarity that on that image predicted person |
subject | string | name of the subject in Face Collection |
Compreface roles system consists of two types of roles - global roles and application roles. The users with these roles have different responsibilities, so we recommend that you delimit such users and follow our recommendations to avoid giving too much access to sensitive information. Of course in small teams and at your own risk you can ignore these recommendations.
Global roles define what permissions you have in the system itself, and the main responsibility of such users is to maintain the system itself. We recommend that the most permissive (owner and administrator) roles be added to technical support employees. Then there is no reason to add such users to applications as they still will have all permissions within the application.
In CompreFace, the first user automatically receives the global owner role and has rights for any operation within CompreFace - managing users, and creating and managing applications. The only restriction for the global owner is that such a user can’t delete themselves from the system, so the user will have to assign the global owner role to somebody else and then remove themselves from the system.
Users with the global administrator role have the same permissions as users with the global owner role. The only difference is that such users can’t manage the user with the global owner role. We recommend reducing users with such a role to the minimum number required to maintain the system.
All new users are automatically assigned the global user role. These users can’t create applications, can access only the applications to which they were added, and can’t manage other users. These users use CompreFace for face recognition and are part of the development team; they are not responsible for managing other users and their permissions.
Application roles define the role of the user within an application, and the main responsibility of such users is to develop applications into which they are going to integrate Compreface. We recommend that the most permissive roles (owner and administrator) be added as project managers and team leads, as they are responsible for the application. We also recommend that all application users have the global user role. To become a member of an application team, users with a global user role need to be added to the application directly by the global owner, global administrator, or application owner.
The user that creates an application automatically receives the application owner role and has rights for any operation within the application - managing the application and its users, and creating and managing Face Collections. The only restriction for the application owner is that they can’t delete themselves from the application, so they have to assign the application owner role to somebody else before deleting themselves.
Users with the application administrator role (global user role + application admin role) can create and manage Face Collections but can’t manage an application and its users.
Users with the application user role can’t manage anything in the application. This is the least permissive role (global user role + application user role), but this provides enough information to integrate CompreFace with any other application, so we recommend that most CompreFace users have this role.
Finding a face
To detect one or more faces in an image, we used multi-task cascaded convolutional neural networks (MTCNNs).
Posing and projecting faces
To normalize all detected faces, we perform rotate, scale, and shear operations.
Calculating embeddings from faces
To calculate facial features, which are called embeddings, we use convolutional deep neural networks.
Recognizing and verifying faces using embeddings
To evaluate the level of similarity between saved faces and those in provided photos, we calculate the Euclidean distance using the ND4J library to determine the level of matching faces.
FaceNet: A Unified Embedding for Face Recognition and Clustering Florian Schroff, Dmitry Kalenichenko, James Philbin (Submitted on 17 Jun 2015)
Joint Face Detection and Alignment using Multi-task Cascaded Convolutional Neural Networks Kaipeng Zhang, Zhanpeng Zhang, Zhifeng Li, Yu Qiao (Submitted on 11 Apr 2016)
Inception-v4, Inception-ResNet and the Impact of Residual Connections on Learning Christian Szegedy, Sergey Ioffe, Vincent Vanhoucke, Alex Alemi (Submitted on 23 Aug 2016)
We want to improve our open-source face recognition solution, so your contributions are welcome and greatly appreciated. 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.
For java just import dev/team_codestyle.xml file in your IntelliJ IDEA.
Please report any bugs here://github.com/exadel-inc/CompreFace/issues.
If you are reporting a bug, please specify:
The best way to send us feedback is to file an issue at https://github.com/exadel-inc/CompreFace/issues.
If you are proposing a feature, please:
CompreFace is open-source real-time facial recognition software released under the Apache 2.0 license.
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。