Use Cases¶
Remote Autocapture¶
One use case for Knomi Face Analyzer is performing automatic capture of a face once it meets certain criteria. Knomi Face Analyzer’s REST interface allows for this functionality even in cases where native code cannot be used, such as in a web browser.
- To implement this use case, the following end points are used:
- /calculateROI
- /autocaptureVideo
/calculateROI is used as an aid in building a usable GUI for an application. It is not strictly required for the use case, but it is recommended. What this endpoint does is calculate a region of interest based on the input video capture size and the profile being used. You can then use this region of interest to outline the area where the user should position their face. This will help improve usability and increase successes in using your application.
/autocaptureVideo is the primary endpoint used in this use case. This endpoint provides information on whether one of the provided images meets the criteria for capture. This infomration is provided in the form of feedback codes, which are detailed below. These feedback codes will either convey that the image is compliant and should be used or whether the image is not compliant, and a list of reasons why. By using the feedback codes and displaying appropriate messages to the user, they can be guided into capturing a compliant photo.
Feedback¶
Description
Here is the list of feedback codes that can be received from the /autocaptureVideo endpoint. It is not recommended that the descriptions be used directly in an application. Instead, consider how a user is interacting with the application and write an instruction for the user. For example, for FACE_TOO_FAR a proper message to the user could be “Move closer to the camera”.
Entries
NO_FACE_DETECTED - No faces were detected in the image.
MULTIPLE_FACES_DETECTED - Multiple faces were detected in the image. There must only be one subject in the image.*
COMPLIANT_IMAGE - The image analyzed is compliant with the current profile after construction.
CAPTURE_IMAGE - Capture criteria has been met.
IMAGE_RESOLUTION_TOO_LOW - The image resolution being used is too low to be compliant.
INVALID_POSE - The subject’s facial pose is invalid.
FACE_TOO_FAR - The subject’s face is too far from the camera.
FACE_TOO_CLOSE - The subject’s face is too close to the camera.
FACE_ON_LEFT - The subject’s face is too far to the left.
FACE_ON_RIGHT - The subject’s face is too far to the right.
FACE_TOO_LOW - The subject’s face is too low in the frame.
FACE_TOO_HIGH - The subject’s face is too hight in the frame.
TOO_MUCH_BLUR - The subject’s face is too blurry.
BACKGROUND_TOO_CLUTTERED - The background has too much clutter.
SMILE_PRESENT - The subject is smiling. The subject should have a neutral expression.
FOREHEAD_COVERING - The subject is wearing a forehead covering. The subject should remove the covering.
MASK_PRESENT - The subject is wearing a medical mask or similar facial covering. The subject should remove their mask.
FACIAL_SHADOWING - The lighting on the subject’s face is uneven. More uniform lighting is require.
RIGHT_EYE_CLOSED - The subject’s right eye is either closed or not clearly visible.
LEFT_EYE_CLOSED - The subject’s left eye is either closed or not clearly visible.
RED_EYE - A red eye effect was detected in the image.
OFF_ANGLE_GAZE - The subject’s gaze is off-center. The subject should look directly at the capture device.
GLASSES_PRESENT - The subject is wearing glasses. The subject should remove their glasses.
HEAVY_FRAMES - The subject is wearing thick framed glasses. The subject should remove their glasses.
GLARE - Lens glare has been detected on the subject’s glasses. The subject should remove their glasses.
DARK_GLASSES - The subject is wearing dark or tinted glasses. The subject should remove their glasses.
LIGHT_TOO_BRIGHT - The environmental lighting is too bright. Adjust the lighting in the capture area.
UNNATURAL_LIGHTING_COLOR - The environmental lighting is is considered an unnatural color. Adjust the lighting in the capture area.
BACKGROUND_TOO_BRIGHT - The background of the image is considered too bright. Adjust the lighting or image background.
BACKGROUND_TOO_DARK - The background of the image is considered too dark. Adjust the lighting or image background.
INSUFFICIENT_LIGHTING - The environmental lighting is too dark. Adjust the lighting in the capture area.
TOO_MUCH_LIGHT_ON_LEFT - The lighting on the left side of the image is too bright. Adjust the lighting in the capture area.
TOO_MUCH_LIGHT_ON_RIGHT - The lighting on the right side of the image is too bright. Adjust the lighting in the capture area.
TOO_MUCH_LIGHT_ABOVE - The lighting towards the top of the image is too bright. Adjust the lighting in the capture area.
FACE_OBSTRUCTED - The subject’s face is obstructed by an object. The object should be moved to no longer block the subject’s face.
* NOTE The MULTIPLE_FACES_DETECTED feedback will only occur when using a Face Detection Mode that is capable of detecting multiple faces. These are the FACE_ORDERING_BY_SCORE and FACE_ORDERING_BY_SIZE modes. The DOMINANT_FACE_BY_SIZE and DOMINANT_FACE_BY_SCORE Face Detection Modes will focus on the most prominent subject in the image ignoring any faces in the background.
Image Metric Calculation¶
Another use case for Knomi Face Analyzer is calculating various metrics for one or more images.
- To implement this use case, the following endpoint is used:
- /analyzeImage
/analyzeImage calculates a wide variety of information for input images. In addition to the information (called “metrics”) specified in the provided profile, the request can ask for addition metrics to be calculated and returned. This allows for a large amount of information to be determined for the input image. For details on the specific metrics that can be returned, please see the Metrics chapter.