Face Recognition Attendance System
A local attendance system: OpenCV reads the webcam, recognises enrolled faces,
and logs each one to SQLite. Nothing leaves the machine.
Tracked live, judged live. The mesh is MediaPipe's; the instruction, checklist
and priority chain are this project's pipeline/guidance.py — fourteen rules in
a fixed order, of which only the first to fire is shown, so a person gets one
thing to do instead of a list. tools/build_static.py refuses to publish the
JavaScript if it disagrees with the Python.
The recording handed a still photograph to the browser as if it were a
camera, and paints the frame over after the measurements are read — so the
GIF carries the tracking and nobody's face. Open the page and it is your own
camera; no frame leaves the tab.
Neither page recognises anyone. That needs a 328 MB trainer.yml and a
camera the server owns; a tab gets detection, landmarks and guidance. MediaPipe
is not this project's detector either — the app uses YuNet or Haar and OpenCV's
68-point LBF model — so the camera page labels every input as the same
measurement, an approximation, or not measured at all.
Read the full write-up →
— the 97,698-face benchmark, where recognition stops working, and every bug this
has had. (Or docs/index.html locally.)
Run it
pip install -r requirements.txt
python -m cli.fetch_models # ~196 MB of pretrained weights, once
python app.py # http://127.0.0.1:5001
The camera is opened by the server, not the browser, so this runs on the
machine it is plugged into — which is why the demos cover only the arithmetic.
Don't skip the middle line: attendance works without those weights, but
traits, liveness, quality scoring and SFace identification degrade quietly,
which looks like the app being broken rather than incomplete.
GET /api/models names the missing ones.
Then register a person and capture ~30 samples. Attendance is decided by SFace
embeddings against a calibrated threshold, with LBPH only as the fallback when
the SFace weights are missing; recognised faces that pass the liveness check
get one attendance row per person per day, recording which recogniser made it. The same
on the CLI — cli.register_user, cli.attendance, cli.view_report — and
cli.seed_demo --people 40 enrolls from LFW to try recognition without
registering anyone. Every feature, with the endpoint and command behind it, is
listed on the camera page.
Measured, not assumed
All 97,698 images of FairFace. Full results in BENCHMARK.md.
- Detection is even — 99.95%, widest race-group gap 0.08pp.
- The quality gate used to be biased, and was fixed. Absolute brightness and
contrast encode skin tone, and flagged 38.8% of Black faces vs 18.5% of
White faces as "too dark". Gating is now scale-free and learned signals
only; disparity fell from 2.15× to 1.24×.
- The right threshold depends on how many people are enrolled — one swept
over a few identities cannot see false matches. Over 4.77 billion impostor
pairs: 0.425 at 10 people, 0.725 at 1,000, nothing sufficient past ~1,646.
The birthday problem, and why
analysis/calibration.py takes a gallery size
instead of returning a constant.
- The gender estimator fails badly for Black women (43.7%, worse than
chance). Leave it off unless you have a reason not to.
Effectiveness. 40 enrolled, held-out LFW images: 92.9% correct
(223/240), 6.7% rejected as unknown, 0.4% misidentified, 100% impostor
rejection over 300 non-enrolled faces. The failure mode is the safe one.
Operating range. Detection holds at 100% throughout; recognition degrades.
| Condition | Holds until | Breaks at |
|---|
| Distance (downscale) | 0.25× (83%) | 0.15× (23%) |
| Motion blur | 9 px (83%) | 13 px (47%) |
| Lighting (gamma 0.4–2.2) | no measurable loss | — |
| In-plane rotation | 15° (80%) | 30° (37%) |
| JPEG compression | q20 (83%) | q10 (77%) |
A tilted camera costs more than a dim room.
Layout
app.py the Flask entry point, and the only module left in the root
core/ paths, vision constants, the database, the model loaders
pipeline/ the capture path: camera, traits, landmarks, liveness,
guidance, recognition, training
analysis/ enrollment quality, threshold sweeps, calibration, fairness
cli/ the command-line entry points
tools/ developer scripts, corpus benchmarks, the demo build
Thirty-one modules used to sit flat in the root. tests/layout.py writes the
grouping down once, and the structural tests read it from there.
notes/ holds the long-form write-ups — BENCHMARK.md, CODE_AUDIT.md — and
CONTRIBUTING.md is in .github/, which is where GitHub looks for it.
Caveats that matter
- Nothing gates on skin tone: exposure advice fires on clipped pixels, not
average brightness. Head coverings are not mentioned either — the honest
failure is "no face detected", not a guess at what somebody is wearing. Brims
and dark lenses do occlude, so those are named, and only when detection is
actually failing.
- Age is one figure with a ±6-year band, shown with how often that band is
right, which is ~40% — MAE 12.4 years over 10,946 faces. Gender guesses
apparent presentation from pixels and says nothing about identity. Both
softmax over a fixed label set, so they label anything confidently,
including a black frame; the readout suppresses them when no face is found.
- This measures image and recogniser properties. Inferring character from
face geometry is physiognomy: it does not work, and nothing here does it.
- Privacy: treat
dataset/ and trainer.yml as biometric data — don't
commit them, and delete a person's folder and retrain if they ask to be
removed.
Tests
pytest -q
1,053 tests, 100% of 4,498 statements, needing no webcam, no weights and no
corpus. Tests that need a real face use a sample frame if one is present and
skip rather than asserting against a synthetic one, because a face a
detector accepts cannot be faked convincingly enough to be evidence.
License
MIT — see CONTRIBUTING.md for setup and conventions.
