M2FP更新日志：新增自动颜色映射，提升可视化体验

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

在计算机视觉领域，人体解析（Human Parsing）是一项关键的细粒度语义分割任务，旨在将人体分解为多个语义明确的部位，如面部、头发、左臂、右腿、上衣、鞋子等。与普通的人体分割不同，人体解析不仅识别“人”这一整体，更进一步区分其内部结构，广泛应用于虚拟试衣、动作分析、智能安防和AR/VR场景中。

M2FP（Mask2Former-Parsing）是基于 ModelScope 平台推出的先进多人人体解析模型，专为复杂真实场景设计。它继承了 Mask2Former 架构的强大建模能力，并针对人体部位的精细化语义进行了专项优化。该模型以ResNet-101作为骨干网络，在 COCO-Person 和 LIP 等主流人体解析数据集上表现优异，能够精准处理多人重叠、姿态多变、部分遮挡等挑战性场景。

本项目封装了一个开箱即用的WebUI + API 一体化服务镜像，集成 M2FP 模型推理引擎与 Flask 轻量级后端框架，支持通过浏览器直接上传图像并实时查看解析结果。更重要的是，本次更新引入了全新的自动颜色映射机制（Auto Color Mapping），显著提升了分割结果的可视化效果和用户体验。

💡 核心亮点升级版： - ✅新增自动颜色映射系统：告别单调灰阶输出，每类身体部位自动分配唯一且高辨识度的颜色。 - ✅环境极度稳定：锁定 PyTorch 1.13.1 + MMCV-Full 1.7.1 黄金组合，彻底解决tuple index out of range与_ext缺失等常见报错。 - ✅内置拼图算法：将模型返回的离散二值掩码（Mask List）自动合成为一张完整的彩色语义图。 - ✅CPU 友好型部署：无需 GPU 支持，经深度优化后可在纯 CPU 环境下实现秒级推理。 - ✅双模式访问：既可通过 WebUI 图形界面操作，也可调用 RESTful API 集成到其他系统。

🎨 技术革新：自动颜色映射如何工作？

1. 传统问题：原始 Mask 的“不可读性”

M2FP 模型底层输出是一组二值掩码列表（Binary Mask List），每个掩码对应一个检测到的人体实例及其各个部位。例如：

masks = [ { "label": "hair", "mask": (H, W) binary array }, { "label": "face", "mask": (H, W) binary array }, { "label": "upper_cloth", "mask": (H, W) binary array }, ... ]

这些掩码本身是黑白图像，缺乏直观色彩信息。若直接叠加显示，用户难以快速分辨哪块区域代表什么部位——这严重影响了交互体验和实际应用效率。

2. 解决方案：构建语义-颜色映射表

为此，我们在后处理阶段设计了一套静态语义颜色查找表（Semantic Color LUT），为每一个预定义的身体部位标签分配一个固定的 RGB 颜色值。该映射表如下所示：

| 标签（Label） | RGB 颜色（示例） | |---------------------|------------------| | background | (0, 0, 0) | | hair | (255, 0, 0) | | face | (255, 85, 0) | | upper_cloth | (255, 170, 0) | | lower_cloth | (255, 255, 0) | | dress | (170, 255, 0) | | coat | (85, 255, 0) | | shoes | (0, 255, 0) | | hat | (0, 255, 85) | | ... | ... |

这套配色方案经过精心挑选，确保相邻类别间颜色差异明显，避免视觉混淆，同时兼顾美观性和可区分性。

3. 实现流程：从 Mask 到彩色分割图

以下是自动颜色映射的核心实现逻辑（Python 伪代码）：

import numpy as np import cv2 # 定义颜色映射表（共19类） COLOR_MAP = [ [0, 0, 0], # background [255, 0, 0], # hair [255, 85, 0], # face [255, 170, 0], # upper_cloth [255, 255, 0], # lower_cloth [170, 255, 0], # dress [85, 255, 0], # coat [0, 255, 0], # shoes [0, 255, 85], # hat [0, 255, 170], # bag [0, 255, 255], # scarf [0, 170, 255], # left_arm [0, 85, 255], # right_arm [0, 0, 255], # left_leg [85, 0, 255], # right_leg [170, 0, 255], # left_shoe [255, 0, 255], # right_shoe [255, 0, 170], # skin [255, 0, 85], # pants ] def apply_color_mapping(masks, labels, image_shape): """ 将一组二值掩码转换为彩色语义分割图 :param masks: list of (H, W) binary arrays :param labels: list of str, each corresponding to mask :param image_shape: (H, W, 3) :return: colored_output (H, W, 3) """ h, w = image_shape[:2] output = np.zeros((h, w, 3), dtype=np.uint8) for mask, label in zip(masks, labels): class_id = get_class_id(label) # 映射 label -> id color = COLOR_MAP[class_id % len(COLOR_MAP)] # 使用 OpenCV 将 mask 区域染色 colored_region = np.stack([mask * c for c in color], axis=-1) output = np.where(np.any(output > 0, axis=-1, keepdims=True), output, # 已有颜色则保留（防止覆盖） colored_region.astype(np.uint8)) return output

📌 关键点说明： - 使用np.where实现非透明叠加，优先保留先绘制的主体区域，避免边缘重叠导致颜色错乱。 - 所有颜色操作均在 CPU 上完成，利用 NumPy 向量化运算保证效率。 - 支持动态扩展新标签，只需在COLOR_MAP中追加即可。

🧩 系统架构与模块整合

整个 M2FP 服务采用前后端分离 + 模型服务化的设计理念，整体架构如下：

+------------------+ +-------------------+ +--------------------+ | 用户浏览器 | <-> | Flask Web Server | <-> | M2FP Model Inference | | (WebUI / API) | | (REST Endpoint) | | (ModelScope Pipeline)| +------------------+ +-------------------+ +--------------------+

各模块职责详解：

| 模块 | 功能描述 | |------|----------| |Flask WebUI| 提供图形化界面，支持图片上传、结果显示、错误提示；使用 Jinja2 渲染前端页面 | |API 接口层| 开放/parse接口，接收 POST 请求中的图像文件，返回 JSON 或图像流 | |图像预处理| 使用 OpenCV 调整输入尺寸至 480x640，归一化像素值，适配模型输入要求 | |M2FP 推理管道| 基于 ModelScope 的pipeline()构建，加载预训练权重并执行前向推理 | |后处理引擎| 执行自动颜色映射 + 拼图合成，生成最终可视化图像 | |响应生成| 将结果编码为 base64 或直接返回 PNG 流，兼容 Web 展示与程序调用 |

🚀 快速使用指南

步骤 1：启动服务

假设你已拉取 Docker 镜像或配置好本地环境，请运行以下命令启动服务：

python app.py --host 0.0.0.0 --port 7860

服务启动后，访问平台提供的 HTTP 链接（如http://<your-ip>:7860）进入 WebUI 页面。

步骤 2：上传图像并查看结果

点击“上传图片”按钮，选择一张包含单人或多个人物的照片。
系统将在3~8 秒内（取决于 CPU 性能）完成推理。
右侧面板将展示：
原始图像（左侧）
彩色语义分割图（右侧），不同颜色代表不同身体部位
黑色区域表示背景未被分类

示例输出说明：

| 颜色 | 对应部位 | |------|----------| | 🔴 红色 | 头发 | | 🟠 橙色 | 脸部 | | 🟡 黄色 | 上衣 | | 🟢 绿色 | 裤子/下装 | | 🔵 蓝色 | 鞋子 | | 🟣 紫色 | 手套/配饰（如有） |

⚠️ 注意：由于模型训练数据限制，某些小众服饰（如泳装、汉服）可能被近似归类为通用类别。

💡 API 调用方式（适用于自动化集成）

除了 WebUI，你还可以通过编程方式调用该服务。以下是一个使用 Pythonrequests发送请求的示例：

import requests from PIL import Image import io # 设置目标 URL url = "http://localhost:7860/parse" # 准备图像文件 with open("test.jpg", "rb") as f: files = {"image": f} response = requests.post(url, files=files) # 检查状态 if response.status_code == 200: # 返回的是 PNG 图像流 result_image = Image.open(io.BytesIO(response.content)) result_image.show() else: print("Error:", response.json())

对应的 Flask 路由实现如下：

@app.route('/parse', methods=['POST']) def parse(): if 'image' not in request.files: return jsonify({"error": "No image uploaded"}), 400 file = request.files['image'] img_bytes = file.read() nparr = np.frombuffer(img_bytes, np.uint8) image = cv2.imdecode(nparr, cv2.IMREAD_COLOR) try: # 调用 M2FP 模型 result = m2fp_pipeline(image) # 提取 masks 与 labels masks = result["masks"] labels = result["labels"] # 应用颜色映射 colored_output = apply_color_mapping(masks, labels, image.shape) # 编码为 PNG 返回 _, buffer = cv2.imencode('.png', colored_output) return Response(buffer.tobytes(), mimetype='image/png') except Exception as e: return jsonify({"error": str(e)}), 500

📦 依赖环境清单与稳定性保障

为了确保服务在各种环境下都能稳定运行，我们对核心依赖进行了严格锁定：

| 组件 | 版本 | 说明 | |------|------|------| | Python | 3.10 | 兼容最新生态，避免 asyncio 冲突 | | ModelScope | 1.9.5 | 支持 M2FP 模型加载与 pipeline 调用 | | PyTorch | 1.13.1+cpu |修复 tuple index out of range 错误，CPU 版本无 CUDA 依赖 | | MMCV-Full | 1.7.1 |解决 mmcv._ext 找不到的问题，提供必要的 CUDA/CPU 算子 | | OpenCV | 4.5+ | 图像编解码、掩码叠加、性能优化 | | Flask | 2.3.3 | 轻量级 Web 框架，低内存占用 |

🔧 特别说明：
我们曾测试过 PyTorch 2.x 版本，但在 CPU 模式下频繁出现RuntimeError: tuple index out of range，经排查为 MMCV 与新版 Torch JIT 的兼容性问题。因此，最终选定PyTorch 1.13.1 + MMCV-Full 1.7.1这一经典组合，实测零报错、高稳定性，特别适合生产级 CPU 部署。