开源协议说明：M2FP遵循Apache 2.0，允许商用与二次开发

🧩 M2FP 多人人体解析服务

在计算机视觉领域，人体解析（Human Parsing）是一项关键的细粒度语义分割任务，旨在将人体分解为多个语义明确的身体部位，如头发、面部、上衣、裤子、手臂等。与传统的人体姿态估计不同，人体解析不仅关注关键点位置，更强调像素级的精确划分。这一能力在虚拟试衣、智能安防、AR/VR内容生成、人机交互等场景中具有广泛的应用价值。

然而，大多数现有方案受限于单人处理、依赖GPU加速或部署复杂等问题，难以在实际业务中快速落地。为此，我们推出了M2FP 多人人体解析服务—— 一个开箱即用、支持多人、无需GPU、具备完整可视化能力的轻量级解决方案。

本项目基于 ModelScope 平台发布的Mask2Former-Parsing（M2FP）模型构建，结合 Flask WebUI 与自研拼图算法，实现了从模型推理到结果可视化的全链路闭环。更重要的是，该项目严格遵循Apache License 2.0开源协议，允许自由用于商业用途，并支持任意形式的二次开发和定制化集成，为企业和开发者提供了极高的灵活性与合规保障。

📖 项目简介

本镜像基于 ModelScope 的M2FP (Mask2Former-Parsing)模型构建。
M2FP 是目前业界领先的语义分割算法，专注于多人人体解析任务。它能精准识别图像中多个人物的不同身体部位（如面部、头发、上衣、裤子、四肢等），并输出像素级的分割掩码。

已集成Flask WebUI，内置自动拼图算法，将模型输出的离散 Mask 实时合成为可视化的彩色分割图。

💡 核心亮点： 1.环境极度稳定：已解决 PyTorch 2.x 与 MMCV 的底层兼容性难题，锁定PyTorch 1.13.1 + MMCV-Full 1.7.1黄金组合，零报错。 2.可视化拼图：针对模型返回的原始 Mask 列表，内置了后处理算法，自动叠加颜色并生成完整的语义分割图。 3.复杂场景支持：基于 ResNet-101 骨干网络，能够有效处理多人重叠、遮挡等复杂场景。 4.CPU 深度优化：针对无显卡环境进行了推理加速，无需 GPU 即可快速出图。

🔍 技术架构概览

整个系统采用模块化设计，分为以下四个核心组件：

| 组件 | 职责 | |------|------| |ModelScope M2FP 模型| 执行多人人体解析，输出每个身体部位的二值掩码列表 | |OpenCV 图像处理器| 负责图像预处理（缩放、归一化）与后处理（色彩映射、融合） | |拼图合成引擎| 将多个独立 Mask 按语义类别着色并合并为一张完整分割图 | |Flask WebUI 服务层| 提供图形界面上传图片、展示结果，并暴露 RESTful API 接口 |

该架构兼顾了性能稳定性与使用便捷性，特别适合边缘设备、本地服务器或低资源环境下的部署需求。

🚀 使用说明

✅ 快速启动流程

启动 Docker 镜像或运行 Python 服务脚本。
访问本地http://localhost:5000（默认端口）进入 WebUI 界面。
点击“上传图片”，选择一张包含人物的照片（单人或多人均可）。
等待几秒后，右侧将显示解析后的结果：
不同颜色代表不同的身体部位（如红色代表头发，绿色代表衣服等）。
黑色区域代表背景。

🖼️ 可视化示例说明

假设输入图像中有两名站立的人物，系统会依次完成以下步骤：

检测与分割：识别出两个人体实例，并对每个人体进行 18 类细分（包括头、眼、鼻、嘴、左臂、右腿等）。
掩码生成：为每一类生成一个二值掩码（0 表示非该类，1 表示属于该类）。
色彩映射：根据预定义调色板为每类分配唯一颜色（例如：头发→红色，上衣→绿色，裤子→蓝色）。
图像融合：将所有着色后的掩码叠加到原图之上，生成最终的语义分割可视化图。

示例调色板片段（共18类）：
python palette = [ [0, 0, 0], # 背景 - 黑色 [255, 0, 0], # 头发 - 红色 [0, 255, 0], # 上半身衣物 - 绿色 [0, 0, 255], # 下半身衣物 - 蓝色 [255, 255, 0], # 左手 - 黄色 ... ]

💻 API 接口调用方式（开发者必看）

除了 WebUI，本项目还暴露了标准的 HTTP API 接口，便于集成到其他系统中。

📥 POST`/parse`

接收图像文件，返回解析结果。

请求示例（Python）

import requests from PIL import Image import io # 准备图像文件 image_path = "test.jpg" files = {'image': open(image_path, 'rb')} # 发送请求 response = requests.post("http://localhost:5000/parse", files=files) # 解析响应 if response.status_code == 200: result_image = Image.open(io.BytesIO(response.content)) result_image.show() else: print("Error:", response.json())

响应格式

成功时返回PNG 格式的合成分割图（带色彩标注）
失败时返回 JSON 错误信息，如：json { "error": "Invalid image format", "code": 400 }

📦 依赖环境清单

为确保跨平台兼容性和运行稳定性，项目已固化以下依赖版本：

| 依赖项 | 版本 | 说明 | |--------|------|------| |Python| 3.10 | 主运行时环境 | |ModelScope| 1.9.5 | 提供 M2FP 模型加载与推理接口 | |PyTorch| 1.13.1+cpu | CPU 版本，避免 CUDA 兼容问题 | |MMCV-Full| 1.7.1 | 修复_ext扩展缺失问题，确保模型正常加载 | |OpenCV| >=4.5 | 图像读取、绘制与拼接 | |Flask| >=2.3.0 | Web 服务框架，提供 UI 与 API 支持 |

⚠️重要提示：若自行构建环境，请务必使用指定版本组合。尤其是mmcv-full==1.7.1与torch==1.13.1的搭配，是避免tuple index out of range和DLL load failed等常见错误的关键。

🛠️ 核心代码实现解析

以下是拼图合成引擎的核心逻辑，封装在一个独立模块puzzle_builder.py中：

# puzzle_builder.py import numpy as np import cv2 from typing import List, Tuple # 定义18类人体部位的颜色映射表（BGR格式） PALETTE = [ [0, 0, 0], # background [0, 0, 255], # hair [0, 128, 0], # upper_body [255, 0, 0], # lower_body [0, 255, 255], # face [255, 255, 0], # left_arm [255, 0, 255], # right_arm [128, 128, 0], # left_leg [128, 0, 128], # right_leg # ... 其余类别省略，实际共18类 ] def merge_masks_to_colormap(masks: List[np.ndarray], h: int, w: int) -> np.ndarray: """ 将多个二值mask合并为彩色语义图 Args: masks: list of binary masks, shape [H, W], len == num_classes h, w: 输出图像高度与宽度 Returns: colored_mask: [H, W, 3] 彩色分割图 """ assert len(masks) == len(PALETTE), "Mask count must match palette length" # 初始化空白图像 colored_mask = np.zeros((h, w, 3), dtype=np.uint8) # 逆序遍历（优先级：后出现的覆盖前面的） for idx in reversed(range(len(masks))): mask = masks[idx] color = PALETTE[idx] # 应用颜色（仅在mask为True的位置） region = (mask > 0) colored_mask[region] = color return colored_mask # 示例调用 # masks = model.predict(image) # 获取18个mask # result = merge_masks_to_colormap(masks, H, W) # cv2.imwrite("output.png", result)

关键技术点说明：

颜色叠加顺序控制：采用反向遍历策略，确保高优先级区域（如面部、手部）不会被衣物遮盖。
内存效率优化：直接操作 NumPy 数组，避免频繁创建临时图像对象。
通道格式统一：OpenCV 使用 BGR，而多数调色板以 RGB 定义，需注意转换一致性。

🔄 自定义扩展建议（二次开发指南）

由于项目采用 Apache 2.0 协议发布，您可自由进行以下类型的二次开发：

✅ 允许的操作（符合协议条款）

商业用途：可用于电商虚拟试衣系统、AI健身教练、数字人建模等盈利项目。
修改源码：调整模型输入尺寸、增加新类别、更换前端UI框架。
打包分发：将服务封装为独立软件产品或SaaS平台对外提供。
与其他代码组合：集成进自有系统，无需公开整体源码。

🎯 推荐扩展方向

性能增强
引入 TensorRT 或 ONNX Runtime 进一步提升 CPU 推理速度
添加异步队列机制，支持批量图片处理
功能拓展
增加姿态关键点检测（Pose Estimation）联动显示
支持视频流解析（通过 OpenCV 读取摄像头或文件）
部署优化
构建轻量化 Docker 镜像（Alpine Linux + 多阶段构建）
集成 Nginx 做反向代理与静态资源缓存
API 增强
返回结构化 JSON 数据（含各 mask 的 base64 编码）
增加分段下载、进度通知等企业级特性

⚖️ Apache 2.0 开源协议详解

本项目明确声明遵循Apache License, Version 2.0，这是目前最宽松且商业友好的开源许可证之一。

主要权利与义务如下：

| 权利 | 说明 | |------|------| | ✅ 免费使用 | 可免费用于个人、教育或商业项目 | | ✅ 修改代码 | 可任意修改源码以适应自身需求 | | ✅ 分发副本 | 可重新分发原始或修改后的版本 | | ✅ 用于专有软件 | 可将代码整合进闭源商业产品 |

| 义务 | 说明 | |------|------| | 🔒 保留版权与许可声明 | 所有副本中必须包含原始 LICENSE 文件和 NOTICE 文本 | | 📄 明确变更说明 | 若修改源码，应在文件中注明“此文件已被修改” | | ❌ 不授予商标权 | 不得使用原作者名称或项目名进行推广 |

📚 完整协议文本见：https://www.apache.org/licenses/LICENSE-2.0

与其他常见协议对比：

| 协议类型 | 是否允许商用 | 是否要求开源衍生作品 | 商业友好度 | |---------|---------------|------------------------|-------------| |Apache 2.0| ✅ 是 | ❌ 否 | ⭐⭐⭐⭐⭐ | | MIT | ✅ 是 | ❌ 否 | ⭐⭐⭐⭐☆ | | GPL-3.0 | ✅ 是 | ✅ 是（传染性） | ⭐⭐☆☆☆ | | AGPL-3.0 | ✅ 是 | ✅ 是（含网络服务） | ⭐☆☆☆☆ |

可见，Apache 2.0 在保护原作者权益的同时，最大程度释放了使用者的自由度，非常适合企业级应用集成。

🧪 实测表现与适用场景

我们在多种真实场景下测试了 M2FP 的解析效果：

| 场景 | 表现评价 | |------|----------| | 单人正面照 | 分割准确，细节清晰（睫毛、手指等小区域也能识别） | | 多人合影（3~5人） | 能正确区分个体，处理轻微遮挡 | | 动作夸张（跳跃、舞蹈） | 四肢分割略有误差，但整体连贯 | | 光照不足或背光 | 头发与面部边界模糊，建议预处理增强亮度 |