facecheck 1.0.0__py3-none-any.whl

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/cli.py ADDED
@@ -0,0 +1,378 @@
1
+ """The facecheck command line.
2
+
3
+ facecheck register NAME register a new person with the camera
4
+ facecheck check who is in front of the camera?
5
+ facecheck check --name NAME is this NAME?
6
+ facecheck list | delete NAME | export | measure
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import argparse
12
+ import os
13
+ import sys
14
+ import unicodedata
15
+ import uuid
16
+ from collections import deque
17
+ from pathlib import Path
18
+
19
+ import cv2
20
+ import numpy as np
21
+
22
+ from . import __version__, measure
23
+ from . import detector as detection
24
+ from .analysis import AVERAGE_IPD_MM, DEFAULT_HFOV_DEG, analyze, to_json
25
+ from .camera import AMBER, GREEN, RED, WHITE, Camera
26
+ from .identity import DEFAULT_THRESHOLD, decide, mean_embedding, rank
27
+ from .storage import Store, utc_now
28
+
29
+ DATA_ENV = "FACECHECK_HOME"
30
+ DB_NAME = "facecheck.db"
31
+ SAMPLE_EVERY = 3 # while registering, keep every 3rd good frame so samples differ a little
32
+ CHECK_SAMPLES = 3 # a check averages this many consecutive good frames
33
+ LANDMARK_FRAMES = 8 # landmark sets averaged for the registration measurement
34
+ EXIT_OK, EXIT_ERROR, EXIT_USAGE, EXIT_NO_MATCH = 0, 1, 2, 3
35
+
36
+
37
+ def default_data_dir():
38
+ """Where the database lives unless --data or FACECHECK_HOME says otherwise."""
39
+ if sys.platform == "win32":
40
+ return Path(os.environ.get("APPDATA") or Path.home() / "AppData" / "Roaming") / "facecheck"
41
+ if sys.platform == "darwin":
42
+ return Path.home() / "Library" / "Application Support" / "facecheck"
43
+ return Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local" / "share") / "facecheck"
44
+
45
+
46
+ def main(argv=None):
47
+ parser = build_parser()
48
+ args = parser.parse_args(argv)
49
+ if not args.command:
50
+ parser.print_help()
51
+ return EXIT_USAGE
52
+ validate(parser, args)
53
+ args.data = Path(args.data or os.environ.get(DATA_ENV) or default_data_dir()).expanduser()
54
+ args.db = args.data / DB_NAME
55
+ handlers = {
56
+ "register": run_register,
57
+ "check": run_check,
58
+ "list": run_list,
59
+ "delete": run_delete,
60
+ "export": run_export,
61
+ "measure": run_measure,
62
+ }
63
+ try:
64
+ return handlers[args.command](args)
65
+ except KeyboardInterrupt:
66
+ log("Cancelled.")
67
+ except (RuntimeError, FileNotFoundError, ValueError) as error:
68
+ log(f"Error: {error}")
69
+ except cv2.error as error:
70
+ log(f"Error from OpenCV: {error}")
71
+ log("If this is about windows or GUI support, run with --no-window.")
72
+ return EXIT_ERROR
73
+
74
+
75
+ def build_parser():
76
+ common = argparse.ArgumentParser(add_help=False)
77
+ common.add_argument("--data", metavar="DIR", help=f"folder for the database (default: {default_data_dir()}, "
78
+ f"or set {DATA_ENV})") # fmt: skip
79
+ common.add_argument("--model-dir", metavar="DIR", help="folder holding your own copies of the model files "
80
+ "(default: downloaded once and cached)") # fmt: skip
81
+
82
+ camera = argparse.ArgumentParser(add_help=False)
83
+ camera.add_argument("--camera", type=int, default=0, metavar="N", help="camera index (default: 0)")
84
+ camera.add_argument("--no-window", action="store_true", help="no preview window")
85
+ camera.add_argument("--no-mirror", action="store_true", help="do not mirror the preview")
86
+ camera.add_argument("--timeout", type=float, default=60.0, metavar="SEC",
87
+ help="give up after this many seconds without a result (default: 60)") # fmt: skip
88
+
89
+ scale = argparse.ArgumentParser(add_help=False)
90
+ scale.add_argument("--ipd", type=float, metavar="MM", help="the person's pupil distance in mm, which sets "
91
+ f"the millimetre scale (default: the adult average, {AVERAGE_IPD_MM:g}; 0 = pixels only)") # fmt: skip
92
+ scale.add_argument("--hfov", type=float, metavar="DEG", help="camera horizontal field of view "
93
+ f"(default: {DEFAULT_HFOV_DEG:g}; 0 = no perspective correction)") # fmt: skip
94
+
95
+ parser = argparse.ArgumentParser(
96
+ prog="facecheck",
97
+ description="Register people with the camera, then check who is in front of it.",
98
+ epilog="Run 'facecheck COMMAND --help' for a command's options. "
99
+ "Exit codes: 0 = success or match, 1 = error, 2 = usage error, 3 = no match.",
100
+ )
101
+ parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
102
+ commands = parser.add_subparsers(dest="command", metavar="COMMAND")
103
+
104
+ register = commands.add_parser("register", parents=[common, camera, scale],
105
+ help="register a new person with the camera") # fmt: skip
106
+ register.add_argument("name", help="the person's name, e.g. \"Saeed Rohani\"")
107
+ register.add_argument("--replace", action="store_true", help="replace a person already registered under this name")
108
+ register.add_argument("--samples", type=int, default=5, metavar="N",
109
+ help="face samples to store (default: 5; more makes matching sturdier)") # fmt: skip
110
+
111
+ check = commands.add_parser("check", parents=[common, camera],
112
+ help="check whether the person in front of the camera is registered") # fmt: skip
113
+ check.add_argument("--name", help="check against this one person only, instead of everyone")
114
+ check.add_argument("--threshold", type=float, default=DEFAULT_THRESHOLD, metavar="T",
115
+ help=f"similarity needed for a match, 0 to 1 (default: {DEFAULT_THRESHOLD})") # fmt: skip
116
+
117
+ commands.add_parser("list", parents=[common], help="list registered people")
118
+ delete = commands.add_parser("delete", parents=[common], help="remove a registered person")
119
+ delete.add_argument("name")
120
+ export = commands.add_parser("export", parents=[common], help="export people, checks and measurements to CSV")
121
+ export.add_argument("--to", default=".", metavar="DIR", help="folder for the CSV files (default: here)")
122
+
123
+ m = commands.add_parser("measure", parents=[common, camera, scale],
124
+ help="measure a face and estimate its shape, without registering anyone") # fmt: skip
125
+ m.add_argument("--image", metavar="FILE", help="measure a photo instead of the camera")
126
+ m.add_argument("--label", help="free-text label stored with each result")
127
+ m.add_argument("--once", action="store_true", help="save one result automatically when the face is steady")
128
+ m.add_argument("--landmarks", action="store_true", help="include all 68 raw landmarks in the JSON")
129
+ return parser
130
+
131
+
132
+ def validate(parser, args):
133
+ hfov, ipd = getattr(args, "hfov", None), getattr(args, "ipd", None)
134
+ if hfov is not None and not 0 <= hfov < 180:
135
+ parser.error("--hfov must be between 0 and 180 degrees")
136
+ if ipd is not None and not (ipd == 0 or 40 <= ipd <= 85):
137
+ parser.error("--ipd must be between 40 and 85 mm, or 0")
138
+ if getattr(args, "timeout", 1) <= 0:
139
+ parser.error("--timeout must be more than 0")
140
+ if not 1 <= getattr(args, "samples", 1) <= 50:
141
+ parser.error("--samples must be between 1 and 50")
142
+ if not 0 < getattr(args, "threshold", 0.5) < 1:
143
+ parser.error("--threshold must be between 0 and 1")
144
+ if hasattr(args, "name") and args.name is not None:
145
+ args.name = clean_name(args.name, parser)
146
+
147
+
148
+ def clean_name(name, parser):
149
+ name = " ".join(unicodedata.normalize("NFC", name).split())
150
+ if not name:
151
+ parser.error("the name must not be empty")
152
+ if len(name) > 100 or any(unicodedata.category(c).startswith("C") for c in name):
153
+ parser.error("the name must be at most 100 printable characters")
154
+ return name
155
+
156
+
157
+ # --- register ----------------------------------------------------------------
158
+
159
+
160
+ def run_register(args):
161
+ with Store(args.db) as store:
162
+ if store.get_user(args.name) and not args.replace:
163
+ log(f"Error: '{args.name}' is already registered. Add --replace to register them again.")
164
+ return EXIT_ERROR
165
+ others = {n: e for n, e in store.gallery().items() if n.casefold() != args.name.casefold()}
166
+
167
+ with detection.FaceDetector(args.model_dir, landmarks=True, recognition=True) as detector, \
168
+ camera_for(args) as camera: # fmt: skip
169
+ captured = capture_samples(args, detector, camera)
170
+ if captured is None:
171
+ return EXIT_ERROR
172
+ frame, face, samples, landmark_sets = captured
173
+ camera.hold(frame, [(f"Captured {args.name}", GREEN)], face, GREEN, seconds=1.5)
174
+
175
+ measurement = measure_registration(args, frame.shape, landmark_sets)
176
+ query = mean_embedding(samples)
177
+ similar = None
178
+ if others:
179
+ best, score = rank(query, others)[0]
180
+ if score >= DEFAULT_THRESHOLD:
181
+ similar = {"name": best, "similarity": round(score, 4)}
182
+ log(f"Warning: this face looks like '{best}', who is already registered (similarity {score:.2f}).")
183
+ user = store.add_user(args.name, samples, measurement, replace=args.replace)
184
+
185
+ result = {"registered": True, **user, "similar_to": similar, "measurement": measurement}
186
+ print(to_json(result), flush=True)
187
+ shape = f", face shape {measurement['face_shape']['label']}" if measurement else ""
188
+ log(f"Registered {user['name']} with {user['samples']} face samples{shape}. Database: {args.db}")
189
+ return EXIT_OK
190
+
191
+
192
+ def capture_samples(args, detector, camera):
193
+ """Collect face samples and landmark sets. Returns (frame, face, samples, landmarks) or None."""
194
+ samples, landmark_sets, good = [], deque(maxlen=LANDMARK_FRAMES), 0
195
+ log(f"Registering {args.name}: look straight at the camera and hold still. Q cancels.")
196
+ for frame in camera.frames():
197
+ face = detector.find_face(frame)
198
+ problem = detection.face_problem(face)
199
+ if problem is None:
200
+ if good % SAMPLE_EVERY == 0:
201
+ samples.append(detector.embedding(frame, face))
202
+ good += 1
203
+ points = detector.landmarks(frame, face)
204
+ if points is not None:
205
+ landmark_sets.append(points)
206
+ elif face is None:
207
+ good = 0 # someone left: do not mix their samples with the next person's
208
+ samples.clear()
209
+ landmark_sets.clear()
210
+ status = problem or f"Hold still... {len(samples)}/{args.samples}"
211
+ lines = [(f"Registering {args.name}", WHITE), (status, AMBER if problem else GREEN)]
212
+ if len(samples) >= args.samples:
213
+ return frame, face, samples, list(landmark_sets)
214
+ if not camera.show(frame, lines, face, AMBER if problem else GREEN):
215
+ log("Cancelled; nothing was saved.")
216
+ return None
217
+ log("No usable face was seen in time. Face the camera in good light and try again.")
218
+ return None
219
+
220
+
221
+ def measure_registration(args, frame_shape, landmark_sets):
222
+ """The face measurement saved with a new person, or None if it failed."""
223
+ if not landmark_sets:
224
+ log("Warning: no landmarks were found, so no measurements were saved.")
225
+ return None
226
+ height, width = frame_shape[:2]
227
+ hfov = DEFAULT_HFOV_DEG if args.hfov is None else (args.hfov or None)
228
+ try:
229
+ return analyze(
230
+ np.mean(landmark_sets, axis=0),
231
+ (width, height),
232
+ ipd_mm=args.ipd,
233
+ hfov_deg=hfov,
234
+ label=args.name,
235
+ source=f"register:camera:{args.camera}",
236
+ frames_averaged=len(landmark_sets),
237
+ )
238
+ except ValueError as error:
239
+ log(f"Warning: the measurements failed ({error}), so none were saved.")
240
+ return None
241
+
242
+
243
+ # --- check -------------------------------------------------------------------
244
+
245
+
246
+ def run_check(args):
247
+ if not args.db.is_file():
248
+ log("Error: nobody is registered yet. Register someone first: facecheck register \"NAME\"")
249
+ return EXIT_ERROR
250
+ with Store(args.db) as store:
251
+ claimed = None
252
+ if args.name is not None:
253
+ user = store.get_user(args.name)
254
+ if user is None:
255
+ log(f"Error: '{args.name}' is not registered. See who is: facecheck list")
256
+ return EXIT_ERROR
257
+ claimed = user["name"]
258
+ gallery = store.gallery()
259
+ if not gallery:
260
+ log("Error: nobody is registered yet. Register someone first: facecheck register \"NAME\"")
261
+ return EXIT_ERROR
262
+
263
+ with detection.FaceDetector(args.model_dir, landmarks=False, recognition=True) as detector, \
264
+ camera_for(args) as camera: # fmt: skip
265
+ captured = capture_check(args, detector, camera, claimed)
266
+ if captured is None:
267
+ return EXIT_ERROR
268
+ frame, face, samples = captured
269
+ result = decide(mean_embedding(samples), gallery, args.threshold, claimed=claimed)
270
+ result = {
271
+ "id": uuid.uuid4().hex,
272
+ "checked_at": utc_now(),
273
+ **result,
274
+ "frames_used": len(samples),
275
+ "source": f"camera:{args.camera}",
276
+ }
277
+ camera.hold(frame, [verdict(result)], face, GREEN if result["matched"] else RED)
278
+ store.log_check(result)
279
+
280
+ print(to_json(result), flush=True)
281
+ log(verdict(result)[0])
282
+ return EXIT_OK if result["matched"] else EXIT_NO_MATCH
283
+
284
+
285
+ def capture_check(args, detector, camera, claimed):
286
+ """Collect a few consecutive good samples. Returns (frame, face, samples) or None."""
287
+ samples = []
288
+ title = f"Checking: is this {claimed}?" if claimed else "Checking who this is"
289
+ log(f"{title}{'' if title.endswith('?') else '.'} Look straight at the camera. Q cancels.")
290
+ for frame in camera.frames():
291
+ face = detector.find_face(frame)
292
+ problem = detection.face_problem(face)
293
+ if problem is None:
294
+ samples.append(detector.embedding(frame, face))
295
+ if len(samples) >= CHECK_SAMPLES:
296
+ return frame, face, samples
297
+ else:
298
+ samples.clear() # only consecutive frames of one steady face count
299
+ lines = [(title, WHITE), (problem or "Hold still...", AMBER if problem else GREEN)]
300
+ if not camera.show(frame, lines, face, AMBER if problem else GREEN):
301
+ log("Cancelled.")
302
+ return None
303
+ log("No usable face was seen in time. Face the camera in good light and try again.")
304
+ return None
305
+
306
+
307
+ def verdict(result):
308
+ """A one-line summary of a check, as (text, colour)."""
309
+ score = f"similarity {result['similarity']:.2f}, needed {result['threshold']:.2f}"
310
+ if result["mode"] == "verify":
311
+ if result["matched"]:
312
+ return f"Confirmed: this is {result['claimed_name']} ({score})", GREEN
313
+ return f"Not confirmed: this does not look like {result['claimed_name']} ({score})", RED
314
+ if result["matched"]:
315
+ return f"Match: {result['name']} ({score})", GREEN
316
+ return f"No match: this person is not registered ({score})", RED
317
+
318
+
319
+ def camera_for(args):
320
+ return Camera(args.camera, window=not args.no_window, mirror=not args.no_mirror, timeout=args.timeout)
321
+
322
+
323
+ # --- list, delete, export, measure -------------------------------------------
324
+
325
+
326
+ def run_list(args):
327
+ if not args.db.is_file():
328
+ print("Nobody is registered yet.")
329
+ return EXIT_OK
330
+ with Store(args.db) as store:
331
+ people = store.users()
332
+ if not people:
333
+ print("Nobody is registered yet.")
334
+ for person in people:
335
+ shape = f" {person['face_shape']}" if person["face_shape"] else ""
336
+ print(f"{person['name']} registered {person['registered_at']} {person['samples']} samples{shape}")
337
+ return EXIT_OK
338
+
339
+
340
+ def run_delete(args):
341
+ if args.db.is_file():
342
+ with Store(args.db) as store:
343
+ if store.delete_user(args.name):
344
+ log(f"Deleted {args.name} and their face samples.")
345
+ return EXIT_OK
346
+ log(f"Error: '{args.name}' is not registered.")
347
+ return EXIT_ERROR
348
+
349
+
350
+ def run_export(args):
351
+ if not args.db.is_file():
352
+ log(f"Error: no database at {args.db}")
353
+ return EXIT_ERROR
354
+ folder = Path(args.to)
355
+ with Store(args.db) as store:
356
+ counts = {
357
+ "users.csv": store.export_users_csv(folder / "users.csv"),
358
+ "checks.csv": store.export_checks_csv(folder / "checks.csv"),
359
+ "measurements.csv": store.export_csv(folder / "measurements.csv"),
360
+ }
361
+ for filename, rows in counts.items():
362
+ log(f"Exported {rows} row(s) to {folder / filename}")
363
+ return EXIT_OK
364
+
365
+
366
+ def run_measure(args):
367
+ args.json_dir = args.data / "json"
368
+ args.csv = args.data / "measurements.csv"
369
+ return measure.run(args)
370
+
371
+
372
+ def log(message):
373
+ """Status messages go to stderr so stdout carries only results."""
374
+ print(message, file=sys.stderr, flush=True)
375
+
376
+
377
+ if __name__ == "__main__":
378
+ raise SystemExit(main())
facecheck/detector.py ADDED
@@ -0,0 +1,291 @@
1
+ """Face detection, landmarks and identity embeddings with OpenCV only.
2
+
3
+ 1. YuNet (OpenCV's face detector) finds the faces; the largest one is kept.
4
+ 2. Facemark LBF (from opencv-contrib) places 68 landmarks, for measurements.
5
+ 3. SFace (OpenCV's face recognizer) turns the face into a 128-number
6
+ embedding, for telling people apart.
7
+
8
+ OpenCV publishes wheels that work on every Python 3 from 3.7 up, so this
9
+ runs wherever OpenCV installs. Each model file is downloaded the first time
10
+ a command needs it.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import math
16
+ import os
17
+ import shutil
18
+ import ssl
19
+ import subprocess
20
+ import sys
21
+ import urllib.error
22
+ import urllib.request
23
+ from dataclasses import dataclass
24
+ from pathlib import Path
25
+
26
+ import cv2
27
+ import numpy as np
28
+
29
+ from .identity import normalize
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class Model:
34
+ filename: str
35
+ url: str
36
+ size_text: str
37
+ min_bytes: int # anything smaller is a failed or partial download
38
+
39
+
40
+ _ZOO = "https://github.com/opencv/opencv_zoo/raw/main/models/"
41
+ MODELS = {
42
+ "detector": Model(
43
+ "face_detection_yunet_2023mar.onnx",
44
+ _ZOO + "face_detection_yunet/face_detection_yunet_2023mar.onnx",
45
+ "about 0.2 MB",
46
+ 100_000,
47
+ ),
48
+ "landmarks": Model(
49
+ "lbfmodel.yaml",
50
+ "https://raw.githubusercontent.com/kurnianggoro/GSOC2017/master/data/lbfmodel.yaml",
51
+ "about 54 MB",
52
+ 20_000_000,
53
+ ),
54
+ "recognizer": Model(
55
+ "face_recognition_sface_2021dec.onnx",
56
+ _ZOO + "face_recognition_sface/face_recognition_sface_2021dec.onnx",
57
+ "about 37 MB",
58
+ 30_000_000,
59
+ ),
60
+ }
61
+ MODEL_DIR_ENV = "FACECHECK_MODEL_DIR"
62
+ DETECT_WIDTH = 640 # frames are shrunk to this width to find the face quickly
63
+
64
+ # A face is good enough to recognise when it is this big and this straight.
65
+ MIN_FACE_PX = 90
66
+ MAX_ROLL_DEG = 15.0
67
+ MAX_TURN = 0.18 # nose offset from the eyes' midpoint, as a fraction of eye distance (about 16 degrees)
68
+
69
+
70
+ def default_model_dir():
71
+ """Where the downloaded models are cached on this machine."""
72
+ if sys.platform == "win32":
73
+ base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
74
+ elif sys.platform == "darwin":
75
+ base = Path.home() / "Library" / "Caches"
76
+ else:
77
+ base = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache")
78
+ return base / "facecheck"
79
+
80
+
81
+ def ensure_models(model_dir=None, names=None):
82
+ """Return {name: path} for the requested models, downloading on first use.
83
+
84
+ An explicit folder (argument or the FACECHECK_MODEL_DIR environment
85
+ variable) must already hold the files; only the default cache folder is
86
+ downloaded to.
87
+ """
88
+ wanted = {name: MODELS[name] for name in (names or MODELS)}
89
+ explicit = model_dir or os.environ.get(MODEL_DIR_ENV)
90
+ if explicit:
91
+ folder = Path(explicit).expanduser()
92
+ paths = {name: folder / model.filename for name, model in wanted.items()}
93
+ missing = [wanted[name] for name, path in paths.items() if not path.is_file()]
94
+ if missing:
95
+ listing = "\n".join(f" {m.filename}: {m.url}" for m in missing)
96
+ raise FileNotFoundError(f"model files missing from {folder}:\n{listing}")
97
+ return paths
98
+
99
+ folder = default_model_dir()
100
+ paths = {}
101
+ for name, model in wanted.items():
102
+ path = folder / model.filename
103
+ if not (path.is_file() and path.stat().st_size >= model.min_bytes):
104
+ _download(model, path)
105
+ paths[name] = path
106
+ return paths
107
+
108
+
109
+ def _download(model, destination):
110
+ print(
111
+ f"Downloading {model.filename} ({model.size_text}, first run only) to {destination.parent}",
112
+ file=sys.stderr,
113
+ flush=True,
114
+ )
115
+ destination.parent.mkdir(parents=True, exist_ok=True)
116
+ partial = destination.with_name(destination.name + ".part")
117
+ try:
118
+ _fetch(model.url, partial)
119
+ if partial.stat().st_size < model.min_bytes:
120
+ raise OSError("the download was incomplete")
121
+ partial.replace(destination)
122
+ except (OSError, subprocess.SubprocessError) as error: # network, timeout, disk or curl errors
123
+ partial.unlink(missing_ok=True)
124
+ hint = ""
125
+ if _is_certificate_error(error) and sys.platform == "darwin":
126
+ hint = (
127
+ "\nThis Python cannot check HTTPS certificates. To fix it for good, open the "
128
+ "Python folder in Applications and run 'Install Certificates.command'."
129
+ )
130
+ raise RuntimeError(
131
+ f"Could not download {model.filename} ({error}).{hint}\n"
132
+ f"Or download the file yourself from {model.url}\n"
133
+ f"into {destination.parent} and run again."
134
+ ) from error
135
+
136
+
137
+ def _fetch(url, path):
138
+ """Download url to path. Certificates are always checked.
139
+
140
+ Some Python installs, notably python.org's on macOS, come without the
141
+ list of trusted certificates, so every HTTPS download fails. The curl
142
+ program that ships with macOS, Windows 10+ and most Linux systems uses
143
+ the system's own list, so it is tried before giving up.
144
+ """
145
+ try:
146
+ with urllib.request.urlopen(url, timeout=60) as response, open(path, "wb") as out:
147
+ shutil.copyfileobj(response, out)
148
+ return
149
+ except urllib.error.URLError as error:
150
+ curl = shutil.which("curl")
151
+ if not (_is_certificate_error(error) and curl):
152
+ raise
153
+ first_error = error
154
+ print("Python could not check the HTTPS certificate; trying the system's curl.", file=sys.stderr, flush=True)
155
+ try:
156
+ subprocess.run(
157
+ [curl, "--fail", "--silent", "--show-error", "--location", "--retry", "2",
158
+ "--output", str(path), url],
159
+ check=True,
160
+ timeout=900,
161
+ ) # fmt: skip
162
+ except subprocess.CalledProcessError as error:
163
+ raise first_error from error # report the original certificate problem
164
+
165
+
166
+ def _is_certificate_error(error):
167
+ while error is not None:
168
+ if isinstance(error, ssl.SSLCertVerificationError) or isinstance(
169
+ getattr(error, "reason", None), ssl.SSLCertVerificationError
170
+ ):
171
+ return True
172
+ error = error.__cause__
173
+ return False
174
+
175
+
176
+ def face_problem(face):
177
+ """None if the face suits recognition, otherwise a short instruction.
178
+
179
+ `face` is a row from find_face(). The check uses YuNet's five key points:
180
+ the eye line gives the head tilt, and the nose's offset from the eyes'
181
+ midpoint shows how far the head is turned.
182
+ """
183
+ if face is None:
184
+ return "No face detected"
185
+ if face[2] < MIN_FACE_PX:
186
+ return "Move closer to the camera"
187
+ (ax, ay), (bx, by) = sorted([tuple(face[4:6]), tuple(face[6:8])]) # eyes, left to right in the image
188
+ eye_distance = math.hypot(bx - ax, by - ay)
189
+ if eye_distance < 1:
190
+ return "Look straight at the camera"
191
+ roll = math.degrees(math.atan2(by - ay, bx - ax))
192
+ turn = (face[8] - (ax + bx) / 2) / eye_distance
193
+ if abs(roll) > MAX_ROLL_DEG or abs(turn) > MAX_TURN:
194
+ return "Look straight at the camera"
195
+ return None
196
+
197
+
198
+ def square_box(face):
199
+ """The square box around a face that the landmark model expects."""
200
+ x, y, w, h = (float(v) for v in face[:4])
201
+ side = max(w, h)
202
+ left, top = x + w / 2 - side / 2, y + h / 2 - side / 2
203
+ return [int(round(left)), int(round(top)), int(round(side)), int(round(side))]
204
+
205
+
206
+ class FaceDetector:
207
+ """Finds the most prominent face in a frame; gives its landmarks and embedding.
208
+
209
+ landmarks=True loads the 68-point model (for measurements);
210
+ recognition=True loads the identity model (for register and check).
211
+ """
212
+
213
+ def __init__(self, model_dir=None, landmarks=True, recognition=False, min_confidence=0.6):
214
+ if landmarks and not hasattr(cv2, "face"):
215
+ raise RuntimeError(
216
+ "OpenCV's face module is missing. It comes with opencv-contrib-python. "
217
+ "If opencv-python or opencv-python-headless is also installed, they hide it: run\n"
218
+ " pip uninstall -y opencv-python opencv-python-headless opencv-contrib-python\n"
219
+ " pip install --only-binary=:all: opencv-contrib-python"
220
+ )
221
+ names = ["detector"] + ["landmarks"] * landmarks + ["recognizer"] * recognition
222
+ paths = ensure_models(model_dir, names)
223
+ self._facemark = self._recognizer = None
224
+ try:
225
+ self._finder = cv2.FaceDetectorYN.create(
226
+ str(paths["detector"]), "", (320, 320), min_confidence, 0.3, 5000
227
+ )
228
+ if landmarks:
229
+ self._facemark = cv2.face.createFacemarkLBF()
230
+ self._facemark.loadModel(str(paths["landmarks"]))
231
+ if recognition:
232
+ self._recognizer = cv2.FaceRecognizerSF.create(str(paths["recognizer"]), "")
233
+ except cv2.error as error:
234
+ raise RuntimeError(
235
+ f"could not load the face models in {paths['detector'].parent} ({error}). "
236
+ "If a file is damaged, delete it and run again to download a fresh copy."
237
+ ) from error
238
+
239
+ def find_face(self, frame_bgr):
240
+ """Return the largest face as 15 numbers in frame pixels, or None.
241
+
242
+ Layout (YuNet's): box x, y, w, h; then x, y of the right eye, left
243
+ eye, nose tip, right and left mouth corners; then the score.
244
+ """
245
+ width = frame_bgr.shape[1]
246
+ scale = min(1.0, DETECT_WIDTH / width)
247
+ small = frame_bgr if scale == 1.0 else cv2.resize(
248
+ frame_bgr, None, fx=scale, fy=scale, interpolation=cv2.INTER_AREA
249
+ )
250
+ self._finder.setInputSize((small.shape[1], small.shape[0]))
251
+ _, faces = self._finder.detect(small)
252
+ if faces is None or len(faces) == 0:
253
+ return None
254
+ face = np.array(max(faces, key=lambda f: f[2] * f[3]), dtype=np.float32)
255
+ face[:14] /= scale
256
+ return face
257
+
258
+ def landmarks(self, frame_bgr, face):
259
+ """Return (68, 2) normalised landmarks for a face from find_face(), or None."""
260
+ if self._facemark is None:
261
+ raise RuntimeError("this FaceDetector was created with landmarks=False")
262
+ height, width = frame_bgr.shape[:2]
263
+ gray = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2GRAY)
264
+ ok, shapes = self._facemark.fit(gray, np.array([square_box(face)], dtype=np.int32))
265
+ if not ok or len(shapes) == 0:
266
+ return None
267
+ points = np.asarray(shapes[0], dtype=np.float32).reshape(-1, 2)
268
+ if len(points) != 68:
269
+ return None
270
+ return points / np.array([width, height], dtype=np.float32)
271
+
272
+ def embedding(self, frame_bgr, face):
273
+ """Return the face's identity embedding: 128 numbers of unit length."""
274
+ if self._recognizer is None:
275
+ raise RuntimeError("this FaceDetector was created with recognition=False")
276
+ aligned = self._recognizer.alignCrop(frame_bgr, face)
277
+ return normalize(self._recognizer.feature(aligned))
278
+
279
+ def detect(self, frame_bgr):
280
+ """Find the largest face and return its (68, 2) landmarks, or None."""
281
+ face = self.find_face(frame_bgr)
282
+ return None if face is None else self.landmarks(frame_bgr, face)
283
+
284
+ def close(self):
285
+ self._finder = self._facemark = self._recognizer = None
286
+
287
+ def __enter__(self):
288
+ return self
289
+
290
+ def __exit__(self, *exc_info):
291
+ self.close()