pigo

Pigo 是一个纯 Go 语言实现的人脸检测、瞳孔/眼睛定位和面部特征点检测库，基于**基于像素强度比较的目标检测**论文。

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

动机

开发 Pigo 的原因是因为目前 Go 生态系统中几乎所有现有的人脸检测解决方案都是纯粹绑定到一些 C/C++ 库，如 OpenCV 或 dlib，但通过 cgo 调用 C 程序会引入巨大的延迟，并在性能方面产生显著的权衡。此外，在许多情况下，在各种平台上安装 OpenCV 是很麻烦的。

Pigo 库不需要安装任何额外的模块或第三方应用程序，尽管如果你希望在实时桌面应用程序中运行该库，你可能需要安装 Python 和 OpenCV。有关更多详细信息，请查看这个小节。

主要特性

待办事项

对象检测和描述

该库还可以检测平面旋转的人脸。 为此，命令行工具中新增了一个 -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*pi 弧度

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

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

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

```Go
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*pi 弧度
  -cf string
    	级联二进制文件
  -flpc string
    	面部特征点级联目录
  -in string
    	源图像（默认 "-"）
  -iou float
    	交并比(IoU)阈值（默认 0.2）
  -json string
    	将检测点输出到 json 文件
  -mark
    	标记检测到的眼睛（默认为 true）
  -marker string
    	检测标记：rect|circle|ellipse（默认 "rect"）
  -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程序，作为共享对象，Go程序中进行核心的人脸检测。但正如你所想象的，这个操作并不高效，导致帧率低于库本身的能力。

WASM (Webassembly) 支持 🎉

重要提示：要运行Webassembly演示至少需要Go 1.13版本！

从v1.4.0版本开始，该库已被移植到WASM。这证明了该库实时人脸检测的能力，可以持续产生约60帧每秒的效果。

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