# WEBFACE SOURCECODE

Bachelor's thesis by **Sergi Díaz Planas**, submitted to Univerity of Barcelona, 
Faculty of Mathematics and Computer Science, 2018.

- - - - 

### Index
1. [WF-WEB Content](#1-wf-web-content)
2. [WF-CPP Content](#2-wf-cpp-content)
3. [Compilation](#3-compilation)
4. [Installation](#4-installation)
5. [Configuration](#5-configuration)
6. [Usage](#6-usage)
- - - -

## 1. WF-WEB Content

### Client

WF-WEB/client content is organized as follows:

* index.php - Webface client's site main layout
* layout:
    * reference.php   
    * validation.php  
    * private.php    
* php:
    * logout.php
* scripts:
    * camera.js
    * client.js
    * config.js
    * network.js
* styles:
    * client.css

The folder named as **client** contains all files related to the client layer. That includes the layouts
for the various pages that compose the Webface client site, the style sheet and scripts. The later have 
been distributed in 4 files. Then, **camera.js** contains scripts that regulate the access to the webcam, 
**network.js** has scripts that communicate with service layer and **client.js** manages the resources of client
layer. Parameters related to the configuration of the client, including the server address and the sizes
of the DNI document, are to be found at **config.js**.



### Server

WF-WEB/server content is organized as follows:

* server.php
* config.php
* resources:
    * tessdata 
    * dlib_face_recognition_resnet_model_v1.dat
    * haarcascade_frontalface_alt.xml
    * shape_predictor_5_face_landmarks.dat
* utils:
    * idvalidation.php
    * protocol.php

The folder named as **client** contains all files related to the service layer. The server's logic is to be
found at **server.php**. Logic relevant to communication with client layer is at **protocol.php**, the configuration
of the service layer is accessible at **config.php** and **idvalidation.php** contains methods for processing the 
data found in the user's DNI. The resources needed for loading computer vision components is at **resources**.

- - - -


## 2. WF-CPP Content

This directory contains the C++ source code files, related to the computer 
vision layer.

* base64.h
* base64.cpp
* Face.h
* Face.cpp
* FaceDetector.h
* FaceDetector.cpp
* FaceVerifier.h
* FaceVerifier.cpp
* idvalidation.h
* idvalidation.cpp
* Image.h
* Image.cpp
* main.cpp
* Reader.h
* Reader.cpp
* utils.h
* utils.cpp

Most files here are self explanatory. The **main.cpp** file contains code for the integration layer.

- - - - 


## 3. Compilation

A Makefile is included to ease the compilation of the PHP extension, though it may 
require some editing to specify the location of the source files and the needed libraries. 
The Makefile has comments on the lines which might need to be edited. An already compilated 
extension can be found in the **Installables** directory.

Libraries needed:
* [OpenCV](https://opencv.org/releases.html)
* [dlib](http://dlib.net/)

- - - - 


## 4. Installation

The 'Installables' directory contains:

* webface.so
* webface.ini

Where webface.so is an already compiled WEBFACE extension for PHP. Webface is currently available only for [PHP5](http://php.net/downloads.php). The following command makes use of the Makefile to install the compiled extension. 
Note that the Makefile contains references of the path to the PHP configuration file and the extensions directory 
which might need to be edited. 

```
sudo make install
```

If necessary, make use of the following command to find the path to configuration file and extensions directory in
your computer.

```
php-config
```


- - - - 


## 5. Configuration

Server's settings can be changed by modifying the parameters found in its configuration file, located at
**./WF-WEB/server** directory. The parameters which can be modified are:

* The data used by the Detector, Verifier and Reader components. The default data files are located at ./WF-WEB/server/resources.
* The tolerance of the Verifier. By lowering the tolerance value, the chances for the Verifier component to predict that two faces belong to the same person decreases.
* Component persistence. 


Regarding component persistence, by default the server does not store in session the Detector, Verifier and Reader components. This means that the data files have to be loaded each time a request is received. Loading the default data files has a low cost when compared to the face detection and face verification processes, and so it is considered that it does not hinder the application performance. 

- - - - 


## 6. Usage 

Webface sourcecode comes with a basic website designed for testing the verification pipeline. If chosen to be run in the PHP built-in web
server, please use this command from **WF-WEB directory**:

```
php5 -S localhost:8080
```

Then go to [localhost:8080/client/index.php](localhost:8080/client/index.php) with the browser of your election.


The sole content of the index, apart from the title of the site, is a **Register** button and a **Log in** button. The log in has not 
been implemented for this testing website, and so its button is disabled. Pressing the **Register** button leads to **Reference**.

![Figure 1](./Images/fig1.png)


The reference setting view includes a form with fields for name, surname and DNI. These fields are editable for the user. The user can also 
stop the registration process by pressing **Cancel** button. The **Continue** button is disabled until a valid reference image has been set.
It redirects to the **Validation** view. Press **Play** to start recording.

![Figure 2](./Images/fig2.png)


The validation view resembles the reference one. The continue button has been substituded by **Finish** button. Navigation to the
private site is performed automatically after a successfu validation.

![Figure 3](./Images/fig3.png)


If validated successfuly, the **Private** view becomes accessible. It contains nothing but a salute message and a **Log out** button, which
clears user session so that the registration process can be repeated.

![Figure 4](./Images/fig4.png)

- - - - 