Vultus Facial Recognition is a C++ project to recognize members of Tecnológico de Monterrey CSF.
Table of Contents
A facial recognition access system that will grant access to registered users if their face is recognized, and will deny access to non-registered users. In addition, it comes with the functionality of registering new users to the database for future access.
- The system recognizes members of Tecnológico de Monterrey CSF.
- The system throws alerts in case the credential does not match the face.
- The system allows to authenticate (comparing) the data of the students with those of the credential.
- The system grants access if the data matches.
- The system shows an alert whether or not he/she is the person.
- The system allows the enrollment of new students.
- The system verifies or identifies the student.
- The system runs in macOS (10.14+), Linux (Ubuntu 18.04+), (Windows not officially supported, but might work).
- Data in the system stays safe and secure.
- Written in C++.
This project uses the following dependencies:
- OpenCV for facial recognition.
- Dlib toolkit for several algorithms.
- Mongocxx Driver for connecting to MongoDB using C++.
- MongoDB for storing face data and users.
- CMake for compiling.
To get a local copy up and running follow these simple example steps.
This project requires that all of its dependencies are correctly installed before running.
To setup the database:
- Download the database info here
- Decompress
ImgFiles.zipandMatFiles.zip - Substitute files in
Database/storage/
There must be a camera attached to the computer for the program to work fully.
NOTE: To use the webcam you must run Vultus in Linux. The GUI works both in Linux and MacOS, however, you can only use the CLI if you are in Windows.
- Clone the repo
git clone https://github.com/empobla/Vultus-Facial-Recognition.git
- Compile
cd Vultus-Facial-Recognition && cd GraphicInterface && mkdir build && cd build && cmake .. && make
- Run Vultus
./GraphicInterface
Option 2 (Docker)
- Pull the docker image
docker pull robtry/face-recognition
- Enable xhost ! (Mack & Linux)
xhost +
- Clone the repo
git clone https://github.com/empobla/Vultus-Facial-Recognition.git
- Run the container
- Linux:
docker run --privileged --device /dev/video0:/dev/video0 -v $(pwd):/root/workspace -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY -p 5000:5000 -p 8888:8888 -it robtry/face-recognition
- MacOS:
docker run -it -v $(pwd):/root/workspace -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=docker.for.mac.host.internal:0 -p 5000:5000 -p 8888:8888 robtry/face-recognition
- Linux:
- Compile
cd Vultus-Facial-Recognition && cd GraphicInterface && mkdir build && cd build && cmake .. && make
- Run Vultus
./GraphicInterface
To better visualize how the GUI for Vultus works, you can reference this diagram:
In this section, you can find the main methods that the project uses alongside a description of what they do and how to use them.
GUI.cpp
Screens.cpp
Inside this script the menu buttons are displayed and the respective functions are executed once the button is pressed. The buttons and funtionalities of each are the following:
- "Face Verification": Calls the main Verify method (full description below).
- "Face identification": Calls the main Identify method (full description below).
- "Enroll a Student": Calls the main Enroll User method. Allows for a new user to be registered in the database. It requires the name, ID, age and picture of the before-mentioned user.
- "Quit": Exits the program.
This method verifies if the subject in the frame matches the subject in the database for a given ID. It uses the Face Detection, Face Alignment and Features Extraction modules to get the features of the subject in the frame, and then uses the Database module to get the features saved for the given ID and compares both features.
- Frame (
cv::Mat): object of the frame captured. - ID (
std::string): ID. - Response (
integer): integer that will contain the response of the verification. 1 if it's the same person, 0 if not matched and -1 for method error. - Result (
Cuatec): Cuatec object that, if matched, will contain the matching Cuatec found in the DB.
This method unites the Face Detection, Face Alignment, Feature Extraction and Database modules into one. It identifies a face and returns an amount of possible matches for said face.
The Identify method begins by creating an empty Mat object called "features", which will be used as an argument along with the current frame when calling getFeatureDescriptorsFromFrame(). That method encapsulates the first three modules of this system (Face Detection, Face Alignment and Feature Extraction), takes "features" and "near_neighbors" as arguments and once all 3 modules have done their job, a boolean variable is returned. If the result is true, it means all 3 modules worked fine, so "result" will be filled with the possible matches to the face in the current frame via a call to fastSearch(). fastSearch() is a method provided by the Database module which takes as arguments the now filled "features" Mat object and "near_neighbors" (the amount of possible matches desired to be seen).
Provided the first position inside of "result" will have the most likely match of the person being identified, a call is made to verify(), which will take as arguments the same received frame, the cuatecID of the first person in "result", a newly defined and initialized "verfiedResponse" integer and an object of type "Cuatec" named "cuatecRseult". The response value that comes from verify() will determine the value for "response". If its equal to 1, so is "response", and there was a match. If its equal to 0, so is "response", and there was no match. If the boolean returned from getFeatureDescriptorsFromFrame() was returned as false, the person using the system is notified through an "Error" message and "response" is saved as 0.
- Frame (
cv::Mat): a Mat object of the current frame being captured. - Response (
integer): an integer that will contain the response of the identification (1 for a match and 0 for no match). - Result (
Cuatec[]): a vector of type Cuatec that will save all the possible matches of the identification.
This methods allows the user to enroll a new student. In order to enroll a student, the method recieves the student's name (string), age (int), and id (string) as a unique key; while the Mat object comes from the picture taken by the opeaning camara. In order to insert the new user into the database, the picture must (1) detect the face to be inserted, (2) align the picture and (3) detect a 128-dimension vector with its features. We use the getFeaturesDescriptorsFromFrame() to determine its feature vector. The response parameter (int) from the function determines whether the insertion was successful (1) or unsuccesful (0).
- Age (
integer): an integer that is an input from the user. - Id (
string): a string recieved from the user, used as a key in the database. - Name (
string): a string that is an input from the user. - Response (
integer): an integer that indicates whether the student was successfully enrolled or not.
| Method | Windows | Mac | Linux |
|---|---|---|---|
| Verify | untested | tested | tested |
| Identify | untested | tested | tested |
| Enroll | untested | tested | tested |
Copyright © 2020 ITESM CSF. All rights are reserved. Modification or redistribution of this code must have explicit consent from ITESM CSF or the project owners.
- Leonardo Chang: Project Manager
- Team 1 : Face Detection | One to Many comparison.
- Team 2 : Face Alignment | Integration.
- Team 3 : Feature Extraction | GUI.
- Team 4 : Database | One to One comparison.
Project Link: https://github.com/empobla/Vultus-Facial-Recognition