save code

docs/发际线生发遮罩算法_pushed模式.md

@@ -1,12 +1,12 @@
 # 发际线生发遮罩算法（pushed 模式）
 
 > 对应接口11 `/api/v1/hairline/grow`、接口12 `/api/v1/hairline/grow_v2`。
-> 遮罩算法固定为 pushed，融合算法固定为 multiband（已移除其他选项）。
-> 代码：`face_analysis/hairline_grow.py`（`_extract_hairline` / `_pushed_mask` / `compute_mask`）。
+> 遮罩算法固定为 pushed；融合算法默认 multiband（多频段金字塔），接口11 可切换 seamless/two_stage/feather。
+> 代码：`face_analysis/hairline_grow.py`（`_extract_hairline` / `_pushed_mask` / `compute_mask` / `_composite`）。
 
 ## 概述
 
-pushed 是发际线生发的**唯一**遮罩算法，multiband（多频段金字塔）是**唯一**融合算法。它从头发分割结果中提取「头发/皮肤交界线」（发际线），以眉心为圆心逐点径向外推一段距离，与 baseline 组成闭合区域作为最终遮罩。这样遮罩顶部会覆盖现有头发下沿一小段，贴回生发结果时顶部与真头发重叠、过渡自然。
+pushed 是发际线生发的**唯一**遮罩算法。融合算法默认 multiband（多频段金字塔），接口11 暴露 `blend_method` 可切换为 seamless(泊松)/two_stage(泊松→多频段两段式)/feather(羽化)，便于对比调优。它从头发分割结果中提取「头发/皮肤交界线」（发际线），以眉心为圆心逐点径向外推一段距离，与 baseline 组成闭合区域作为最终遮罩。这样遮罩顶部会覆盖现有头发下沿一小段，贴回生发结果时顶部与真头发重叠、过渡自然。
 
 > 接口12 `/api/v1/hairline/grow_v2` 只需传 `image` + `hairline_id`，遮罩和融合全部固定，无需任何算法选择参数。
 
@@ -57,14 +57,48 @@ segformer（默认）或 bisenet 得到的头发二值掩码。
 
 ## 关键参数
 
-遮罩算法（pushed）和融合算法（multiband）已固定，接口不再暴露选择参数。可调的只有：
+遮罩算法（pushed）固定。融合算法接口11 通过 `blend_method` 可切换（默认 multiband），其余融合参数均可调：
 
 | 参数 | 默认 | 说明 |
 |---|---|---|
 | `hairline_push_cm` | 1.0 | 内轮廓径向外推距离（厘米），= push_px / px_per_cm。`px_per_cm` 由虹膜直径标定 |
 | `hairline_edge` | `column` | 兼容保留的入参；内轮廓提取（轮廓+内侧判定）不再按它分支，取值不影响结果 |
 | `mb_levels` | 5 | 多频段金字塔层数（2~6，越大低频色差抹得越宽）|
+| `blend_method` | `multiband` | 接缝融合：multiband(多频段金字塔) / seamless(泊松) / two_stage(泊松→多频段,大色差) / feather(羽化) / alpha_gradient。接口12 固定 multiband |
+| `color_match` | `true` | 融合前 Reinhard 颜色迁移消除整体色差（multiband/feather/alpha_gradient 生效；seamless/two_stage 自带调色故跳过）|
+| `color_match_strength` | 1.0 | 颜色迁移强度（0~1，<1 只迁移部分，防 Reinhard 过度改色）|
+| `mb_feather_px` | 1 | 多频段最细层掩码轻羽化像素（0=不羽化），消除发丝边缘锯齿 |
+| `transition_band_px` | -1 | keep-region 过渡带边距（-1=自动按层数 `2**n`；>=0 用绝对像素与层数解耦）|
+| `edge_erode_px` | 3 | 贴图前遮罩内缩像素（防边缘露皮/光晕）|
 | `erode_cm` | 0.6（接口12 固定）| baseline 参考内缩距离，对 pushed 影响很小 |
+| `redraw` | `false` | 发际线带重绘开关：开启后用 final（④融合图）在「外推线↔发际线」带重绘，swapHair/Flux-2 两路对比，结果单独展示（不替换 final）|
+| `inpainting_fill` | 1 | change_hair 重绘填充：0=保留原图(治染绿) / 1=填充噪声(默认) / 2=纯色 / 3=潜变量噪声 |
+| `mask_blur` | 11 | change_hair 遮罩边缘模糊像素（越大颜色越易从边缘渗透）|
+| `mask_dilate_scale` | 1.0 | change_hair 遮罩膨胀核缩放（1.0=原始，<1 收缩防越界）|
+| `comfyui_prompt` | `null` | redraw Flux-2 路提示词，null 用默认「补充遮罩区域的头发，加一点美颜」|
+
+> 接口12 `/api/v1/hairline/grow_v2` 只需传 `image` + `hairline_id`，遮罩和融合全部用默认值（multiband + color_match=true），不暴露算法选择参数。
+
+### 融合方法选择建议
+
+- **multiband**（默认）：常规首选。低频抹色差、高频保发丝。需配合 `color_match=true` 消除整体色差。
+- **two_stage**：生成图与原图色差大时用。先泊松克隆统一色调，再多频段贴细节，兼顾调色与保发丝。比纯 seamless 更不易溢色。
+- **seamless**：纯泊松梯度域调和，色调统一干净，但可能整体改色/边缘溢色。
+- **feather / alpha_gradient**：单层 alpha 过渡，最轻量，但过渡带内色差不会被抹平，仅适合色差极小的场景。
+
+## 发际线带重绘（redraw，接口11 可选）
+
+`redraw=true` 时，在主流程（④接缝融合 final）之后额外跑一条重绘分支，结果单独展示（`steps.redraw_a` / `redraw_c`），**不替换** final。
+
+**重绘区域** = ①-g 外推发际线（`outer_pts`）与 ①-f 发际线（`inner_pts`）两条折线端点相连组成的带状闭合区域（宽度 ≈ `hairline_push_cm`，只覆盖发际线交界处）。
+
+**两路后端对比**（输入图 + 融合基底都用 final）：
+- **swapHair 路**（`redraw_a`）：final + 带遮罩调 change_hair → final 走 multiband 融合
+- **Flux-2 路**（`redraw_c`）：final + 带遮罩调 ComfyUI（`hair_repaint.json` 工作流）→ final 走 multiband 融合。Flux-2 经 reference latent + ColorMatch 双重保色，**不易染绿**
+
+> `inpainting_fill` / `mask_blur` / `mask_dilate_scale` 透传 change_hair 服务端（仅影响 swapHair 路）。`comfyui_prompt` 仅影响 Flux-2 路。
+> 两路独立容错：任一路失败只跳过该路，不影响另一路和主 final。
+> ⚠️ Flux-2 路需 ComfyUI（8188）在跑；swapHair 路需 change_hair（8801）在跑。
 
 ## 与旧模式（eroded/closed，已移除）的区别
 

docs/接口文档.md

@@ -209,9 +209,11 @@
 | annotated_image_url | string | 标注图层 PNG URL（透明底，仅标注线/文字，不含人物） |
 | face_total_height_cm | number | 面部总高度（cm）= 上庭 + 中庭 + 下庭（**不含顶庭**） |
 | four_courts | object | 三庭数据（上/中/下庭，各含 cm 与 ratio；**无顶庭**） |
-| seven_eyes | object | 七眼数据（眼宽/脸宽/两眼间距，各含 cm 与 ratio） |
+| seven_eyes | object | 七眼数据（眼宽/脸宽/两眼间距 cm + 占比 ratios + **eye2~eye6** 共 5 段宽度） |
 | landmarks | object | 四个关键点像素坐标（发际线/眉心/鼻翼下缘/下巴尖） |
 
+> 接口6 是**三庭五眼**：`four_courts`/`landmarks` 不含顶庭与头顶点（无 `top_court_cm`/`hair_top`）；`seven_eyes` 只含 **eye2~eye6**（左脸颊/左眼/两眼间距/右眼/右脸颊，5 段），**无 eye1/eye7**（耳外段需头发轮廓端线，仅接口1 有）。
+
 ### 响应示例
 
 ```json
@@ -228,7 +230,8 @@
     },
     "seven_eyes": {
       "eye_width_cm": 3.44, "face_width_cm": 24.08, "inter_eye_distance_cm": 3.44,
-      "ratios": { "eye_width": 0.143, "inter_eye_distance": 0.143 }
+      "ratios": { "eye_width": 0.143, "inter_eye_distance": 0.143 },
+      "eye2": 3.0, "eye3": 3.44, "eye4": 3.44, "eye5": 3.44, "eye6": 3.0
     },
     "landmarks": {
       "hairline": { "x": 540, "y": 430 },
@@ -410,7 +413,9 @@
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | hairline_images | object[] | **选中发型**列表，**数量 = 所选发型数**，元素见下表 |
-| best_hairline_center_point | object | **首个选中发型**的 middle 档发际线曲线「面部中间点」坐标，原图像素：`{ "x": number, "y": number }` |
+| best_hairline_center_point | object \| null | **首个选中发型**的 **middle 档**发际线曲线「面部中间点」坐标，原图像素：`{ "x": number, "y": number }` |
+| high_hairline_center_point | object \| null | 同上，**high 档**发际线中点（发际线偏高） |
+| low_hairline_center_point | object \| null | 同上，**low 档**发际线中点（发际线偏低） |
 | face_measure | object \| null | **复用接口1**的四庭七眼测量**数值**（不含标注图）。独立流程，测量失败（无人脸/非正面/分割失败）时为 `null`，不影响发际线主结果。字段结构见下表 |
 
 `hairline_images` 元素：
@@ -468,6 +473,8 @@
       }
     ],
     "best_hairline_center_point": { "x": 540, "y": 430 },
+    "high_hairline_center_point": { "x": 540, "y": 380 },
+    "low_hairline_center_point": { "x": 540, "y": 480 },
     "face_measure": {
       "face_total_height_cm": 26.76,
       "four_courts": {