Download src/face_verification/conditions.py from Jadebks/face-verification-prototype: direct link, hf CLI and curl.
- Browser
- Download file 19.6 kB
-
https://huggingface.co/Jadebks/face-verification-prototype/resolve/main/src/face_verification/conditions.py
- Command line
-
hf download hf://Jadebks/face-verification-prototype/src/face_verification/conditions.py
-
curl -L -o conditions.py https://huggingface.co/Jadebks/face-verification-prototype/resolve/main/src/face_verification/conditions.py
19.6 kB
| """Role 2 — preprocessing and test conditions. | |
| Two public functions, shared by every model (see docs/TEAM_PLAN.md): | |
| preprocess(img) -> 160x160x3 uint8 face crop | |
| apply_condition(img, name, level) -> same crop with lighting / occlusion | |
| Pipeline for every photo, every model, both datasets: | |
| photo -> preprocess() -> [apply_condition() at test time only] -> model | |
| preprocess() | |
| * Face detector: MTCNN (Zhang et al. 2016) from `facenet-pytorch` (MIT | |
| licence, https://github.com/timesler/facenet-pytorch). The FaceNet | |
| reference model expects exactly these crops (160x160, MTCNN). | |
| * If several faces are found, keep the one closest to the image centre: | |
| LFW photos are centred on the labelled person by construction (Huang et | |
| al., 2007, LFW technical report 07-49), and CALFW reuses LFW identities. | |
| * Margin of 20 px in the final 160 px image, following the facenet-pytorch | |
| convention, so the face box fills the central 140x140 px. | |
| * If no face is found, fall back to a fixed centre crop (counted and | |
| reported by `preprocess_dataset`). | |
| * Output is uint8 RGB in 0-255. Each model applies its own normalisation. | |
| apply_condition() | |
| * Applied to the 160x160 crop, so "% of face area" is well defined. | |
| * `level` is a severity index 0-5. Level 0 always returns the image | |
| unchanged. The physical value of each level is in LEVELS and is set from | |
| the natural ranges measured in Stage 1 (results/figures/fig3). | |
| * Deterministic: the random patch position depends only on SEED and the | |
| image content, so the same image always gets the same patch. | |
| Run on the full datasets (crops are cached under data/processed/, never | |
| committed): | |
| python -m face_verification.conditions --dataset all | |
| """ | |
| from __future__ import annotations | |
| import argparse | |
| import json | |
| import time | |
| import zlib | |
| from pathlib import Path | |
| import numpy as np | |
| import pandas as pd | |
| from PIL import Image | |
| from .lfw_io import ROOT | |
| SEED = 42 | |
| IMAGE_SIZE = 160 # FaceNet input size | |
| MARGIN = 20 # px of border in the final image (facenet-pytorch convention) | |
| FACE_LO = MARGIN // 2 # the detected face box spans pixels [10, 150) of the crop | |
| FACE_HI = IMAGE_SIZE - MARGIN // 2 | |
| FACE_SIZE = FACE_HI - FACE_LO | |
| # Fallback when no face is detected. LFW faces fill roughly the central | |
| # 250 / 2.2 = 114 px of a 250 px photo (LFW tech report). Adding the same | |
| # relative margin (140 -> 160) gives ~130 px, i.e. 52% of the shorter side. | |
| FALLBACK_FRACTION = 0.52 | |
| # Average landmark positions in the 160 px crop, used for occlusion when a | |
| # photo has no landmarks (fallback crops). Order: left eye, right eye, nose, | |
| # left mouth corner, right mouth corner, as (x, y). | |
| # Mean MTCNN landmarks over all 13,233 LFW crops (full run, 6 Nov 2026; | |
| # results/reports/preprocess_summary.json). CALFW means are within 1.5 px. | |
| DEFAULT_LANDMARKS = np.array( | |
| [[51.5, 65.1], [113.8, 64.2], [82.9, 92.3], [56.0, 116.6], [111.0, 115.9]], | |
| dtype=np.float32, | |
| ) | |
| PROCESSED = ROOT / "data" / "processed" | |
| RAW = ROOT / "data" / "raw" | |
| REPORTS = ROOT / "results" / "reports" | |
| # --------------------------------------------------------------------------- | |
| # Severity levels (APPROVED in review of PR #14 by Noor and Jade, 7 Nov 2026; | |
| # gamma dropped and occlusion_lower capped at 50% on Jade's request). Index = level 0..5. | |
| # Natural range of the face box in LFW crops (300 View 1 training photos, | |
| # results/reports/level_calibration.json): brightness p5-p95 = 89-164 | |
| # (median 127), contrast (pixel std) p5-p95 = 28-59 (median 42). | |
| # Level 1 is mild (at or just inside the natural range); level 2+ goes beyond it. | |
| # --------------------------------------------------------------------------- | |
| LEVELS: dict[str, list[float]] = { | |
| # multiply pixel values; median face 127 -> 89 (= natural p5), 63, 44, 32, 19 | |
| "brightness_low": [1.0, 0.70, 0.50, 0.35, 0.25, 0.15], | |
| # multiply pixel values; median face 127 -> 151, 173 (> natural p95), 192, 206, 216 (clipping grows) | |
| "brightness_high": [1.0, 1.20, 1.40, 1.60, 1.80, 2.00], | |
| # scale distance from the mean; median std 42 -> 31 (near natural p5), 21, 15, 10, 6 | |
| "contrast_low": [1.0, 0.75, 0.50, 0.35, 0.25, 0.15], | |
| # % of the face box covered (black), band centred on the eyes | |
| "occlusion_eyes": [0, 10, 15, 20, 25, 30], | |
| # % of the face box covered (black), band rising from the chin; 50% = chin to | |
| # nose (surgical mask) and stays below the eye line (y ~ 65 of 160) | |
| "occlusion_lower": [0, 10, 20, 30, 40, 50], | |
| # % of the face box covered by one black square at a random position | |
| "occlusion_patch": [0, 5, 10, 15, 20, 25], | |
| } | |
| CONDITIONS = tuple(LEVELS) | |
| LIGHTING = ("brightness_low", "brightness_high", "contrast_low") | |
| OCCLUSION = ("occlusion_eyes", "occlusion_lower", "occlusion_patch") | |
| MAX_LEVEL = 5 | |
| def describe(name: str, level: int) -> str: | |
| """Human-readable label for plots and the app, e.g. 'brightness ×0.50'.""" | |
| v = LEVELS[name][level] | |
| if name in OCCLUSION: | |
| return f"{v:g}% of face" | |
| return f"×{v:.2f}" | |
| # =========================================================================== | |
| # Preprocessing | |
| # =========================================================================== | |
| _DETECTOR = None | |
| def _detector(): | |
| """Load MTCNN once (lazy, so importing this module is cheap).""" | |
| global _DETECTOR | |
| if _DETECTOR is None: | |
| import torch | |
| from facenet_pytorch import MTCNN | |
| device = "cuda" if torch.cuda.is_available() else "cpu" | |
| _DETECTOR = MTCNN(keep_all=True, device=device) | |
| return _DETECTOR | |
| def to_rgb(img: np.ndarray) -> np.ndarray: | |
| """Return an HxWx3 uint8 RGB copy of a grayscale, RGB or RGBA image.""" | |
| img = np.asarray(img) | |
| if img.dtype != np.uint8: | |
| raise TypeError(f"expected a uint8 image (0-255), got {img.dtype}") | |
| if img.ndim == 2: | |
| return np.repeat(img[..., None], 3, axis=2) | |
| if img.ndim == 3 and img.shape[2] == 1: | |
| return np.repeat(img, 3, axis=2) | |
| if img.ndim == 3 and img.shape[2] == 4: | |
| return img[..., :3].copy() | |
| if img.ndim == 3 and img.shape[2] == 3: | |
| return img.copy() | |
| raise ValueError(f"unsupported image shape {img.shape}") | |
| def pick_central(boxes: np.ndarray, width: int, height: int) -> int: | |
| """Index of the box whose centre is closest to the image centre.""" | |
| centres = (boxes[:, :2] + boxes[:, 2:4]) / 2 | |
| target = np.array([width / 2, height / 2]) | |
| return int(np.argmin(((centres - target) ** 2).sum(axis=1))) | |
| def _margin_box(box, width: int, height: int) -> tuple[int, int, int, int]: | |
| """Add MARGIN (in final-image pixels) around a detector box. | |
| Same arithmetic as facenet_pytorch.extract_face, so our crops match the | |
| ones the FaceNet reference model was evaluated with. | |
| """ | |
| x0, y0, x1, y1 = box | |
| mx = MARGIN * (x1 - x0) / (IMAGE_SIZE - MARGIN) | |
| my = MARGIN * (y1 - y0) / (IMAGE_SIZE - MARGIN) | |
| return ( | |
| int(max(x0 - mx / 2, 0)), | |
| int(max(y0 - my / 2, 0)), | |
| int(min(x1 + mx / 2, width)), | |
| int(min(y1 + my / 2, height)), | |
| ) | |
| def _fallback_box(width: int, height: int) -> tuple[int, int, int, int]: | |
| side = FALLBACK_FRACTION * min(width, height) | |
| x0, y0 = (width - side) / 2, (height - side) / 2 | |
| return int(x0), int(y0), int(x0 + side), int(y0 + side) | |
| def _crop(rgb: np.ndarray, box) -> np.ndarray: | |
| out = Image.fromarray(rgb).crop(box).resize((IMAGE_SIZE, IMAGE_SIZE), Image.BILINEAR) | |
| return np.asarray(out, dtype=np.uint8).copy() | |
| def _finish(rgb, boxes, probs, points) -> tuple[np.ndarray, dict]: | |
| """Turn one image's detector output into a crop plus metadata.""" | |
| h, w = rgb.shape[:2] | |
| if boxes is None or len(boxes) == 0: | |
| box = _fallback_box(w, h) | |
| info = dict(fallback=True, n_faces=0, prob=float("nan"), box=list(box), landmarks=None) | |
| return _crop(rgb, box), info | |
| i = pick_central(np.asarray(boxes), w, h) | |
| box = _margin_box(boxes[i], w, h) | |
| x0, y0, x1, y1 = box | |
| # Landmarks in crop coordinates (same scaling as the resize). | |
| lm = (np.asarray(points[i], dtype=np.float32) - [x0, y0]) * [ | |
| IMAGE_SIZE / (x1 - x0), | |
| IMAGE_SIZE / (y1 - y0), | |
| ] | |
| info = dict( | |
| fallback=False, | |
| n_faces=int(len(boxes)), | |
| prob=float(probs[i]), | |
| box=[int(v) for v in box], | |
| landmarks=lm.round(2).tolist(), | |
| ) | |
| return _crop(rgb, box), info | |
| def preprocess_with_info(img: np.ndarray) -> tuple[np.ndarray, dict]: | |
| """Like `preprocess`, but also return detection metadata. | |
| info keys: fallback (bool), n_faces, prob (detector confidence), | |
| box (crop box in the original photo), landmarks (5x2 list in crop | |
| coordinates, or None for fallback crops). | |
| """ | |
| rgb = to_rgb(img) | |
| boxes, probs, points = _detector().detect(Image.fromarray(rgb), landmarks=True) | |
| return _finish(rgb, boxes, probs, points) | |
| def preprocess(img: np.ndarray) -> np.ndarray: | |
| """Detect, crop and resize a face to the shared format. | |
| Input : HxW (grayscale), HxWx3 (RGB) or HxWx4 (RGBA) uint8 array. | |
| Output: 160x160x3 uint8 RGB array, face centred with a 20 px margin. | |
| """ | |
| return preprocess_with_info(img)[0] | |
| def load_image(path) -> np.ndarray: | |
| """Read a photo from disk as a uint8 RGB array.""" | |
| with Image.open(path) as im: | |
| return np.asarray(im.convert("RGB")) | |
| # =========================================================================== | |
| # Test conditions | |
| # =========================================================================== | |
| def _check(img: np.ndarray, name: str, level: int) -> None: | |
| if name not in LEVELS: | |
| raise ValueError(f"unknown condition {name!r}; choose from {CONDITIONS}") | |
| if isinstance(level, bool) or not isinstance(level, (int, np.integer)) or not 0 <= level <= MAX_LEVEL: | |
| raise ValueError(f"level must be an integer 0-{MAX_LEVEL}, got {level!r}") | |
| if img.dtype != np.uint8 or img.ndim != 3 or img.shape[2] != 3: | |
| raise ValueError("apply_condition expects an HxWx3 uint8 image (output of preprocess)") | |
| def _to_uint8(x: np.ndarray) -> np.ndarray: | |
| return np.clip(np.rint(x), 0, 255).astype(np.uint8) | |
| def _lighting(img: np.ndarray, name: str, value: float) -> np.ndarray: | |
| x = img.astype(np.float32) | |
| if name in ("brightness_low", "brightness_high"): | |
| return _to_uint8(x * value) | |
| if name == "contrast_low": | |
| m = x.mean() | |
| return _to_uint8((x - m) * value + m) | |
| raise AssertionError(name) | |
| def _face_box(img: np.ndarray) -> tuple[float, float, float, float]: | |
| """Face region of a crop: (x0, y0, x1, y1). Scales if the crop isn't 160 px.""" | |
| s = img.shape[0] / IMAGE_SIZE | |
| return FACE_LO * s, FACE_LO * s, FACE_HI * s, FACE_HI * s | |
| def _occlusion(img, name, pct, landmarks, seed) -> np.ndarray: | |
| out = img.copy() | |
| x0, y0, x1, y1 = _face_box(img) | |
| fw, fh = x1 - x0, y1 - y0 | |
| area = pct / 100.0 * fw * fh | |
| s = img.shape[0] / IMAGE_SIZE | |
| lm = (np.asarray(landmarks, np.float32) if landmarks is not None else DEFAULT_LANDMARKS * s) | |
| if name == "occlusion_eyes": | |
| # full-width band, height chosen to cover `pct` of the face box | |
| band = area / fw | |
| cy = lm[:2, 1].mean() | |
| top = int(round(np.clip(cy - band / 2, y0, y1 - band))) | |
| out[top:top + int(round(band)), int(x0):int(x1)] = 0 | |
| elif name == "occlusion_lower": | |
| band = area / fw | |
| out[int(round(y1 - band)):int(y1), int(x0):int(x1)] = 0 | |
| elif name == "occlusion_patch": | |
| side = np.sqrt(area) | |
| # Position depends on SEED and the image itself: deterministic, but | |
| # different photos get different positions. | |
| rng = np.random.default_rng([seed, zlib.crc32(img.tobytes())]) | |
| px = rng.uniform(x0, x1 - side) | |
| py = rng.uniform(y0, y1 - side) | |
| r = int(round(side)) | |
| out[int(round(py)):int(round(py)) + r, int(round(px)):int(round(px)) + r] = 0 | |
| else: | |
| raise AssertionError(name) | |
| return out | |
| def apply_condition(img: np.ndarray, name: str, level: int, | |
| landmarks=None, seed: int = SEED) -> np.ndarray: | |
| """Apply one test condition to a preprocessed crop and return a new image. | |
| name : one of CONDITIONS (see LEVELS for the physical values) | |
| level : severity 0-5; 0 returns an unchanged copy | |
| landmarks : optional 5x2 crop-coordinate landmarks from preprocess_with_info | |
| or get_landmarks(); used to place the eye band. Defaults to | |
| average positions. | |
| seed : random patch position seed (default SEED = 42) | |
| The input image is never modified. | |
| """ | |
| img = np.asarray(img) | |
| _check(img, name, level) | |
| value = LEVELS[name][level] | |
| if level == 0: | |
| return img.copy() | |
| if name in LIGHTING: | |
| return _lighting(img, name, value) | |
| return _occlusion(img, name, value, landmarks, seed) | |
| # =========================================================================== | |
| # Whole-dataset preprocessing with a disk cache | |
| # =========================================================================== | |
| def processed_path(raw_path) -> Path: | |
| """Where the cached crop of a raw photo is stored (PNG, lossless).""" | |
| rel = Path(raw_path).resolve().relative_to(RAW.resolve()) | |
| return (PROCESSED / rel).with_suffix(".png") | |
| def _index_path(dataset: str) -> Path: | |
| return PROCESSED / f"{dataset}_index.csv" | |
| _INDEX_CACHE: dict[str, pd.DataFrame] = {} | |
| def _index(dataset: str) -> pd.DataFrame: | |
| if dataset not in _INDEX_CACHE: | |
| _INDEX_CACHE[dataset] = pd.read_csv(_index_path(dataset)).set_index("raw_path") | |
| return _INDEX_CACHE[dataset] | |
| def load_face(raw_path) -> np.ndarray: | |
| """Preprocessed 160x160 crop for a raw photo path (as given by data.py). | |
| Uses the cache from `preprocess_dataset` when it exists, otherwise runs | |
| the detector on the fly. | |
| """ | |
| cached = processed_path(raw_path) | |
| if cached.exists(): | |
| return load_image(cached) | |
| return preprocess(load_image(raw_path)) | |
| def get_landmarks(raw_path, dataset: str | None = None): | |
| """5x2 crop-coordinate landmarks for a raw photo, or None (fallback crop).""" | |
| dataset = dataset or ("calfw" if "calfw" in str(raw_path) else "lfw") | |
| row = _index(dataset).loc[str(Path(raw_path).resolve())] | |
| if bool(row["fallback"]): | |
| return None | |
| return np.array(json.loads(row["landmarks"]), dtype=np.float32) | |
| def _paths_for(dataset: str) -> list[Path]: | |
| if dataset == "lfw": # every LFW photo: triplet training uses them all | |
| from .lfw_io import list_images | |
| return list(list_images()["path"]) | |
| if dataset == "calfw": # only photos that appear in the official pairs | |
| from .data import load_pairs | |
| pairs = load_pairs("calfw") | |
| return sorted(set(pairs["path1"]) | set(pairs["path2"])) | |
| raise ValueError("dataset must be 'lfw' or 'calfw'") | |
| def preprocess_dataset(dataset: str, batch_size: int = 32, overwrite: bool = False) -> dict: | |
| """Crop every photo of a dataset once, save PNGs + an index CSV, return a summary.""" | |
| paths = _paths_for(dataset) | |
| rows, t0 = [], time.time() | |
| todo = [p for p in paths if overwrite or not processed_path(p).exists()] | |
| print(f"[{dataset}] {len(paths)} photos, {len(todo)} to process") | |
| for start in range(0, len(todo), batch_size): | |
| batch = todo[start:start + batch_size] | |
| rgbs = [load_image(p) for p in batch] | |
| same_size = len({r.shape for r in rgbs}) == 1 | |
| if same_size: # MTCNN batches only images of equal size | |
| out = _detector().detect([Image.fromarray(r) for r in rgbs], landmarks=True) | |
| results = [(out[0][j], out[1][j], out[2][j]) for j in range(len(batch))] | |
| else: | |
| results = [_detector().detect(Image.fromarray(r), landmarks=True) for r in rgbs] | |
| for p, rgb, (b, pr, pt) in zip(batch, rgbs, results): | |
| crop, info = _finish(rgb, b, pr, pt) | |
| dst = processed_path(p) | |
| dst.parent.mkdir(parents=True, exist_ok=True) | |
| Image.fromarray(crop).save(dst) | |
| rows.append(dict(raw_path=str(Path(p).resolve()), crop_path=str(dst), | |
| fallback=info["fallback"], n_faces=info["n_faces"], | |
| prob=info["prob"], landmarks=json.dumps(info["landmarks"]))) | |
| n = min(start + batch_size, len(todo)) | |
| if n % (batch_size * 20) == 0 or n == len(todo): | |
| print(f" {n}/{len(todo)} ({time.time() - t0:.0f}s)") | |
| new = pd.DataFrame(rows) | |
| old = (pd.read_csv(_index_path(dataset)) | |
| if not overwrite and _index_path(dataset).exists() else pd.DataFrame()) | |
| index = pd.concat([old, new], ignore_index=True).drop_duplicates("raw_path", keep="last") | |
| wanted = {str(Path(p).resolve()) for p in paths} | |
| index = index[index["raw_path"].isin(wanted)].reset_index(drop=True) | |
| PROCESSED.mkdir(parents=True, exist_ok=True) | |
| index.to_csv(_index_path(dataset), index=False) | |
| _INDEX_CACHE.pop(dataset, None) | |
| return summarise(dataset, index, seconds=time.time() - t0) | |
| def summarise(dataset: str, index: pd.DataFrame, seconds: float | None = None) -> dict: | |
| """Numbers for the report: fallback rate, multi-face photos, landmarks, lighting.""" | |
| det = index[~index["fallback"].astype(bool)] | |
| lms = np.array([json.loads(s) for s in det["landmarks"]], dtype=np.float32) | |
| # Natural brightness / contrast of the face box in the crops (sample of 2,000) | |
| sample = index.sample(min(2000, len(index)), random_state=SEED) | |
| lum, con = [], [] | |
| for p in sample["crop_path"]: | |
| g = np.asarray(Image.open(p).convert("L"), np.float32)[FACE_LO:FACE_HI, FACE_LO:FACE_HI] | |
| lum.append(g.mean()); con.append(g.std()) | |
| pct = lambda v: {f"p{q}": round(float(np.percentile(v, q)), 3) for q in (1, 5, 50, 95, 99)} | |
| return { | |
| "dataset": dataset, | |
| "photos": int(len(index)), | |
| "fallback_crops": int(index["fallback"].astype(bool).sum()), | |
| "fallback_rate": round(float(index["fallback"].astype(bool).mean()), 4), | |
| "photos_with_several_faces": int((index["n_faces"] > 1).sum()), | |
| "detector_confidence": pct(det["prob"]) if len(det) else None, | |
| "mean_landmarks": np.round(lms.mean(axis=0).astype(float), 1).tolist() if len(lms) else None, | |
| "crop_face_brightness": pct(lum), | |
| "crop_face_contrast": pct(con), | |
| "seconds": None if seconds is None else round(seconds, 1), | |
| } | |
| def main(argv=None) -> None: | |
| ap = argparse.ArgumentParser(description="Preprocess LFW / CALFW photos once and cache the crops.") | |
| ap.add_argument("--dataset", choices=["lfw", "calfw", "all"], default="all") | |
| ap.add_argument("--batch-size", type=int, default=32) | |
| ap.add_argument("--overwrite", action="store_true") | |
| args = ap.parse_args(argv) | |
| datasets = ["lfw", "calfw"] if args.dataset == "all" else [args.dataset] | |
| REPORTS.mkdir(parents=True, exist_ok=True) | |
| out = REPORTS / "preprocess_summary.json" | |
| summary = json.loads(out.read_text()) if out.exists() else {} | |
| for d in datasets: | |
| summary[d] = preprocess_dataset(d, args.batch_size, args.overwrite) | |
| print(json.dumps(summary[d], indent=2)) | |
| summary["settings"] = dict(image_size=IMAGE_SIZE, margin=MARGIN, detector="MTCNN (facenet-pytorch)", | |
| face_choice="closest to image centre", | |
| fallback=f"centre crop, {FALLBACK_FRACTION:.0%} of shorter side") | |
| out.write_text(json.dumps(summary, indent=2)) | |
| print(f"wrote {out}") | |
| if __name__ == "__main__": | |
| main() | |