dsqoder-faceid

A local offline face enrollment, training, and recognition demo for Windows.

The project uses:

• OpenCV Haar cascade for face detection
• OpenCV LBPH recognizer for local face recognition
• A simple CLI and Tkinter GUI
• Local-only data storage

Project path used during development: D:\dsqoder-faceid

Privacy notice

Face images and recognition models may contain sensitive biometric information. Only enroll people who have explicitly agreed to be enrolled.

This repository intentionally ignores local private data:

• data/faces/** face samples
• data/people.json local person records
• models/*.yml trained models
• models/labels.json model labels

Only empty placeholders and data/people.example.json are committed.

Quick start

cd "D:\dsqoder-faceid"
.\.venv\Scripts\Activate.ps1
faceid diagnose

If the virtual environment does not exist yet, run:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
pip install -e .

You can also use the included Windows scripts:

• install_env.bat - install or repair the environment
• run_gui.bat - start the GUI
• open_shell.bat - open an activated command prompt

Chinese wrapper scripts are also provided for convenience.

CLI workflow

1. Diagnose the environment

faceid diagnose

2. Probe cameras

faceid cameras --max 5

Usually camera 0 is the built-in or default camera.

3. Test face detection

faceid detect --camera 0

Press q or Esc to close the OpenCV window.

4. Enroll a person from the camera

faceid enroll --name AG --samples 40 --camera 0

Tips:

• Use good lighting.
• Look at the camera.
• Slowly turn your head left/right and up/down.
• Capture 40 to 80 samples per person.

Samples are saved to:

data/faces/AG/

5. Train the model

faceid train

This creates:

models/lbph_model.yml
models/labels.json

6. Recognize faces

faceid recognize --camera 0 --threshold 70

Recognition window states:

• Green SUCCESS: name - accepted match
• Red FAIL: UNKNOWN - rejected or unknown face
• Gray NO FACE - no face detected

The console also prints status lines such as:

[SUCCESS] AG confidence=42.3 threshold=70.0
[FAIL] unknown closest=AG confidence=86.1 threshold=70.0
[NO FACE]

The confidence value is a distance: lower is more similar.

• confidence <= threshold means success
• confidence > threshold means fail/unknown

Optional sound alert:

faceid recognize --camera 0 --threshold 70 --alert

Import existing photos

Instead of using the camera, you can import existing photos and let the tool crop face samples automatically.

Put clear face photos in a folder, for example:

D:\AG_photos

Then run:

faceid import-images --name AG --source "D:\AG_photos" --samples 40
faceid train
faceid recognize --camera 0

The importer scans the source folder, detects the largest face in each photo, crops it to a training sample, and saves it under data/faces/AG/.

GUI workflow

Start the GUI:

faceid gui

Or double-click:

run_gui.bat

Recommended order:

1. Diagnose
2. Probe Camera
3. Detect
4. Enroll Camera or Import Photos
5. Train
6. Recognize

Only run one camera command at a time. Close OpenCV windows with q or Esc before starting another camera command.

Useful commands

faceid status
faceid people
faceid remove --name AG --yes
faceid cameras --max 5
faceid detect --camera 0
faceid enroll --name AG --samples 40 --camera 0
faceid import-images --name AG --source "D:\AG_photos" --samples 40
faceid train
faceid recognize --camera 0 --threshold 70 --alert

Project structure

D:\dsqoder-faceid
|-- data/
|   |-- faces/              # local face samples, ignored by git
|   `-- people.example.json # public example only
|-- models/                 # local trained model files, ignored by git
|-- src/faceid/             # application source code
|-- main.py
|-- pyproject.toml
|-- requirements.txt
|-- install_env.bat
|-- run_gui.bat
`-- open_shell.bat

License

MIT