org.openimaj.image.processing.face.recognition

Class FaceRecognitionEngine<FACE extends DetectedFace,PERSON>

java.lang.Object

org.openimaj.image.processing.face.recognition.FaceRecognitionEngine<FACE,PERSON>

Type Parameters:

FACE - Type of DetectedFace

PERSON - Type representing a person

All Implemented Interfaces:

ReadableBinary, ReadWriteableBinary, WriteableBinary

public class FaceRecognitionEngine<FACE extends DetectedFace,PERSON>
extends Object
implements ReadWriteableBinary

The FaceRecognitionEngine ties together the implementations of a FaceDetector and FaceRecogniser, and provides a single convenience API with which to interact with a face recognition system.

Author:

Jonathon Hare (jsh2@ecs.soton.ac.uk)

Field Summary

Fields

Modifier and Type	Field and Description
protected FaceDetector<FACE,FImage>	detector
protected FaceRecogniser<FACE,PERSON>	recogniser

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	FaceRecognitionEngine()
	FaceRecognitionEngine(FaceDetector<FACE,FImage> detector, FaceRecogniser<FACE,PERSON> recogniser) Construct a FaceRecognitionEngine with the given face detector and recogniser.

Method Summary

Modifier and Type	Method and Description
byte[]	binaryHeader() Header for binary input.
static <FACE extends DetectedFace,EXTRACTOR extends FeatureExtractor<?,FACE>,PERSON> FaceRecognitionEngine<FACE,PERSON>	create(FaceDetector<FACE,FImage> detector, FaceRecogniser<FACE,PERSON> recogniser) Create a FaceRecognitionEngine with the given face detector and recogniser.
FaceDetector<FACE,FImage>	getDetector()
FaceRecogniser<FACE,PERSON>	getRecogniser()
static <O extends DetectedFace,P> FaceRecognitionEngine<O,P>	load(File file) Load a FaceRecognitionEngine previously saved by save(File).
void	readBinary(DataInput in) Read internal state from in.
List<IndependentPair<FACE,List<ScoredAnnotation<PERSON>>>>	recognise(FImage image) Detect and recognise the faces in the given image, returning a list of potential people for each face.
List<IndependentPair<FACE,List<ScoredAnnotation<PERSON>>>>	recognise(FImage image, Set<PERSON> restrict) Detect and recognise the faces in the given image, returning a list of potential people for each face.
List<IndependentPair<FACE,ScoredAnnotation<PERSON>>>	recogniseBest(FImage image) Detect and recognise the faces in the given image, returning the most likely person for each face.
List<IndependentPair<FACE,ScoredAnnotation<PERSON>>>	recogniseBest(FImage image, Set<PERSON> restrict) Detect and recognise the faces in the given image, returning the most likely person for each face.
void	save(File file) Save the FaceRecognitionEngine to a file, including all the internal state of the recogniser, etc.
FACE	train(FACE face, PERSON person) Train for the given face patch without doing any face detection.
void	train(GroupedDataset<PERSON,ListDataset<FImage>,FImage> dataset) Train with a dataset
FACE	train(PERSON person, FImage image) Train the recogniser with a single example, returning the detected face.
void	writeBinary(DataOutput out) Write the content of this as binary to out.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

detector

protected FaceDetector<FACE extends DetectedFace,FImage> detector

recogniser

protected FaceRecogniser<FACE extends DetectedFace,PERSON> recogniser

Constructor Detail

FaceRecognitionEngine

protected FaceRecognitionEngine()

FaceRecognitionEngine

public FaceRecognitionEngine(FaceDetector<FACE,FImage> detector,
                             FaceRecogniser<FACE,PERSON> recogniser)

Construct a FaceRecognitionEngine with the given face detector and recogniser.

Parameters:

detector - the face detector

recogniser - the face recogniser

Method Detail

create

public static <FACE extends DetectedFace,EXTRACTOR extends FeatureExtractor<?,FACE>,PERSON> FaceRecognitionEngine<FACE,PERSON> create(FaceDetector<FACE,FImage> detector,
                                                                                                                                      FaceRecogniser<FACE,PERSON> recogniser)

Create a FaceRecognitionEngine with the given face detector and recogniser.

Type Parameters:

FACE - Type of DetectedFace

EXTRACTOR - Type of FeatureExtractor

PERSON - Type representing a person

Parameters:

detector - the face detector

recogniser - the face recogniser

Returns:

new FaceRecognitionEngine

getDetector

public FaceDetector<FACE,FImage> getDetector()

Returns:

the detector

getRecogniser

public FaceRecogniser<FACE,PERSON> getRecogniser()

Returns:

the recogniser

save

public void save(File file)
          throws IOException

Save the FaceRecognitionEngine to a file, including all the internal state of the recogniser, etc.

Parameters:

file - the file to save to

Throws:

IOException - if an error occurs when writing

load

public static <O extends DetectedFace,P> FaceRecognitionEngine<O,P> load(File file)
                                                                  throws IOException

Load a FaceRecognitionEngine previously saved by save(File).

Type Parameters:

O - Type of DetectedFace

P - Type representing a person

Parameters:

file - the file to read from

Returns:

the created recognition engine

Throws:

IOException - if an error occurs during the read

train

public void train(GroupedDataset<PERSON,ListDataset<FImage>,FImage> dataset)

Train with a dataset

Parameters:

dataset - the dataset

train

public FACE train(PERSON person,
                  FImage image)

Train the recogniser with a single example, returning the detected face. If multiple faces are found, the biggest is chosen.

If you need more control, consider calling getDetector() to get a detector which you can apply to your image and getRecogniser() to get the recogniser which you can train with the detections directly.

Parameters:

person - the person

image - the image with the persons face

Returns:

the detected face

train

public FACE train(FACE face,
                  PERSON person)

Train for the given face patch without doing any face detection. It is assumed that the given image will be a cropped/aligned image of the face as is necessary for the given recogniser.

Parameters:

face - The detected face implementation

person - The person to whom this face belongs

Returns:

The face image

recognise

public List<IndependentPair<FACE,List<ScoredAnnotation<PERSON>>>> recognise(FImage image)

Detect and recognise the faces in the given image, returning a list of potential people for each face.

Parameters:

image - the image

Returns:

a list of faces and recognitions

recogniseBest

public List<IndependentPair<FACE,ScoredAnnotation<PERSON>>> recogniseBest(FImage image)

Detect and recognise the faces in the given image, returning the most likely person for each face.

Parameters:

image - the image

Returns:

a list of faces with the most likely person

recognise

public List<IndependentPair<FACE,List<ScoredAnnotation<PERSON>>>> recognise(FImage image,
                                                                            Set<PERSON> restrict)

Detect and recognise the faces in the given image, returning a list of potential people for each face. The recognised people will be restricted to the given set.

Parameters:

image - the image

restrict - set of people to restrict to

Returns:

a list of faces and recognitions

recogniseBest

public List<IndependentPair<FACE,ScoredAnnotation<PERSON>>> recogniseBest(FImage image,
                                                                          Set<PERSON> restrict)

Detect and recognise the faces in the given image, returning the most likely person for each face. The recognised people will be restricted to the given set.

Parameters:

image - the image

restrict - set of people to restrict to

Returns:

a list of faces with the most likely person

readBinary

public void readBinary(DataInput in)
                throws IOException

Description copied from interface: ReadableBinary

Read internal state from in.

Specified by:

readBinary in interface ReadableBinary

Parameters:

in - source to read from.

Throws:

IOException - an error reading input

binaryHeader

public byte[] binaryHeader()

Description copied from interface: ReadableBinary

Header for binary input. Will be automatically read by IOUtils when using readBinary().

Specified by:

binaryHeader in interface ReadableBinary

Specified by:

binaryHeader in interface WriteableBinary

Returns:

header

writeBinary

public void writeBinary(DataOutput out)
                 throws IOException

Description copied from interface: WriteableBinary

Write the content of this as binary to out.

Specified by:

writeBinary in interface WriteableBinary

Parameters:

out - sink to write to

Throws:

IOException - an error writing to out