face

Documentation

Overview

Package face implements face recognition for Go using dlib, a popular machine learning toolkit.

Example (Basic)

This example shows the basic usage of the package: create an recognizer, recognize faces, classify them using few known ones.

package main

import (
	"fmt"
	"log"
	"path/filepath"

	"github.com/Arturbox/go-face"
)

// Path to directory with models and test images. Here it's assumed it
// points to the <https://github.com/Arturbox/go-face-testdata> clone.
const dataDir = "testdata"

// This example shows the basic usage of the package: create an
// recognizer, recognize faces, classify them using few known ones.
func main() {
	// Init the recognizer.
	rec, err := face.NewRecognizer(filepath.Join(dataDir, "models"))
	if err != nil {
		log.Fatalf("Can't init face recognizer: %v", err)
	}
	// Free the resources when you're finished.
	defer rec.Close()

	// Test image with 10 faces.
	testImagePristin := filepath.Join(dataDir, "images", "pristin.jpg")
	// Recognize faces on that image.
	faces, err := rec.RecognizeFile(testImagePristin)
	if err != nil {
		log.Fatalf("Can't recognize: %v", err)
	}
	if len(faces) != 10 {
		log.Fatalf("Wrong number of faces")
	}

	// Fill known samples. In the real world you would use a lot of images
	// for each person to get better classification results but in our
	// example we just get them from one big image.
	var samples []face.Descriptor
	var cats []int32
	for i, f := range faces {
		samples = append(samples, f.Descriptor)
		// Each face is unique on that image so goes to its own category.
		cats = append(cats, int32(i))
	}
	// Name the categories, i.e. people on the image.
	labels := []string{
		"Sungyeon", "Yehana", "Roa", "Eunwoo", "Xiyeon",
		"Kyulkyung", "Nayoung", "Rena", "Kyla", "Yuha",
	}
	// Pass samples to the recognizer.
	rec.SetSamples(samples, cats)

	// Now let's try to classify some not yet known image.
	testImageNayoung := filepath.Join(dataDir, "images", "nayoung.jpg")
	nayoungFace, err := rec.RecognizeSingleFile(testImageNayoung)
	if err != nil {
		log.Fatalf("Can't recognize: %v", err)
	}
	if nayoungFace == nil {
		log.Fatalf("Not a single face on the image")
	}
	catID := rec.Classify(nayoungFace.Descriptor)
	if catID < 0 {
		log.Fatalf("Can't classify")
	}
	// Finally print the classified label. It should be "Nayoung".
	fmt.Println(labels[catID])
}

Index

• func SquaredEuclideanDistance(d1 Descriptor, d2 Descriptor) (sum float64)
• type Descriptor
• type Face
  • func New(r image.Rectangle, d Descriptor) Face
  • func NewWithShape(r image.Rectangle, s []image.Point, d Descriptor) Face
• type ImageLoadError
  • func (e ImageLoadError) Error() string
• type Recognizer
  • func NewRecognizer(modelDir string) (rec *Recognizer, err error)
  • func NewRecognizerWithConfig(modelDir string, size int, padding float32, jittering int) (rec *Recognizer, err error)
  • func (rec *Recognizer) Classify(testSample Descriptor) int
  • func (rec *Recognizer) ClassifyThreshold(testSample Descriptor, tolerance float32) int
  • func (rec *Recognizer) Close()
  • func (rec *Recognizer) Recognize(imgData []byte) (faces []Face, err error)
  • func (rec *Recognizer) RecognizeCNN(imgData []byte) (faces []Face, err error)
  • func (rec *Recognizer) RecognizeFile(imgPath string) (faces []Face, err error)
  • func (rec *Recognizer) RecognizeFileCNN(imgPath string) (faces []Face, err error)
  • func (rec *Recognizer) RecognizeSingle(imgData []byte) (face *Face, err error)
  • func (rec *Recognizer) RecognizeSingleCNN(imgData []byte) (face *Face, err error)
  • func (rec *Recognizer) RecognizeSingleFile(imgPath string) (face *Face, err error)
  • func (rec *Recognizer) RecognizeSingleFileCNN(imgPath string) (face *Face, err error)
  • func (rec *Recognizer) SetSamples(samples []Descriptor, cats []int32)
• type SerializationError
  • func (e SerializationError) Error() string
• type UnknownError
  • func (e UnknownError) Error() string

Examples

• Package (Basic)

Functions

func SquaredEuclideanDistance

func SquaredEuclideanDistance(d1 Descriptor, d2 Descriptor) (sum float64)

Types

type Descriptor

type Descriptor [128]float32

Descriptor holds 128-dimensional feature vector.

type Face

type Face struct {
	Rectangle  image.Rectangle
	Descriptor Descriptor
	Shapes     []image.Point
}

Face holds coordinates and descriptor of the human face.

func New

func New(r image.Rectangle, d Descriptor) Face

New creates new face with the provided parameters.

func NewWithShape

func NewWithShape(r image.Rectangle, s []image.Point, d Descriptor) Face

type ImageLoadError

type ImageLoadError string

An ImageLoadError is returned when provided image file is corrupted.

func (ImageLoadError) Error

func (e ImageLoadError) Error() string

type Recognizer

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

A Recognizer creates face descriptors for provided images and classifies them into categories.

func NewRecognizer

func NewRecognizer(modelDir string) (rec *Recognizer, err error)

NewRecognizer returns a new recognizer interface. modelDir points to directory with shape_predictor_5_face_landmarks.dat and dlib_face_recognition_resnet_model_v1.dat files.

func NewRecognizerWithConfig

func NewRecognizerWithConfig(modelDir string, size int, padding float32, jittering int) (rec *Recognizer, err error)

func (*Recognizer) Classify

func (rec *Recognizer) Classify(testSample Descriptor) int

Classify returns class ID for the given descriptor. Negative index is returned if no match. Thread-safe.

func (*Recognizer) ClassifyThreshold

func (rec *Recognizer) ClassifyThreshold(testSample Descriptor, tolerance float32) int

Same as Classify but allows to specify max distance between faces to consider it a match. Start with 0.6 if not sure.

func (*Recognizer) Close

func (rec *Recognizer) Close()

Close frees resources taken by the Recognizer. Safe to call multiple times. Don't use Recognizer after close call.

func (*Recognizer) Recognize

func (rec *Recognizer) Recognize(imgData []byte) (faces []Face, err error)

Recognize returns all faces found on the provided image, sorted from left to right. Empty list is returned if there are no faces, error is returned if there was some error while decoding/processing image. Only JPEG format is currently supported. Thread-safe.

func (*Recognizer) RecognizeCNN

func (rec *Recognizer) RecognizeCNN(imgData []byte) (faces []Face, err error)

func (*Recognizer) RecognizeFile

func (rec *Recognizer) RecognizeFile(imgPath string) (faces []Face, err error)

Same as Recognize but accepts image path instead.

func (*Recognizer) RecognizeFileCNN

func (rec *Recognizer) RecognizeFileCNN(imgPath string) (faces []Face, err error)

func (*Recognizer) RecognizeSingle

func (rec *Recognizer) RecognizeSingle(imgData []byte) (face *Face, err error)

RecognizeSingle returns face if it's the only face on the image or nil otherwise. Only JPEG format is currently supported. Thread-safe.

func (*Recognizer) RecognizeSingleCNN

func (rec *Recognizer) RecognizeSingleCNN(imgData []byte) (face *Face, err error)

func (*Recognizer) RecognizeSingleFile

func (rec *Recognizer) RecognizeSingleFile(imgPath string) (face *Face, err error)

Same as RecognizeSingle but accepts image path instead.

func (*Recognizer) RecognizeSingleFileCNN

func (rec *Recognizer) RecognizeSingleFileCNN(imgPath string) (face *Face, err error)

func (*Recognizer) SetSamples

func (rec *Recognizer) SetSamples(samples []Descriptor, cats []int32)

SetSamples sets known descriptors so you can classify the new ones. Thread-safe.

type SerializationError

type SerializationError string

An SerializationError is returned when provided model is corrupted.

func (SerializationError) Error

func (e SerializationError) Error() string

type UnknownError

type UnknownError string

An UnknownError represents some nonclassified error.

func (UnknownError) Error

func (e UnknownError) Error() string