Face crop: make it hair-aware (don't clip top hair; cover long hair)

The RetinaFace box starts ~at the hairline, so the pixel3dmm crop clipped the
top of the head. Grow the crop to also enclose the face+hair segmentation bbox
(reusing the facer parser already used for tracks), with extra headroom on top.
Square the box anchored at the TOP so, when it can't fit everything in a narrow
portrait, the hair is kept and the bottom rides up to the jaw (still excludes
shoulders). Width now follows the hair extent, so long hair on the sides is
covered too. Verified on the example: top raised 143->61 (full headroom), hair
fully inside.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

app.py

@@ -429,10 +429,39 @@ def _cstm_crop_box(mean_b, max_b, img_h, img_w, scale=1.42):
     return ymin, ymax, xmin, xmax
 
 
+def _combine_face_hair_box(face_box, hair_bbox, img_h, img_w,
+                           pad_top=0.10, pad_side=0.05, pad_bot=0.03):
+    """Grow the pixel3dmm face box so it also encloses the hair (the face+hair
+    segmentation bbox), with extra headroom on top — fixes hair being clipped at
+    the top of the head and covers long hair on the sides. Squares the box; when
+    it can't fit everything (narrow portrait), it keeps the TOP (hair) and lets the
+    bottom ride up rather than clipping the hair. Falls back to the face box if no
+    hair bbox is available.
+
+    face_box: (ymin, ymax, xmin, xmax). hair_bbox: (x0, y0, x1, y1) or None."""
+    fy0, fy1, fx0, fx1 = face_box
+    if hair_bbox is None:
+        return face_box
+    hx0, hy0, hx1, hy1 = hair_bbox
+    x0 = min(fx0, hx0); y0 = min(fy0, hy0)
+    x1 = max(fx1, hx1); y1 = max(fy1, hy1)
+    bw = max(x1 - x0, 1.0); bh = max(y1 - y0, 1.0)
+    x0 -= pad_side * bw; x1 += pad_side * bw
+    y0 -= pad_top * bh;  y1 += pad_bot * bh
+    side = min(max(x1 - x0, y1 - y0), float(img_w), float(img_h))
+    nx0 = (x0 + x1) / 2.0 - side / 2.0          # centered horizontally
+    ny0 = y0                                     # anchored at the top (keep hair)
+    nx0 = min(max(nx0, 0.0), img_w - side)
+    ny0 = min(max(ny0, 0.0), img_h - side)
+    xmin = int(round(nx0)); ymin = int(round(ny0)); side = int(round(side))
+    return ymin, min(ymin + side, img_h - 1), xmin, min(xmin + side, img_w - 1)
+
+
 def _face_crop_frames(frame_paths, device, out_dir, log, process_res):
-    """Crop every frame to a face-centric square (pixel3dmm-style). Returns new
-    frame paths; on any failure (facer missing / no face) returns the originals so
-    the run never breaks."""
+    """Crop every frame to a face-centric square (pixel3dmm-style), grown to also
+    cover the hair (top of head + long hair on the sides) via the face+hair
+    segmentation. Returns new frame paths; on any failure (facer missing / no face)
+    returns the originals so the run never breaks."""
     import cv2
     try:
         import torch
@@ -442,15 +471,17 @@ def _face_crop_frames(frame_paths, device, out_dir, log, process_res):
         log.append(f"WARNING: face crop unavailable ({e}); using full frames.")
         return frame_paths
 
-    imgs, sizes, boxes = [], [], []
-    for fp in frame_paths:
-        im = cv2.imread(fp)
-        imgs.append(im)
-        if im is None:
-            sizes.append(None); boxes.append(None); continue
-        sizes.append(im.shape[:2])
+    imgs = [cv2.imread(fp) for fp in frame_paths]
+    rgb_imgs = [cv2.cvtColor(im, cv2.COLOR_BGR2RGB) if im is not None else None
+                for im in imgs]
+    sizes = [im.shape[:2] if im is not None else None for im in imgs]
+
+    # face detection boxes (x, y, w, h)
+    boxes = []
+    for rgb in rgb_imgs:
+        if rgb is None:
+            boxes.append(None); continue
         try:
-            rgb = cv2.cvtColor(im, cv2.COLOR_BGR2RGB)
             t = facer.hwc2bchw(torch.from_numpy(np.ascontiguousarray(rgb))).to(device)
             with torch.inference_mode():
                 faces = detector(t)
@@ -469,6 +500,21 @@ def _face_crop_frames(frame_paths, device, out_dir, log, process_res):
         log.append("WARNING: face crop found no faces; using full frames.")
         return frame_paths
 
+    # face + hair mask → bbox per frame, so the crop encloses the hair, not just
+    # the face detection box (which starts around the hairline).
+    hair_masks = _face_hair_masks(rgb_imgs, device, log)
+
+    def _mask_bbox(m):
+        if m is None:
+            return None
+        ys, xs = np.nonzero(m)
+        if not len(xs):
+            return None
+        return [int(xs.min()), int(ys.min()), int(xs.max()), int(ys.max())]
+
+    hair_bboxes = ([_mask_bbox(m) for m in hair_masks]
+                   if hair_masks is not None else [None] * len(frame_paths))
+
     # One static box for the whole clip when every frame shares a resolution.
     uniq = set(s for s in sizes if s is not None)
     static_box = None
@@ -479,7 +525,11 @@ def _face_crop_frames(frame_paths, device, out_dir, log, process_res):
         x0, y0 = xs.min(), ys.min()
         mean_b = [xs.mean(), ys.mean(), ws.mean(), hs.mean()]
         max_b = [x0, y0, (xs + ws - x0).max(), (ys + hs - y0).max()]   # union box
-        static_box = _cstm_crop_box(mean_b, max_b, H, W)
+        face_static = _cstm_crop_box(mean_b, max_b, H, W)
+        hb = [b for b in hair_bboxes if b is not None]
+        hair_static = ([min(b[0] for b in hb), min(b[1] for b in hb),
+                        max(b[2] for b in hb), max(b[3] for b in hb)] if hb else None)
+        static_box = _combine_face_hair_box(face_static, hair_static, H, W)
 
     out_size = int(min(1024, max(512, int(process_res))))
     crop_dir = os.path.join(out_dir, "cropped")
@@ -496,7 +546,9 @@ def _face_crop_frames(frame_paths, device, out_dir, log, process_res):
             ymin, ymax, xmin, xmax = static_box
         else:
             b = boxes[i] if boxes[i] is not None else fallback
-            ymin, ymax, xmin, xmax = _cstm_crop_box(b, b, h, w)
+            face_box = _cstm_crop_box(b, b, h, w)
+            ymin, ymax, xmin, xmax = _combine_face_hair_box(
+                face_box, hair_bboxes[i], h, w)
         crop = im[ymin:ymax, xmin:xmax]
         out_fp = os.path.join(crop_dir, f"frame_{i:04d}.png")
         if crop.size == 0:
@@ -506,8 +558,9 @@ def _face_crop_frames(frame_paths, device, out_dir, log, process_res):
             n_cropped += 1
         new_paths.append(out_fp)
     log.append(
-        f"Face crop (pixel3dmm-style): {n_cropped}/{len(frame_paths)} frame(s) → "
-        f"{out_size}x{out_size}" + (" static box." if static_box is not None else " per-frame."))
+        f"Face crop (pixel3dmm-style, hair-aware): {n_cropped}/{len(frame_paths)} "
+        f"frame(s) → {out_size}x{out_size}"
+        + (" static box." if static_box is not None else " per-frame."))
     return new_paths