mheimann

mheimann / RecognizeFaces / 0.1.3

README.md

Uses a trained face recognizer to identify faces. This is a wrapper for the FaceRecognition algorithm.  The FaceRecognition algorithm additionally requires a user to specify a "classify" 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 "Path" field specifying the image URL (e.g. the path to the image in an Algorithmia collection).  Optionally, it may have a "ID" field with an ID (or label) saying whose face is pictured.  This is useful mainly for academic purposes to evaluate the model; of course in many real-world situations the point of having a face recognizer is to recognize people whose identity is not explicitly labeled already.  

(Note: if an image has multiple faces, each face will be classified.  As in the accompanying Train/Update Face Recognizer algorithms, any ID that is provided will be the "ground truth" ID for each face in the image.)

Users must also specify the full path to a face recognizer in an Algorithmia data collection (including the name of the face recognizer XML file).  There must also be a map of human IDs to internal numeric labels in a file with the same name plus an "_idList.txt" tag and extension instead of a ".xml" extension. Both files must have the same name and must be in the same directory (the default name is facerec.xml and facerec_idList.txt).  These would both have been created, say, by a run of the companion Train Face Recognizer algorithm.  

The output will be in JSON format, where each image path will have a list of predictions--one prediction for each face in the image--in JSON format.  Each prediction will contain: the predicted ID, the actual ID (if known), and the uncertainty, which is actually a distance measure to the nearest match.  Note: the predicted ID will be "Unknown" if the uncertainty is too high (at this time the threshold is 100).  (For clarity, it is obviously highly recommended that "Unknown" not be used as a valid image ID.)