facedetect

README

About

go-face-detect is a Go library, cli tool, and Web Assembly module to detect faces in images (using pigo), and transform them for use as a portrait (e.g. for a name badge).

Library

The library contains high-level functions to configurably transform images into portraits, as well as low-level general face detection and image transformation functions.

CLI tool

The included face-detect utility can quickly process multiple images in parallel, applying the following transformations:

• Rotate the image so face is level
• Crop the image so the face is well framed
• Brighten the image so face detail is easier to see

Usage: face-detect [flags] -out <output directory> <input file>...
  -aspect-ratio float
    	the width / height aspect ratio for the converted portraits (default 0.75)
  -brightness float
    	the percentage to adjust the converted portrait brightness (-100 to 100)
  -contrast float
    	the percentage to adjust the converted portrait contrast (-100 to 100) (default 5)
  -gamma float
    	the amount to adjust the converted portrait gamma (1.0 returns the gamma as-is) (default 1.4)
  -level string
    	logging level parsable by slog.UnmarshalText (default "INFO")
  -max-width-ratio float
    	the max portrait width / detected face width ratio (default 1.5)
  -out string
    	the directory where converted portraits will be written
  -overwrite
    	overwrite existing files
  -use-exif
    	automatically rotate photos based on EXIF orientation (default true)
  -workers int
    	number of concurrent workers to use (default 16)

face-detect detects a single face in an image, automatically rotates, crops, brightens the image and writes it to a new file.
If multiple input images are given, they'll be processed in parallel.

Web Assembly Live Demo

go-face-detect also includes a wasm module that can be compiled to a standalone wasm file (including embedded cascade files).

Visit https://korylprince.github.io/go-face-detect/ for a live demo using wasm to convert portraits in the browser.

Dependencies

• github.com/esimov/pigo for pure-Go face detection
• github.com/mholt/goexif2 for EXIF parsing
• github.com/disintegration/imaging for image manipulation

License

facefinder and puploc cascade files are from the pigo. These were originally created by Nenad Markuš.

wasm_exec.js is included in Go's distribution.

All other code licensed by LICENSE.

Documentation

Index

• Variables
• func Brighten(img image.Image, brightness, contrast, gamma float64) *image.NRGBA
• func ChooseBestFace(faces []pigo.Detection) pigo.Detection
• func Crop(img image.Image, face *Face, aspectRatio, maxWidthRatio float64) *image.NRGBA
• func DecodeFileWithEXIF(path string) (*image.NRGBA, error)
• func DecodeWithEXIF(r io.ReadSeeker) (*image.NRGBA, error)
• func Rotate(img image.Image, face *Face) *image.NRGBA
• type DetectParams
• type Detector
  • func (d *Detector) DetectFace(img *image.NRGBA, angle float64) (*Face, error)
  • func (d *Detector) DetectFaces(img pigo.ImageParams, params *DetectParams, angle float64) []pigo.Detection
  • func (d *Detector) DetectPupils(img pigo.ImageParams, face pigo.Detection, angle float64) (leftEye, rightEye *pigo.Puploc)
  • func (d *Detector) Portrait(img *image.NRGBA, config *PortraitConfig) (*image.NRGBA, error)
  • func (d *Detector) PortraitFile(inpath, outpath string, config *PortraitConfig) error
  • func (d *Detector) PortraitFileWithEXIF(inpath, outpath string, config *PortraitConfig) error
• type Face
• type PortraitConfig

Variables

var (
	ErrFaceUndetected   = errors.New("face undetected")
	ErrPupilsUndetected = errors.New("pupils undetected")
)

var (
	ErrNoOrientationTag      = errors.New("no orientation tag")
	ErrInvalidOrientationTag = errors.New("invalid orientation tag")
)

var DefaultPortraitConfig = &PortraitConfig{
	AspectRatio:   3.0 / 4.0,
	MaxWidthRatio: 1.5,
	Brightness:    0,
	Contrast:      5,
	Gamma:         1.4,
}

var FastDetectParams = &DetectParams{
	MinSizeFactor: 0.2,
	MaxSizeFactor: 0.8,
	ShiftFactor:   0.15,
	ScaleFactor:   1.15,
	IoUThreshold:  0.15,
}

var SlowDetectParams = &DetectParams{
	MinSizeFactor: 0.1,
	MaxSizeFactor: 0.9,
	ShiftFactor:   0.05,
	ScaleFactor:   1.03,
	IoUThreshold:  0,
}

Functions

func Brighten

func Brighten(img image.Image, brightness, contrast, gamma float64) *image.NRGBA

Brighten brightens the image for better detail in the face

func ChooseBestFace

func ChooseBestFace(faces []pigo.Detection) pigo.Detection

ChooseBestFace returns the face with the highest quality (Q)

func Crop

func Crop(img image.Image, face *Face, aspectRatio, maxWidthRatio float64) *image.NRGBA

Crop crops the image to the largest bounding box that doesn't contain transparent pixels. aspectRatio is the ratio width / height. maxWidthRatio is the maximum width of the cropped image / the width of the detected face

func DecodeFileWithEXIF

func DecodeFileWithEXIF(path string) (*image.NRGBA, error)

DecodeFileWithEXIF decodes the image at path, rotating it using EXIF data if it exists

func DecodeWithEXIF

func DecodeWithEXIF(r io.ReadSeeker) (*image.NRGBA, error)

DecodeWithEXIF decodes an image from r, rotating it using EXIF data if it exists

func Rotate

func Rotate(img image.Image, face *Face) *image.NRGBA

Rotate rotates the image so that the line going through the pupils is parallel with the top edge of the image

Types

type DetectParams

type DetectParams struct {
	MinSizeFactor float64
	MaxSizeFactor float64
	ShiftFactor   float64
	ScaleFactor   float64
	IoUThreshold  float64
}

DetectParams are the parameters given to the face detector. MinSizeFactor is the smallest size area searched for as a percentage of the largest dimension of the image. MaxSizeFactor is the largest size area searched for as a percentage of the largest dimension of the image. 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. IoUThreshold is the threshold to consider multiple face regions the same face

type Detector

type Detector struct {
	FaceCascade  *pigo.Pigo
	PupilCascade *pigo.PuplocCascade
}

func (*Detector) DetectFace

func (d *Detector) DetectFace(img *image.NRGBA, angle float64) (*Face, error)

DetectFace detects a single face and pupils in an image, returning the detected areas. DetectFace attempts detection using FastDetectParams, falling back to SlowDetectParams if a face isn't detected

func (*Detector) DetectFaces

func (d *Detector) DetectFaces(img pigo.ImageParams, params *DetectParams, angle float64) []pigo.Detection

func (*Detector) DetectPupils

func (d *Detector) DetectPupils(img pigo.ImageParams, face pigo.Detection, angle float64) (leftEye, rightEye *pigo.Puploc)

func (*Detector) Portrait

func (d *Detector) Portrait(img *image.NRGBA, config *PortraitConfig) (*image.NRGBA, error)

Portrait detects a single face in an image, rotates, crops, and brightens it, and returns the result. If config is nil, DefaultPortraitConfig is used

func (*Detector) PortraitFile

func (d *Detector) PortraitFile(inpath, outpath string, config *PortraitConfig) error

PortraitFile detects a single face in the image at inpath, rotates, crops, and brightens it, and writes the result to outpath. If config is nil, DefaultPortraitConfig is used

func (*Detector) PortraitFileWithEXIF

func (d *Detector) PortraitFileWithEXIF(inpath, outpath string, config *PortraitConfig) error

PortraitFileWithEXIF reads EXIF data from the image at inpath, rotating it if necessary, detects a single face in the image, rotates, crops, and brightens it, and writes the result to outpath. If config is nil, DefaultPortraitConfig is used

type Face

type Face struct {
	Bounds   pigo.Detection
	LeftEye  *pigo.Puploc
	RightEye *pigo.Puploc
}

type PortraitConfig

type PortraitConfig struct {
	AspectRatio   float64
	MaxWidthRatio float64
	Brightness    float64
	Contrast      float64
	Gamma         float64
}