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.
- facecheck-1.0.0/LICENSE +21 -0
- facecheck-1.0.0/MANIFEST.in +1 -0
- facecheck-1.0.0/PKG-INFO +407 -0
- facecheck-1.0.0/README.md +375 -0
- facecheck-1.0.0/pyproject.toml +54 -0
- facecheck-1.0.0/setup.cfg +4 -0
- facecheck-1.0.0/src/facecheck/__init__.py +31 -0
- facecheck-1.0.0/src/facecheck/__main__.py +3 -0
- facecheck-1.0.0/src/facecheck/analysis.py +334 -0
- facecheck-1.0.0/src/facecheck/camera.py +153 -0
- facecheck-1.0.0/src/facecheck/cli.py +378 -0
- facecheck-1.0.0/src/facecheck/detector.py +291 -0
- facecheck-1.0.0/src/facecheck/identity.py +79 -0
- facecheck-1.0.0/src/facecheck/measure.py +196 -0
- facecheck-1.0.0/src/facecheck/storage.py +282 -0
- facecheck-1.0.0/src/facecheck.egg-info/PKG-INFO +407 -0
- facecheck-1.0.0/src/facecheck.egg-info/SOURCES.txt +25 -0
- facecheck-1.0.0/src/facecheck.egg-info/dependency_links.txt +1 -0
- facecheck-1.0.0/src/facecheck.egg-info/entry_points.txt +2 -0
- facecheck-1.0.0/src/facecheck.egg-info/requires.txt +5 -0
- facecheck-1.0.0/src/facecheck.egg-info/top_level.txt +1 -0
- facecheck-1.0.0/tests/conftest.py +59 -0
- facecheck-1.0.0/tests/test_analysis.py +151 -0
- facecheck-1.0.0/tests/test_cli.py +285 -0
- facecheck-1.0.0/tests/test_detector.py +324 -0
- facecheck-1.0.0/tests/test_identity.py +82 -0
- facecheck-1.0.0/tests/test_storage.py +169 -0
facecheck-1.0.0/LICENSE
ADDED
|
@@ -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
|
facecheck-1.0.0/PKG-INFO
ADDED
|
@@ -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.
|