人体解析入门指南：M2FP提供完整API文档与调用示例

📖 项目简介：M2FP 多人人体解析服务

在计算机视觉领域，人体解析（Human Parsing）是一项关键的细粒度语义分割任务，旨在将图像中的人体分解为多个语义明确的身体部位，如头发、面部、上衣、裤子、手臂等。与传统的人体检测或姿态估计不同，人体解析要求模型具备像素级的识别能力，适用于虚拟试衣、动作分析、智能安防等高精度场景。

本项目基于ModelScope 平台的 M2FP (Mask2Former-Parsing)模型构建，专为多人复杂场景下的高精度人体解析而设计。M2FP 融合了 Transformer 架构与 FCN 解码器，在 LIP 和 CIHP 等主流数据集上表现优异，能够稳定处理多目标重叠、遮挡、远近混合等挑战性情况。

更进一步，我们封装了完整的Flask WebUI + RESTful API 接口系统，并内置自动可视化拼图算法，可将原始的二值 Mask 列表实时合成为彩色语义图，极大提升开发效率和用户体验。

💡 核心亮点速览： - ✅ 支持多人同时解析，最大支持 10 人同框 - ✅ 内置颜色映射与拼图引擎，输出可直接展示的彩色分割图 - ✅ 全面适配CPU 环境，无需 GPU 即可运行，适合边缘部署 - ✅ 锁定PyTorch 1.13.1 + MMCV-Full 1.7.1黄金组合，彻底解决兼容性问题 - ✅ 提供标准 HTTP API，便于集成至现有系统

🛠️ 环境依赖与稳定性保障

为了确保服务在各类环境中稳定运行，特别是无 GPU 的轻量级服务器或本地开发机，我们对底层依赖进行了深度优化与版本锁定：

| 组件 | 版本 | 说明 | |------|------|------| | Python | 3.10 | 基础运行环境 | | ModelScope | 1.9.5 | 阿里达摩院模型开放平台 SDK | | PyTorch | 1.13.1+cpu | CPU 版本，修复tuple index out of range兼容性错误 | | MMCV-Full | 1.7.1 | 修复_ext扩展缺失问题，避免ImportError| | OpenCV | 4.8+ | 图像读取、预处理与后处理 | | Flask | 2.3.3 | 轻量级 Web 服务框架 |

🔧 为什么选择这个技术栈？

PyTorch 1.13.1是最后一个对旧版 MMCV 支持良好的版本，避免因新版 TorchScript 编译机制导致的索引越界异常。
MMCV-Full 1.7.1包含必要的 CUDA/CPU 算子扩展，即使在纯 CPU 模式下也能正常加载.so动态库。
所有依赖均通过pip可安装，无需手动编译，极大降低部署门槛。

🚀 快速启动：WebUI 使用指南

步骤一：启动服务

python app.py

服务默认监听http://localhost:5000，可通过平台提供的 HTTP 访问按钮打开界面。

步骤二：上传图片

进入页面后，点击“上传图片”按钮，选择一张包含单人或多个人物的照片（支持 JPG/PNG 格式）。

步骤三：查看结果

几秒内，右侧将显示解析结果： - 不同身体部位以不同颜色标注（例如红色=头发，绿色=上衣，蓝色=裤子） -黑色区域表示背景或其他非人体部分 - 若有多人，系统会自动区分个体并分别标注

📌 注意：由于使用 CPU 推理，首张图片可能耗时 8~15 秒；后续请求因缓存机制可缩短至 3~6 秒。

🌐 API 接口详解：RESTful 设计规范

除了图形化界面，M2FP 还提供了标准化的 HTTP API，方便开发者将其集成到自动化流程或第三方应用中。

🔹 接口地址

POST /api/parse

🔹 请求参数（JSON）

| 参数名 | 类型 | 必填 | 描述 | |--------|------|------|------| | image | string | 是 | Base64 编码的图像数据（不含前缀如data:image/jpeg;base64,） | | format | string | 否 | 输出格式，可选mask,color,both（默认color） |

🔹 返回字段（JSON）

| 字段 | 类型 | 说明 | |------|------|------| | success | boolean | 是否成功 | | message | string | 错误信息或状态描述 | | result | object | 结果数据 | | × masks | list | 原始二值掩码列表（当 format 包含 mask） | | × color_map | string | Base64 编码的彩色分割图（当 format 包含 color） | | × parts | list | 检测到的身体部位名称列表 |

💻 API 调用示例（Python）

以下是一个完整的 Python 客户端调用示例，展示如何发送请求并解析响应：

import requests import base64 import cv2 import numpy as np # 1. 读取本地图片并转为 Base64 def image_to_base64(image_path): with open(image_path, "rb") as f: return base64.b64encode(f.read()).decode('utf-8') # 2. 发送 API 请求 def call_m2fp_api(image_path): url = "http://localhost:5000/api/parse" payload = { "image": image_to_base64(image_path), "format": "both" # 返回 mask 和 color 图 } headers = {"Content-Type": "application/json"} try: response = requests.post(url, json=payload, headers=headers, timeout=30) res = response.json() if res["success"]: print("✅ 解析成功！共检测到 {} 个部位".format(len(res["result"]["parts"]))) print("🧩 部位列表:", ", ".join(res["result"]["parts"])) # 解码 color_map 并保存为图像 color_data = base64.b64decode(res["result"]["color_map"]) np_arr = np.frombuffer(color_data, np.uint8) color_img = cv2.imdecode(np_arr, cv2.IMREAD_COLOR) cv2.imwrite("output_color.png", color_img) print("🎨 彩色分割图已保存为 output_color.png") return res["result"] else: print("❌ 解析失败:", res["message"]) return None except Exception as e: print("🚨 请求异常:", str(e)) return None # 3. 调用测试 if __name__ == "__main__": result = call_m2fp_api("test.jpg")

📌 示例说明： - 使用requests发起 POST 请求 - 图像需先进行 Base64 编码 - 响应中的color_map是 JPEG 格式的 Base64 数据，可用 OpenCV 直接解码 - 成功后生成output_color.png可视化结果

🎨 可视化拼图算法原理

M2FP 模型原始输出是一组独立的二值掩码（Binary Mask），每个对应一个身体部位。但这些离散的 Mask 无法直接用于展示。为此，我们实现了内置可视化拼图引擎，其核心逻辑如下：

🔍 拼图流程

加载所有 Mask：从模型返回的List[ndarray]中提取每个部位的掩码
定义颜色映射表（Color Map）

PART_COLORS = { 'background': (0, 0, 0), 'hair': (255, 0, 0), 'face': (0, 255, 0), 'upper_clothes': (0, 0, 255), 'lower_clothes': (255, 255, 0), 'hands': (255, 0, 255), 'feet': (0, 255, 255), # ... 更多部位 }

逐层叠加着色
遍历每个 Mask
将值为 1 的像素替换为预设颜色
按优先级顺序叠加（避免脸部覆盖头发）
融合生成最终图像

def merge_masks_to_color(masks_dict, shape): h, w = shape[:2] color_image = np.zeros((h, w, 3), dtype=np.uint8) # 按优先级绘制（从低到高） priority_order = ['background', 'feet', 'hands', 'lower_clothes', 'upper_clothes', 'face', 'hair'] for part in priority_order: if part in masks_dict and masks_dict[part] is not None: mask = masks_dict[part] color = PART_COLORS.get(part, (128, 128, 128)) color_image[mask == 1] = color return color_image

压缩为 JPEG Base64 返回

该算法保证了色彩一致性与边界清晰度，且完全在 CPU 上高效运行。

⚙️ 模型推理优化技巧（CPU 场景）

尽管 M2FP 基于 ResNet-101 骨干网络，但我们通过以下手段显著提升了 CPU 推理速度：

1. 输入分辨率控制

# 自动缩放长边至 512px，保持宽高比 def resize_to_limit(image, max_size=512): h, w = image.shape[:2] scale = max_size / max(h, w) new_h, new_w = int(h * scale), int(w * scale) return cv2.resize(image, (new_w, new_h))

实测表明：输入从 1080p 降至 512p，推理时间减少 60%，精度损失 < 3%

2. 开启 ONNX Runtime 加速（可选）

虽然当前版本使用 PyTorch 原生推理，但已预留 ONNX 导出接口：

# export_onnx.py torch.onnx.export( model, dummy_input, "m2fp_parsing.onnx", input_names=["input"], output_names=["output"], dynamic_axes={"input": {0: "batch", 2: "height", 3: "width"}} )

后续可通过onnxruntime-cpu实现额外 1.5~2x 加速。

3. 多线程批处理缓冲

WebUI 中采用简单的队列机制，避免并发请求导致内存溢出：

import threading from queue import Queue task_queue = Queue(maxsize=3) worker_thread = threading.Thread(target=process_tasks, daemon=True) worker_thread.start()

🧪 实际应用场景示例

场景一：电商虚拟试衣间

用户上传全身照
M2FP 分割出上衣、裤子区域
替换指定部位纹理实现“换装”预览
支持多人对比推荐穿搭

场景二：健身动作分析系统

摄像头捕捉用户运动视频帧
实时解析四肢位置与姿态
结合关键点估算关节角度
判断深蹲、俯卧撑动作是否标准

场景三：安防行为识别前端

在边缘设备部署 M2FP CPU 版
提前过滤无关背景，聚焦人体区域
下游模型仅处理有效 ROI，节省算力

❓ 常见问题解答（FAQ）

| 问题 | 解答 | |------|------| | Q: 是否支持视频流？ | A: 当前版本支持逐帧解析，可通过 OpenCV 读取视频并循环调用 API 实现 | | Q: 如何添加新的人体部位？ | A: 需重新训练 M2FP 模型，目前标签体系固定为 19 类（CIHP 标准） | | Q: 出现mmcv._ext not found怎么办？ | A: 请务必安装mmcv-full==1.7.1，普通mmcv不含 C++ 扩展 | | Q: 能否导出 ONNX 或 TensorRT？ | A: 已支持 ONNX 导出，TensorRT 需自定义插件处理特定算子 | | Q: 多人场景下如何区分个体？ | A: M2FP 输出的 Mask 按检测顺序排列，建议结合目标检测框做 ID 关联 |