github/deepface
1
1
Fork 0
mirror of https://github.com/serengil/deepface.git synced 2025-06-08 04:25:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

read me format

Browse Source
This commit is contained in:
Sefik Ilkin Serengil 2020-05-26 12:59:03 +03:00 committed by GitHub
parent b3c0211baa
commit d9a505f189
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 16 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
README.md
View File

@ -16,9 +16,11 @@ pip install deepface
## Face Recognition
[`Demo`](https://youtu.be/KRCvkNCOphE)
A modern face recognition pipeline consists of 4 common stages: detect, [align](https://sefiks.com/2020/02/23/face-alignment-for-face-recognition-in-python-within-opencv/), represent and verify. Deepface handles all these common stages in the background.
Verify function under the DeepFace interface is used for face recognition.
**Face Verification** - [`Demo`](https://youtu.be/KRCvkNCOphE)
Verification function under the DeepFace interface offers a single face recognition.
```python
from deepface import DeepFace
@ -29,8 +31,6 @@ print("Is verified: ", result["verified"])
<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/stock-1.jpg" width="95%" height="95%"></p>
Modern face recognition pipelines consist of 4 stages: detect, [align](https://sefiks.com/2020/02/23/face-alignment-for-face-recognition-in-python-within-opencv/), represent and verify. Deepface handles all these common stages in the background.
Each call of verification function builds a face recognition model from scratch and this is a costly operation. If you are going to verify multiple faces sequentially, then you should pass an array of faces to verification function to speed the operation up. In this way, complex face recognition models will be built once.
```python
@ -43,9 +43,7 @@ resp_obj = DeepFace.verify(dataset)
Items of resp_obj might be unsorted when you pass multiple instances to verify function. Please check the item indexes in the response object.
## Large scale face recognition
[`Demo`](https://youtu.be/Hrjp-EStM_s)
**Large scale face recognition** - [`Demo`](https://youtu.be/Hrjp-EStM_s)
You can [apply](https://youtu.be/Hrjp-EStM_s) face recognition on a large scale data set as well. Vector representations of faces in your database folder stored in a pickle file when find function is called once. Then, deepface just finds vector representation of the target image. Finding an identity in a large scale data set will be performed in just seconds.
@ -57,7 +55,7 @@ print(df.head())
#DeepFace.find(img_path = ["img1.jpg", "img2.jpg"], db_path = "C:/workspace/my_db") #apply face recognition for multiple identities. this will return a list including pandas dataframe items.
```
## Face recognition models
**Supported face recognition models**
Face recognition can be handled by different models. Currently, [`VGG-Face`](https://sefiks.com/2018/08/06/deep-face-recognition-with-keras/) , [`Google FaceNet`](https://sefiks.com/2018/09/03/face-recognition-with-facenet-in-keras/), [`OpenFace`](https://sefiks.com/2019/07/21/face-recognition-with-openface-in-keras/) and [`Facebook DeepFace`](https://sefiks.com/2020/02/17/face-recognition-with-facebook-deepface-in-keras/) models are supported in deepface. The default configuration verifies faces with **VGG-Face** model. You can set the base model while verification as illustared below. Accuracy and speed show difference based on the performing model.
@ -76,7 +74,7 @@ The complexity and response time of each face recognition model is different so
| Building | 2.35 s ± 46.9 ms | 6.37 s ± 1.28 s | 25.7 s ± 7.93 s | 23.9 s ± 2.52 s |
| Verification | 897 ms ± 38.3 ms | 616 ms ± 12.1 ms | 684 ms ± 7.69 ms | 605 ms ± 13.2 ms |
## Passing pre-built models
**Passing pre-built models**
You can build a face recognition model once and pass this to verify function as well. This might be logical if you need to call verify function several times.
@ -86,7 +84,7 @@ model = VGGFace.loadModel() #all face recognition models have loadModel() functi
DeepFace.verify("img1.jpg", "img2.jpg", model_name = "VGG-Face", model = model)
```
## Similarity
**Similarity**
Face recognition models are regular [`convolutional neural networks`](https://sefiks.com/2018/03/23/convolutional-autoencoder-clustering-images-with-neural-networks/) and they are responsible to represent face photos as vectors. Decision of verification is based on the distance between vectors. We can classify pairs if its distance is less than a [`threshold`](https://sefiks.com/2020/05/22/fine-tuning-the-threshold-in-face-recognition/). Distance could be found by different metrics such as [`Cosine Similarity`](https://sefiks.com/2018/08/13/cosine-similarity-in-machine-learning/), Euclidean Distance and L2 form. The default configuration finds the **cosine similarity**. You can alternatively set the similarity metric while verification as demostratred below.
@ -98,10 +96,10 @@ result = DeepFace.verify("img1.jpg", "img2.jpg", model_name = "VGG-Face", distan
## Facial Attribute Analysis
[`Demo`](https://youtu.be/GT2UeN85BdA)
Deepface also offers facial attribute analysis including [`age`](https://sefiks.com/2019/02/13/apparent-age-and-gender-prediction-in-keras/), [`gender`](https://sefiks.com/2019/02/13/apparent-age-and-gender-prediction-in-keras/), [`facial expression`](https://sefiks.com/2018/01/01/facial-expression-recognition-with-keras/) (including angry, fear, neutral, sad, disgust, happy and surprise)and [`race`](https://sefiks.com/2019/11/11/race-and-ethnicity-prediction-in-keras/) (including asian, white, middle eastern, indian, latino and black) predictions. Analysis function under the DeepFace interface is used to find demography of a face.
[`Demo`](https://youtu.be/GT2UeN85BdA)
```python
from deepface import DeepFace
demography = DeepFace.analyze("img4.jpg") #passing nothing as 2nd argument will find everything
@ -123,7 +121,7 @@ Model building and prediction times are different for those facial analysis mode
| Building | 243 ms ± 15.2 ms | 2.25 s ± 34.9 | 2.25 s ± 90.9 ms | 2.23 s ± 68.6 ms |
| Prediction | 389 ms ± 11.4 ms | 524 ms ± 16.1 ms | 516 ms ± 10.8 ms | 493 ms ± 20.3 ms |
## Passing pre-built models
**Passing pre-built models**
You can build facial attribute analysis models once and pass these to analyze function as well. This might be logical if you need to call analyze function several times.
@ -142,9 +140,9 @@ DeepFace.analyze("img1.jpg", models=models)
## Streaming and Real Time Analysis
[`Demo`](https://youtu.be/-c9sSJcx6wI)
You can run deepface for real time videos as well. [`Demo`](https://youtu.be/-c9sSJcx6wI)
You can run deepface for real time videos as well. Calling stream function under the DeepFace interface will access your webcam and apply both face recognition and facial attribute analysis. Stream function expects a database folder including face images. VGG-Face is the default face recognition model and cosine similarity is the default distance metric similar to verify function. The function starts to analyze if it can focus a face sequantially 5 frames. Then, it shows results 5 seconds.
Calling stream function under the DeepFace interface will access your webcam and apply both face recognition and facial attribute analysis. Stream function expects a database folder including face images. VGG-Face is the default face recognition model and cosine similarity is the default distance metric similar to verify function. The function starts to analyze if it can focus a face sequantially 5 frames. Then, it shows results 5 seconds.
```python
from deepface import DeepFace
@ -169,12 +167,12 @@ BTW, you should use regular slash ( / ) instead of backslash ( \ ) in Windows OS
## API
[`Demo`](https://youtu.be/HeKCQ6U9XmI)
Deepface serves an API as well. [`Demo`](https://youtu.be/HeKCQ6U9XmI)
You can clone [`/api/api.py`](https://github.com/serengil/deepface/tree/master/api/api.py) and pass it to python command as an argument. This will get a rest service up. In this way, you can call deepface from an external system.
<p align="center"><img src="https://raw.githubusercontent.com/serengil/deepface/master/icon/deepface-api.jpg" width="90%" height="90%"></p>
Deepface [serves](https://youtu.be/HeKCQ6U9XmI) an API as well. You can clone [`/api/api.py`](https://github.com/serengil/deepface/tree/master/api/api.py) and pass it to python command as an argument. This will get a rest service up.
```
python api.py
```