feat(接口2): C端生发发际线预览(真实实现，替换Mock)

第一步：按性别把发际线类型贴图渲染到照片，输出 N 张发际线叠加预览图。

- hairline/render.py: 解析 face_ext.obj(502 UV + 64 ribbon扩展面) + OpenCV 逐三角
  仿射 warp 渲染器；关键修复——face_ext.obj 是 OBJ序，用 INDEX_MAP_468 把 MP序
  502点重排成 OBJ序后再投影，否则 ribbon 会错贴到中脸
- hairline/service.py: FaceLandmarker+SegFormer 单例 + 性别贴图映射(扫描去空格)
  + generate_previews 管线(female5/male4)
- 集成点修复: face_landmarks DEFAULT_MODEL_PATH 改 hairline/models/;
  constants HF_FACE_PARSER_MODEL 改本地路径(离线)
- app.py: /api/v1/hair/grow 接真实实现，gender 必填(非法→1004)，返回
  results[].image_base64(不落盘)，校验/鉴权同接口1；lifespan 预热接口2单例；
  补 logging.basicConfig
- 依赖: transformers==4.45.2；SegFormer 权重走 hf-mirror 下载(见 OFFLINE_ASSETS)
- 测试: tests/test_hairline.py(mesh/重排/贴图映射) + test_api 接口2用例，31 全绿

注：SegFormer 受 5090/torch 限制走 CPU(~2.5s/张)，换 cu128 可 SEG_DEVICE=cuda。

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

hairline/constants.py

@@ -162,4 +162,9 @@ PARSE_NECK_L   = 16
 PARSE_NECK     = 17
 PARSE_CLOTH    = 18
 
-HF_FACE_PARSER_MODEL = "jonathandinu/face-parsing"
+# 内网/离线：指向本地权重目录（transformers from_pretrained 支持本地路径）。
+# 在线 id 为 "jonathandinu/face-parsing"，权重已放到 hairline/models/face-parsing/。
+import os as _os
+HF_FACE_PARSER_MODEL = _os.path.join(
+    _os.path.dirname(_os.path.abspath(__file__)), "models", "face-parsing"
+)

hairline/face_landmarks.py

@@ -11,8 +11,9 @@ from __future__ import annotations
 import os
 import numpy as np
 
+# 模型在 hairline/models/ 下（模块即在 hairline/ 根），故只取一层 dirname。
 DEFAULT_MODEL_PATH = os.path.join(
-    os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+    os.path.dirname(os.path.abspath(__file__)),
     "models", "face_landmarker.task",
 )
 

hairline/render.py

@@ -0,0 +1,107 @@
+"""接口2 渲染器：把发际线类型贴图按 502 点 mesh 贴到照片上（OpenCV 逐三角仿射 warp）。
+
+原理（技术方案 §4）：face_ext.obj 的 502 顶点里，[468..485) 中间行 + [485..502) 发际线行
+与 17 个 MP 顶部锚点连成 ~64 个 ribbon 三角形，其 UV 落在贴图顶部条带（发际线曲线所在）。
+只 warp 这些扩展三角形，即可把贴图里的发际线曲线贴到额头/发际线区域，且天然只画在 ribbon 区。
+"""
+from __future__ import annotations
+import os
+
+import cv2
+import numpy as np
+from PIL import Image
+
+from .obj_io import read_obj
+from ._index_map_data import INDEX_MAP_468
+
+_MESH_PATH = os.path.join(os.path.dirname(__file__), "mesh", "face_ext.obj")
+_N_MP = 468
+
+_mesh_cache = None
+_INDEX_MAP = np.asarray(INDEX_MAP_468, dtype=np.int64)   # OBJ顶点i → MP点索引
+
+
+def mp_order_to_obj_order(points502_mp: np.ndarray) -> np.ndarray:
+    """把 MP 顺序的 502 点重排成 face_ext.obj 的顶点顺序。
+
+    extract_hairline 输出为 MP 顺序：[0..468) MP / [468..485) middle / [485..502) hairline。
+    而 face_ext.obj 的前 468 顶点经 INDEX_MAP_468 重排（obj_i → mp_i）；扩展顶点
+    [468..502) 两侧同序，直接对应。
+    """
+    out = np.empty_like(points502_mp)
+    out[:_N_MP] = points502_mp[_INDEX_MAP]      # obj[0..468) = mp[INDEX_MAP]
+    out[_N_MP:] = points502_mp[_N_MP:]          # 扩展行同序
+    return out
+
+
+def load_ext_mesh(obj_path: str = _MESH_PATH):
+    """解析 face_ext.obj，返回 (uv502, ext_faces)。结果缓存。
+
+    - uv502: (502, 2) float32，每个顶点的 UV（V_raw，V=1 对应贴图顶部）。
+    - ext_faces: list[(i,j,k)]，仅保留顶点索引含 ≥468 的扩展三角形（ribbon）。
+    obj 中 v 与 vt 一一对应（face 用相同索引），故按位置索引取 UV。
+    """
+    global _mesh_cache
+    if _mesh_cache is not None:
+        return _mesh_cache
+
+    mesh = read_obj(obj_path)
+    n_v = len(mesh.positions)
+    uv = np.zeros((n_v, 2), dtype=np.float32)
+    for face in mesh.faces:
+        for pi, ti, _ni in face:
+            if ti >= 0 and pi >= 0:
+                uv[pi] = mesh.texcoords[ti]
+
+    ext_faces = []
+    for face in mesh.faces:
+        idx = [pi for (pi, _t, _n) in face]
+        if max(idx) >= _N_MP:                 # 含扩展顶点 → ribbon 三角形
+            ext_faces.append(tuple(idx))
+
+    _mesh_cache = (uv, ext_faces)
+    return _mesh_cache
+
+
+def load_texture_rgba(path: str) -> np.ndarray:
+    """读发际线贴图为 (H, W, 4) uint8 RGBA。"""
+    return np.array(Image.open(path).convert("RGBA"))
+
+
+def render_hairline_overlay(photo_bgr: np.ndarray,
+                            points502_norm: np.ndarray,
+                            ext_faces,
+                            uv502: np.ndarray,
+                            texture_rgba: np.ndarray) -> np.ndarray:
+    """把 texture_rgba 的发际线曲线渲染到 photo_bgr 上，返回 BGR 预览图。
+
+    points502_norm: (502, 3) 归一化坐标（x,y ∈ [0,1]），**MP 顺序**（extract_hairline 输出）。
+    """
+    H, W = photo_bgr.shape[:2]
+    TH, TW = texture_rgba.shape[:2]
+    pts_obj = mp_order_to_obj_order(points502_norm)              # MP序 → OBJ序
+    img_xy = pts_obj[:, :2] * np.array([W, H], dtype=np.float32)  # (502,2)
+
+    overlay = np.zeros((H, W, 4), np.float32)        # 累积曲线层 RGBA
+    tex = texture_rgba.astype(np.float32)
+    for (i, j, k) in ext_faces:
+        dst = img_xy[[i, j, k]].astype(np.float32)
+        # UV → 贴图像素；flipY：贴图 y = (1 - v_raw) * TH（与 head3d Three.js flipY=true 一致）
+        src = np.array([[uv502[v][0] * TW, (1.0 - uv502[v][1]) * TH] for v in (i, j, k)],
+                       dtype=np.float32)
+        # 退化三角形（投影到一条线）跳过，避免 getAffineTransform 奇异
+        if cv2.contourArea(dst.astype(np.int32)) < 1.0:
+            continue
+        M = cv2.getAffineTransform(src, dst)
+        warped = cv2.warpAffine(tex, M, (W, H), flags=cv2.INTER_LINEAR,
+                                borderMode=cv2.BORDER_CONSTANT, borderValue=(0, 0, 0, 0))
+        tri_mask = np.zeros((H, W), np.uint8)
+        cv2.fillConvexPoly(tri_mask, dst.astype(np.int32), 255)
+        sel = tri_mask > 0
+        overlay[sel] = warped[sel]
+
+    # alpha 合成（RGBA→BGR：贴图 RGB 顺序需反成 BGR）
+    a = overlay[:, :, 3:4] / 255.0
+    rgb = overlay[:, :, :3][..., ::-1]               # RGB→BGR
+    out = photo_bgr.astype(np.float32) * (1.0 - a) + rgb * a
+    return np.clip(out, 0, 255).astype(np.uint8)

hairline/service.py

@@ -0,0 +1,123 @@
+"""接口2 服务层：模型单例 + 性别贴图映射 + 「照片→N 张发际线预览图」管线。
+
+把 head3d 的 extract_hairline 步骤包成单例复用（避免每请求重建模型），再按性别
+对每张贴图调 render.render_hairline_overlay 生成预览图。
+"""
+from __future__ import annotations
+import glob
+import os
+
+import cv2
+import numpy as np
+
+from . import constants as C
+from .face_landmarks import FaceLandmarker
+from .face_parsing import FaceParser
+from .hairline_2d import sample_hairline, smooth_hairline
+from .lift_3d import lift_hairline_to_3d, build_middle_row, assemble_full
+from .render import load_ext_mesh, load_texture_rgba, render_hairline_overlay
+
+_TEXTURE_DIR = os.path.join(os.path.dirname(os.path.dirname(__file__)), "hairline_texture")
+
+# ⚠️ 本 worker 是 RTX 5090(sm_120)，torch 2.2.2(cu121) 只编到 sm_90，CUDA 跑算子会报
+#    "no kernel image"。SegFormer 默认走 CPU（~2.5s/张）。换 torch cu128 后可设 SEG_DEVICE=cuda。
+_SEG_DEVICE = os.getenv("SEG_DEVICE", "cpu")
+
+_landmarker = None
+_parser = None
+_texture_map = None
+
+
+def get_landmarker() -> FaceLandmarker:
+    global _landmarker
+    if _landmarker is None:
+        _landmarker = FaceLandmarker(static_image_mode=True)
+    return _landmarker
+
+
+def get_parser() -> FaceParser:
+    global _parser
+    if _parser is None:
+        _parser = FaceParser(device=_SEG_DEVICE)
+    return _parser
+
+
+def _gender_key(stem: str):
+    """文件名 stem → (gender, key)；非 girl_/man_ 前缀返回 (None, None)。"""
+    if stem.startswith("girl_"):
+        return "female", stem[5:].replace(" ", "").strip()
+    if stem.startswith("man_"):
+        return "male", stem[4:].replace(" ", "").strip()
+    return None, None
+
+
+def get_texture_map() -> dict:
+    """扫描 hairline_texture/ 建 {gender: [(key, path)]}，按 key 排序、缓存。
+
+    文件名规范化去空格（如 `man_ inverse_arc.png` → key `inverse_arc`）。
+    """
+    global _texture_map
+    if _texture_map is not None:
+        return _texture_map
+    mapping: dict[str, list] = {"female": [], "male": []}
+    for path in sorted(glob.glob(os.path.join(_TEXTURE_DIR, "*.png"))):
+        stem = os.path.splitext(os.path.basename(path))[0]
+        gender, key = _gender_key(stem)
+        if gender:
+            mapping[gender].append((key, path))
+    for g in mapping:
+        mapping[g].sort(key=lambda kp: kp[0])
+    _texture_map = mapping
+    return _texture_map
+
+
+def extract_502(image_bgr: np.ndarray):
+    """照片(BGR) → (points502 MP序, valid17)。无人脸返回 (None, None)。"""
+    rgb = cv2.cvtColor(image_bgr, cv2.COLOR_BGR2RGB)
+    landmarks = get_landmarker().detect(rgb)
+    if landmarks is None:
+        return None, None
+    parse_map = get_parser().parse(rgb)
+    hairline_2d, valid = sample_hairline(landmarks, parse_map)
+    hairline_2d = smooth_hairline(hairline_2d, valid)
+    hairline_3d = lift_hairline_to_3d(landmarks, hairline_2d)
+    middle_3d = build_middle_row(landmarks, hairline_3d)
+    points = assemble_full(landmarks, middle_3d, hairline_3d)
+    return points, valid
+
+
+def generate_previews(image_bgr: np.ndarray, gender: str):
+    """生成该性别全部发际线预览图。
+
+    Returns: list[dict]，每项 {"hairline_type": key, "image_bgr": ndarray, "order": 1..N}。
+    无人脸返回 None。gender 必须是 male/female。
+    """
+    if gender not in ("male", "female"):
+        raise ValueError(f"gender 必须是 male/female，收到 {gender!r}")
+    points, _valid = extract_502(image_bgr)
+    if points is None:
+        return None
+
+    uv, ext_faces = load_ext_mesh()
+    results = []
+    for order, (key, path) in enumerate(get_texture_map()[gender], start=1):
+        tex = load_texture_rgba(path)
+        preview = render_hairline_overlay(image_bgr, points, ext_faces, uv, tex)
+        results.append({"hairline_type": key, "image_bgr": preview, "order": order})
+    return results
+
+
+if __name__ == "__main__":
+    import sys
+    g = sys.argv[2] if len(sys.argv) > 2 else "female"
+    img = cv2.imread(sys.argv[1] if len(sys.argv) > 1 else "tests/fixtures/frontal.jpg")
+    os.makedirs("tests/output", exist_ok=True)
+    print("texture map:", {k: [kp[0] for kp in v] for k, v in get_texture_map().items()})
+    res = generate_previews(img, g)
+    if res is None:
+        print("无人脸")
+        sys.exit(1)
+    for r in res:
+        out = f"tests/output/preview_{g}_{r['hairline_type']}.png"
+        cv2.imwrite(out, r["image_bgr"])
+        print(f"  order={r['order']} type={r['hairline_type']} -> {out}")