xsl/hair
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(接口6): 复刻接口1，新增 /api/v1/face/measure-v2

Browse Source 
- 抽取 _face_measure_impl() 共用实现，接口1/6 零逻辑差异
- 接口6 路径 POST /api/v1/face/measure-v2
- 入参/出参与接口1 完全一致
- 文档同步更新（接口文档、实现说明、网关待改动）

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
xsl
2026-06-23 20:27:51 +08:00
co-authored by Claude
parent 76bae98073
commit 8cd44848d6
4 changed files with 239 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
app.py
+154 -49
View File
@@ -316,9 +316,71 @@ class ImageJsonBody(BaseModel):
# ---------------------------------------------------------------------------
# 接口 1：四庭七眼测量标注
# 接口 1/6 共用实现
# ---------------------------------------------------------------------------
async def _face_measure_impl(image_file, image_url, image_base64):
"""接口1/6 共用实现：四庭七眼测量 + 标注图生成。返回 (ok_dict, err_dict)。"""
# 1. 三选一取图
raw, e = await resolve_image_bytes(image_file, image_url, image_base64)
if e is not None:
return None, e
# 2. 大小校验（≤ 1MB）
if len(raw) > MAX_FILE_BYTES:
return None, err(1006, "文件超出 1 MB 限制")
# 3. 解码
image = cv2.imdecode(np.frombuffer(raw, np.uint8), cv2.IMREAD_COLOR)
if image is None:
return None, err(1008, "图片格式不支持（仅 JPG / PNG）")
# 4. 分辨率（短边/长边，方向无关，可配置门槛）
h, w = image.shape[:2]
short_side, long_side = min(w, h), max(w, h)
if short_side < MIN_SHORT_SIDE or long_side < MIN_LONG_SIDE:
return None, err(1002, "人像分辨率过低")
try:
from face_analysis.detector import detector
from face_analysis.pose import estimate_head_pose, check_frontal_face
from face_analysis.measure import measure_face
from face_analysis.annotation import create_annotated_image
# 5. 人脸检测
landmarks = detector.detect(image)
if landmarks is None:
return None, err(1001, "无法识别人像")
# 6. 姿态校验
if not check_frontal_face(landmarks, w, h):
return None, err(1003, "角度问题，请上传正面照")
head_pose = estimate_head_pose(landmarks, w, h)
# 7. 头发分割（方案 B），失败传 None 由 measure 内部回退方案 A
hair_mask = None
try:
from face_analysis.hair_segmenter import get_segmenter
hair_mask = get_segmenter().segment_hair(image)
except Exception as seg_e: # noqa: BLE001
logger.warning("头发分割失败，回退方案A：%s", seg_e)
# 8. 测量 + 标注图
result = measure_face(landmarks, hair_mask, w, h, head_pose=head_pose)
annotated = create_annotated_image(image, result)
buf = BytesIO()
annotated.save(buf, format="PNG")
# 9. 拆分架构：返回 base64，不落盘不拼 URL（落盘改 URL 由网关完成）
data = result.to_response()
data["annotated_image_base64"] = base64.b64encode(buf.getvalue()).decode()
return ok(data), None
except Exception as ex: # noqa: BLE001
logger.exception("接口1/6 处理异常")
return None, err(1007, f"处理失败：{ex}")
@app.post(
"/api/v1/face/measure",
summary="接口1 四庭七眼测量标注",
@@ -405,63 +467,106 @@ async def face_measure(
image_url: Optional[str] = Form(default=None, description="图片 URL"),
image_base64: Optional[str] = Form(default=None, description="图片 base64（需带 data:image/...;base64, 前缀）"),
):
# 1. 三选一取图
raw, e = await resolve_image_bytes(image_file, image_url, image_base64)
if e is not None:
return e
"""接口1：四庭七眼测量标注"""
ok_data, err_data = await _face_measure_impl(image_file, image_url, image_base64)
return ok_data if ok_data is not None else err_data
# 2. 大小校验（≤ 1MB）
if len(raw) > MAX_FILE_BYTES:
return err(1006, "文件超出 1 MB 限制")
# 3. 解码
image = cv2.imdecode(np.frombuffer(raw, np.uint8), cv2.IMREAD_COLOR)
if image is None:
return err(1008, "图片格式不支持（仅 JPG / PNG）")
# ---------------------------------------------------------------------------
# 接口 6：四庭七眼测量标注 v2（复刻接口1）
# ---------------------------------------------------------------------------
# 4. 分辨率（短边/长边，方向无关，可配置门槛）
h, w = image.shape[:2]
short_side, long_side = min(w, h), max(w, h)
if short_side < MIN_SHORT_SIDE or long_side < MIN_LONG_SIDE:
return err(1002, "人像分辨率过低")
@app.post(
"/api/v1/face/measure-v2",
summary="接口6 四庭七眼测量标注 v2",
tags=["人脸分析"],
description=f"""
输入用户正面照，返回：
- 标注好四庭七眼数据的 **PNG 图片**（仅标注图层，不含人物）
- 四庭（顶庭/上庭/中庭/下庭）各段**厘米数值及占比**
- 七眼（眼宽/脸宽/两眼间距）**厘米数值及占比**
- 五个关键分界点的**原图像素坐标**（头顶/发际线/眉心/鼻翼下缘/下巴尖）
try:
from face_analysis.detector import detector
from face_analysis.pose import estimate_head_pose, check_frontal_face
from face_analysis.measure import measure_face
from face_analysis.annotation import create_annotated_image
功能与接口1 完全一致，复刻实现。
# 5. 人脸检测
landmarks = detector.detect(image)
if landmarks is None:
return err(1001, "无法识别人像")
{_image_fields_desc}
# 6. 姿态校验
if not check_frontal_face(landmarks, w, h):
return err(1003, "角度问题，请上传正面照")
head_pose = estimate_head_pose(landmarks, w, h)
图片同时支持 `multipart/form-data` 文件上传（字段名 `image_file`），或 JSON Body 传 `image_url` / `image_base64`。
# 7. 头发分割（方案 B），失败传 None 由 measure 内部回退方案 A
hair_mask = None
try:
from face_analysis.hair_segmenter import get_segmenter
hair_mask = get_segmenter().segment_hair(image)
except Exception as seg_e: # noqa: BLE001
logger.warning("头发分割失败，回退方案A：%s", seg_e)
---
# 8. 测量 + 标注图
result = measure_face(landmarks, hair_mask, w, h, head_pose=head_pose)
annotated = create_annotated_image(image, result)
buf = BytesIO()
annotated.save(buf, format="PNG")
**坐标说明**：所有坐标以原图像素为基准，原点为图片左上角，x 向右，y 向下。
# 9. 拆分架构：返回 base64，不落盘不拼 URL（落盘改 URL 由网关完成）
data = result.to_response()
data["annotated_image_base64"] = base64.b64encode(buf.getvalue()).decode()
return ok(data)
except Exception as ex: # noqa: BLE001
logger.exception("接口1 处理异常")
return err(1007, f"处理失败：{ex}")
**标注图片 UI 规范**（真实版本生效）：
- 字体/线条颜色：`#FFFFFF 100%`
- 四庭数值在图片**左侧**呈现，七眼间距**上下穿插**展示
- 字体：PingFangSC-Regular 10pt，线宽 1pt
- 横线/竖线渐变消失，虚线两侧带箭头
""",
responses={
200: {
"description": "成功",
"content": {
"application/json": {
"example": {
"code": 0,
"message": "success",
"request_id": "mock-request-id",
"data": {
"annotated_image_url": SAMPLE_IMAGE_URL,
"face_total_height_cm": 13.76,
"four_courts": {
"top_court_cm": 3.44,
"upper_court_cm": 3.44,
"middle_court_cm": 3.44,
"lower_court_cm": 3.44,
"ratios": {
"top_court": 0.25,
"upper_court": 0.25,
"middle_court": 0.25,
"lower_court": 0.25,
},
},
"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},
},
"landmarks": {
"hair_top": {"x": 540, "y": 120},
"hairline": {"x": 540, "y": 430},
"brow_center": {"x": 540, "y": 740},
"nose_bottom": {"x": 540, "y": 1050},
"chin_tip": {"x": 540, "y": 1360},
},
},
}
}
},
},
400: {
"description": "参数错误 / 图片识别失败",
"content": {
"application/json": {
"examples": {
"图片参数错误": {"value": {"code": 1007, "message": "图片参数错误：必须且只能传 image_file / image_url / image_base64 其中一个", "request_id": "x", "data": None}},
"无法识别人像": {"value": {"code": 1001, "message": "无法识别人像", "request_id": "x", "data": None}},
"多张人脸": {"value": {"code": 1005, "message": "检测到多张人脸，仅支持单人照片", "request_id": "x", "data": None}},
}
}
},
},
},
)
async def face_measure_v2(
image_file: Optional[UploadFile] = File(default=None, description="上传图片文件（JPG/PNG，≤ 1 MB）"),
image_url: Optional[str] = Form(default=None, description="图片 URL"),
image_base64: Optional[str] = Form(default=None, description="图片 base64（需带 data:image/...;base64, 前缀）"),
):
"""接口6：四庭七眼测量标注 v2（复刻接口1）"""
ok_data, err_data = await _face_measure_impl(image_file, image_url, image_base64)
return ok_data if ok_data is not None else err_data
# ---------------------------------------------------------------------------
docs/实现说明.md
+7 -1
View File
@@ -13,7 +13,7 @@
```
客户端 ──HTTPS──> 外网网关(gateway/) ──HTTP(X-Internal-Token)──> worker(GPU 机, app.py)
│ 薄代理 + 落盘改URL │ 跑算法(本地模型/ComfyUI)
└ 接口4 本机直接调豆包(不转发) └ 接口1/2/3/5/7
└ 接口4 本机直接调豆包(不转发) └ 接口1/2/3/5/6/7
```
- **worker**（`app.py` + `face_analysis/` + `hairline/`）：跑真正的算法，**纯本地、无外网依赖**。
@@ -29,6 +29,7 @@
| 接口 | worker 字段（内部） | 对外字段 |
|------|--------------------|----------|
| 1 | `annotated_image_base64` | `annotated_image_url` |
| 6 | `annotated_image_base64` | `annotated_image_url` |
| 2 | `results[].image_base64` / `results[].grown_image_base64`(可空) | `results[].image_url` / `results[].grown_image_url` |
| 3 | `hair_growth_image_base64`(可空) | `hair_growth_image_url` |
| 5 | `hairline_images[].image_base64` | `hairline_images[].image_url` |
@@ -55,6 +56,11 @@
失败回退比例推算(方案A，`hairline_source` 透出)。标注图 numpy 向量化渐变线 + 思源黑体。返回 `annotated_image_base64`。
- 门槛可配：`MIN_SHORT_SIDE`/`MIN_LONG_SIDE`(默认600/800)、姿态阈值 `FRONTAL_*_THR`(默认30°)。
### 接口6 四庭七眼测量 v2 `/api/v1/face/measure-v2`（worker）—— 复刻接口1
- **做什么**：与接口 1 完全一致（正面照 → 四庭七眼 cm 与占比 + 5 个关键点 + 标注 PNG）。
- **怎么实现**：与接口 1 共用 `_face_measure_impl()`，零额外逻辑。对外路径 `/api/v1/face/measure-v2`。
- **网关改动**：新增路由 `POST /api/v1/face/measure-v2`，转发到 worker 同路径；base64→URL 改写无需改动。
### 接口2 C端生发 `/api/v1/hair/grow`（worker）—— 预览 + 生发图
- **做什么**：正面照 + `gender`(必填) + `hair_style`(必填，逗号分隔多选，如 `1,2,3`) → 指定发际线类型 **N 组**：**预览图**(发际线叠在照片上) + **生发后图**(植发3个月效果)。
- **怎么实现**（`hairline/`）：移植 head3d——MediaPipe(Tasks) + SegFormer 分割 + 17 锚点射线检测 → 502 点 mesh，
docs/接口文档.md
+54 -1
View File
@@ -15,6 +15,7 @@
| 接口 | 方法 | 路径 |
|------|------|------|
| 1 四庭七眼测量 | POST | `/api/v1/face/measure` |
| 6 四庭七眼测量 v2 | POST | `/api/v1/face/measure-v2` |
| 2 C 端生发 | POST | `/api/v1/hair/grow` |
| 3 B 端生发 | POST | `/api/v1/hair/grow-b` |
| 4 用户特征 | POST | `/api/v1/face/features` |
@@ -176,6 +177,57 @@
---
## 接口 6：四庭七眼测量 v2 接口
**说明**：功能与[接口 1](#接口-1四庭七眼测量标注接口)完全一致，复刻实现。输入用户正面照，返回四庭七眼测量数据和标注 PNG。
**请求**：`POST /api/v1/face/measure-v2`
### 输入
与接口 1 完全相同。图片参数见「通用约定 → 图片传参字段」（`image_file` / `image_url` / `image_base64` 三选一）。本接口无其他专属参数。
### 输出（data）
与接口 1 完全相同。详见[接口 1 输出](#接口-1四庭七眼测量标注接口)。
| 字段 | 类型 | 说明 |
|------|------|------|
| annotated_image_url | string | 标注图层 PNG URL（透明底，仅标注线/文字，不含人物） |
| face_total_height_cm | number | 面部总高度（cm） |
| four_courts | object | 四庭数据（顶庭/上庭/中庭/下庭，各含 cm 与 ratio） |
| seven_eyes | object | 七眼数据（眼宽/脸宽/两眼间距，各含 cm 与 ratio） |
| landmarks | object | 五个关键点像素坐标 |
### 响应示例
```json
{
"code": 0,
"message": "success",
"request_id": "mock-request-id",
"data": {
"annotated_image_url": "https://hair.xiangsilian.com/static/sample.jpg",
"face_total_height_cm": 13.76,
"four_courts": {
"top_court_cm": 3.44, "upper_court_cm": 3.44, "middle_court_cm": 3.44, "lower_court_cm": 3.44,
"ratios": { "top_court": 0.25, "upper_court": 0.25, "middle_court": 0.25, "lower_court": 0.25 }
},
"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 }
},
"landmarks": {
"hair_top": { "x": 540, "y": 120 }, "hairline": { "x": 540, "y": 430 },
"brow_center": { "x": 540, "y": 740 }, "nose_bottom": { "x": 540, "y": 1050 },
"chin_tip": { "x": 540, "y": 1360 }
}
}
}
```
---
## 接口 2：C 端生发接口
**说明**：输入用户正面照 + 性别 + 发型序号（可多选），按指定发际线类型渲染预览图 + 生发图。
@@ -421,7 +473,8 @@
| 接口 | 输入 | 主要输出 |
|------|------|----------|
| 1 四庭七眼测量 | 用户照片 | 标注 PNG（无人物）+ 四庭/七眼厘米数值与坐标 |
| 2 C 端生发 | 用户照片 | 生发后图片 + 指定发际线预览（单张） |
| 6 四庭七眼测量 v2 | 用户照片 | 同接口1，复刻实现 |
| 2 C 端生发 | 用户照片 | 生发后图片 + 指定发际线预览（单/多张） |
| 3 B 端生发 | 划线图片 | 最合适发际线图片 + 生发后图片 |
| 4 用户特征 | 用户照片 | 6 个用户特征字段（脸形/眉形/年龄/动静/性别/基因风格） |
| 5 发际线 PNG | 用户照片 | N 张发际线 PNG + 最合适发际线面部中间点坐标 |
docs/网关待改动.md
+24
View File
@@ -109,6 +109,30 @@ async def hair_grow_v2(request: Request):
若想让网关 `/docs` 展示准确，在 `gateway/app.py` 新增 `_GROW_V2_FORMS`（或复用 `_GROW_FORMS` 并补充 `gender`/`hair_style` 字段），然后将路由函数签名改为显式声明 Form 参数（参考接口 4 的写法）。不改也不影响实际转发。
---
## 6. 🔲【新增】接口6 四庭七眼测量 v2（`/api/v1/face/measure-v2`）
**背景**：worker 侧已新增接口 6，功能与接口 1 完全一致（复刻），共用同一实现。
**网关需新增一个路由**：
```python
# gateway/app.py
@app.post("/api/v1/face/measure-v2", tags=["人脸分析"])
async def face_measure_v2(request: Request):
"""接口6：四庭七眼测量 v2（复刻接口1）"""
return await _proxy(request, "/api/v1/face/measure-v2")
```
**无需额外改动**：
- 入参：与接口 1 完全相同（image_file/url/base64 三选一）
- 出参：`annotated_image_base64` → 经现有 `rewrite_base64_to_url` 自动改写为 `annotated_image_url`
- worker 侧与接口 1 共用 `_face_measure_impl()`，逻辑零差异
---
## 已经做好、无需再动的