mheimann / TrainFaceRecognizer / 0.1.5

Trains a face recognizer from a labeled set of faces. This is a wrapper for the FaceRecognition algorithm.  The FaceRecognition algorithm additionally requires a user to specify a "train" mode, so this wrapper makes things slightly more convenient. 

Users must pass in a list of JSON objects, one for each image.  Each image JSON object must have a "ID" field with an ID (or label) saying whose face is pictured.  It must also have a "Path" field specifying the image URL (e.g. the path to the image in an Algorithmia collection).

(Note: if an image has multiple faces, all faces will be detected and used in training, but each face will have the ID specified to the image as a whole.  For instance, in a multi-face picture of the Smith siblings, each face will be used for training and each will have the image "Smith siblings".   It is difficult to specify labels more precisely than that, so that is the greatest level of precision this algorithm supports.)

After preprocessing the image data by using an OpenCV face detector to detect faces, this program trains a face recognizer using Local Binary Pattern Histograms, also as implemented in OpenCV.  This face recognizer will be saved in XML format to a data collection of the user's choosing, along with a file of the same name (but with an additional _idList tag and a .txt extension) that maps people's IDs to numeric labels used internally.  For use when updating the model or classifying with it, both files must have the same name and must be in the same directory.

Users must also specify an Algorithmia data collection to which a face recognizer can be written as well as a file name for the face recognizer.  This is done by specifying the full path that the .xml face recognizer file will have when saved (including the file name and a .xml extension).  If a file with this path exists, the model in that file will be updated with the new training images.  Otherwise, a new model will be created from scratch.  

Upon successful completion, a user will receive a notification: "Successfully completed!"  In the specified directory will then be the face recognition model (face recognizer and ID list).