Pigo 是一个纯 Go 语言实现的人脸检测、瞳孔/眼睛定位以及面部关键点检测库，其核心基于 基于像素强度比较的目标检测 论文。

矩形人脸标记	圆形人脸标记

动机

开发 Pigo 的原因在于，目前 Go 生态中几乎所有的人脸检测解决方案都只是对一些 C/C++ 库（如 OpenCV 或 dlib）的绑定。然而，通过 cgo 调用 C 程序会引入巨大的延迟，并在性能上做出显著的权衡。此外，在许多平台上安装 OpenCV 也颇为繁琐。

Pigo 库无需安装任何额外的模块或第三方应用程序，不过如果你希望在实时桌面应用中运行该库，则可能需要安装 Python 和 OpenCV。更多详情请参阅此 子主题。

核心特性

• 不需安装 OpenCV 或任何第三方模块
• 处理速度快
• 检测前无需进行图像预处理
• 无需计算积分图像、图像金字塔、HOG 金字塔或其他类似的数据结构
• 人脸检测基于二进制文件树结构中编码的像素强度比较
• 快速检测平面内旋转的人脸
• 即使佩戴眼镜也能检测到人脸
• 瞳孔/眼睛定位
• 面部关键点检测
• WebAssembly 支持 🎉

待办事项

• 对象检测与描述

该库还可以检测平面内旋转的人脸。 因此，命令行工具中新增了一个 -angle 参数。以下命令将生成如下结果（有关所有支持的选项，请参阅下表）：

$ pigo -in input.jpg -out output.jpg -cf cascade/facefinder -angle=0.8 -iou=0.01

输入文件	输出文件

注意：对于平面内旋转的人脸，角度值应根据提供的图像进行调整。

瞳孔/眼睛定位

自 v1.2.0 起，Pigo 提供了瞳孔/眼睛定位功能。其实现基于 使用随机森林集成进行瞳孔定位。

可在此示例中查看实时演示：https://github.com/esimov/pigo/tree/master/examples/puploc

面部关键点检测

v1.3.0 标志着该库发展的一个新里程碑，Pigo 现已能够检测面部关键点。其实现基于 快速定位面部关键点。

可在此示例中查看实时演示：https://github.com/esimov/pigo/tree/master/examples/facial_landmark

安装

安装 Go，设置好 GOPATH，并确保 $GOPATH/bin 已添加到你的 PATH 中。

$ go install github.com/esimov/pigo/cmd/pigo@latest

二进制发布

如果你没有安装 Go 或不想安装，也可以从 releases 文件夹获取二进制文件。

该库同样可以通过 snapcraft 运行。

API

以下是使用人脸检测 API 的最小示例。

首先，你需要加载并解析二进制分类器，然后将图像转换为灰度模式， 最后运行级联函数，该函数会返回一个包含行、列、尺度和检测分数的切片。

cascadeFile, err := ioutil.ReadFile("/path/to/cascade/file")
if err != nil {
	log.Fatalf("读取级联文件时出错：%v", err)
}

src, err := pigo.GetImage("/path/to/image")
if err != nil {
	log.Fatalf("无法打开图像文件：%v", err)
}

pixels := pigo.RgbToGrayscale(src)
cols, rows := src.Bounds().Max.X, src.Bounds().Max.Y

cParams := pigo.CascadeParams{
	MinSize:     20,
	MaxSize:     1000,
	ShiftFactor: 0.1,
	ScaleFactor: 1.1,

	ImageParams: pigo.ImageParams{
		Pixels: pixels,
		Rows:   rows,
		Cols:   cols,
		Dim:    cols,
	},
}

pigo := pigo.NewPigo()
// 解包二进制文件。这将返回级联树的数量、树的深度、阈值以及来自树叶节点的预测。
classifier, err := pigo.Unpack(cascadeFile)
if err != nil {
	log.Fatalf("读取级联文件时出错：%s", err)
}

angle := 0.0 // 级联旋转角度。0.0 表示 0 弧度，1.0 表示 2π 弧度

// 在获得的叶节点上运行分类器，并返回检测结果。
// 结果包含四元组，分别表示行、列、尺度和检测分数。
dets := classifier.RunCascade(cParams, angle)

// 计算两个聚类之间的交并比 (IoU)。
dets = classifier.ClusterDetections(dets, 0.2)

关于导入的说明：为了解码生成的图像，你必须导入 image/jpeg 或 image/png（取决于提供的图像类型），如下面的示例所示，否则你会收到 "Image: Unknown format" 错误。

import (
    _ "image/jpeg"
    pigo "github.com/esimov/pigo/core"
)

使用方法

该库附带了一个命令行工具。

$ pigo -in input.jpg -out out.jpg -cf cascade/facefinder

支持的标志：

$ pigo --help

┌─┐┬┌─┐┌─┐
├─┘││ ┬│ │
┴  ┴└─┘└─┘

Go（Golang）人脸检测库。
    版本：1.4.2

  -angle float
    	0.0 表示 0 弧度，1.0 表示 2π 弧度
  -cf string
    	级联二进制文件
  -flpc string
    	面部特征点级联目录
  -in string
    	源图像（默认为“-”）
  -iou float
    	交并比 (IoU) 阈值（默认为 0.2）
  -json string
    	将检测点输出到 JSON 文件
  -mark
    	标记检测到的眼睛（默认为真）
  -marker string
    	检测标记：矩形|圆形|椭圆（默认为“矩形”）
  -max int
    	人脸的最大尺寸（默认为 1000）
  -min int
    	人脸的最小尺寸（默认为 20）
  -out string
    	目标图像（默认为“-”）
  -plc string
    	瞳孔/眼睛定位级联文件
  -scale float
    	按百分比缩放检测窗口（默认为 1.1）
  -shift float
    	按百分比移动检测窗口（默认为 0.1）

重要提示：如果你还想运行瞳孔/眼睛定位功能，则需要使用 plc 标志，并提供指向瞳孔定位级联文件的有效路径。面部特征点检测也是如此，只不过这次 flpc 标志接受的参数是一个目录，该目录指向位于 cascades/lps 下的面部特征点级联文件。

CLI 命令示例

你还可以使用 stdin 和 stdout 管道命令：

$ cat input/source.jpg | pigo > -in - -out - >out.jpg -cf=/path/to/cascade

in 和 out 的默认值为 -，因此你也可以这样使用：

$ cat input/source.jpg | pigo >out.jpg -cf=/path/to/cascade
$ pigo -out out.jpg < input/source.jpg -cf=/path/to/cascade

将 -out 标志的值设置为空字符串会跳过图像生成部分。结合 -json 标志，可以将检测结果编码到指定的 JSON 文件中。你还可以使用管道 - 值结合 -json 标志，将检测坐标输出到标准输出 (stdout)。

实时人脸检测（作为共享对象运行）

如果你想测试该库的实时人脸检测能力，examples 文件夹中包含几个用 Python 编写的演示程序。

但你可能会问，为什么是 Python？ 因为 Go 生态系统（目前）仍然缺少一个跨平台且与系统无关的库来访问网络摄像头。

在 Python 程序中，我们访问网络摄像头，并通过 cgo 将像素数据以字节数组的形式作为 共享对象 传输到 Go 程序中，在那里进行核心的人脸检测。然而，正如你所想象的那样，这种操作并不经济高效，导致帧率低于该库所能达到的水平。

WASM（WebAssembly）支持 🎉

重要提示：要运行 WebAssembly 演示，至少需要 Go 1.13！

从版本 v1.4.0 开始，该库已移植到 WASM。这证明了该库的实时人脸检测能力，能够持续产生 ~60 FPS。

WASM 演示

要运行 wasm 演示，请选择 wasm 文件夹并输入 make。

更多详情请查看子页面描述：https://github.com/esimov/pigo/tree/master/wasm。

有关使用 Pigo 库的更多精彩 WASM 演示，请参阅此仓库：https://github.com/esimov/pigo-wasm-demos。

基准测试结果

以下是使用相同条件运行 Pigo 与 GoCV 时得到的基准测试结果。

    BenchmarkGoCV-4   	       3	 414122553 ns/op	     704 B/op	       1 allocs/op
    BenchmarkPIGO-4   	      10	 173664832 ns/op	       0 B/op	       0 allocs/op
    PASS
    ok  	github.com/esimov/gocv-test	4.530s

用于上述测试的代码可在以下链接找到：https://github.com/esimov/pigo-gocv-benchmark

作者

• Endre Simo (@simo_endre)

许可证

版权所有 © 2019 Endre Simo

本软件根据 MIT 许可证分发。完整的许可证文本请参见 LICENSE 文件。

Pigo 快速上手指南

Pigo 是一个纯 Go 语言编写的人脸检测库，支持瞳孔/眼睛定位及面部关键点检测。它基于“像素强度比较”算法，无需安装 OpenCV 或任何 C/C++ 第三方依赖，具有极高的处理速度和零内存分配特性。

环境准备

• 操作系统：Linux, macOS, Windows (支持跨平台)
• Go 版本：建议 Go 1.13 或更高版本（若需使用 WebAssembly 功能必须 >= 1.13）
• 前置依赖：无。Pigo 是纯 Go 实现，不需要安装 OpenCV、Python 或其他系统级库即可运行核心检测功能。
  • 注：仅当需要运行官方提供的实时摄像头演示（调用 webcam）时，才需要安装 Python 和 OpenCV，因为 Go 生态尚缺跨平台的摄像头访问库。

安装步骤

你可以通过以下两种方式安装 Pigo：

方式一：通过 Go 模块安装（推荐）

确保已配置好 GOPATH 并将 $GOPATH/bin 加入环境变量 PATH 中。

go install github.com/esimov/pigo/cmd/pigo@latest

方式二：下载二进制文件

如果不希望安装 Go 环境，可以直接从 Releases 页面 下载对应平台的编译好的二进制文件。

此外，Pigo 也支持通过 Snap 安装：

sudo snap install pigo

基本使用

Pigo 提供了命令行工具和 Go API 两种使用方式。使用前请确保你拥有分类器文件（cascade file），通常位于项目仓库的 cascade/ 目录下（如 facefinder）。

1. 命令行使用 (CLI)

最简单的用法是指定输入图片、输出图片和分类器文件路径：

pigo -in input.jpg -out output.jpg -cf cascade/facefinder

常用参数说明：

• -in: 输入图片路径（支持 - 表示 stdin）
• -out: 输出图片路径（支持 - 表示 stdout，设为空字符串可跳过生成图片）
• -cf: 人脸检测分类器二进制文件路径
• -angle: 检测旋转角度（0.0 为 0 弧度，1.0 为 2*pi 弧度），用于检测侧脸或旋转人脸
• -json: 将检测结果坐标输出到 JSON 文件
• -marker: 标记样式，可选 rect (矩形), circle (圆形), ellipse (椭圆)

管道流式处理示例：

cat input.jpg | pigo -cf cascade/facefinder > output.jpg

2. Go API 集成

在你的 Go 项目中引入 Pigo 核心包。注意：为了正确解码图片，必须导入 _ "image/jpeg" 或 _ "image/png"。

package main

import (
	"io/ioutil"
	"log"

	_ "image/jpeg" // 必须导入以支持 JPEG 解码
	pigo "github.com/esimov/pigo/core"
)

func main() {
	// 1. 加载并解析分类器文件
	cascadeFile, err := ioutil.ReadFile("cascade/facefinder")
	if err != nil {
		log.Fatalf("Error reading the cascade file: %v", err)
	}

	// 2. 读取图片并转换为灰度
	src, err := pigo.GetImage("input.jpg")
	if err != nil {
		log.Fatalf("Cannot open the image file: %v", err)
	}

	pixels := pigo.RgbToGrayscale(src)
	cols, rows := src.Bounds().Max.X, src.Bounds().Max.Y

	// 3. 设置检测参数
	cParams := pigo.CascadeParams{
		MinSize:     20,
		MaxSize:     1000,
		ShiftFactor: 0.1,
		ScaleFactor: 1.1,
		ImageParams: pigo.ImageParams{
			Pixels: pixels,
			Rows:   rows,
			Cols:   cols,
			Dim:    cols,
		},
	}

	// 4. 初始化并运行检测
	p := pigo.NewPigo()
	classifier, err := p.Unpack(cascadeFile)
	if err != nil {
		log.Fatalf("Error unpacking the cascade file: %s", err)
	}

	angle := 0.0 // 旋转角度
	dets := classifier.RunCascade(cParams, angle)

	// 5. 聚类检测结果 (去除重叠框)
	dets = classifier.ClusterDetections(dets, 0.2)

	// dets 包含检测到的人脸坐标 (row, col, scale, score)
	for _, det := range dets {
		log.Printf("Face detected at row: %f, col: %f, scale: %f", det.Row, det.Col, det.Scale)
	}
}

进阶功能提示

• 瞳孔/眼睛定位：使用 -plc 参数指定瞳孔定位分类器文件。
• 面部关键点检测：使用 -flpc 参数指向包含关键点分类器的目录（通常在 cascades/lps 下）。
• WebAssembly：Pigo 支持编译为 WASM，可在浏览器中实现约 60 FPS 的实时人脸检测，详见项目 wasm 目录。