"""Age & Gender Estimator: our FaceDetector + an EfficientNet-B2 with an age head and a gender head. Single source of truth for the architecture, preprocessing, inference and Grad-CAM. It is used by the Hugging Face Space (`space/app.py`), the Inference Endpoint (`handler.py`), the training code (`training/src/`) and anyone who downloads this repo from the Hub: import model predictor = model.load("path/to/this/repo", device="cpu") predictor.predict("face.jpg") # {"faces": [{"box": [x1, y1, x2, y2], "age": 31.4, "age_range": "26-37", # "age_top": {"30": 0.08, ...}, "gender": {"male": 0.97, "female": 0.03}, # "confidence": 0.999, "detected": True}], "n_faces": 1} Pipeline: image -> FaceDetector (`face_detector.safetensors`, trained in the face-recognition project) finds every face -> each box is padded by `crop_padding` px and cropped -> EfficientNet-B2 trunk -> age head (softmax over 90 age bins; headline age = sum(p_i * representative_age_i)) + gender head (softmax over male/female). If no face is found, the whole image is classified (`detected: false`, `n_faces: 0`). """ from __future__ import annotations import base64 import io from pathlib import Path import numpy as np import torch import torch.nn.functional as F import torchvision from huggingface_hub import PyTorchModelHubMixin from PIL import Image, ImageDraw, ImageFont from safetensors.torch import load_file from torch import nn from torchvision.models import EfficientNet_B2_Weights, efficientnet_b2 REPO_ID = "shalev396/age-estimator" FRAMEWORK = "pytorch" WEIGHTS_FILE = "model.safetensors" # --------------------------------------------------------------------------- face detector # FaceDetector: our own single-shot face + 5-landmark detector, trained in the face-recognition # project (github.com/shalev396/ml-lab/tree/main/face-recognition) and reused here as-is. Ideas from # MTCNN (Zhang et al. 2016): three tasks per candidate (face / box / landmarks), PReLU, online # hard-negative mining. Unlike MTCNN: one fully-convolutional network with a feature pyramid # (strides 8/16/32) and anchors instead of an image pyramid + three cascaded networks. DETECTOR_WEIGHTS = "face_detector.safetensors" DETECTOR_WIDTH = 32 DETECT_THRESHOLD = 0.5 # default face score above which a detection counts (config: min_face_confidence) ANCHOR_LEVELS = ((8, (16, 24, 32)), (16, (48, 64, 96)), (32, (128, 192, 256, 384))) # stride, anchor sides BOX_VAR = (0.1, 0.2) def _conv_bn(cin, cout, k=3, s=1, groups=1): return nn.Sequential(nn.Conv2d(cin, cout, k, s, k // 2, groups=groups, bias=False), nn.BatchNorm2d(cout), nn.PReLU(cout)) class _Block(nn.Module): """Residual block: (3x3 depthwise + 1x1 pointwise) twice; the stride is on the first depthwise.""" def __init__(self, cin, cout, stride): super().__init__() self.body = nn.Sequential(_conv_bn(cin, cin, 3, stride, groups=cin), _conv_bn(cin, cout, 1), _conv_bn(cout, cout, 3, 1, groups=cout), _conv_bn(cout, cout, 1)) self.skip = None if stride == 1 and cin == cout else nn.Sequential( nn.AvgPool2d(stride) if stride > 1 else nn.Identity(), nn.Conv2d(cin, cout, 1, bias=False), nn.BatchNorm2d(cout)) def forward(self, x): return self.body(x) + (x if self.skip is None else self.skip(x)) class FaceDetector(nn.Module): """(N, 3, H, W) RGB 0..1 (H, W multiples of 32) -> per anchor: face logit, box deltas (4) and landmark offsets (10). `detect()` turns them into faces for one PIL image.""" def __init__(self, width: int = DETECTOR_WIDTH): super().__init__() w = width self.stem = nn.Sequential(_conv_bn(3, w, 3, 2), _conv_bn(w, w, 3, 1, groups=w), _conv_bn(w, w, 1)) # /2 self.s1 = nn.Sequential(_Block(w, 2 * w, 2), _Block(2 * w, 2 * w, 1)) # /4 self.s2 = nn.Sequential(_Block(2 * w, 4 * w, 2), _Block(4 * w, 4 * w, 1), _Block(4 * w, 4 * w, 1)) # /8 self.s3 = nn.Sequential(_Block(4 * w, 8 * w, 2), _Block(8 * w, 8 * w, 1), _Block(8 * w, 8 * w, 1)) # /16 self.s4 = nn.Sequential(_Block(8 * w, 16 * w, 2), _Block(16 * w, 16 * w, 1)) # /32 f = 4 * w self.lat = nn.ModuleList([nn.Conv2d(c, f, 1) for c in (4 * w, 8 * w, 16 * w)]) self.smooth = nn.ModuleList([_conv_bn(f, f) for _ in range(3)]) self.context = nn.ModuleList([nn.Sequential(_conv_bn(f, f), _conv_bn(f, f, 3, 1, groups=f), _conv_bn(f, f, 1)) for _ in range(3)]) self.n_anchor = [len(sizes) for _, sizes in ANCHOR_LEVELS] self.cls = nn.ModuleList([nn.Conv2d(f, a, 1) for a in self.n_anchor]) self.box = nn.ModuleList([nn.Conv2d(f, a * 4, 1) for a in self.n_anchor]) self.ldm = nn.ModuleList([nn.Conv2d(f, a * 10, 1) for a in self.n_anchor]) for c in self.cls: nn.init.constant_(c.bias, -4.595) # log(0.01 / 0.99): start at p(face) = 0.01 def forward(self, x): x = (x - 0.5) / 0.5 c2 = self.s2(self.s1(self.stem(x))) c3 = self.s3(c2) c4 = self.s4(c3) p5 = self.lat[2](c4) p4 = self.lat[1](c3) + F.interpolate(p5, size=c3.shape[-2:], mode="nearest") p3 = self.lat[0](c2) + F.interpolate(p4, size=c2.shape[-2:], mode="nearest") outs = [] for i, p in enumerate((p3, p4, p5)): p = self.smooth[i](p) p = p + self.context[i](p) n, _, h, w = p.shape a = self.n_anchor[i] outs.append((self.cls[i](p).permute(0, 2, 3, 1).reshape(n, h * w * a), self.box[i](p).permute(0, 2, 3, 1).reshape(n, h * w * a, 4), self.ldm[i](p).permute(0, 2, 3, 1).reshape(n, h * w * a, 10))) return tuple(torch.cat([o[k] for o in outs], 1) for k in range(3)) @torch.inference_mode() def detect(self, images: list[Image.Image], score: float = DETECT_THRESHOLD, nms_iou: float = 0.4, max_side: int = 1024, min_side: int = 320) -> list[tuple[np.ndarray, np.ndarray, np.ndarray]]: """Same-size PIL images -> per image (boxes (K, 4), scores (K,), landmarks (K, 5, 2)) in image pixels, best first. The longer side is scaled into [min_side, max_side] first.""" w0, h0 = images[0].size s = min(max_side / max(w0, h0), 1.0) if max(w0, h0) < min_side: # small photos are upscaled (faces this small are hard to see) s = min_side / max(w0, h0) w, h = max(32, round(w0 * s / 32) * 32), max(32, round(h0 * s / 32) * 32) dev = next(self.parameters()).device x = torch.from_numpy(np.stack([np.asarray(im.resize((w, h), Image.BILINEAR), dtype=np.float32) for im in images])) logits, d_box, d_ldm = self(x.permute(0, 3, 1, 2).div(255).to(dev)) anc = anchors(h, w, dev) sx, sy = w0 / w, h0 / h out = [] for i in range(len(images)): p = logits[i].float().sigmoid() keep = p > score boxes, ldm = decode_detections(d_box[i][keep].float(), d_ldm[i][keep].float(), anc[keep]) p = p[keep] k = torchvision.ops.nms(boxes, p, nms_iou) boxes = (boxes[k] * torch.tensor([sx, sy, sx, sy], device=dev)).cpu().numpy() ldm = (ldm[k].view(-1, 5, 2) * torch.tensor([sx, sy], device=dev)).cpu().numpy() out.append((boxes, p[k].cpu().numpy(), ldm)) return out _ANCHORS: dict = {} def anchors(h: int, w: int, device) -> torch.Tensor: """(A, 4) anchors (cx, cy, side, side) for an h x w input, in the order of FaceDetector's outputs.""" key = (h, w, str(device)) if key not in _ANCHORS: out = [] for stride, sizes in ANCHOR_LEVELS: fh, fw = -(-h // stride), -(-w // stride) ys, xs = torch.meshgrid(torch.arange(fh), torch.arange(fw), indexing="ij") cx = (xs.reshape(-1, 1).float() + 0.5) * stride cy = (ys.reshape(-1, 1).float() + 0.5) * stride side = torch.tensor(sizes, dtype=torch.float32).view(1, -1) out.append(torch.stack([cx.expand(-1, len(sizes)), cy.expand(-1, len(sizes)), side.expand(fh * fw, -1), side.expand(fh * fw, -1)], -1).reshape(-1, 4)) _ANCHORS[key] = torch.cat(out).to(device) return _ANCHORS[key] def decode_detections(d_box, d_ldm, anc): """Network deltas + anchors -> boxes (K, 4) x1 y1 x2 y2 and landmarks (K, 10).""" cx = anc[:, 0] + d_box[:, 0] * BOX_VAR[0] * anc[:, 2] cy = anc[:, 1] + d_box[:, 1] * BOX_VAR[0] * anc[:, 3] w = anc[:, 2] * torch.exp((d_box[:, 2] * BOX_VAR[1]).clamp(max=6)) h = anc[:, 3] * torch.exp((d_box[:, 3] * BOX_VAR[1]).clamp(max=6)) boxes = torch.stack([cx - w / 2, cy - h / 2, cx + w / 2, cy + h / 2], 1) ldm = anc[:, None, :2] + d_ldm.view(-1, 5, 2) * BOX_VAR[0] * anc[:, None, 2:] return boxes, ldm.reshape(-1, 10) # ImageNet weights the trunk is initialised from for training; their preset also defines the # preprocessing (resize 288 bicubic -> center-crop 288 -> ImageNet mean/std). BACKBONE_WEIGHTS = EfficientNet_B2_Weights.IMAGENET1K_V1 FEATURE_DIM = 1408 # EfficientNet-B2 channels after global average pooling # Age is classified into CONTIGUOUS BINS: one per year for 2..89, plus "0-1" and "90+" at the # sparse tails of UTKFace (no age-0 images, < 10 images for most ages >= 90). DEFAULT_AGE_BIN_EDGES: list[list[int]] = [[0, 1]] + [[a, a] for a in range(2, 90)] + [[90, 116]] DEFAULT_GENDER_LABELS: list[str] = ["male", "female"] # Grad-CAM rendering: opacity = value**CAM_GAMMA * CAM_MAX_ALPHA, so weak evidence fades out. CAM_MAX_ALPHA = 0.85 CAM_GAMMA = 1.5 # Feature blocks the CAM is fused from: the last stride-16 block (18x18 map at 288 px) and the final # stride-32 block (9x9). Geometric mean keeps only regions both scales call evidence. CAM_LAYERS = (5, -1) BOX_COLOR = (52, 168, 83) def cuda_available() -> bool: return torch.cuda.is_available() def get_transform(): """PIL image -> normalized (3, 288, 288) tensor, exactly as EfficientNet-B2 was pretrained.""" return BACKBONE_WEIGHTS.transforms() def bin_label(lo: int, hi: int, is_last: bool = False) -> str: """'5' for a single year, '0-1' for a closed range, '90+' for the open top bin.""" if is_last and hi > lo: return f"{lo}+" return str(lo) if lo == hi else f"{lo}-{hi}" def age_labels_for(edges: list[list[int]]) -> list[str]: return [bin_label(lo, hi, i == len(edges) - 1) for i, (lo, hi) in enumerate(edges)] def age_to_bin(age: int, edges: list[list[int]] = DEFAULT_AGE_BIN_EDGES) -> int: """Raw integer age -> bin index (clamped to the first/last bin).""" for i, (lo, hi) in enumerate(edges): if lo <= age <= hi: return i return 0 if age < edges[0][0] else len(edges) - 1 def default_representatives(edges: list[list[int]]) -> list[float]: """Bin midpoints (open top bin capped at 100). Training replaces them with data-driven means.""" return [(lo + min(hi, 100)) / 2.0 for lo, hi in edges] class AgeGenderNet( nn.Module, PyTorchModelHubMixin, tags=["ml-lab", "pytorch", "age-estimation", "gender-classification", "face"], repo_url="https://github.com/shalev396/ml-lab", pipeline_tag="image-classification", license="mit", ): """torchvision EfficientNet-B2 trunk (features + global average pool) shared by two heads: `age_head = Dropout -> Linear(1408, n_age_bins)` and `gender_head = Dropout -> Linear(1408, 2)`. Every __init__ argument is written to config.json by the mixin, so the file holds the age bins, their labels and representative ages, the gender labels and the detection settings. Args: age_bin_edges: [[lo, hi], ...] inclusive age range of each bin, in logit order. age_representatives: age that stands for each bin in the expected-age sum (training uses the mean true age of the training faces in that bin). gender_labels: gender head labels in logit order. dropout: dropout in front of both linear heads. image_size: input resolution (fixed by the EfficientNet-B2 preset). crop_padding: pixels of context added around each detected face before classifying it. min_face_confidence: detections scoring below this are ignored. age_labels: display label of each bin (derived from the edges when omitted). pretrained: initialise the trunk from ImageNet. Only for training; `load()` passes False. """ def __init__(self, age_bin_edges: list[list[int]] | None = None, age_representatives: list[float] | None = None, gender_labels: list[str] | None = None, dropout: float = 0.3, image_size: int = 288, crop_padding: int = 20, min_face_confidence: float = 0.9, age_labels: list[str] | None = None, pretrained: bool = False): super().__init__() self.age_bin_edges = [list(map(int, e)) for e in (age_bin_edges or DEFAULT_AGE_BIN_EDGES)] self.age_labels = list(age_labels or age_labels_for(self.age_bin_edges)) self.age_representatives = [float(r) for r in (age_representatives or default_representatives(self.age_bin_edges))] self.gender_labels = list(gender_labels or DEFAULT_GENDER_LABELS) if not (len(self.age_labels) == len(self.age_representatives) == len(self.age_bin_edges)): raise ValueError("age_bin_edges, age_labels and age_representatives must have the same length") self.image_size = image_size self.crop_padding = crop_padding self.min_face_confidence = min_face_confidence backbone = efficientnet_b2(weights=BACKBONE_WEIGHTS if pretrained else None) self.features = backbone.features self.avgpool = backbone.avgpool # inplace=False: both heads read the same pooled tensor. self.age_head = nn.Sequential(nn.Dropout(p=dropout), nn.Linear(FEATURE_DIM, len(self.age_labels))) self.gender_head = nn.Sequential(nn.Dropout(p=dropout), nn.Linear(FEATURE_DIM, len(self.gender_labels))) def forward(self, x: torch.Tensor) -> dict[str, torch.Tensor]: """(N, 3, H, W) normalized images -> {"age": (N, n_bins) logits, "gender": (N, 2) logits}.""" pooled = torch.flatten(self.avgpool(self.features(x)), 1) return {"age": self.age_head(pooled), "gender": self.gender_head(pooled)} # --------------------------------------------------------------------------- helpers def expected_age(age_probs: torch.Tensor, representatives: list[float]) -> torch.Tensor: """(N, n_bins) probabilities -> (N,) expected ages sum_i p_i * rep_i.""" reps = torch.tensor(representatives, dtype=age_probs.dtype, device=age_probs.device) return (age_probs * reps).sum(dim=-1) def to_pil(image) -> Image.Image: """PIL image, file path, raw bytes, base64 string or HxWxC uint8 array -> RGB PIL image.""" if isinstance(image, Image.Image): return image.convert("RGB") if isinstance(image, (str, Path)): path = Path(image) if len(str(image)) < 1024 and path.is_file(): with Image.open(path) as img: return img.convert("RGB") image = base64.b64decode(str(image).split(",", 1)[-1]) # base64 (optionally a data: URI) if isinstance(image, (bytes, bytearray)): with Image.open(io.BytesIO(image)) as img: return img.convert("RGB") if isinstance(image, np.ndarray): return Image.fromarray(image.astype(np.uint8)).convert("RGB") raise TypeError(f"unsupported image input: {type(image).__name__}") def _clamp_box(box, width: int, height: int, pad: int = 0) -> list[int]: x1, y1, x2, y2 = (int(round(float(v))) for v in box) return [max(x1 - pad, 0), max(y1 - pad, 0), min(x2 + pad, width), min(y2 + pad, height)] def _age_range(probs: np.ndarray, edges: list[list[int]], mass: float = 0.8) -> str: """Central `mass` interval of the predicted age distribution, e.g. '26-37'.""" cdf = np.cumsum(probs) tail = (1.0 - mass) / 2 lo_bin = int(np.searchsorted(cdf, tail)) hi_bin = min(int(np.searchsorted(cdf, 1.0 - tail)), len(edges) - 1) lo = edges[lo_bin][0] if hi_bin == len(edges) - 1 and edges[-1][1] > edges[-1][0]: return f"{lo}+" if lo_bin == hi_bin else f"{lo}-{edges[-1][0]}+" hi = edges[hi_bin][1] return str(lo) if lo == hi else f"{lo}-{hi}" def _colorize(base_rgb: np.ndarray, cam: np.ndarray) -> np.ndarray: """Warm heat ramp (yellow = weaker, red = decisive) blended onto an RGB float array.""" v = np.clip(cam, 0.0, 1.0) alpha = (v ** CAM_GAMMA) * CAM_MAX_ALPHA heat = np.stack([np.full_like(v, 255.0), (1.0 - v) * 255.0, np.zeros_like(v)], axis=-1) return ((1 - alpha[..., None]) * base_rgb + alpha[..., None] * heat).astype(np.uint8) def _font(image: Image.Image) -> ImageFont.ImageFont: return ImageFont.load_default(size=max(14, image.height // 40)) def annotate(image, result: dict, labels: bool = True) -> Image.Image: """Draw each face box of a `predict()` result (+ 'Age: 31 | male 97%' labels) on a copy.""" out = to_pil(image).copy() draw = ImageDraw.Draw(out) font = _font(out) line_w = max(2, out.height // 250) for face in result.get("faces", []): x1, y1, x2, y2 = face["box"] draw.rectangle((x1, y1, x2, y2), outline=BOX_COLOR, width=line_w) if not labels: continue gender = max(face["gender"], key=face["gender"].get) text = f"Age: {round(face['age'])} | {gender} {face['gender'][gender]:.0%}" tx1, ty1, tx2, ty2 = draw.textbbox((0, 0), text, font=font) tw, th = tx2 - tx1, ty2 - ty1 sy = y1 - th - 6 if y1 - th - 6 > 0 else y2 + 2 # above the box, else below it sy = max(0, min(sy, out.height - th - 6)) sx = max(0, min(x1, out.width - tw - 8)) draw.rectangle((sx, sy, sx + tw + 8, sy + th + 6), fill=BOX_COLOR) draw.text((sx + 4 - tx1, sy + 3 - ty1), text, fill=(255, 255, 255), font=font) return out class Predictor: """Loads the face detector + trained network once; `predict()` returns plain JSON.""" def __init__(self, model_dir: str | Path, device: str = "cpu"): model_dir = Path(model_dir) if not (model_dir / WEIGHTS_FILE).is_file(): raise FileNotFoundError( f"{WEIGHTS_FILE} not found in {model_dir}: train/export the model first " f"or download it with huggingface_hub.snapshot_download('{REPO_ID}')." ) if not (model_dir / DETECTOR_WEIGHTS).is_file(): raise FileNotFoundError(f"{DETECTOR_WEIGHTS} not found in {model_dir}") self.device = torch.device(device) self.model = AgeGenderNet.from_pretrained(model_dir, pretrained=False, map_location="cpu", strict=True) self.model.to(self.device).eval() self.detector = FaceDetector() self.detector.load_state_dict(load_file(model_dir / DETECTOR_WEIGHTS), strict=True) self.detector.to(self.device).eval() self.transform = get_transform() self.age_labels = self.model.age_labels self.gender_labels = self.model.gender_labels # ------------------------------------------------------------------ detection def detect(self, image: Image.Image) -> list[dict]: """Face boxes (most confident first) with their padded crop boxes. Falls back to the whole image (`detected: False`) when no face passes `min_face_confidence`.""" w, h = image.size boxes, scores, _ = self.detector.detect([image.convert("RGB")], score=self.model.min_face_confidence)[0] faces = [] for box, score in zip(boxes, scores): faces.append({"box": _clamp_box(box, w, h), "confidence": float(score), "detected": True, "pad_box": _clamp_box(box, w, h, self.model.crop_padding)}) faces = [f for f in faces if f["box"][2] > f["box"][0] and f["box"][3] > f["box"][1]] if not faces: faces = [{"box": [0, 0, w, h], "pad_box": [0, 0, w, h], "confidence": 0.0, "detected": False}] return faces # ------------------------------------------------------------------ classification @torch.inference_mode() def classify(self, crops: list[Image.Image]) -> tuple[np.ndarray, np.ndarray]: """Face crops -> (age_probs (N, n_bins), gender_probs (N, 2)) as float numpy arrays.""" x = torch.stack([self.transform(c.convert("RGB")) for c in crops]).to(self.device) out = self.model(x) return (out["age"].float().softmax(dim=1).cpu().numpy(), out["gender"].float().softmax(dim=1).cpu().numpy()) def predict(self, image, top_k: int = 5) -> dict: """Image (PIL / path / bytes / base64 / array) -> {"faces": [...], "n_faces": n}. Each face: box [x1, y1, x2, y2] in pixels, age (expected value, years), age_range (central 80% interval), age_top (top-k bins -> probability), gender {"male": p, "female": p}, confidence (face-detector score; 0.0 for the whole-image fallback), detected (bool). n_faces counts detected faces (0 when the whole image was classified instead). """ image = to_pil(image) faces = self.detect(image) age_probs, gender_probs = self.classify([image.crop(tuple(f["pad_box"])) for f in faces]) ages = expected_age(torch.from_numpy(age_probs), self.model.age_representatives).tolist() results = [] for face, ap, gp, age in zip(faces, age_probs, gender_probs, ages): top = np.argsort(ap)[::-1][:top_k] results.append({ "box": face["box"], "age": round(float(age), 1), "age_range": _age_range(ap, self.model.age_bin_edges), "age_top": {self.age_labels[i]: round(float(ap[i]), 4) for i in top}, "gender": {label: round(float(p), 4) for label, p in zip(self.gender_labels, gp)}, "confidence": round(face["confidence"], 4), "detected": face["detected"], }) return {"faces": results, "n_faces": sum(f["detected"] for f in faces)} # ------------------------------------------------------------------ Grad-CAM def gradcam_map(self, crop: Image.Image, head: str = "age") -> np.ndarray: """Grad-CAM evidence for one face crop: (h, w) float array in [0, 1], 1 = most decisive for the winning class of `head` ("age" or "gender").""" if head not in ("age", "gender"): raise ValueError("head must be 'age' or 'gender'") x = self.transform(crop.convert("RGB")).unsqueeze(0).to(self.device) activations: list[torch.Tensor] = [] handles = [self.model.features[i].register_forward_hook(lambda _m, _i, out: activations.append(out)) for i in CAM_LAYERS] try: with torch.enable_grad(): logits = self.model(x)[head] target = logits[0, int(logits[0].argmax())] grads = torch.autograd.grad(target, activations) finally: for handle in handles: handle.remove() # The transform resizes the shorter edge and center-crops a square: build the CAM on that # square and paste it into a zero canvas so no heat lands on pixels the net never saw. w, h = crop.size side = min(w, h) fused = np.ones((side, side), dtype=np.float32) for acts, grad in zip(activations, grads): weights = grad.mean(dim=(2, 3), keepdim=True) cam = torch.relu((weights * acts).sum(dim=1)).squeeze(0).detach().float().cpu().numpy() if cam.max() > 0: cam = cam / cam.max() cam_img = Image.fromarray((np.clip(cam, 0, 1) * 255).astype(np.uint8)).resize((side, side), Image.BILINEAR) fused *= np.asarray(cam_img, dtype=np.float32) / 255.0 fused = np.sqrt(fused) if fused.max() > 0: fused /= fused.max() canvas = np.zeros((h, w), dtype=np.float32) x0, y0 = (w - side) // 2, (h - side) // 2 canvas[y0:y0 + side, x0:x0 + side] = fused return canvas def gradcam(self, image, result: dict | None = None) -> dict[str, Image.Image]: """Full-size Grad-CAM views {"age": PIL, "gender": PIL} with every face's evidence composited back in place (face boxes drawn on top). Reuses the boxes of `result` when given.""" image = to_pil(image) w, h = image.size if result is None: faces = self.detect(image) else: faces = [{"box": f["box"], "pad_box": _clamp_box(f["box"], w, h, self.model.crop_padding if f.get("detected", True) else 0)} for f in result["faces"]] base = np.asarray(image, dtype=np.float32) views = {} for head in ("age", "gender"): heat = np.zeros((h, w), dtype=np.float32) for face in faces: x1, y1, x2, y2 = face["pad_box"] cam = self.gradcam_map(image.crop((x1, y1, x2, y2)), head) region = heat[y1:y2, x1:x2] np.maximum(region, cam[:region.shape[0], :region.shape[1]], out=region) views[head] = annotate(Image.fromarray(_colorize(base, heat)), {"faces": faces}, labels=False) return views def load(model_dir: str | Path, device: str = "cpu") -> Predictor: return Predictor(model_dir, device)