facecheck 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Saeed Rohani
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ recursive-include tests *.py
@@ -0,0 +1,407 @@
1
+ Metadata-Version: 2.4
2
+ Name: facecheck
3
+ Version: 1.0.0
4
+ Summary: Register face with a camera, then check who is in front of it and verify their identity. Also measures faces and estimates face shape. Needs only OpenCV and NumPy.
5
+ Author: Saeed Rohani
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/saeed-rohani/facecheck
8
+ Project-URL: Issues, https://github.com/saeed-rohani/facecheck/issues
9
+ Keywords: face,face-recognition,face-verification,webcam,opencv,landmarks,face-shape
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3 :: Only
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Programming Language :: Python :: 3.15
22
+ Classifier: Topic :: Multimedia :: Video :: Capture
23
+ Classifier: Topic :: Scientific/Engineering :: Image Recognition
24
+ Requires-Python: >=3.10
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Requires-Dist: opencv-contrib-python>=4.8
28
+ Requires-Dist: numpy>=1.23
29
+ Provides-Extra: test
30
+ Requires-Dist: pytest>=7; extra == "test"
31
+ Dynamic: license-file
32
+
33
+ # facecheck
34
+
35
+ Register face with a camera, then check who is in front of it and verify their identity.
36
+ `facecheck` saves each person's face data and measurements in a local
37
+ database and matches new faces against it. It needs only OpenCV and NumPy,
38
+ and pip installs both for you.
39
+
40
+ ```console
41
+ $ pip install facecheck
42
+ $ facecheck register "Saeed Rohani"
43
+ $ facecheck check
44
+ ```
45
+
46
+ Everything runs on your own computer. No image is ever saved or uploaded:
47
+ only face data (numbers) is stored, in a database on this machine.
48
+
49
+ ## What it does
50
+
51
+ - **`facecheck register NAME`** opens the camera, waits until the person
52
+ looks straight at it, takes 5 face samples, measures the face, and saves it
53
+ all under that name.
54
+ - **`facecheck check`** opens the camera and says who it is: the best match
55
+ among everyone registered, or "no match".
56
+ - **`facecheck check --name NAME`** answers a narrower question: is this
57
+ NAME?
58
+
59
+ Under the hood, all three models come from OpenCV:
60
+
61
+ | Step | Model | Size |
62
+ | ----------------- | ----------------------------------------- | ------------ |
63
+ | Find the face | YuNet | about 0.2 MB |
64
+ | Tell people apart | SFace, a 128-number "face print" per face | about 37 MB |
65
+ | Measure the face | Facemark LBF, 68 landmarks | about 54 MB |
66
+
67
+ The models download automatically the first time a command needs them and
68
+ are cached; after that no network is needed.
69
+
70
+ ## Install
71
+
72
+ ```console
73
+ $ pip install facecheck
74
+ ```
75
+
76
+ That is all: pip also installs the two dependencies, `opencv-contrib-python`
77
+ and `numpy`. To be safe on older computers, you can add `--only-binary`, which
78
+ makes pip use ready-made builds instead of trying to compile OpenCV:
79
+
80
+ ```console
81
+ $ pip install --only-binary=opencv-contrib-python,numpy facecheck
82
+ ```
83
+
84
+ Requirements:
85
+
86
+ - Python 3.10 or newer
87
+ - A webcam
88
+ - Windows (64- or 32-bit); macOS 11+ on Apple silicon or 12+ on Intel; or
89
+ Linux with glibc 2.17+ on x86-64 or ARM64
90
+
91
+ ## Usage
92
+
93
+ ### Register a person
94
+
95
+ ```console
96
+ $ facecheck register "Saeed Rohani"
97
+ ```
98
+
99
+ A preview window shows a box around the face: amber while it waits ("Move
100
+ closer", "Look straight at the camera"), green while it takes samples. It
101
+ takes about a second once the face is steady. Names are not case-sensitive,
102
+ so "saeed rohani" is the same person.
103
+
104
+ The command prints the saved record as JSON:
105
+
106
+ ```json
107
+ {
108
+ "registered": true,
109
+ "name": "Saeed Rohani",
110
+ "registered_at": "2026-11-18T15:49:29Z",
111
+ "samples": 5,
112
+ "replaced": false,
113
+ "similar_to": null,
114
+ "measurement": { "face_shape": { "label": "oval", "...": "..." }, "...": "..." }
115
+ }
116
+ ```
117
+
118
+ `measurement` holds the full face measurement described under Measurements
119
+ below. If the face already looks like someone who is
120
+ registered, `similar_to` names them and a warning is printed, which catches
121
+ the same person being registered twice under two names.
122
+
123
+ To register someone again under the same name, add `--replace`.
124
+
125
+ ### Check who is in front of the camera
126
+
127
+ ```console
128
+ $ facecheck check
129
+ ```
130
+
131
+ ```json
132
+ {
133
+ "id": "7f864a9e6fa74e5fa2bf9eb4204e183f",
134
+ "checked_at": "2026-11-18T15:49:29Z",
135
+ "mode": "identify",
136
+ "claimed_name": null,
137
+ "matched": true,
138
+ "name": "Saeed Rohani",
139
+ "similarity": 0.9361,
140
+ "threshold": 0.363,
141
+ "candidates": [{ "name": "Saeed Rohani", "similarity": 0.9361 }],
142
+ "frames_used": 3,
143
+ "source": "camera:0"
144
+ }
145
+ ```
146
+
147
+ The window shows the verdict in green ("Match: Saeed Rohani") or red ("No
148
+ match"). Every check is also logged in the database.
149
+
150
+ ### Check one named person
151
+
152
+ ```console
153
+ $ facecheck check --name "Saeed Rohani"
154
+ ```
155
+
156
+ Same output, with `"mode": "verify"` and `claimed_name` filled in.
157
+
158
+ ### Use it from a script
159
+
160
+ Only the JSON result goes to standard output; messages go to standard error.
161
+ The exit code tells you the outcome:
162
+
163
+ | Exit code | Meaning |
164
+ | --------- | ------------------------------------------- |
165
+ | `0` | Success; for `check`, a match |
166
+ | `1` | Error, cancelled, or no usable face in time |
167
+ | `2` | Wrong command-line options |
168
+ | `3` | `check` ran, but there was no match |
169
+
170
+ ```console
171
+ $ facecheck check --name "Saeed Rohani" --no-window > result.json && echo "Welcome"
172
+ ```
173
+
174
+ ### Other commands
175
+
176
+ | Command | What it does |
177
+ | ----------------------- | --------------------------------------------------------------------------- |
178
+ | `facecheck list` | List registered people |
179
+ | `facecheck delete NAME` | Remove a person and all their face data |
180
+ | `facecheck export` | Write `users.csv`, `checks.csv` and `measurements.csv` here (or `--to DIR`) |
181
+ | `facecheck measure` | Measure a face without registering anyone (see below) |
182
+
183
+ ### Options
184
+
185
+ Options go after the command, for example `facecheck check --camera 1`.
186
+
187
+ | Option | Commands | Meaning |
188
+ | ------------------------ | ------------------------ | ---------------------------------------------------------- |
189
+ | `--camera N` | register, check, measure | Camera index, default `0`. Try `1` for an external camera. |
190
+ | `--no-window` | register, check, measure | No preview window. |
191
+ | `--no-mirror` | register, check, measure | Do not mirror the preview. |
192
+ | `--timeout SEC` | register, check, measure | Give up after this long, default `60`. |
193
+ | `--replace` | register | Replace a person already registered under this name. |
194
+ | `--samples N` | register | Face samples to store, default `5`. |
195
+ | `--name NAME` | check | Check against this person only. |
196
+ | `--threshold T` | check | Similarity needed for a match, default `0.363`. |
197
+ | `--ipd MM`, `--hfov DEG` | register, measure | Scale settings for measurements (see below). |
198
+ | `--data DIR` | all | Folder for the database. |
199
+ | `--model-dir DIR` | all | Folder with your own copies of the model files. |
200
+
201
+ ### Run from the source folder, without installing
202
+
203
+ ```console
204
+ $ pip install --only-binary=:all: opencv-contrib-python numpy
205
+ $ python run.py register "Saeed Rohani"
206
+ $ python run.py check
207
+ ```
208
+
209
+ ## Where the data is kept
210
+
211
+ The database is `facecheck.db` in:
212
+
213
+ | System | Folder |
214
+ | ------- | ----------------------------------------- |
215
+ | macOS | `~/Library/Application Support/facecheck` |
216
+ | Windows | `%APPDATA%\facecheck` |
217
+ | Linux | `~/.local/share/facecheck` |
218
+
219
+ Use `--data DIR`, or set the `FACECHECK_HOME` environment variable, to keep
220
+ it somewhere else; for example, one folder per site or project.
221
+
222
+ Tables in the database:
223
+
224
+ | Table | Contents |
225
+ | -------------- | ---------------------------------------------------------------------- |
226
+ | `users` | name, registration time, number of samples, link to the measurement |
227
+ | `face_samples` | each person's face prints (128 numbers each) |
228
+ | `measurements` | face measurements: one per registered person, plus `measure` results |
229
+ | `checks` | every check: when, which mode, who was claimed, who matched, the score |
230
+
231
+ `facecheck export` never writes face prints to CSV; they stay in the
232
+ database.
233
+
234
+ ## How matching works
235
+
236
+ SFace turns a face into 128 numbers. Two photos of the same person give
237
+ nearly the same numbers, and the **similarity** (cosine similarity, from −1
238
+ to 1) measures how close they are. A person matches when the similarity
239
+ reaches the threshold, 0.363 by default. That is OpenCV's published
240
+ threshold for this model; on the LFW benchmark of face photos the model is
241
+ 99.6% accurate with it.
242
+
243
+ Registration stores 5 samples taken a moment apart, and a person's score is
244
+ their best-matching sample. A check averages 3 consecutive frames of one
245
+ steady face.
246
+
247
+ - To turn away look-alikes more strictly, raise the threshold, for example
248
+ `--threshold 0.5`. The right person will then be turned away more often,
249
+ especially in poor light.
250
+ - If the right person is often not recognised, register them again in the
251
+ light where the camera is used (`--replace`), or lower the threshold a
252
+ little.
253
+
254
+ ## Measurements
255
+
256
+ Each registration also saves the measurements and face-shape estimate of the
257
+ original `facemeasure` app. `facecheck measure` runs that app on its own:
258
+ `SPACE` saves, `E` exports CSV, `Q` quits; `--once` saves one result
259
+ automatically, and `--image photo.jpg` measures a photo.
260
+
261
+ It finds 12 lengths, 4 ratios, a jaw angle and the head pose, and estimates
262
+ the face shape: oval, round, square, oblong, heart, diamond or triangle.
263
+ Lengths use the standard 68-point landmark layout:
264
+
265
+ | Name | From → to |
266
+ | ------------------------------------------------------- | ----------------------------------------------------- |
267
+ | `face_length` | Estimated hairline → chin, using the "rule of thirds" |
268
+ | `face_width` | Across the face at cheekbone level |
269
+ | `forehead_width` | Outer ends of the eyebrows |
270
+ | `jaw_width` | Across the jaw corners |
271
+ | `eye_distance_inner`, `eye_distance_outer` | Inner and outer eye corners |
272
+ | `pupil_distance` | Centres of the two eyes |
273
+ | `eye_width`, `nose_length`, `nose_width`, `mouth_width` | As named |
274
+ | `lower_face_height` | Base of the nose → chin |
275
+
276
+ Millimetres assume an average adult pupil distance of 63 mm. Pass the
277
+ person's real pupil distance (it is on most glasses prescriptions) with
278
+ `--ipd 61.5` for real-scale numbers. The face shape is a hand-tuned
279
+ heuristic, not a validated classifier.
280
+
281
+ ## Limitations
282
+
283
+ Please read these before relying on `facecheck`.
284
+
285
+ - **It can be fooled by a photo.** There is no liveness or anti-spoofing
286
+ check, so a printed photo or a phone screen showing a registered face may
287
+ match. Do not use `facecheck` alone to protect anything valuable, such as
288
+ doors, accounts or payments.
289
+ - **Matching is not perfect.** Look-alikes and twins can match each other,
290
+ and poor light, strong angles, masks or heavy changes in appearance can
291
+ stop the right person matching. The threshold trades one error for the
292
+ other.
293
+ - **It has been tested with synthetic data only.** The automated tests use a
294
+ synthetic face and fake camera and models, and the real models have not
295
+ yet been tried together on a large set of real faces. Try it in your own
296
+ setting before you depend on it.
297
+ - **Measurements are estimates.** See above.
298
+
299
+ ## Privacy and consent
300
+
301
+ Face prints are biometric data, which many laws treat as sensitive
302
+ personal data (for example the GDPR in the EU and BIPA in Illinois). If you
303
+ register anyone other than yourself:
304
+
305
+ - Tell them what is stored and why, and get their consent first.
306
+ - Keep the database private, and delete people (`facecheck delete NAME`)
307
+ when their data is no longer needed.
308
+ - Never commit `facecheck.db` or exported CSV files to a public repository.
309
+
310
+ Frames are processed in memory and discarded; no image is written to disk.
311
+ The only network requests are the one-time model downloads.
312
+
313
+ ## Use from Python
314
+
315
+ ```python
316
+ import cv2
317
+ from facecheck import FaceDetector, Store, decide, face_problem, mean_embedding
318
+
319
+ with FaceDetector(landmarks=False, recognition=True) as detector, Store("people.db") as store:
320
+ frame = cv2.imread("visitor.jpg")
321
+ face = detector.find_face(frame)
322
+ if face_problem(face) is None:
323
+ result = decide(mean_embedding([detector.embedding(frame, face)]), store.gallery())
324
+ print(result["matched"], result["name"], result["similarity"])
325
+ ```
326
+
327
+ `store.add_user(name, embeddings, measurement=None)` registers someone the
328
+ same way.
329
+
330
+ ## Troubleshooting
331
+
332
+ **pip is stuck at `Building wheel for opencv-contrib-python`.** pip found no
333
+ ready-made OpenCV for your system and is compiling it. Stop it with `Ctrl+C`
334
+ and install with `--only-binary`, as shown under Install. If pip then finds
335
+ no OpenCV at all, check your system against the requirements:
336
+
337
+ ```console
338
+ $ python -c "import sys, platform; print(sys.version); print(platform.platform())"
339
+ ```
340
+
341
+ **The download fails with `CERTIFICATE_VERIFY_FAILED`.** Your Python has no
342
+ list of trusted HTTPS certificates; this is common with the python.org
343
+ installer on macOS. `facecheck` then retries with the system's `curl`. To fix
344
+ Python itself, open the Python folder in Applications and run
345
+ `Install Certificates.command`.
346
+
347
+ **A model download fails for another reason.** Download the file yourself
348
+ into the cache folder that the error message names (on macOS
349
+ `~/Library/Caches/facecheck`) and run again:
350
+
351
+ ```console
352
+ $ mkdir -p ~/Library/Caches/facecheck && cd ~/Library/Caches/facecheck
353
+ $ curl -L -O https://github.com/opencv/opencv_zoo/raw/main/models/face_detection_yunet/face_detection_yunet_2023mar.onnx
354
+ $ curl -L -O https://github.com/opencv/opencv_zoo/raw/main/models/face_recognition_sface/face_recognition_sface_2021dec.onnx
355
+ $ curl -L -O https://raw.githubusercontent.com/kurnianggoro/GSOC2017/master/data/lbfmodel.yaml
356
+ ```
357
+
358
+ **"OpenCV's face module is missing".** Another OpenCV build is hiding the
359
+ contrib one. Remove them all and reinstall only the contrib build:
360
+
361
+ ```console
362
+ $ pip uninstall -y opencv-python opencv-python-headless opencv-contrib-python
363
+ $ pip install --only-binary=:all: opencv-contrib-python
364
+ ```
365
+
366
+ **The camera does not open.** Close other apps that use it and try
367
+ `--camera 1`. On macOS, allow your terminal under System Settings → Privacy &
368
+ Security → Camera, then restart the terminal.
369
+
370
+ **The box stays amber.** Follow the message: move closer, look straight at
371
+ the camera, and add light from the front.
372
+
373
+ ## Development
374
+
375
+ ```console
376
+ $ git clone https://github.com/YOUR-GITHUB-USERNAME/facecheck.git
377
+ $ cd facecheck
378
+ $ python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
379
+ $ pip install --only-binary=opencv-contrib-python,numpy -e ".[test]"
380
+ $ pytest
381
+ ```
382
+
383
+ The tests need neither a camera nor the model files. Release steps are in
384
+ `PUBLISHING.md`.
385
+
386
+ ## Credits
387
+
388
+ - [OpenCV](https://opencv.org/), and the YuNet and SFace models from the
389
+ [OpenCV Zoo](https://github.com/opencv/opencv_zoo)
390
+ - Facemark LBF and its trained model by Laksono Kurnianggoro
391
+ ([GSoC 2017](https://github.com/kurnianggoro/GSOC2017))
392
+ - The generic 3D face used for measurements comes from MediaPipe's canonical
393
+ face model, by Google (Apache License 2.0)
394
+ - [NumPy](https://numpy.org/)
395
+
396
+ The model files are not part of this package; they are downloaded from their
397
+ authors' repositories. Check each model's terms before commercial use: the
398
+ OpenCV Zoo keeps a licence file next to each model, and the LBF model's
399
+ repository states no licence.
400
+
401
+ ## Author
402
+
403
+ Created and maintained by **Saeed Rohani**.
404
+
405
+ ## License
406
+
407
+ MIT © 2026 Saeed Rohani. See the `LICENSE` file.