如何用 InsightFace 的 SCRFD Person 模型完成全身人物检测？

如何用 InsightFace 的 SCRFD Person 模型完成全身人物检测？

【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface

InsightFace 的 SCRFD Person 检测示例 可以完成一个具体任务：给定一张图片，在一次前向推理中同时输出全身人物的 bounding box，以及该人物当前可见区域的标记。模型是scrfd_person_2.5g.onnx，通过download=True参数自动从官方存储服务器下载到本地，不需要手动找模型文件。最终产物是叠加了标注结果的图片：绿色框表示全身，蓝色掩码表示可见区域。

环境准备

示例入口是 scrfd_person.py，文件开头的版本断言给出了最低要求：

import insightface assert insightface.__version__>='0.4'

安装与升级方式见 examples/README.md 和 examples/person_detection/README.md：

pip install -U insightface

代码中还依赖cv2和numpy来读图、画框和保存结果。运行示例脚本前，需要准备两样东西：

1. 一个可读写的工作目录（脚本从这里读取输入图片）；
2. 一个名为data/images的目录，把待检测的.jpg图片放进去——脚本用glob.glob('data/images/*.jpg')匹配文件。

另外注意脚本结尾会把结果写到./outputs/目录，运行前需确认当前工作目录下已存在该目录，否则cv2.imwrite会失败。

加载并初始化 SCRFD Person 模型

模型加载和参数配置是两行代码，官方示例中的写法是：

detector = insightface.model_zoo.get_model('scrfd_person_2.5g.onnx', download=True) detector.prepare(0, nms_thresh=0.5)

逐条说明：

• get_model('scrfd_person_2.5g.onnx', download=True)：如果本地~/.insightface/models/下已有该 onnx 文件就直接加载；不存在则自动下载（model_zoo.py 中allow_download为 True 时走下载分支，默认root为~/.insightface）。这一步需要网络可访问，断网环境下请提前准备好模型文件再传download=False以外的本地路径。
• detector.prepare(0, nms_thresh=0.5)：ctx_id传0表示使用非负上下文标识初始化，nms_thresh用于后置 NMS 的 IoU 阈值。SCRFD 类中 NMS 阈值默认为0.4、检测分数阈值det_thresh默认为0.5（见 scrfd.py 第 87–88 行），示例显式把nms_thresh调到了0.5，即框重叠达到 0.5 才会被 NMS 抑制。

运行检测并理解返回结果

官方示例的核心函数（节选自 scrfd_person.py）：

def detect_person(img, detector): bboxes, kpss = detector.detect(img) bboxes = np.round(bboxes[:,:4]).astype(np.int) kpss = np.round(kpss).astype(np.int) kpss[:,:,0] = np.clip(kpss[:,:,0], 0, img.shape[1]) kpss[:,:,1] = np.clip(kpss[:,:,1], 0, img.shape[0]) vbboxes = bboxes.copy() vbboxes[:,0] = kpss[:, 0, 0] vbboxes[:,1] = kpss[:, 0, 1] vbboxes[:,2] = kpss[:, 4, 0] vbboxes[:,3] = kpss[:, 4, 1] return bboxes, vbboxes

detector.detect(img)返回两个数组：

• bboxes：每个检测出的人物一行，前 4 列是全身框(x1, y1, x2, y2)，最后一列是置信度；示例取前 4 列并取整用于画框。
• kpss：每个人物 5 个关键点，形状(n, 5, 2)。

示例的“可见区域”是这样得到的：直接取第 1 个关键点(kpss[:, 0, 0], kpss[:, 0, 1])作为可见框左上角、第 5 个关键点(kpss[:, 4, 0], kpss[:, 4, 1])作为右下角，构造vbboxes，并把坐标裁剪到图像边界内。这就是 README 里说的“单次前向中同时输出全身框与可见区域”。

完整脚本的运行逻辑是：遍历data/images/*.jpg，对每张图调用detect_person，然后为每个人物画绿色全身框（cv2.rectangle，颜色(0,255,0)），并在可见区域内用 alpha 为 0.8 的蓝色(255, 0, 0)做混合着色，四角再画圆点标记。最后按原文件名写入./outputs/。

如果你的图片不是.jpg，把glob.glob('data/images/*.jpg')里的后缀改成实际格式即可，其余代码不变。

验证结果

示例脚本没有打印数值型指标，验证方式是查看./outputs/下生成的标注图：

• 绿色矩形 = 该人物的全身检测框；
• 蓝色着色区域 = 该人物的可见区域。

examples/person_detection/README.md 中给出的检测效果示意（文档示例图片，仅供参考）：

判断运行是否正常的依据：

1. 加载模型时如果本地没有 onnx 文件，终端会打印download_path:开头的下载信息；加载成功后get_model内部会打印Applied providers: ...一行（onnxruntime 会话创建后输出）。
2. ./outputs/下出现了与输入同名的图片，且图中框与人物位置相符，即说明检测链路已跑通。
3. 如果某张图输出为空白（没有框），表示该输入下没有满足阈值的检测——可以调低nms_thresh/检测阈值重新尝试，但示例本身没有给出推荐数值，请按自己的数据试验。

限制与适用条件

• 官方示例的测试条件是 640 输入尺寸（README 原文：“We make tests on the input size of 640”），换其他输入尺寸效果未在该文档中说明。
• 模型自动下载依赖网络；download=True时请确认能访问存储服务器。
• 脚本按data/images/*.jpg硬匹配输入目录，图片放错目录或格式不符时img_paths为空，脚本会静默不处理任何图片——运行前先用ls data/images确认。
• 版本要求以示例自带的断言insightface.__version__>='0.4'为准。

进一步阅读：模型实现见 detection/scrfd 目录，onnx 模型加载逻辑见 python-package/insightface/model_zoo。

【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface