age-estimator / model.py
shalev396's picture
Add age-estimator model: weights, model.py, Inference Endpoint handler, card
b8e43ad
Raw History Blame Contribute Delete
25.8 kB
"""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)