Partial Face Recognition

An experimental Python toolkit for recognizing partially visible faces. It uses face_recognition for face detection, optional dlib landmark alignment, and OpenCV ORB descriptors for local-feature matching.

Important

This is a research/learning project, not a biometric security system. Accuracy depends strongly on the dataset, pose, occlusion, lighting, and the matching threshold. Validate it on representative data before drawing conclusions.

What was fixed in v0.2

• repaired package imports and image color/type handling;
• clipped face crops safely and made crop export optional;
• removed hard-coded data and landmark-model paths;
• fixed matching state corruption and incorrect unknown-result bookkeeping;
• replaced GUI and plotting side effects with return values;
• added a working build, identify, and evaluate command-line interface;
• modernized packaging and continuous integration; and
• restored automated tests that do not require the restricted AR Face Database.

Installation

Python 3.9 or newer is required.

git clone https://github.com/itsmeeChandU/partial_face_recognition.git
cd partial_face_recognition
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[cnn]"

The cnn extra installs face_recognition, dlib, and the optional alignment helper. Building dlib may require CMake and a C++ compiler on your platform.

Dataset layout

Place training images in one directory. AR-style filenames are grouped by their first two hyphen-separated fields:

train/
├── m-001-01.jpg  # identity m-001
├── m-001-02.jpg  # identity m-001
└── w-002-01.jpg  # identity w-002

Other filenames use their complete stem as the identity. The repository does not include the AR Face Database because its redistribution terms prohibit it. Obtain and use datasets only under their applicable consent and license terms.

Usage

Build a database from labelled training images:

partial-face-recognition build data/train --output train-features.pickle

Use the faster HOG detector when a CUDA-capable dlib installation is not available:

partial-face-recognition build data/train --detector hog

Identify one image:

partial-face-recognition identify photo.jpg --database train-features.pickle

Evaluate a labelled test directory and write text reports:

partial-face-recognition evaluate data/test --database train-features.pickle

Run partial-face-recognition COMMAND --help for threshold and detector options. Feature database files use Python pickle; load only files you trust.

Optional alignment

Pass a local dlib 68-point landmark model when building a database:

partial-face-recognition build data/train \
  --landmark-model shape_predictor_68_face_landmarks.dat

The model is intentionally not bundled. Use the same preprocessing choices for training and queries when comparing results.

Development

python -m pip install -e ".[dev]"
ruff check .
ruff format --check .
pytest
python -m build

See CONTRIBUTING.md for the contribution workflow.

Method and limitations

Each detected face is represented by ORB descriptors. Query descriptors are compared with every enrolled identity using Hamming-distance nearest-neighbor matching and Lowe's ratio test. The identity with the highest number of good matches is accepted only when it reaches --min-matches.

ORB is fast and useful for local occlusion experiments, but it is not a modern face embedding. Thresholds are dataset-specific, and the current score is not a calibrated probability. For production biometrics, use an audited model, calibrated evaluation, liveness protection, privacy review, and human fallback.

Reference

Martinez, A. M., and Benavente, R. (1998). The AR Face Database. CVC Technical Report 24.

Citing this project

GitHub can generate a citation from CITATION.cff. The citation currently describes version 0.2.0 of the software; a DOI can be added after an archival release is published.

License

Code is available under the MIT License. Dataset and model files have their own terms and are not covered by this repository's license.