简介：这份资源是基于MaskRCNN实现猫脸分割的完整项目包，面向计算机、人工智能、数据科学等相关专业的在校学生、教师及企业开发者，可用于课程设计、毕业设计、大作业或初期项目立项演示，也适合深度学习入门者进阶学习。压缩包共22个文件，约11.16MB，包含6个Python源码文件（训练、测试及配置脚本）、10张png效果图、2个数据集压缩包、2个md与2个txt说明文档，覆盖从数据准备到模型训练测试的完整流程，并支持自定义数据集替换。项目代码经过运行验证，稳定可靠，目录结构清晰，便于快速上手与二次开发。目前已有343人学习下载，读者可借此掌握MaskRCNN实例分割的核心思路、猫脸区域提取方法及数据集组织方式，并在此基础上DIY其他目标分割功能，具备较高的学习借鉴与实战参考价值。
1. 猫脸分割这件事，为什么值得从 Mask R-CNN 开始动手
猫脸分割听起来像个玩具项目，但真正做过的人都知道，它把实例分割里最典型的几个难点全凑齐了：目标姿态变化大、毛发边缘模糊、遮挡频繁、同类目标可能紧挨在一起。你拿它练手，等于一次性把数据标注、骨干网络选型、掩码分支调参、推理后处理这几条链路都走了一遍。而 Mask R-CNN 作为两阶段实例分割的经典结构，检测框和掩码双分支输出，恰好能让你把「先定位再分割」的思路吃透。这份「源码+数据集」的组合，核心价值不在于猫本身，而在于它提供了一套可替换数据集的完整训练管线——你把猫换成工业零件、医学影像、农作物，流程几乎不用大改。适合谁？适合已经跑通过分类或检测、想往实例分割迈一步的工程师，也适合需要快速验证自定义数据集可行性的团队。
2. 把 Mask R-CNN 的猫脸分割管线拆开看：从输入到掩码的完整链路
2.1 两阶段结构到底在猫脸上做了什么
Mask R-CNN 的推理过程可以拆成四步。第一步，输入图像经过骨干网络（常见做法是 ResNet-50 或 ResNet-101 配合 FPN）提取多尺度特征图。第二步，RPN（区域提议网络）在特征图上生成候选框，每个框带一个前景/背景的置信度。第三步，ROI Align 把每个候选框对应的特征区域裁剪并对齐成固定尺寸——这里注意，ROI Align 用双线性插值替代了 ROI Pooling 的量化取整，对猫脸这种小目标、边缘精细的场景，掩码精度提升非常明显。第四步，分类头输出类别和精修框，掩码头对每个类别输出一张 28×28 的二值掩码。
为什么猫脸分割特别依赖 ROI Align？因为猫的胡须、耳朵尖、眼眶边缘在特征图上只占几个像素，量化误差会把它们直接抹掉。我一般会在配置文件里确认 ROI Align 的采样点数设为 2，这个值在自定义数据集上比默认的 0 更稳。
2.2 数据集目录结构与标注格式的硬性要求
这份数据集通常按 COCO 格式组织，目录结构大致如下：
dataset/ ├── annotations/ │ ├── instances_train.json │ └── instances_val.json ├── train/ │ ├── cat_001.jpg │ ├── cat_002.jpg │ └── ... └── val/ ├── cat_101.jpg └── ...标注文件必须是 COCO JSON，关键字段包括images、annotations、categories。猫脸分割的segmentation字段用多边形点集表示，每个实例一组[[x1,y1,x2,y2,...]]。如果你要自定义数据集，最省事的路径是用 LabelMe 标注后转 COCO，或者直接用 CVAT 导出 COCO 格式。
注意：多边形点数不要少于 6 个，猫脸轮廓如果只点 4 个点，掩码会变成菱形，训练时 loss 降不下去。
2.3 环境搭建与依赖版本锁定
我一般用 Python 3.8 + PyTorch 1.10 + torchvision 0.11 这套组合，CUDA 选 11.3。检测框架用 Detectron2 或 MMDetection 都行，但这份源码如果自带训练脚本，优先按它的requirements.txt来。下面是我常用的环境初始化命令：
conda create -n catmask python=3.8 -y conda activate catmask pip install torch==1.10.0+cu113 torchvision==0.11.1+cu113 -f https://download.pytorch.org/whl/torch_stable.html pip install opencv-python pycocotools matplotlib tensorboard逻辑说明：先锁 Python 版本，因为 pycocotools 在 3.9 以上编译容易出问题；PyTorch 和 torchvision 版本必须匹配，否则 ROI Align 的 CUDA 算子会报符号未定义。参数上，CUDA 11.3 对应 cu113 后缀，如果你用的是 11.6，把后缀换成 cu116。
2.4 训练配置里必须改的五个参数
拿到源码后，不要直接python train.py就跑。先打开配置文件，逐项确认下面五个参数：
| 参数名 | 默认值 | 猫脸分割建议值 | 原因 |
|---|---|---|---|
| NUM_CLASSES | 81 | 2（背景+猫脸） | COCO 预训练是 80 类，自定义必须改 |
| SOLVER.IMS_PER_BATCH | 16 | 2 或 4 | 显存不够时优先降这个 |
| SOLVER.BASE_LR | 0.02 | 0.001 | 小数据集上大学习率会震荡 |
| ROI_HEADS.BATCH_SIZE_PER_IMAGE | 512 | 128 | 猫脸实例少，采样太多引入背景噪声 |
| MAX_ITER | 90000 | 3000~5000 | 自定义小数据集不需要训那么久 |
改完这五项，再检查MODEL.ROI_HEADS.SCORE_THRESH_TEST，推理时默认 0.05 太低，猫脸场景建议调到 0.5，否则满屏都是误检框。
3. 用自定义数据集跑通训练：从标注转换到 loss 收敛
3.1 把 LabelMe 标注转成 COCO JSON 的脚本
如果你手头只有 LabelMe 的 JSON，需要先转成 COCO。下面这个脚本我用了很多次，处理猫脸多边形标注没问题：
import json import os from glob import glob def labelme_to_coco(labelme_dir, output_json, category_name="cat_face"): coco = {"images": [], "annotations": [], "categories": []} coco["categories"].append({"id": 1, "name": category_name, "supercategory": "animal"}) ann_id = 1 img_id = 1 for json_path in glob(os.path.join(labelme_dir, "*.json")): with open(json_path, "r", encoding="utf-8") as f: data = json.load(f) img_w = data["imageWidth"] img_h = data["imageHeight"] img_name = data["imagePath"] coco["images"].append({ "id": img_id, "file_name": img_name, "width": img_w, "height": img_h }) for shape in data["shapes"]: if shape["label"] != category_name: continue points = shape["points"] # 展平多边形点集，COCO 要求一维数组 segmentation = [coord for pt in points for coord in pt] xs = [p[0] for p in points] ys = [p[1] for p in points] x_min, x_max = min(xs), max(xs) y_min, y_max = min(ys), max(ys) coco["annotations"].append({ "id": ann_id, "image_id": img_id, "category_id": 1, "segmentation": [segmentation], "bbox": [x_min, y_min, x_max - x_min, y_max - y_min], "area": (x_max - x_min) * (y_max - y_min), "iscrowd": 0 }) ann_id += 1 img_id += 1 with open(output_json, "w", encoding="utf-8") as f: json.dump(coco, f, ensure_ascii=False, indent=2) labelme_to_coco("./labelme_jsons", "./instances_train.json")逻辑说明：segmentation字段必须是[[x1,y1,x2,y2,...]]的嵌套列表，外层列表表示一个实例可以有多个多边形（比如猫脸被遮挡分成两块）。bbox用[x,y,w,h]格式，area用外接矩形面积近似，COCO 评估时会用 segmentation 重新算，所以这里不精确也没关系。参数上，category_name必须和 LabelMe 里的标签名完全一致，大小写敏感。
3.2 注册数据集并启动训练的命令行
Detectron2 注册自定义数据集的代码如下：
from detectron2.data.datasets import register_coco_instances register_coco_instances( "cat_train", {}, "./dataset/annotations/instances_train.json", "./dataset/train" ) register_coco_instances( "cat_val", {}, "./dataset/annotations/instances_val.json", "./dataset/val" )注册完成后，在配置里把DATASETS.TRAIN设为("cat_train",)，DATASETS.TEST设为("cat_val",)。启动训练：
python train_net.py \ --config-file configs/cat_mask_rcnn_R_50_FPN.yaml \ --num-gpus 1 \ SOLVER.IMS_PER_BATCH 2 \ SOLVER.BASE_LR 0.001 \ SOLVER.MAX_ITER 4000 \ MODEL.ROI_HEADS.NUM_CLASSES 2逻辑说明：命令行覆盖配置的好处是不用改文件就能做多组实验。--num-gpus 1表示单卡，如果你有两张卡，改成 2 并把IMS_PER_BATCH翻倍。MAX_ITER 4000配合BASE_LR 0.001，在 500 张猫脸图上大约 40 分钟能跑完，loss 从 2.5 降到 0.3 左右。
3.3 训练过程中看什么指标判断是否正常
启动后重点盯三个数：total_loss、loss_mask、loss_cls。正常情况下，前 200 次迭代total_loss从 2.5 快速降到 1.0 以下，loss_mask从 1.2 降到 0.4 左右。如果loss_mask卡在 0.8 以上不降，八成是掩码标注有问题——要么多边形点太少，要么segmentation格式不对。另一个信号是验证集的mask AP，在 4000 次迭代时应该能到 0.35 以上（猫脸单类，数据量 500 张左右）。如果 AP 一直是 0，检查NUM_CLASSES是不是忘了改。
提示：TensorBoard 里看
loss_mask曲线，如果它比loss_cls高很多且不降，优先怀疑 ROI Align 的采样配置，把POOLER_SAMPLING_RATIO设为 2 试试。
4. 推理与掩码后处理：让猫脸边缘不再像狗啃
4.1 单张图片推理的最小代码
训练完保存的模型可以直接拿来推理：
import cv2 from detectron2.engine import DefaultPredictor from detectron2.config import get_cfg cfg = get_cfg() cfg.merge_from_file("configs/cat_mask_rcnn_R_50_FPN.yaml") cfg.MODEL.WEIGHTS = "output/model_final.pth" cfg.MODEL.ROI_HEADS.SCORE_THRESH_TEST = 0.5 cfg.MODEL.ROI_HEADS.NUM_CLASSES = 2 predictor = DefaultPredictor(cfg) img = cv2.imread("test_cat.jpg") outputs = predictor(img) instances = outputs["instances"] masks = instances.pred_masks.cpu().numpy() # shape: (N, H, W) boxes = instances.pred_boxes.tensor.cpu().numpy() scores = instances.scores.cpu().numpy()逻辑说明：pred_masks是布尔数组，每个实例一张与原图同尺寸的掩码。SCORE_THRESH_TEST设 0.5 是猫脸场景的经验值，低于这个值的框基本是误检。如果你发现漏检多，降到 0.3 再试，但要做好后处理过滤。
4.2 掩码边缘优化的两个实用技巧
Mask R-CNN 输出的 28×28 掩码上采样到原图后，边缘会有锯齿。我一般做两步优化：第一步，用cv2.morphologyEx做闭运算填小孔；第二步，用cv2.GaussianBlur平滑边缘后再二值化。
import numpy as np def refine_mask(mask, kernel_size=5): mask_uint8 = (mask * 255).astype(np.uint8) kernel = np.ones((kernel_size, kernel_size), np.uint8) # 闭运算填内部小孔 closed = cv2.morphologyEx(mask_uint8, cv2.MORPH_CLOSE, kernel) # 高斯平滑后重新二值化，边缘更自然 blurred = cv2.GaussianBlur(closed, (kernel_size, kernel_size), 0) _, refined = cv2.threshold(blurred, 127, 255, cv2.THRESH_BINARY) return refined > 0逻辑说明：kernel_size控制平滑强度，猫脸建议 5，太大耳朵尖会被磨圆。闭运算先填孔，因为猫脸内部如果有白色斑点（比如鼻头高光），掩码会误判为背景。高斯平滑的 sigma 设为 0 表示由 kernel 大小自动推算。
4.3 多只猫重叠时的掩码分离处理
一张图里两只猫挨着，Mask R-CNN 可能输出两个高度重叠的掩码。这时候不能简单叠加，否则重叠区域颜色会加深。我的做法是按 score 排序，从高到低依次绘制，低分掩码只绘制未被高分掩码覆盖的像素：
def merge_masks(masks, scores): order = np.argsort(scores)[::-1] # 按分数降序 canvas = np.zeros(masks[0].shape, dtype=np.uint8) for idx in order: m = masks[idx].astype(np.uint8) # 只填充当前画布上还是 0 的区域 canvas = np.where((canvas == 0) & (m == 1), 1, canvas) return canvas逻辑说明：np.argsort(scores)[::-1]拿到从高到低的索引，np.where保证先画的掩码不被覆盖。这个策略在猫脸紧贴时效果稳定，但如果两只猫颜色接近，视觉上会像一只，需要靠检测框区分。
5. 避坑与排查：猫脸分割训练中最容易翻车的五个地方
5.1 现象：loss 正常下降但 mask AP 始终为 0
原因：NUM_CLASSES没改，模型输出 81 类，评估时按 80 类 COCO 算，你的猫脸类别 id 对不上。解决：确认配置里MODEL.ROI_HEADS.NUM_CLASSES设为 2，并且注册数据集时category_id从 1 开始。
5.2 现象：训练到一半 loss 突然变成 NaN
原因：学习率太大，或者某张图的标注框宽高为 0。解决：先把BASE_LR降到 0.0005，然后在数据加载阶段加一个过滤，跳过bbox宽或高小于 2 像素的标注。我一般会在转换脚本里直接过滤掉面积小于 100 像素的实例。
5.3 现象：推理时掩码整体偏移，框对但掩码错位
原因：ROI Align 的POOLER_SAMPLING_RATIO设为 0 时，某些 PyTorch 版本下采样点计算有 bug。解决：显式设为 2，并在配置里确认POOLER_TYPE是ROIAlign而不是ROIPool。
5.4 现象：猫脸边缘掩码缺一块，尤其是耳朵和下巴
原因：标注时多边形点太稀疏，或者训练时MASK_ON没开。解决：检查配置里MODEL.MASK_ON是否为True，然后重新标注那些边缘缺失的图，多边形点至少 12 个。
5.5 现象：显存溢出，batch size 降到 1 还是 OOM
原因：输入图像分辨率太大，或者MAX_SIZE_TEST没限制。解决：把INPUT.MIN_SIZE_TRAIN设为 (640,)，MAX_SIZE_TRAIN设为 800，推理时MAX_SIZE_TEST设为 1000。猫脸分割不需要 4K 输入，640 短边足够。
6. 把猫脸模型迁移到自定义数据集：三个验证技巧和一个习惯
迁移到自定义数据集时，最怕的是「训练 loss 降了但实际效果不能用」。我一般用三个技巧做验证。第一个，留出 10% 的图完全不参与训练，训练结束后逐张推理，用cv2.addWeighted把掩码叠在原图上，肉眼过一遍。第二个，统计验证集上每个实例的 mask IoU，把低于 0.5 的图单独挑出来，看是标注问题还是模型问题。第三个，用torchvision.ops.nms对检测框做一次后处理 NMS，IoU 阈值设 0.5，能去掉大量重叠误检。
from torchvision.ops import nms def postprocess(outputs, iou_thresh=0.5): boxes = outputs["instances"].pred_boxes.tensor scores = outputs["instances"].scores keep = nms(boxes, scores, iou_thresh) outputs["instances"] = outputs["instances"][keep] return outputs逻辑说明：nms按分数排序后抑制重叠框，猫脸场景iou_thresh设 0.5 比较合适，设 0.3 会误杀紧挨的两只猫。这个后处理在推理脚本里加一次就行，训练时不需要。
还有一个习惯：每次换数据集，先拿 20 张图跑一遍过拟合测试。把MAX_ITER设 200，学习率 0.001，如果 20 张图都过拟合不到 mask AP 0.9 以上，说明管线有问题，别急着上全量数据。这个习惯帮我省过很多次「训了一整天发现标注格式错了」的后悔药。猫脸分割本身不难，难的是把数据、配置、后处理这三块串成一条稳定的流水线。希望帮到你。
本文还有配套的精品资源，点击获取
