Skip to content

Commit

Permalink
clean the Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@sajjjadayobi
sajjjadayobi authored May 7, 2022
1 parent d84454d commit c6a7677
Showing 1 changed file with 80 additions and 135 deletions.
215 changes: 80 additions & 135 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,180 +1,139 @@
# [FaceLib](https://github.com/sajjjadayobi/FaceLib):
- use for Detection, Facial Expression, Age & Gender Estimation and Recognition with PyTorch
- this repository works with CPU and GPU(Cuda)

## Installation
- Clone and install with this command:
- with pip and automatic installs everything all you need
- `pip install git+https://github.com/sajjjadayobi/FaceLib.git`

- or with cloning the repo and install required packages
- `git clone https://github.com/sajjjadayobi/FaceLib.git`
- you can see the required packages in [requirements.txt](https://github.com/sajjjadayobi/FaceLib/blob/master/requirements.txt)
# [FaceLib](https://github.com/sajjjadayobi/FaceLib): Face Analysis
Used for face detection, facial expression, AgeGender estimation and recognition with PyTorch.
- Instalation: `pip install git+https://github.com/sajjjadayobi/FaceLib.git`

## How to use:
- the simplest way is at [example_notebook.ipynb](https://github.com/sajjjadayobi/FaceLib/blob/master/example_notebook.ipynb)
- for low-level usage check out the following sections
- if you have an NVIDIA GPU don't change the device param if not use `cpu`
Check this [example_notebook](https://github.com/sajjjadayobi/FaceLib/blob/master/example_notebook.ipynb) or take a look at the following sections

## 1. Face Detection: RetinaFace

- you can use these backbone networks: Resnet50, mobilenet
- default weights and model is `mobilenet` and it will be automatically download
- for more details, you can see the documentation
- The following example illustrates the ease of use of this package:

```python
from facelib import FaceDetector
detector = FaceDetector()
boxes, scores, landmarks = detector.detect_faces(image)
```

- FaceDetection live on your webcam
You can use these backbone networks: Resnet50, mobilenet. Default model is `mobilenet` and it will be automatically downloaded.
- The following example illustrates the ease of use of this package on your webcam:
```python
from facelib import WebcamFaceDetector
from facelib import WebcamFaceDetector
detector = WebcamFaceDetector()
detector.run()
```
- Low-level access to bounding boxes and face landmarks
```python
from facelib import FaceDetector
detector = FaceDetector()
boxes, scores, landmarks = detector.detect_faces(image)
```


- you can check or change it [Face Detector](https://github.com/sajjjadayobi/FaceLib/tree/master/facelib/Retinaface)

#### WiderFace Validation Performance on a single scale When using Mobilenet for backbone
| Style | easy | medium | hard |
|:-|:-:|:-:|:-:|
| Pytorch (same parameter with Mxnet) | 88.67% | 87.09% | 80.99% |
| Pytorch (original image scale) | 90.70% | 88.16% | 73.82% |
| Mxnet(original image scale) | 89.58% | 87.11% | 69.12% |


## 2. Face Alignment: Similar Transformation
- always use detect_align it gives you better performance
- you can use this module like this:
- `detect_align` instead of `detect_faces`

## 2. Face Alignment: Using face landmarkd
For face aligment always use the `detect_align` function it gives you better performance.
- Face detection and aligment using the `detect_align` function.
```python
from facelib import FaceDetector
detector = FaceDetector()
faces, boxes, scores, landmarks = detector.detect_align(image)
```

- for more details read detect_image function documentation
- let's see a few examples

Original | Aligned & Resized | Original | Aligned & Resized |
|---|---|---|---|
|![image](https://github.com/sajjjadayobi/FaceLib/blob/master/facelib/imgs/input1.jpg)|![image](https://github.com/sajjjadayobi/FaceLib/blob/master/facelib/imgs/res1.jpg)|![image](https://github.com/sajjjadayobi/FaceLib/blob/master/facelib/imgs/input2.jpg)|![image](https://github.com/sajjjadayobi/FaceLib/blob/master/facelib/imgs/res2.jpg)|


## 3. Age & Gender Estimation:
- I used UTKFace DataSet for Age & Gender Estimation
- default weights and model is `ShufflenetFull` and it will be automatically download
- you can use this module like this:

`ShufflenetFull` is the default model, and it will be automatically downloaded.
- Age and gender estimation live on your webcam (or any camera)
```python
from facelib import FaceDetector, AgeGenderEstimator

face_detector = FaceDetector()
age_gender_detector = AgeGenderEstimator()

faces, boxes, scores, landmarks = face_detector.detect_align(image)
genders, ages = age_gender_detector.detect(faces)
print(genders, ages)
```
from facelib import WebcamAgeGenderEstimator
estimator = WebcamAgeGenderEstimator()
estimator.run()
```

- AgeGenderEstimation live on your webcam
- Low-lvel access to ages and genders
```python
from facelib import WebcamAgeGenderEstimator
estimator = WebcamAgeGenderEstimator()
estimator.run()
```
from facelib import FaceDetector, AgeGenderEstimator
face_detector = FaceDetector()
age_gender_detector = AgeGenderEstimator()

faces, boxes, scores, landmarks = face_detector.detect_align(image)
genders, ages = age_gender_detector.detect(faces)
print(genders, ages)
```

## 4. Facial Expression Recognition:
- Facial Expression Recognition using Residual Masking Network
- default weights and model is `densnet121` and it will be automatically download
- face size must be (224, 224), you can fix it in FaceDetector init function with face_size=(224, 224)

```python
from facelib import FaceDetector, EmotionDetector

face_detector = FaceDetector(face_size=(224, 224))
emotion_detector = EmotionDetector()

faces, boxes, scores, landmarks = face_detector.detect_align(image)
list_of_emotions, probab = emotion_detector.detect_emotion(faces)
print(list_of_emotions)
```

- EmotionDetector live on your webcam
The default model is `densnet121` and it will be automatically downloaded. Note that face size must be (224, 224).
- Emotion detector live on your webcam
```python
from facelib import WebcamEmotionDetector
detector = WebcamEmotionDetector()
detector.run()
from facelib import WebcamEmotionDetector
detector = WebcamEmotionDetector()
detector.run()
```

- on my Webcam 🙂
- Emotions as an array with their probabilities
```python
from facelib import FaceDetector, EmotionDetector
face_detector = FaceDetector(face_size=(224, 224))
emotion_detector = EmotionDetector()

faces, boxes, scores, landmarks = face_detector.detect_align(image)
emotions, probab = emotion_detector.detect_emotion(faces)
```
- on my Webcam 🙂
![Alt Text](https://github.com/sajjjadayobi/FaceLib/blob/master/facelib/imgs/emotion.gif)

## 5. Face Recognition: InsightFace
- This module is a reimplementation of Arcface(paper), or Insightface(Github)
- This module is a pytorch reimplementation of Arcface(paper), or Insightface(Github)

#### Pretrained Models & Performance

- IR-SE50


| LFW(%) | CFP-FF(%) | CFP-FP(%) | AgeDB-30(%) | calfw(%) | cplfw(%) | vgg2_fp(%) |
| ------ | --------- | --------- | ----------- | -------- | -------- | ---------- |
| 0.9952 | 0.9962 | 0.9504 | 0.9622 | 0.9557 | 0.9107 | 0.9386 |

- Mobilefacenet

| LFW(%) | CFP-FF(%) | CFP-FP(%) | AgeDB-30(%) | calfw(%) | cplfw(%) | vgg2_fp(%) |
| ------ | --------- | --------- | ----------- | -------- | -------- | ---------- |
| 0.9918 | 0.9891 | 0.8986 | 0.9347 | 0.9402 | 0.866 | 0.9100 |

#### Prepare the Facebank (For testing over camera, video or image)
- the faces images you want to detect it save them in this folder:
```
Insightface/models/data/facebank/
---> person_1/
---> img_1.jpg
---> img_2.jpg
---> person_2/
---> img_1.jpg
---> img_2.jpg
```
- you can save a new preson in facebank with 3 ways:
- use `add_from_webcam`: it takes 4 images and saves them on facebank
```python
from facelib import add_from_webcam
add_from_webcam(person_name='sajjad')
```

- use `add_from_folder`: it takes a path with some images from just a person
```python
from facelib import add_from_folder
add_from_folder(folder_path='./', person_name='sajjad')
```

- or add faces manually (just face of a person not image of a person)
- I don't suggest this

#### Using
- default weights and model is `mobilenet` and it will be automatically download
#### Prepare the Facebank
Save the images of the **faces** you want to detect in this folder
```
Insightface/models/data/facebank/
---> person_1/
---> img_1.jpg
---> img_2.jpg
---> person_2/
---> img_1.jpg
---> img_2.jpg
```
You can save a new preson in facebank with 2 ways:
- Use `add_from_webcam`: it takes 4 images and saves them on facebank.
```python
from facelib import add_from_webcam
add_from_webcam(person_name='sajjad')
```
- use `add_from_folder`: it takes a path with some images from just a person.
```python
from facelib import add_from_folder
add_from_folder(folder_path='./', person_name='sajjad')
```

#### Recognizer
The default model is `mobilenet` and it will be automatically downloaded
- Face Recognition live on your webcam
```python
from facelib import WebcamVerify
verifier = WebcamVerify(update=True)
verifier.run()
```
- Low-level access to your images
```python
import cv2
from facelib import FaceRecognizer, FaceDetector
from facelib import update_facebank, load_facebank, special_draw, get_config

conf = get_config()
# conf.use_mobilenet=False # if you want to use the bigger model
detector = FaceDetector(device=conf.device)
face_rec = FaceRecognizer(conf)

# set True when you add someone new
# set True when you add someone new to the facebank
update_facebank_for_add_new_person = False
if update_facebank_for_add_new_person:
targets, names = update_facebank(conf, face_rec.model, detector)
Expand All @@ -188,20 +147,6 @@ print(names[results.cpu()])
for idx, bbox in enumerate(boxes):
special_draw(image, bbox, landmarks[idx], names[results[idx]+1], score[idx])
```

- Face Recognition live on your webcam
```python
from facelib import WebcamVerify
verifier = WebcamVerify(update=True)
verifier.run()
```


- example of run this code:

![image](https://github.com/sajjjadayobi/FaceLib/blob/master/facelib/imgs/face_rec.jpg)

## Reference:
- [InsightFace](https://github.com/TreB1eN/InsightFace_Pytorch)
- [RetinaFace](https://github.com/biubug6/Pytorch_Retinaface)
- [Facial Expression](https://github.com/phamquiluan/ResidualMaskingNetwork)
Reference: [InsightFace](https://github.com/TreB1eN/InsightFace_Pytorch)

0 comments on commit c6a7677

Please sign in to comment.