You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: examples/pytorch/vision/Face_Detection/README.md
+28-22Lines changed: 28 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,9 +1,10 @@
1
-
# Code for Face Detection experiments with RNNPool
1
+
# Code for Face Detection Experiments with RNNPool
2
+
Refer to README_M4.md for instructions related to the M4 model
2
3
## Requirements
3
-
1. Follow instructions to install requirements for EdgeML operators and the EdgeML operators[here](https://github.com/microsoft/EdgeML/blob/master/pytorch/README.md).
4
+
1. Follow instructions to install EdgeML operators and their pre-requisites[here](https://github.com/microsoft/EdgeML/blob/master/pytorch/README.md).
4
5
2. Install requirements for face detection model using
5
6
``` pip install -r requirements.txt ```
6
-
We have tested the installation and the code on Ubuntu 18.04 with Cuda 10.2 and CuDNN 7.6
7
+
We have tested the installation and the code on Ubuntu 18.04 with Python 3.6, Cuda 10.2 and CuDNN 7.6
7
8
8
9
## Dataset
9
10
1. Download WIDER face dataset images and annotations from http://shuoyang1213.me/WIDERFACE/ and place them all in a folder with name 'WIDER_FACE'. That is, download WIDER_train.zip, WIDER_test.zip, WIDER_val.zip, wider_face_split.zip and place it in WIDER_FACE folder, and unzip files using:
@@ -18,12 +19,17 @@ cd ..
18
19
19
20
```
20
21
21
-
2. In `data/config.py` , set _C.HOME to the parent directory of the above folder, and set the _C.FACE.WIDER_DIR to the folder path.
22
-
That is, if the WIDER_FACE folder is created in /mnt folder, then _C.HOME='/mnt'
23
-
_C.FACE.WIDER_DIR='/mnt/WIDER_FACE'.
24
-
Similarly, change `data/config_qvga.py` to set _C.HOME and _C.FACE.WIDER_DIR.
22
+
2. Set environment variable DATA_HOME to the parent directory of the above folder
23
+
That is, if the WIDER_FACE folder is created in /mnt folder
24
+
25
+
``` export DATA_HOME='/mnt' ```
26
+
27
+
Note that for Windows '/' should be replaced by '\'.
28
+
For all following commands the environment variable IS_QVGA_MONO has to be set as 0 for using config.py (to use RGB 640x480 images) and as 1 for using config_qvga.py (to use monochrome 320x240 images) as the configuration file.
@@ -64,15 +70,15 @@ There are two modes of testing the trained model -- the evaluation mode to gener
64
70
65
71
#### Evaluation Mode
66
72
67
-
Given a set of images in <your_image_folder>, `eval/py` generates bounding boxes around faces (where the confidence is higher than certain threshold) and write the images in <your_save_folder>. To evaluate the `rpool_face_best_state.pth` model (stored in ./weights), execute the following command:
73
+
Given a set of images in <your_image_folder>, `eval/py` generates bounding boxes around faces (where the confidence is higher than certain threshold) and write the images in <your_save_folder>. Specify if the model was trained in multigpu setting in --multigpu. To evaluate the `rpool_face_best_state.pth` model (stored in ./weights), execute the following command:
This will save images in <your_save_folder> with bounding boxes around faces, where the confidence is high. Here is an example image with a single bounding box.
@@ -86,15 +92,15 @@ If IS_QVGA_MONO=1 the evaluation code accepts an image of any size and resizes a
86
92
#### WIDER Set Test
87
93
In this mode, we test the generated model against the provided WIDER_FACE validation and test dataset.
88
94
89
-
For this, first run the following to generate predictions of the model and store output in the '--save_folder' folder.
95
+
For this, first run the following to generate predictions of the model and store output in the '--save_folder' folder. Specify if the model was trained in multigpu setting in --multigpu.
The above command generates predictions for each image in the "validation" dataset. For each image, a separate prediction file is provided (image_name.txt file in appropriate folder). The first line of the prediction file contains the total number of boxes identified.
@@ -104,8 +110,8 @@ If IS_QVGA_MONO=1 then testing is done by converting images to monochrome and QV
104
110
105
111
The architecture RPool_Face_QVGA_monochrome is for QVGA monochrome format while RPool_Face_C and RPool_Face_Quant are for VGA RGB format.
106
112
107
-
###### For calculating MAP scores:
108
-
Now using these boxes, we can compute the standard MAP score that is widely used in this literature (see [here](https://medium.com/@jonathan_hui/map-mean-average-precision-for-object-detection-45c121a31173) for more details) as follows:
113
+
###### For calculating mAP scores:
114
+
Now using these boxes, we can compute the standard mAP score that is widely used in this literature (see [here](https://medium.com/@jonathan_hui/map-mean-average-precision-for-object-detection-45c121a31173) for more details) as follows:
109
115
110
116
1. Download eval_tools.zip from http://shuoyang1213.me/WIDERFACE/support/eval_script/eval_tools.zip and unzip in a folder of same name in this directory.
2. Set up scripts to use the Matlab '.mat' data files in eval_tools/ground_truth folder for MAP calculation: The following installs python files that provide the same functionality as the '.m' matlab scripts in eval_tools folder.
125
+
2. Set up scripts to use the Matlab '.mat' data files in eval_tools/ground_truth folder for mAP calculation: The following installs python files that provide the same functionality as the '.m' matlab scripts in eval_tools folder.
3. Run ```python3 evaluation.py -p <your_save_folder> -g <groud truth dir>``` in WiderFace-Evaluation folder
128
134
129
-
where `prediction_dir` is the '--save_folder' used for `wider_test.py` above and <groudtruthdir> is the subfolder `eval_tools/ground_truth`. That is in, WiderFace-Evaluation directory, run:
135
+
where `-p` is the '--save_folder' used for `wider_test.py` above and <groudtruthdir> is the subfolder `eval_tools/ground_truth`. That is in, WiderFace-Evaluation directory, run:
This script should output the MAP for the WIDER-easy, WIDER-medium, and WIDER-hard subsets of the dataset. Our best performance using RPool_Face_Quant model is: 0.80 (WIDER-easy), 0.78 (WIDER-medium), 0.53 (WIDER-hard).
140
+
This script should output the mAP for the WIDER-easy, WIDER-medium, and WIDER-hard subsets of the dataset. Our best performance using RPool_Face_Quant model is: 0.80 (WIDER-easy), 0.78 (WIDER-medium), 0.53 (WIDER-hard).
135
141
136
142
137
143
##### Dump RNNPool Input Output Traces and Weights
138
144
139
-
To save model weights and/or input output pairs for each patch through RNNPool in numpy format use the command below. Put images which you want to save traces for in <your_image_folder> . Specify output folder for saving model weights in numpy format in <your_save_model_numpy_folder>. Specify output folder for saving input output traces of RNNPool in numpy format in <your_save_traces_numpy_folder>. Note that input traces will be saved in a folder named 'inputs' and output traces in a folder named 'outputs' inside <your_save_traces_numpy_folder>.
145
+
For saving model weights and/or input output pairs for each patch through RNNPool in numpy format use the command below. Put images which you want to save traces for in <your_image_folder> . Specify output folder for saving model weights in numpy format in <your_save_model_numpy_folder>. Specify output folder for saving input output traces of RNNPool in numpy format in <your_save_traces_numpy_folder>. Note that input traces will be saved in a folder named 'inputs' and output traces in a folder named 'outputs' inside <your_save_traces_numpy_folder>.
# Code for Face Detection Experiments with RNNPool
2
+
## Requirements
3
+
1. Follow instructions to install EdgeML operators and their pre-requisites [here](https://github.com/microsoft/EdgeML/blob/master/pytorch/README.md).
4
+
2. Install requirements for face detection model using
5
+
``` pip install -r requirements.txt ```
6
+
We have tested the installation and the code on Ubuntu 18.04 with Python 3.6, Cuda 10.2 and CuDNN 7.6
7
+
8
+
## Dataset - WIDER Face
9
+
1. Download WIDER face dataset images and annotations from http://shuoyang1213.me/WIDERFACE/ and place them all in a folder with name 'WIDER_FACE'. That is, download WIDER_train.zip, WIDER_test.zip, WIDER_val.zip, wider_face_split.zip and place it in WIDER_FACE folder, and unzip files using:
10
+
11
+
```shell
12
+
cd WIDER_FACE
13
+
unzip WIDER_train.zip
14
+
unzip WIDER_test.zip
15
+
unzip WIDER_val.zip
16
+
unzip wider_face_split.zip
17
+
cd ..
18
+
19
+
```
20
+
21
+
2. Set environment variable DATA_HOME to the parent directory of the above folder
22
+
That is, if the WIDER_FACE folder is created in /mnt folder
23
+
24
+
``` export DATA_HOME='/mnt' ```
25
+
26
+
Note that for Windows '/' should be replaced by '\'.
Download SCUT Head Part B dataset images and annotations from https://github.com/HCIILAB/SCUT-HEAD-Dataset-Release. Unzipping will create a folder by the name 'SCUT_HEAD_Part_B'. Place this folder in the same parent directory as the WIDER_FACE folder.
This will save checkpoints after every '--save_frequency' number of iterations in a weight file with 'checkpoint.pth' at the end and weights for the best state in a file with 'best_state.pth' at the end. These will be saved in '--save_folder'. For resuming training from a checkpoint, use '--resume <checkpoint_name>.pth' with the above command. For example,
If IS_QVGA_MONO is 0 then training input images will be 640x640 and RGB.
55
+
If IS_QVGA_MONO is 1 then training input images will be 320x320 and converted to monochrome.
56
+
57
+
Input images for training models are cropped and reshaped to square to maintain consistency with [S3FD](https://arxiv.org/abs/1708.05237). However testing can be done on any size of images, thus we resize testing input image size to have area equal to VGA (640x480)/QVGA (320x240), so that aspect ratio is not changed.
58
+
59
+
The architecture RPool_Face_QVGA_monochrome and RPool_Face_M4 is for QVGA monochrome format while RPool_Face_C and RPool_Face_Quant are for VGA RGB format.
60
+
61
+
## Finetuning
62
+
63
+
To obtain a model better suited for conference room scenarios we finetune our model on the SCUT Head B dataset. Set --finetune as True and pass the model pretrained on WIDER_FACE in --resume as follows:
There are two modes of testing the trained model -- the evaluation mode to generate bounding boxes for a set of sample images, and the test mode to compute statistics like mAP scores.
74
+
75
+
#### Evaluation Mode
76
+
77
+
Given a set of images in <your_image_folder>, `eval/py` generates bounding boxes around faces (where the confidence is higher than certain threshold - 0.5 in this case) and write the images in <your_save_folder>. Specify if the model was trained in multigpu setting in --multigpu. To evaluate the `rpool_face_best_state.pth` model (stored in ./weights), execute the following command:
This will save images in <your_save_folder> with bounding boxes around faces, where the confidence is high. It is recommended to use the model finetuned on SCUT Head for evaluation.
84
+
85
+
If IS_QVGA_MONO=0 the evaluation code accepts an image of any size and resizes it to 640x480x3 while preserving original image aspect ratio.
86
+
87
+
If IS_QVGA_MONO=1 the evaluation code accepts an image of any size and resizes and converts it to monochrome to make it 320x240x1 while preserving original image aspect ratio.
88
+
89
+
90
+
#### Saving Full Model Traces
91
+
Setting the flag --save_traces as True will save input output traces in two separate .npy files for each image in <your_image_folder>, given the architecture and trained model. Run:
For generating traces on SCUT Head images, set <your_image_folder> as $DATA_HOME/SCUT_HEAD_Part_B/JPEGImages/
99
+
100
+
#### SCUT Head Validation Set Test
101
+
In this mode, we test the generated model against the provided SCUT Head Part B validation dataset. Use the SCUT Head finetuned model for this step.
102
+
103
+
For this, first run the following to generate predictions of the model and store output in the '--save_folder' folder. Specify if the model was trained in multigpu setting in --multigpu.
The above command generates predictions for each image in the "validation" dataset. For each image, a separate prediction file is provided (image_name.txt file in appropriate folder). The first line of the prediction file contains the total number of boxes identified.
110
+
Then each line in the file corresponds to an identified box. For each box, five numbers are generated: length of the box, height of the box, x-axis offset, y-axis offset, confidence value for presence of a face in the box.
111
+
112
+
If IS_QVGA_MONO=1 then testing is done by converting images to monochrome and QVGA, else if IS_QVGA_MONO=0 then testing is done on VGA RGB images.
113
+
114
+
###### For calculating mAP scores:
115
+
Now using these boxes, we can compute the standard mAP score that is widely used in this literature (see [here](https://medium.com/@jonathan_hui/map-mean-average-precision-for-object-detection-45c121a31173) for more details).
Run ```IS_QVGA_MONO=1 python3 scut_evaluation.py -p ../rpool_face_m4_val ``` in WiderFace-Evaluation folder.
126
+
127
+
where `-p` is the '--save_folder' used for `scut_test.py` above.
128
+
129
+
This script should output the mAP on SCUT Head Part B Validation set. Our best performance using RPool_Face_M4 model is: 0.61.
130
+
131
+
132
+
##### Dump RNNPool Input Output Traces and Weights
133
+
134
+
For saving model weights and/or input output pairs for each patch through RNNPool in numpy format use the command below. Put images which you want to save traces for in <your_image_folder> . Specify output folder for saving model weights in numpy format in <your_save_model_numpy_folder>. Specify output folder for saving input output traces of RNNPool in numpy format in <your_save_traces_numpy_folder>. Note that input traces will be saved in a folder named 'inputs' and output traces in a folder named 'outputs' inside <your_save_traces_numpy_folder>.
0 commit comments