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/__init__.py +31 -0
- facecheck/__main__.py +3 -0
- facecheck/analysis.py +334 -0
- facecheck/camera.py +153 -0
- facecheck/cli.py +378 -0
- facecheck/detector.py +291 -0
- facecheck/identity.py +79 -0
- facecheck/measure.py +196 -0
- facecheck/storage.py +282 -0
- facecheck-1.0.0.dist-info/METADATA +407 -0
- facecheck-1.0.0.dist-info/RECORD +15 -0
- facecheck-1.0.0.dist-info/WHEEL +5 -0
- facecheck-1.0.0.dist-info/entry_points.txt +2 -0
- facecheck-1.0.0.dist-info/licenses/LICENSE +21 -0
- facecheck-1.0.0.dist-info/top_level.txt +1 -0
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()
|