PEnrollment Class Reference

Detailed Description

The PEnrollment class is an helper class for face recognition, used to enroll people from a video or some images and save to a watchlist.

About thread-safety:
Use PEnrollment::Configure(), PEnrollment::AutoConfigureForFaceRecognition() or PEnrollment::CreateWatchlist() to configure an instance of PEnrollment. Once configured is done, you can call EnrollFromXXX() methods from different threads at the same time: the instance is thread-safe; both detection and description will be performed in parallel.

How to use PEnrollment?

PEnrollment enrollment;
PEnrollment::AutoConfigureForFaceRecognition(); // you first have to call AutoConfigureForFaceRecognition() or Configure() before using PEnrollment
// Option1: use EnrollFrom* methods to add people one by one
if (enrollment.EnrollFrom*(...).Ok()) ...
// Option2: use CreateWatchlist to enroll several people from a list of pictures or video files stored on disk
if (enrollment.CreateWatchlist(...).Ok()) ...

Definition at line 58 of file PEnrollment.h.

#include <PEnrollment.h>

Constructor & Destructor Documentation

◆ PEnrollment() [1/2]

PEnrollment::PEnrollment ( )

Constructs an empty enrollment object.

◆ PEnrollment() [2/2]

PEnrollment::PEnrollment ( const PEnrollment other)

Constructs a shared copy of other.

◆ ~PEnrollment()

virtual PEnrollment::~PEnrollment ( )
virtual

Destroys this object.

Member Function Documentation

◆ AutoConfigureForFaceRecognition()

PResult PEnrollment::AutoConfigureForFaceRecognition ( papillon::int32  minDetectionSize = 80,
bool  keepSourceImageForEachDescriptor = true,
const PString describerModelName = PString("DescriberDnn") 
)

Auto configures this enroller to use standard face recognition PDetector and PDescriber.

By default, minDetectionSize = 80 pixels and source images will be kept for each descriptor (to be able to recompute descriptors with a different describer engine).

If keepSourceImageForEachDescriptor is true, then the source image is stored in each PDescriptor. Source images are stored in the PProperties container attached to PDescriptor with key name C_PROPERTY_DATA_SOURCE (see PStringConstants.h); the format is a PByteArray storing a PNG image. If this flag is enabled, a thumbnail will also be attached to output descriptions (PDescription).

Warning: this method is blocking and take a few seconds to complete.

Returns PResult::C_OK if success, another result otherwise.

◆ Configure()

void PEnrollment::Configure ( const PDetector detector,
const PDescriber describer 
)

Configures this enroller to use the specified detector and describer.

◆ CreateWatchlist()

PResult PEnrollment::CreateWatchlist ( const PString configurationFile,
PWatchlist watchlist,
papillon::int32  maxFrames = -1,
papillon::int32  maxExamples = -1 
)

Creates a watchlist (a binary file) from a configuration file.

If the PEnrollment object is not configured yet, then PEnrollment::AutoConfigureForFaceRecognition() will be automatically called before processing.

The watchlist configuration file must be a text file with the following format:

[Watchlist]
SubjectsPath=/path/input/subjects
OutputFile=/path/to/output/watchlist.bin
[Subjects]
Kieron MESSER=/path/to/video/of/kieron01.avi;kieron02.jpg;kieron03.png
Kjetil JACOBSEN=/path/to/video/of/kjetil01.avi

SubjectsPath is optional: if present, then it is uses a the root path for all images/video files

Notes, we assume only one subject is present in each image or video file. For each video we analyse at most maxFrames until we get maxExamples. To use all frames and all examples set to -1.

◆ CreateWatchlistFromFolder()

PResult PEnrollment::CreateWatchlistFromFolder ( const PString path,
PWatchlist watchlist,
bool  thumbnail = true,
papillon::int32  maxFrames = -1,
papillon::int32  maxExamples = -1 
)

Creates a watchlist (a binary file) from a folder containing images, video clips or sub-folders.

If the PEnrollment object is not configured yet, then PEnrollment::AutoConfigureForFaceRecognition() will be automatically called before processing.

Each image or video file should contain only one people. Image and video filenames will be used as subject names. You can use suffix numbers to get several samples of the same subject. Warning: filename name are case sensitive: "John Doe.jpg" will be a different subject than "John DOE.jpg" (but will be the same than "John Doe2.jpg").

Example1: the folder could contain the following files:

/subjects/US_presidents
|___ "Kennedy1.jpg"
|___ "Kennedy2.jpg"
|___ "Johnson.jpg"
|___ "Nixon1.avi"
|___ "Nixon2.jpg"
|___ "Ford.avi"
|___ "Carter1.png"
|___ "Carter2.png"
|___ "Carter3.png"
|___ "Reagan.tif"
|___ "Bush1.jpg"
|___ "Bush2.jpg"
|___ "Clinton.mov"
|___ "BushGW1.mov"
|___ "BushGW2.mov"
|___ "Obama1.jpg"
|___ "Obama2.jpg"
|___ "Trump.png"
=> It will create a watchlist with 11 subjects: "Kennedy", ..., "Trump"

Example@: the folder could contain the following sub-folders:

/subjects/US_presidents
|___ "Kennedy01.jpg"
|___ "Kennedy02.jpg"
/subjects/US_presidents/Kennedy/
|___ "img1.jpg"
|___ "img2.jpg"
/subjects/US_presidents/Johnson/
|___ "video1.avi"
|___ "video2.jpg"
/subjects/US_presidents/Nixon/
|___ "Richard Nixon.mov"
=> It will create a watchlist with 3 subjects: "Kennedy", "Johnson" and "Nixon"

If the PEnrollment object is not configured yet, then PEnrollment::AutoConfigureForFaceRecognition() will be automatically called before processing.

For each video we analyse at most maxFrames until we get maxExamples. To use all frames and all examples set to -1.

◆ EnableDisplay()

void PEnrollment::EnableDisplay ( bool  isEnabled) const

Enables or disables display.

Display is disabled by default.

◆ EnrollFromCSV()

PResult PEnrollment::EnrollFromCSV ( const PString csvInputFilename,
papillon::int32  videoMaxFrames,
papillon::int32  videoMaxExamples,
const PString csvOutputFilename,
PWatchlist watchlist,
PCallback_EnrollFromCSV  callback = NULL 
) const

Enrolls the subjects from the specified CSV file and put descriptions into the specified watchlist.

Expected input CSV file in english format: separator must be comma (,) not semicolon (;)

The input CSV file must have the following format:

identifier (string) name (string) URL (string)
same string = same person displayed name images (JPG, PNG, TIF, BMP) or video file/stream

Example 1:

870ff17d-5c27-4f3e-a408-4e442e97e0cd,John Doe,john01.jpg
870ff17d-5c27-4f3e-a408-4e442e97e0cd,John Doe,/data/videos/johndoe.avi
d0abdbc7-d28d-47c3-a523-b062e859ad82,Jane Doe,images/jane.png

Example 2:

01,John Doe,john01.jpg
01,John Doe,/data/videos/johndoe.avi
02,Jane Doe,images/jane.png

Identifier can be any string used to uniquely identify a person: UUID, index, unique name, etc.

Video must only contain faces of the subject (no other subjects/faces expected). Stops enrollment if more than videoMaxExamples are found (use -1 for no limit) OR the end of the video stream has been reached OR videoMaxFrames has been analyzed (use -1 for no limit).

The output CSV file will contain the following information (append information if the file already exists):

timestamp identifier (string) name (string) URL (string) subject id OK or KO media type num detected faces bounding boxes of detected faces
PDateTime(ISO UTC) same as input file same as input file same as input file PGuid OK=success image or video 0..n see format below
  • If the identifier is a PGuid, then this identifier will be re-used as subject-id (id of the subject in the watchlist)
  • For images, bounding box string format is the following: x1 y1 width1 height1|x2 y2 width2 height2|...
  • For videos, bounding box string format is the following: frame_number1 x1 y1 width1 height1|frame_number2 x2 y2 width2 height2|...

Note: order of the lines in the output CSV file can be different from input CSV file because of asynchronous/multithreaded processing.

If the specified watchlist contains some subjects with the same name (identifier), then descriptions are merged.

Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromImage() [1/4]

PResult PEnrollment::EnrollFromImage ( const PImage image,
PDescription description,
const PString subjectName = PString::Empty(),
const PGuid subjectId = PGuid::CreateUniqueId() 
) const

DEPRECATED, use EnrollFromImageToDescription() instead.

Enrolls the subject found in the specified image into a description An empty name is given by default and a unique random guid.

Warning: image expected to be in BGR8U format (see PImage::Convert()); returns an error if wrong format.

Assumes there is only 1 subject in the image; returns an error otherwise. Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromImage() [2/4]

PResult PEnrollment::EnrollFromImage ( const PString imageFilename,
PDescription description,
const PString subjectName = PString::Empty(),
const PGuid subjectId = PGuid::CreateUniqueId() 
) const

DEPRECATED, use EnrollFromImageFilenameToDescription() instead.

Enrolls the subject found in the specified image into a description An empty name is given by default and a unique random guid.

Assumes there is only 1 subject in the image; returns an error otherwise. Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromImage() [3/4]

PResult PEnrollment::EnrollFromImage ( const PImage image,
const PGuid subjectId,
const PString subjectName,
PWatchlist watchlist 
) const

DEPRECATED, use EnrollFromImageToWatchlist() instead.

Enrolls the subject found in the specified image to the given watchlist.

If the subject already exists (according to the specified id), then the related description is updated, otherwise a new subject is created.

Warning: image expected to be in BGR8U format (see PImage::Convert()); returns an error if wrong format.

Assumes there is only 1 subject in the image; returns an error otherwise. Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromImage() [4/4]

PResult PEnrollment::EnrollFromImage ( const PString imageFilename,
const PGuid subjectId,
const PString subjectName,
PWatchlist watchlist 
) const

DEPRECATED, use EnrollFromImageFilenameToWatchlist() instead.

Enrolls the subject found in the specified image to the given watchlist.

If the subject already exists (according to the specified id), then the related description is updated, otherwise a new subject is created.

Assumes there is only 1 subject in the image; returns an error otherwise. Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromImageFilenameToDescription()

PResult PEnrollment::EnrollFromImageFilenameToDescription ( const PString imageFilename,
PDescription description,
const PString subjectName = PString::Empty(),
const PGuid subjectId = PGuid::CreateUniqueId() 
) const

Enrolls the subject found in the specified image file into a description By default, the enrolled subject will have an empty name and a unique random guid.

Assumes there is only 1 subject in the image; returns an error otherwise. Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromImageFilenameToWatchlist()

PResult PEnrollment::EnrollFromImageFilenameToWatchlist ( const PString imageFilename,
const PGuid subjectId,
const PString subjectName,
PWatchlist watchlist 
) const

Enrolls the subject found in the specified image to the given watchlist.

If the subject already exists (according to the specified id), then the related description is updated, otherwise a new subject is created.

Assumes there is only 1 subject in the image; returns an error otherwise. Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromImages() [1/2]

PResult PEnrollment::EnrollFromImages ( const PString path,
const PGuid subjectId,
const PString subjectName,
PWatchlist watchlist 
) const

DEPRECATED, use EnrollFromImagesToWatchlist() instead.

Enrolls the subject from all the images found in the specified path to the given watchlist.

If the subject already exists (according to the specified id), then the related description is updated, otherwise a new subject is created.

Assumes there is only 1 subject in the image; returns an error otherwise. Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromImages() [2/2]

PResult PEnrollment::EnrollFromImages ( const PString path,
PDescription description,
const PString subjectName = PString::Empty(),
const PGuid subjectId = PGuid::CreateUniqueId() 
) const

DEPRECATED, use EnrollFromImagesToWatchlist() instead.

Enrolls the subject from all the images found in the specified path.

Assumes there is only 1 subject in the image; returns an error otherwise. Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromImagesToDescription()

PResult PEnrollment::EnrollFromImagesToDescription ( const PString path,
PDescription description,
const PString subjectName = PString::Empty(),
const PGuid subjectId = PGuid::CreateUniqueId() 
) const

Enrolls the subject from all the images found in the specified path.

Assumes there is only 1 subject in the image; returns an error otherwise. Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromImagesToWatchlist()

PResult PEnrollment::EnrollFromImagesToWatchlist ( const PString path,
const PGuid subjectId,
const PString subjectName,
PWatchlist watchlist 
) const

Enrolls the subject from all the images found in the specified path to the given watchlist.

If the subject already exists (according to the specified id), then the related description is updated, otherwise a new subject is created.

Assumes there is only 1 subject in the image; returns an error otherwise. Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromImageToDescription()

PResult PEnrollment::EnrollFromImageToDescription ( const PImage image,
PDescription description,
const PString subjectName = PString::Empty(),
const PGuid subjectId = PGuid::CreateUniqueId() 
) const

Enrolls the subject found in the specified image into a description By default, the enrolled subject will have an empty name and a unique random guid.

Warning: image expected to be in BGR8U format (see PImage::Convert()); returns an error if wrong format.

Assumes there is only 1 subject in the image; returns an error otherwise. Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromImageToWatchlist()

PResult PEnrollment::EnrollFromImageToWatchlist ( const PImage image,
const PGuid subjectId,
const PString subjectName,
PWatchlist watchlist 
) const

Enrolls the subject found in the specified image to the given watchlist.

If the subject already exists (according to the specified id), then the related description is updated, otherwise a new subject is created.

Warning: image expected to be in BGR8U format (see PImage::Convert()); returns an error if wrong format.

Assumes there is only 1 subject in the image; returns an error otherwise. Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromVideo()

PResult PEnrollment::EnrollFromVideo ( const PString videoFilename,
PDescription description,
papillon::int32  maxFrames = -1,
papillon::int32  maxExamples = -1,
const PString subjectName = PString::Empty(),
const PGuid subjectId = PGuid::CreateUniqueId() 
) const

Enrolls the subject found in the specified video into a description.

Stops enrollment if more than maxExamples are found (use -1 for no limit) OR the end of the video stream has been reached OR maxFrames has been analyzed (use -1 for no limit).

Assumes this is always the same subject in the video.

Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromVideoStream() [1/2]

PResult PEnrollment::EnrollFromVideoStream ( PInputVideoStream ivs,
papillon::int32  maxFrames,
papillon::int32  maxExamples,
const PGuid subjectId,
const PString subjectName,
PWatchlist watchlist 
) const

DEPRECATED, use EnrollFromImagesToWatchlist() instead.

Enrolls the subject found in the specified video stream to the given watchlist.

If the subject already exists (according to the specified id), then the related description is updated, otherwise a new subject is created.

Stops enrollment if more than maxExamples are found (use -1 for no limit) OR the end of the video stream has been reached OR maxFrames has been analyzed (use -1 for no limit).

Assumes this is always the same subject in the video.

Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromVideoStream() [2/2]

PResult PEnrollment::EnrollFromVideoStream ( PInputVideoStream ivs,
PDescription description,
papillon::int32  maxFrames,
papillon::int32  maxExamples,
const PGuid subjectId,
const PString subjectName 
) const

DEPRECATED, use EnrollFromImagesToWatchlist() instead.

Enrolls the subject found in the specified video stream to the given watchlist.

If the subject already exists (according to the specified id), then the related description is updated, otherwise a new subject is created.

Stops enrollment if more than maxExamples are found (use -1 for no limit) OR the end of the video stream has been reached OR maxFrames has been analyzed (use -1 for no limit).

Assumes this is always the same subject in the video.

Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromVideoStreamToDescription()

PResult PEnrollment::EnrollFromVideoStreamToDescription ( PInputVideoStream ivs,
PDescription description,
papillon::int32  maxFrames,
papillon::int32  maxExamples,
const PGuid subjectId,
const PString subjectName 
) const

Enrolls the subject found in the specified video stream to the given watchlist.

If the subject already exists (according to the specified id), then the related description is updated, otherwise a new subject is created.

Stops enrollment if more than maxExamples are found (use -1 for no limit) OR the end of the video stream has been reached OR maxFrames has been analyzed (use -1 for no limit).

Assumes this is always the same subject in the video.

Returns PResult::C_OK if success, another result otherwise.

◆ EnrollFromVideoStreamToWatchlist()

PResult PEnrollment::EnrollFromVideoStreamToWatchlist ( PInputVideoStream ivs,
papillon::int32  maxFrames,
papillon::int32  maxExamples,
const PGuid subjectId,
const PString subjectName,
PWatchlist watchlist 
) const

Enrolls the subject found in the specified video stream to the given watchlist.

If the subject already exists (according to the specified id), then the related description is updated, otherwise a new subject is created.

Stops enrollment if more than maxExamples are found (use -1 for no limit) OR the end of the video stream has been reached OR maxFrames has been analyzed (use -1 for no limit).

Assumes this is always the same subject in the video.

Returns PResult::C_OK if success, another result otherwise.

◆ GetDescriber()

PDescriber PEnrollment::GetDescriber ( ) const

Returns the PDescriber associated with this enroller.

◆ GetDetector()

PDetector PEnrollment::GetDetector ( ) const

Returns the PDetector associated with this enroller.

◆ GetLastDescription()

PDescription PEnrollment::GetLastDescription ( ) const

Returns the description of the last subject enrolled (successful enrollment) or an empty description.

◆ IsConfigured()

bool PEnrollment::IsConfigured ( ) const

Returns true if this enroller is configured and ready to be used, false otherwise.

◆ operator=()

PEnrollment& PEnrollment::operator= ( const PEnrollment other)

Performs a shared copy of other to this object.