Airport Face Recognition

FaceRecognition.mp4

This project is a local face recognition prototype based on webcam input.

The application allows you to:

• register a person from the webcam
• save the registered face locally
• start live face recognition
• compare the detected face with the registered ones

Requirements

To run the project you need:

• Python 3
• pip
• a working webcam
• webcam permissions enabled for the terminal or editor you are using

Before running ./setup.sh, make sure that Python 3 is already installed on your system and that pip is available through python3.

You can verify this with:

python3 --version
python3 -m pip --version

If both commands return a valid version, you can continue with the setup script.

If python3 is not installed, you must install it before running the project.

Install Python 3 on macOS

If you use Homebrew, install Python with:

brew install python

Then verify the installation:

python3 --version
python3 -m pip --version

Install Python 3 on Linux

On Debian/Ubuntu-based systems:

sudo apt update
sudo apt install python3 python3-pip

Then verify the installation:

python3 --version
python3 -m pip --version

On Fedora:

sudo dnf install python3 python3-pip

Then verify the installation:

python3 --version
python3 -m pip --version

On Arch Linux:

sudo pacman -S python python-pip

Then verify the installation:

python3 --version
python3 -m pip --version

Python Libraries Required

Before running the project, these Python libraries must be installed:

• opencv-python==4.10.0.84 Used for webcam access, live video windows, face detection, keyboard handling inside the OpenCV window, and image saving.
• numpy==1.24.4 Used for numerical operations and for computing and comparing face descriptors.
• matplotlib==3.7.5 Present in the project requirements because it was used by the original simulation part of the repository.
• scipy==1.10.1 Present in the project requirements because it was used by the original simulation/statistical part of the repository.

When installing these packages, pip may also install additional dependencies required by them.

Installation Commands

If you want to install everything manually, use:

python3 -m pip install -r requirements.txt

The requirements.txt file currently contains:

matplotlib==3.7.5
numpy==1.24.4
opencv-python==4.10.0.84
scipy==1.10.1

If you want to install the libraries one by one, the commands are:

python3 -m pip install matplotlib
python3 -m pip install scipy
python3 -m pip install opencv-python==4.10.0.84

numpy is also installed because it is required by these libraries and by the project itself.

Setup Script

To simplify setup, the repository includes a script:

./setup.sh

This script:

• moves into the project folder
• creates the folders needed by the project
• installs all Python dependencies from requirements.txt

The expected execution flow is:

python3 --version
python3 -m pip --version
./setup.sh

The folders created are:

• .mplconfig
• .cache
• plots
• data/faces
• OUTPUT

Run Script

To start the application quickly, use:

./run.sh

This script:

• moves into the project folder
• creates the required local folders if they are missing
• starts the application with:

python3 main.py

If you do not want to use the script, you can also run the program manually:

python3 main.py

How To Use The Program

After starting the application, the main menu shows:

• 1. Start real face recognition
• 0. Exit

Register a Face

1. Run the program
2. Enter 1
3. In the next menu choose 1 to register a new face
4. Type the person's name in the terminal
5. The webcam window opens
6. Click on the webcam window to make sure it has focus
7. When the face is correctly framed, press SPACE or ENTER
8. The face sample is saved locally

Start Live Recognition

1. Run the program
2. Enter 1
3. In the next menu choose 2
4. The webcam opens and the program tries to recognize registered faces live

List Registered Faces

1. Run the program
2. Enter 1
3. In the next menu choose 3
4. The program prints the list of people already registered

Controls Inside The Webcam Window

The keyboard controls must be used directly inside the webcam window, not in the terminal.

During Face Registration

• SPACE captures the current face
• ENTER captures the current face
• q exits
• Q exits
• ESC exits

During Live Recognition

• q exits
• Q exits
• ESC exits

If the window does not respond to the keyboard:

1. click on the webcam window
2. try again
3. if needed, stop the program from the terminal with Ctrl+C

Saved Data

Registered faces are stored locally in:

• data/face_db.json
• data/faces/

Useful Verification Commands

To check which Python libraries are installed:

python3 -m pip list

To show only the main libraries used for this project:

python3 -m pip list | grep -E 'matplotlib|scipy|opencv-python|numpy'

To inspect package details and installation path:

python3 -m pip show matplotlib scipy opencv-python numpy

Notes

• This is a local prototype, not a production-grade biometric security system.
• The recognition pipeline currently uses OpenCV face detection plus handcrafted face descriptors.
• Good lighting and a stable frontal face position improve recognition quality.

Curiosities About The Shell Scripts

This section explains exactly what is inside setup.sh and run.sh, and what each instruction means.

Content of setup.sh

#!/usr/bin/env bash

set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

cd "$ROOT_DIR"

mkdir -p .mplconfig .cache plots data/faces OUTPUT

python3 -m pip install -r requirements.txt

echo
echo "Setup completed."
echo "Run the app with:"
echo "python3 main.py"

What each instruction means in setup.sh

• #!/usr/bin/env bash Tells the operating system to execute the script using bash.
• set -euo pipefail Enables a safer shell mode.
• -e Stops the script immediately if a command fails.
• -u Stops the script if an undefined variable is used.
• pipefail Makes pipelines fail if any command inside them fails.
• ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" Computes the absolute path of the directory where the script is located.
• ${BASH_SOURCE[0]} Refers to the current script file.
• dirname "${BASH_SOURCE[0]}" Extracts the directory that contains the script.
• cd ... && pwd Moves into that directory and prints its absolute path.
• ROOT_DIR=... Stores that absolute path in the variable ROOT_DIR.
• Example: If setup.sh is located at /Users/simoneremoli/PYTHON_VIRTUAL_WORLD/airport-face-recognition/setup.sh, then: ${BASH_SOURCE[0]} becomes /Users/simoneremoli/PYTHON_VIRTUAL_WORLD/airport-face-recognition/setup.sh, dirname "${BASH_SOURCE[0]}" becomes /Users/simoneremoli/PYTHON_VIRTUAL_WORLD/airport-face-recognition, and ROOT_DIR is finally set to /Users/simoneremoli/PYTHON_VIRTUAL_WORLD/airport-face-recognition.
• cd "$ROOT_DIR" Moves into the root folder of the project.
• mkdir -p .mplconfig .cache plots data/faces OUTPUT Creates the directories used by the project if they do not already exist.
• mkdir Creates directories.
• -p Prevents errors if a directory already exists and creates parent directories when needed.
• .mplconfig Used by matplotlib for configuration and cache files.
• .cache Generic local cache directory.
• plots Directory originally used for generated plot files.
• data/faces Directory used to store saved face samples.
• OUTPUT Directory originally used by the legacy simulation output.
• python3 -m pip install -r requirements.txt Installs all required Python packages listed in requirements.txt.
• python3 -m pip Runs pip through the current Python 3 interpreter.
• install Tells pip to install packages.
• -r requirements.txt Reads the list of packages from the requirements.txt file.
• echo Prints a blank line.
• echo "Setup completed." Prints a confirmation message.
• echo "Run the app with:" Prints an instruction line.
• echo "python3 main.py" Prints the manual command used to start the application.

Content of run.sh

#!/usr/bin/env bash

set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

cd "$ROOT_DIR"

mkdir -p .mplconfig .cache plots data/faces OUTPUT

python3 main.py

What each instruction means in run.sh

• #!/usr/bin/env bash Tells the operating system to execute the script using bash.
• set -euo pipefail Enables a safer shell mode.
• -e Stops the script if a command fails.
• -u Stops the script if an undefined variable is used.
• pipefail Makes pipelines fail if any command inside them fails.
• ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" Computes the absolute path of the directory where run.sh is located.
• ${BASH_SOURCE[0]} Refers to the current script.
• dirname "${BASH_SOURCE[0]}" Extracts the folder containing the script.
• cd ... && pwd Moves there and prints the absolute path.
• ROOT_DIR=... Saves that path into the variable ROOT_DIR.
• Example: If run.sh is located at /Users/simoneremoli/PYTHON_VIRTUAL_WORLD/airport-face-recognition/run.sh, then: ${BASH_SOURCE[0]} becomes /Users/simoneremoli/PYTHON_VIRTUAL_WORLD/airport-face-recognition/run.sh, dirname "${BASH_SOURCE[0]}" becomes /Users/simoneremoli/PYTHON_VIRTUAL_WORLD/airport-face-recognition, and ROOT_DIR is finally set to /Users/simoneremoli/PYTHON_VIRTUAL_WORLD/airport-face-recognition.
• cd "$ROOT_DIR" Moves into the project root.
• mkdir -p .mplconfig .cache plots data/faces OUTPUT Creates the local folders required by the project if they are missing.
• python3 main.py Starts the application.
• python3 Launches the Python 3 interpreter.
• main.py Runs the main entry point of the project.