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
Constants ¶
This section is empty.
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 ChooseBestFace ¶
ChooseBestFace returns the face with the highest quality (Q)
func Crop ¶
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 ¶
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
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 ¶
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 (*Detector) Portrait ¶
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
Source Files
Directories