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 ADDED
@@ -0,0 +1,31 @@
1
+ """facecheck: register people with a camera, then check who is in front of it.
2
+
3
+ Only OpenCV and NumPy are needed; the face models download on first use.
4
+ """
5
+
6
+ from importlib.metadata import version
7
+
8
+ from .analysis import analyze, classify_shape, to_json
9
+ from .detector import FaceDetector, face_problem
10
+ from .identity import DEFAULT_THRESHOLD, decide, mean_embedding, rank, similarity
11
+ from .storage import Store
12
+
13
+ try:
14
+ __version__ = version("facecheck")
15
+ except Exception: # not installed (a source checkout), or its metadata is unreadable
16
+ __version__ = "0.0.0"
17
+
18
+ __all__ = [
19
+ "DEFAULT_THRESHOLD",
20
+ "FaceDetector",
21
+ "Store",
22
+ "analyze",
23
+ "classify_shape",
24
+ "decide",
25
+ "face_problem",
26
+ "mean_embedding",
27
+ "rank",
28
+ "similarity",
29
+ "to_json",
30
+ "__version__",
31
+ ]
facecheck/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())
facecheck/analysis.py ADDED
@@ -0,0 +1,334 @@
1
+ """Landmarks in, numbers out.
2
+
3
+ This module turns one face's landmarks into measurements, ratios, a head-pose
4
+ estimate and a face-shape estimate. It needs only NumPy and OpenCV, so it can
5
+ be tested without a camera or a model file.
6
+
7
+ Landmarks use the common 68-point layout (iBUG 300-W, as produced by OpenCV
8
+ Facemark and dlib): a (68, 2) array of ``x, y`` values as fractions of the
9
+ image width and height. Point 0 is on the image's left edge of the face,
10
+ which is the subject's right side.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import json
16
+ import math
17
+ import uuid
18
+ from datetime import datetime, timezone
19
+
20
+ import cv2
21
+ import numpy as np
22
+
23
+ SCHEMA_VERSION = 2
24
+ LANDMARK_COUNT = 68
25
+
26
+ # --- Landmark indices (R / L are the subject's own right and left) ----------
27
+ CHIN = 8
28
+ CHEEK_R, CHEEK_L = 1, 15
29
+ JAW_R, JAW_L = 4, 12
30
+ BROW_OUTER_R, BROW_OUTER_L = 17, 26
31
+ BROW_PEAK_R, BROW_PEAK_L = 19, 24
32
+ NASION, NOSE_TIP, NOSE_BASE = 27, 30, 33
33
+ NOSTRIL_R, NOSTRIL_L = 31, 35
34
+ EYE_OUTER_R, EYE_INNER_R, EYE_INNER_L, EYE_OUTER_L = 36, 39, 42, 45
35
+ EYE_R, EYE_L = tuple(range(36, 42)), tuple(range(42, 48))
36
+ MOUTH_R, MOUTH_L = 48, 54
37
+
38
+ # Points worked out from the landmarks; extend() appends them after the 68.
39
+ BROW_CENTRE, FOREHEAD_TOP, PUPIL_R, PUPIL_L = 68, 69, 70, 71
40
+
41
+ # --- Measurements ------------------------------------------------------------
42
+ # name -> landmark pairs. A measurement with several pairs is their average.
43
+ SEGMENTS = {
44
+ "face_length": ((FOREHEAD_TOP, CHIN),),
45
+ "face_width": ((CHEEK_R, CHEEK_L),),
46
+ "forehead_width": ((BROW_OUTER_R, BROW_OUTER_L),),
47
+ "jaw_width": ((JAW_R, JAW_L), (JAW_R + 1, JAW_L - 1)),
48
+ "eye_distance_inner": ((EYE_INNER_R, EYE_INNER_L),),
49
+ "eye_distance_outer": ((EYE_OUTER_R, EYE_OUTER_L),),
50
+ "pupil_distance": ((PUPIL_R, PUPIL_L),),
51
+ "eye_width": ((EYE_OUTER_R, EYE_INNER_R), (EYE_INNER_L, EYE_OUTER_L)),
52
+ "nose_length": ((NASION, NOSE_BASE),),
53
+ "nose_width": ((NOSTRIL_R, NOSTRIL_L),),
54
+ "mouth_width": ((MOUTH_R, MOUTH_L),),
55
+ "lower_face_height": ((NOSE_BASE, CHIN),),
56
+ }
57
+
58
+ # name -> (numerator, denominator)
59
+ RATIOS = {
60
+ "length_to_width": ("face_length", "face_width"),
61
+ "forehead_to_width": ("forehead_width", "face_width"),
62
+ "jaw_to_width": ("jaw_width", "face_width"),
63
+ "jaw_to_forehead": ("jaw_width", "forehead_width"),
64
+ }
65
+
66
+ # --- A generic face -----------------------------------------------------------
67
+ # The 68 points of an average adult face in centimetres: x towards the
68
+ # subject's left, y up, z towards the camera. Taken from MediaPipe's canonical
69
+ # face model (Apache-2.0, google-ai-edge/mediapipe, face_geometry/data). It is
70
+ # used to estimate head pose and how far back each point lies.
71
+ FACE_MODEL_CM = np.array([
72
+ (-7.743, 2.365, -2.005), (-7.664, 0.673, -2.436), (-7.542, -1.049, -2.431), (-7.271, -2.891, -2.252),
73
+ (-6.720, -4.789, -1.745), (-5.085, -7.179, 0.715), (-4.069, -7.993, 1.925), (-2.309, -8.974, 3.609),
74
+ (0.000, -9.403, 4.264), (2.309, -8.974, 3.609), (4.069, -7.993, 1.925), (5.085, -7.179, 0.715),
75
+ (6.720, -4.789, -1.745), (7.271, -2.891, -2.252), (7.542, -1.049, -2.431), (7.664, 0.673, -2.436),
76
+ (7.743, 2.365, -2.005), (-5.721, 4.255, 2.831), (-4.986, 4.802, 3.752), (-3.987, 5.109, 4.466),
77
+ (-2.760, 5.101, 5.016), (-1.396, 5.012, 5.316), (1.396, 5.012, 5.316), (2.760, 5.101, 5.016),
78
+ (3.987, 5.109, 4.466), (4.986, 4.802, 3.752), (5.721, 4.255, 2.831), (0.000, 3.271, 5.236),
79
+ (0.000, 1.728, 6.317), (0.000, 0.366, 7.243), (0.000, -0.463, 7.587), (-1.044, -1.465, 5.662),
80
+ (-0.597, -2.014, 5.866), (0.000, -2.089, 6.058), (0.597, -2.014, 5.866), (1.044, -1.465, 5.662),
81
+ (-4.446, 2.664, 3.173), (-3.670, 2.928, 3.724), (-2.724, 2.962, 3.872), (-1.856, 2.585, 3.758),
82
+ (-2.724, 2.316, 3.777), (-3.670, 2.360, 3.635), (1.856, 2.585, 3.758), (2.724, 2.962, 3.872),
83
+ (3.670, 2.928, 3.724), (4.446, 2.664, 3.173), (3.670, 2.360, 3.635), (2.724, 2.316, 3.777),
84
+ (-2.456, -4.343, 4.284), (-1.432, -3.501, 5.496), (-0.711, -3.329, 5.877), (0.000, -3.406, 5.980),
85
+ (0.711, -3.329, 5.877), (1.432, -3.501, 5.496), (2.456, -4.343, 4.284), (1.325, -5.107, 5.205),
86
+ (0.700, -5.292, 5.448), (0.000, -5.365, 5.535), (-0.700, -5.292, 5.448), (-1.325, -5.107, 5.205),
87
+ (-2.153, -4.276, 4.038), (-0.533, -3.993, 5.138), (0.000, -3.994, 5.219), (0.533, -3.993, 5.138),
88
+ (2.153, -4.276, 4.038), (0.583, -4.518, 5.340), (0.000, -4.542, 5.405), (-0.583, -4.518, 5.340),
89
+ ]) # fmt: skip
90
+
91
+ # Pose is fitted on points that stay put when the head turns. The jaw line is
92
+ # left out: on a turned head the visible outline slides around the face.
93
+ POSE_POINTS = [NASION, NOSE_TIP, NOSE_BASE, EYE_OUTER_R, EYE_INNER_R, EYE_INNER_L, EYE_OUTER_L,
94
+ MOUTH_R, MOUTH_L, CHIN] # fmt: skip
95
+
96
+ # --- Scale and pose ----------------------------------------------------------
97
+ AVERAGE_IPD_MM = 63.0 # adult average pupil distance; about 61-65 mm for most people
98
+ MIN_IPD_PX = 10.0 # eyes closer than this on screen give no usable scale
99
+ DEFAULT_HFOV_DEG = 60.0 # typical laptop webcam
100
+ FRONTAL_LIMITS_DEG = {"yaw": 12.0, "pitch": 15.0, "roll": 12.0}
101
+
102
+ # --- Face shape --------------------------------------------------------------
103
+ # Each shape is a typical point in feature space; a face gets the label of the
104
+ # nearest one. "oval" is the generic face above; the others are hand-set
105
+ # offsets from it. Not fitted to labelled faces: tune them here if needed.
106
+ SHAPE_FEATURES = ("length_to_width", "forehead_to_width", "jaw_to_width", "jaw_angle_deg")
107
+ SHAPE_PROTOTYPES = {
108
+ "oval": (1.42, 0.75, 0.77, 139.0),
109
+ "round": (1.28, 0.74, 0.80, 144.0),
110
+ "square": (1.28, 0.78, 0.86, 131.0),
111
+ "oblong": (1.57, 0.76, 0.79, 137.0),
112
+ "heart": (1.41, 0.80, 0.70, 141.0),
113
+ "diamond": (1.43, 0.68, 0.71, 141.0),
114
+ "triangle": (1.37, 0.69, 0.85, 134.0),
115
+ }
116
+ SHAPE_SPREAD = (0.075, 0.036, 0.04, 8.0) # how far each feature usually strays
117
+
118
+
119
+ def extend(points):
120
+ """Return the landmarks with the derived points appended (rows 68 to 71).
121
+
122
+ The forehead top is an estimate: by the facial "rule of thirds" the
123
+ forehead is about as tall as the brow-to-nose-base distance.
124
+ """
125
+ p = np.asarray(points, dtype=np.float64)
126
+ brow = (p[BROW_PEAK_R] + p[BROW_PEAK_L]) / 2
127
+ forehead = brow + (brow - p[NOSE_BASE])
128
+ pupil_r, pupil_l = p[list(EYE_R)].mean(axis=0), p[list(EYE_L)].mean(axis=0)
129
+ return np.vstack([p, brow, forehead, pupil_r, pupil_l])
130
+
131
+
132
+ # The generic face in OpenCV camera axes (x right, y down, z away), in mm.
133
+ _MODEL = extend(FACE_MODEL_CM * 10.0 * (1, -1, -1))
134
+ _MODEL_IPD_MM = float(np.linalg.norm(_MODEL[PUPIL_L] - _MODEL[PUPIL_R]))
135
+
136
+
137
+ def analyze(
138
+ landmarks,
139
+ image_size,
140
+ *,
141
+ ipd_mm=None,
142
+ hfov_deg=DEFAULT_HFOV_DEG,
143
+ label=None,
144
+ source=None,
145
+ frames_averaged=1,
146
+ include_landmarks=False,
147
+ ):
148
+ """Measure one face and return a JSON-serialisable result dict.
149
+
150
+ landmarks: (68, 2) normalised landmarks.
151
+ image_size: (width, height) of the frame the landmarks came from.
152
+ ipd_mm: the person's pupil distance in mm, which sets the millimetre
153
+ scale. None assumes the adult average; 0 gives pixels only.
154
+ hfov_deg: the camera's horizontal field of view, used to undo perspective.
155
+ Pass None for cropped or resized photos, where it cannot be known.
156
+ """
157
+ points = np.asarray(landmarks, dtype=np.float64)
158
+ if points.shape != (LANDMARK_COUNT, 2):
159
+ raise ValueError(f"landmarks must be a ({LANDMARK_COUNT}, 2) array")
160
+ width, height = int(image_size[0]), int(image_size[1])
161
+ if width <= 0 or height <= 0:
162
+ raise ValueError("image_size must be (width, height) in pixels")
163
+
164
+ pixels = points * (width, height)
165
+ on_image = extend(pixels)
166
+ on_screen = _lengths(on_image)
167
+ if on_screen["face_width"] < 1 or on_screen["forehead_width"] < 1 or on_screen["pupil_distance"] < 1:
168
+ raise ValueError("landmarks are degenerate (no face width)")
169
+
170
+ # Pose needs some focal length; for photos a typical one is good enough.
171
+ focal_px = (width / 2) / math.tan(math.radians(hfov_deg or DEFAULT_HFOV_DEG) / 2)
172
+ rotation = _head_rotation(pixels, focal_px, width, height)
173
+
174
+ scale = None
175
+ in_space = on_screen
176
+ measured_ipd = AVERAGE_IPD_MM if ipd_mm is None else float(ipd_mm)
177
+ if measured_ipd > 0 and on_screen["pupil_distance"] >= MIN_IPD_PX:
178
+ solid, mm_per_px, distance = _to_3d(
179
+ pixels, rotation, measured_ipd, focal_px if hfov_deg else None, width, height
180
+ )
181
+ in_space = _lengths(extend(solid)) # derive points in 3D, not on the flat image
182
+ scale = {
183
+ "method": "average_ipd" if ipd_mm is None else "given_ipd",
184
+ "ipd_mm": measured_ipd,
185
+ "mm_per_px": round(mm_per_px, 4),
186
+ "camera_distance_mm": round(distance) if distance else None,
187
+ "hfov_deg": float(hfov_deg) if hfov_deg else None,
188
+ }
189
+
190
+ ratios = {
191
+ name: round(in_space[top] / in_space[bottom], 4) for name, (top, bottom) in RATIOS.items()
192
+ }
193
+ jaw_angle = round(_jaw_angle(on_image), 1)
194
+
195
+ result = {
196
+ "schema_version": SCHEMA_VERSION,
197
+ "id": uuid.uuid4().hex,
198
+ "captured_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
199
+ "label": label,
200
+ "source": source,
201
+ "image": {"width": width, "height": height},
202
+ "frames_averaged": int(frames_averaged),
203
+ "pose": _pose(rotation),
204
+ "scale": scale,
205
+ "measurements_px": _rounded(on_screen, 1),
206
+ "measurements_mm": _rounded(in_space, 1) if scale else None,
207
+ "jaw_angle_deg": jaw_angle,
208
+ "ratios": ratios,
209
+ "face_shape": classify_shape(
210
+ ratios["length_to_width"],
211
+ ratios["forehead_to_width"],
212
+ ratios["jaw_to_width"],
213
+ jaw_angle,
214
+ ),
215
+ }
216
+ if include_landmarks:
217
+ result["landmarks"] = np.round(points, 5).tolist()
218
+ return result
219
+
220
+
221
+ def classify_shape(length_to_width, forehead_to_width, jaw_to_width, jaw_angle_deg):
222
+ """Label a face by its nearest shape prototype.
223
+
224
+ Returns {"label", "confidence", "scores"}. The scores add up to 1 and say
225
+ how well each shape matches relative to the others; they are not
226
+ calibrated probabilities.
227
+ """
228
+ features = np.array([length_to_width, forehead_to_width, jaw_to_width, jaw_angle_deg])
229
+ names = list(SHAPE_PROTOTYPES)
230
+ offsets = (np.array([SHAPE_PROTOTYPES[n] for n in names]) - features) / SHAPE_SPREAD
231
+ logits = -0.5 * np.sum(offsets**2, axis=1)
232
+ weights = np.exp(logits - logits.max()) # subtracting the max avoids underflow
233
+ weights /= weights.sum()
234
+ best = int(np.argmax(weights))
235
+ return {
236
+ "label": names[best],
237
+ "confidence": round(float(weights[best]), 3),
238
+ "scores": {n: round(float(w), 3) for n, w in zip(names, weights)},
239
+ }
240
+
241
+
242
+ def to_json(result, indent=2):
243
+ """Serialise a result dict to a JSON string."""
244
+ return json.dumps(result, indent=indent)
245
+
246
+
247
+ # --- Internals ---------------------------------------------------------------
248
+
249
+
250
+ def _head_rotation(pixels, focal_px, width, height):
251
+ """Rotation of the head relative to the camera, fitted to the generic face."""
252
+ camera = np.array([[focal_px, 0, width / 2], [0, focal_px, height / 2], [0, 0, 1]], dtype=np.float64)
253
+ ok, rvec, tvec = cv2.solvePnP(
254
+ _MODEL[POSE_POINTS],
255
+ pixels[POSE_POINTS].reshape(-1, 1, 2),
256
+ camera,
257
+ None,
258
+ flags=cv2.SOLVEPNP_ITERATIVE,
259
+ )
260
+ if not ok or tvec[2, 0] <= 0: # no fit, or a "face" behind the camera
261
+ raise ValueError("could not estimate the head pose")
262
+ rotation, _ = cv2.Rodrigues(rvec)
263
+ return rotation
264
+
265
+
266
+ def _pose(rotation):
267
+ """Head rotation in degrees.
268
+
269
+ yaw > 0: head turned towards the subject's left.
270
+ pitch > 0: chin tucked in (looking down).
271
+ roll > 0: head tilted towards the subject's left shoulder.
272
+ """
273
+ across = rotation @ (1.0, 0.0, 0.0) # towards the subject's left
274
+ down = rotation @ (0.0, 1.0, 0.0) # from forehead to chin
275
+ angles = {
276
+ "yaw": math.degrees(math.atan2(across[2], across[0])),
277
+ "pitch": math.degrees(math.atan2(down[2], down[1])),
278
+ "roll": math.degrees(math.atan2(across[1], across[0])),
279
+ }
280
+ return { # "+ 0.0" turns -0.0 into 0.0
281
+ "yaw_deg": round(angles["yaw"], 1) + 0.0,
282
+ "pitch_deg": round(angles["pitch"], 1) + 0.0,
283
+ "roll_deg": round(angles["roll"], 1) + 0.0,
284
+ "frontal": all(abs(angles[k]) <= FRONTAL_LIMITS_DEG[k] for k in angles),
285
+ }
286
+
287
+
288
+ def _to_3d(pixels, rotation, ipd_mm, focal_px, width, height):
289
+ """Place the 68 landmarks in millimetres. Returns (points, mm per px, distance).
290
+
291
+ The pupil distance sets the scale. With a known focal length each point
292
+ is also pushed back to the depth the generic face gives it, which undoes
293
+ the perspective that makes the far-back cheeks look narrow.
294
+ """
295
+ on_image = extend(pixels)
296
+ ipd_px = float(np.linalg.norm(on_image[PUPIL_L] - on_image[PUPIL_R]))
297
+ eye_axis = rotation @ (_MODEL[PUPIL_L] - _MODEL[PUPIL_R])
298
+ facing = math.hypot(eye_axis[0], eye_axis[1]) / float(np.linalg.norm(eye_axis)) # < 1 when turned
299
+ if not focal_px:
300
+ mm_per_px = ipd_mm * facing / ipd_px
301
+ return pixels * mm_per_px, mm_per_px, None
302
+
303
+ distance = focal_px * ipd_mm * facing / ipd_px # camera to eyes, in mm
304
+ depth = (_MODEL @ rotation.T)[:, 2] * (ipd_mm / _MODEL_IPD_MM)
305
+ depth = distance + depth - (depth[PUPIL_R] + depth[PUPIL_L]) / 2
306
+ depth = depth[:LANDMARK_COUNT]
307
+ x = (pixels[:, 0] - width / 2) * depth / focal_px
308
+ y = (pixels[:, 1] - height / 2) * depth / focal_px
309
+ return np.column_stack([x, y, depth]), distance / focal_px, distance
310
+
311
+
312
+ def _lengths(points):
313
+ return {
314
+ name: float(np.mean([np.linalg.norm(points[a] - points[b]) for a, b in pairs]))
315
+ for name, pairs in SEGMENTS.items()
316
+ }
317
+
318
+
319
+ def _rounded(values, digits):
320
+ return {k: round(v, digits) for k, v in values.items()}
321
+
322
+
323
+ def _angle(vertex, a, b):
324
+ u, v = a - vertex, b - vertex
325
+ cosine = float(np.dot(u, v) / (np.linalg.norm(u) * np.linalg.norm(v) or 1.0))
326
+ return math.degrees(math.acos(max(-1.0, min(1.0, cosine))))
327
+
328
+
329
+ def _jaw_angle(p):
330
+ """Angle at the jaw corner between the cheekbone and the chin, both sides averaged.
331
+ Smaller means a more angular jaw."""
332
+ right = _angle(p[JAW_R], p[CHEEK_R], p[CHIN])
333
+ left = _angle(p[JAW_L], p[CHEEK_L], p[CHIN])
334
+ return (right + left) / 2
facecheck/camera.py ADDED
@@ -0,0 +1,153 @@
1
+ """Camera frames, the preview window, and drawing on it."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import sys
6
+ import time
7
+
8
+ import cv2
9
+ import numpy as np
10
+
11
+ from .analysis import SEGMENTS, extend
12
+
13
+ WINDOW = "facecheck"
14
+ MAX_BAD_READS = 30 # consecutive failed camera reads before giving up
15
+
16
+ # Colours are BGR.
17
+ WHITE, GREEN, AMBER, RED, GREY = (255, 255, 255), (120, 220, 120), (60, 190, 255), (90, 90, 240), (200, 200, 200)
18
+ OUTLINES = [list(range(0, 17)), list(range(17, 22)), list(range(22, 27))] # jaw, brows
19
+ GUIDES = {
20
+ "face_length": (255, 200, 80),
21
+ "face_width": (120, 220, 120),
22
+ "forehead_width": (240, 150, 240),
23
+ "jaw_width": (60, 190, 255),
24
+ }
25
+
26
+
27
+ def open_camera(index):
28
+ # DirectShow opens much faster than the default backend on Windows.
29
+ backends = [cv2.CAP_DSHOW, cv2.CAP_ANY] if sys.platform == "win32" else [cv2.CAP_ANY]
30
+ for backend in backends:
31
+ capture = cv2.VideoCapture(index, backend)
32
+ if capture.isOpened():
33
+ capture.set(cv2.CAP_PROP_FRAME_WIDTH, 1280)
34
+ capture.set(cv2.CAP_PROP_FRAME_HEIGHT, 720)
35
+ capture.set(cv2.CAP_PROP_BUFFERSIZE, 1) # show the newest frame, not a queued one
36
+ return capture
37
+ capture.release()
38
+ raise RuntimeError(
39
+ f"could not open camera {index}. Check that it is connected, not in use by "
40
+ "another app, and that this terminal is allowed to use the camera."
41
+ )
42
+
43
+
44
+ class Camera:
45
+ """Frames from the camera, plus an optional mirrored preview window.
46
+
47
+ Use as a context manager. frames() stops after `timeout` seconds and sets
48
+ timed_out; show() returns False once the user presses Q or ESC or closes
49
+ the window.
50
+ """
51
+
52
+ def __init__(self, index=0, window=True, mirror=True, timeout=60.0):
53
+ self.index, self.window, self.mirror, self.timeout = index, window, mirror, timeout
54
+ self.timed_out = False
55
+ self._capture = None
56
+ self._was_visible = False
57
+
58
+ def __enter__(self):
59
+ self._capture = open_camera(self.index)
60
+ return self
61
+
62
+ def __exit__(self, *exc_info):
63
+ self._capture.release()
64
+ if self.window:
65
+ cv2.destroyAllWindows()
66
+
67
+ def frames(self):
68
+ started, bad_reads = time.monotonic(), 0
69
+ while time.monotonic() - started <= self.timeout:
70
+ ok, frame = self._capture.read()
71
+ if not ok:
72
+ bad_reads += 1
73
+ if bad_reads > MAX_BAD_READS:
74
+ raise RuntimeError("the camera stopped delivering frames")
75
+ continue
76
+ bad_reads = 0
77
+ yield frame
78
+ self.timed_out = True
79
+
80
+ def show(self, frame, lines, face=None, colour=WHITE, footer="Q quit"):
81
+ """Show one preview frame. Returns False when the user wants to stop."""
82
+ if not self.window:
83
+ return True
84
+ cv2.imshow(WINDOW, draw_face(frame, face, colour, lines, footer, self.mirror))
85
+ key = chr(cv2.waitKey(1) & 0xFF).lower()
86
+ if key in ("q", "\x1b"): # \x1b is ESC
87
+ return False
88
+ visible = window_visible()
89
+ if visible >= 1:
90
+ self._was_visible = True
91
+ elif visible == 0 and self._was_visible: # closed with the window's own button
92
+ return False
93
+ return True
94
+
95
+ def hold(self, frame, lines, face=None, colour=WHITE, seconds=2.5):
96
+ """Keep a final frame on screen for a moment, or until a key is pressed."""
97
+ if self.window:
98
+ cv2.imshow(WINDOW, draw_face(frame, face, colour, lines, "Press any key", self.mirror))
99
+ cv2.waitKey(int(seconds * 1000))
100
+
101
+
102
+ def draw_face(frame, face, colour, lines, footer="", mirror=True):
103
+ """Draw the face box and its five key points, then the text on top."""
104
+ height, width = frame.shape[:2]
105
+ if face is not None:
106
+ values = np.clip(np.asarray(face[:14], dtype=np.float64), -10 * width, 10 * width)
107
+ x, y, w, h = (int(round(v)) for v in values[:4])
108
+ cv2.rectangle(frame, (x, y), (x + w, y + h), colour, 2, cv2.LINE_AA)
109
+ for px, py in values[4:14].reshape(5, 2).astype(np.int32).tolist():
110
+ cv2.circle(frame, (px, py), 3, colour, -1)
111
+ return _finish(frame, lines, footer, mirror)
112
+
113
+
114
+ def draw_overlay(frame, landmarks, lines, footer="", mirror=True):
115
+ """Draw the 68 landmarks and the measurement guide lines, then the text."""
116
+ height, width = frame.shape[:2]
117
+ if landmarks is not None:
118
+ # Clip so landmarks far off-screen cannot overflow the int32 drawing coordinates.
119
+ pixels = np.clip(extend(landmarks) * (width, height), -10 * width, 10 * width)
120
+ points = pixels.astype(np.int32)
121
+ for x, y in points[:68].tolist():
122
+ cv2.circle(frame, (x, y), 2, GREY, -1)
123
+ cv2.polylines(frame, [points[line] for line in OUTLINES], False, WHITE, 1, cv2.LINE_AA)
124
+ for name, colour in GUIDES.items():
125
+ a, b = SEGMENTS[name][0]
126
+ cv2.line(frame, tuple(points[a].tolist()), tuple(points[b].tolist()), colour, 2, cv2.LINE_AA)
127
+ return _finish(frame, lines, footer, mirror)
128
+
129
+
130
+ def _finish(frame, lines, footer, mirror):
131
+ view = cv2.flip(frame, 1) if mirror else frame # mirror first so the text stays readable
132
+ for row, (text, colour) in enumerate(lines):
133
+ put_text(view, text, (14, 32 + 30 * row), colour, 0.7)
134
+ if footer:
135
+ put_text(view, footer, (14, view.shape[0] - 16), GREY, 0.5)
136
+ return view
137
+
138
+
139
+ def put_text(image, text, origin, colour, size):
140
+ """Text on a dark label, so it stays readable over any background."""
141
+ font = cv2.FONT_HERSHEY_SIMPLEX
142
+ (text_width, text_height), baseline = cv2.getTextSize(text, font, size, 1)
143
+ x, y = origin
144
+ cv2.rectangle(image, (x - 8, y - text_height - 8), (x + text_width + 8, y + baseline + 6), (0, 0, 0), -1)
145
+ cv2.putText(image, text, origin, font, size, colour, 1, cv2.LINE_AA)
146
+
147
+
148
+ def window_visible():
149
+ """1 if the preview is on screen, 0 if it was closed, -1 if OpenCV cannot tell."""
150
+ try:
151
+ return cv2.getWindowProperty(WINDOW, cv2.WND_PROP_VISIBLE)
152
+ except cv2.error:
153
+ return -1