pigo

Documentation

Overview

Package pigo is a lightweight pure Go face detection, pupil/eyes localization and facial landmark points detection library based on Pixel Intensity Comparison-based Object detection paper (https://arxiv.org/pdf/1305.4537.pdf). Is platform agnostic and does not require any external dependencies and third party modules.

Face detection API example

First you need to load and parse the binary classifier, then convert the image to grayscale mode and finally to run the cascade function which returns a slice containing the row, column, scale and the detection score.

cascadeFile, err := ioutil.ReadFile("/path/to/cascade/file")
if err != nil {
	log.Fatalf("Error reading the cascade file: %v", err)
}

src, err := pigo.GetImage("/path/to/image")
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

cParams := pigo.CascadeParams{
	MinSize:     fd.minSize,
	MaxSize:     fd.maxSize,
	ShiftFactor: fd.shiftFactor,
	ScaleFactor: fd.scaleFactor,

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

pigo := pigo.NewPigo()
// Unpack the binary file. This will return the number of cascade trees,
// the tree depth, the threshold and the prediction from tree's leaf nodes.
classifier, err := pigo.Unpack(cascadeFile)
if err != nil {
	log.Fatalf("Error reading the cascade file: %s", err)
}

angle := 0.0 // cascade rotation angle. 0.0 is 0 radians and 1.0 is 2*pi radians

// Run the classifier over the obtained leaf nodes and return the detection results.
// The result contains quadruplets representing the row, column, scale and detection score.
dets := classifier.RunCascade(cParams, angle)

// Calculate the intersection over union (IoU) of two clusters.
dets = classifier.ClusterDetections(dets, 0.2)

For pupil/eyes localization and facial landmark points detection API example check the source code.

Index

• func GetImage(input string) (*image.NRGBA, error)
• func ImgToNRGBA(img image.Image) *image.NRGBA
• func RgbToGrayscale(src image.Image) []uint8
• type CascadeParams
• type Detection
• type FlpCascade
• type ImageParams
• type Pigo
  • func NewPigo() *Pigo
  • func (pg *Pigo) ClusterDetections(detections []Detection, iouThreshold float64) []Detection
  • func (pg *Pigo) RunCascade(cp CascadeParams, angle float64) []Detection
  • func (pg *Pigo) Unpack(packet []byte) (*Pigo, error)
• type Puploc
• type PuplocCascade
  • func NewPuplocCascade() *PuplocCascade
  • func (plc *PuplocCascade) FindLandmarkPoints(leftEye, rightEye *Puploc, img ImageParams, perturb int, flipV bool) *Puploc
  • func (plc *PuplocCascade) ReadCascadeDir(path string) (map[string][]*FlpCascade, error)
  • func (plc *PuplocCascade) RunDetector(pl Puploc, img ImageParams, angle float64, flipV bool) *Puploc
  • func (plc *PuplocCascade) UnpackCascade(packet []byte) (*PuplocCascade, error)
  • func (plc *PuplocCascade) UnpackFlp(cf string) (*PuplocCascade, error)

Functions

func GetImage

func GetImage(input string) (*image.NRGBA, error)

GetImage retrieves and decodes the image file to *image.NRGBA type.

func ImgToNRGBA

func ImgToNRGBA(img image.Image) *image.NRGBA

ImgToNRGBA converts any image type to *image.NRGBA with min-point at (0, 0).

func RgbToGrayscale

func RgbToGrayscale(src image.Image) []uint8

RgbToGrayscale converts the image to grayscale mode.

Types

type CascadeParams

type CascadeParams struct {
	MinSize     int
	MaxSize     int
	ShiftFactor float64
	ScaleFactor float64
	ImageParams
}

CascadeParams contains the basic parameters to run the analyzer function over the defined image. MinSize: represents the minimum size of the face. MaxSize: represents the maximum size of the face. ShiftFactor: determines to what percentage to move the detection window over its size. ScaleFactor: defines in percentage the resize value of the detection window when moving to a higher scale.

type Detection

type Detection struct {
	Row   int
	Col   int
	Scale int
	Q     float32
}

Detection struct contains the detection results composed of the row, column, scale factor and the detection score.

type FlpCascade

type FlpCascade struct {
	*PuplocCascade
	// contains filtered or unexported fields
}

FlpCascade holds the binary representation of the facial landmark points cascade files

type ImageParams

type ImageParams struct {
	Pixels []uint8
	Rows   int
	Cols   int
	Dim    int
}

ImageParams is a struct for image related settings. Pixels: contains the grayscale converted image pixel data. Rows: the number of image rows. Cols: the number of image columns. Dim: the image dimension.

type Pigo

type Pigo struct {
	// contains filtered or unexported fields
}

Pigo struct defines the basic binary tree components.

func NewPigo

func NewPigo() *Pigo

NewPigo initializes the Pigo constructor method.

func (*Pigo) ClusterDetections

func (pg *Pigo) ClusterDetections(detections []Detection, iouThreshold float64) []Detection

ClusterDetections returns the intersection over union of multiple clusters. We need to make this comparison to filter out multiple face detection regions.

func (*Pigo) RunCascade

func (pg *Pigo) RunCascade(cp CascadeParams, angle float64) []Detection

RunCascade analyze the grayscale converted image pixel data and run the classification function over the detection window. It will return a slice containing the detection row, column, it's center and the detection score (in case this is greater than 0.0).

func (*Pigo) Unpack

func (pg *Pigo) Unpack(packet []byte) (*Pigo, error)

Unpack unpack the binary face classification file.

type Puploc

type Puploc struct {
	Row      int
	Col      int
	Scale    float32
	Perturbs int
}

Puploc contains all the information resulted from the pupil detection needed for accessing from a global scope.

type PuplocCascade

type PuplocCascade struct {
	// contains filtered or unexported fields
}

PuplocCascade is a general struct for storing the cascade tree values encoded into the binary file.

func NewPuplocCascade

func NewPuplocCascade() *PuplocCascade

NewPuplocCascade initializes the PuplocCascade constructor method.

func (*PuplocCascade) FindLandmarkPoints

func (plc *PuplocCascade) FindLandmarkPoints(leftEye, rightEye *Puploc, img ImageParams, perturb int, flipV bool) *Puploc

FindLandmarkPoints detects the facial landmark points based on the pupil localization results.

func (*PuplocCascade) ReadCascadeDir

func (plc *PuplocCascade) ReadCascadeDir(path string) (map[string][]*FlpCascade, error)

ReadCascadeDir reads the facial landmark points cascade files from the provided directory.

func (*PuplocCascade) RunDetector

func (plc *PuplocCascade) RunDetector(pl Puploc, img ImageParams, angle float64, flipV bool) *Puploc

RunDetector runs the pupil localization function.

func (*PuplocCascade) UnpackCascade

func (plc *PuplocCascade) UnpackCascade(packet []byte) (*PuplocCascade, error)

UnpackCascade unpacks the pupil localization cascade file.

func (*PuplocCascade) UnpackFlp

func (plc *PuplocCascade) UnpackFlp(cf string) (*PuplocCascade, error)

UnpackFlp unpacks the facial landmark points cascade file. This will return the binary representation of the cascade file.