The following codebase is a face recognition toolkit. It consists of three endpoints: A communal endpoint that uploads the images given an ID, an endpoint which copies these images to the image databaase, and an endpoints which verifies the image.

In this documentn we'll explain how this codebase works.

Jump to Section:

• Face Recognition System
  • Endpoints API
    • Resulting Codes
  • Run Development Mode
    • Environment Variables

After launching an instnce of faceapp.py on development mode, you can use Postman or in case you're in mood for CLI, cURL to run the following commands. They, given the accopanying data, will trigger a chain of functions and they, in turn, will perform an action.

The following table documents these three endpoints:

Here's how it works.

You first upload how many images you want using upload_imgs/?id=[reco_id] for example upload_imgs/?id=RECO_ID_000023. The JSON response, if successful, will return the name of a subdirectory inside your UPLOAD_FOLDER (see: Environment Variables). For example, RECO_ID_000023-13134.

/upload_imgs yields a JSON response which contain:

Now you have two options:

Option 1: Use /upload_db and save the faces inside the images, and a few augmented versions (depending on AUG_NUM, again see: Environment Variables) to your DB_PATH under a subfolder called {given_name}-{RECO_ID}. The data wil lbe saved to MySQL.

The following form data can be passed to upload_db:

This endpoint will yield a JSON response containing the following keys:

After upload to image DB is done, the folder will be renamed and it can't be used anymore.

Option 2: Use /verify, detect the faces, create augmented versions, and send the images down the verification pipline.

/verify accepts the following keys:

This endpoint will return the following results:

The API will return codes. These codes are stored in codes_dict.py. The *_message will return the message of this code. You can view the message for each code here:

For now, until I deploy this codebase to server and make a frontend for it, please test it by running it on your local machine. To do that:

1. Install Mini Conda.
2. Create an environment by conda create -n face-reco python=3.9
3. Activate the environment by conda activate face-reco
4. Navigate to the main folder and run pip install -r requirements.txt
5. Make sure the Environment Variables are set and port 8001 is free.
6. Make sure MySQL is installed on your system and the schema and the table exist to what is specified in .env.
7. Run python faceapp.py.
8. Download Postman from the link earlier in this document.
9. Send requests.
10. If you run into any problems contact either me (Chubak#7400), Szymon, or Felix.
11. You may need to install dlib.

You can use this file to test. This file is also used in unit tests.

Note: Your table schema should look like this:

Columns: ID, RECO_ID, RECO_NAME, RECO_PATH
Types: PK, VARCHAR(12), VARCHAR(200), VARCHAR(500)

Names of columns can change BUT THEIR ORDER CAN'T.

In order for this application to run, it requires a long list of environment variables. This file is validated, and if a key doesn't exist in it, or doesn't match the desired pattern, the endpoint will return system_errors. This key maps to two sub-keys, not_in_env which lists all the keys that are not in .env file, and env_errs, which contains all the errors generated from not matching the .env file.

So create a file in the root called .env and make sure it contains the following keys, separted by a newline. Each key must be assigned with an equal sign (KEY=VALUE).