Scenarios
A scenario is a named list of procedures and checks. When you select a scenario, only the included into the scenario parameters are checked and all the others are ignored.
Why use scenarios?
- Using a scenario provides a simple request code. Instead of listing several dozen parameters, you can indicate just one line with the name of the scenario.
- If your requirements change, you do not have to edit the application code but just correct the necessary parameters in the scenario.
Scenario structure
A scenario may consist of the following blocks:
scenariois the name of the scenario.outputImageParamsare the preprocessing parameters: cut, background fill, resize.onlyCentralFaceis for defining whether to check only the central face on the image or all the faces.qualityincludes the image quality assessment parameters.attributesincludes the attribute assessment parameters.
A scenario that does not contain outputImageParams, quality, attributes can perform only face detection.
If there is no processParam field in the request, a dummy scenario OldMode is generated and you can set only the onlyCentralFace and thumbnails parameters to evaluate only the central face and return the cropped face images.
Predefined scenarios
The settings for all the scenarios are listed in the Scenarios file.
QualityFull
Checks all the available quality characteristics.
See the `QualityFull` configuration
{
"scenario": "QualityFull",
"onlyCentralFace": true,
"outputImageParams": {
"crop": {"type": 0, "padColor": [128, 128, 128]}
},
"quality": {
"backgroundMatchColor": [255, 255, 255],
"config": [
{"name": "ImageWidth", "range": [1200.0, 10000.0]},
{"name": "ImageHeight", "range": [1600.0, 10000.0]},
{"name": "ImageWidthToHeight", "range": [0.74, 0.80]},
{"name": "ImageChannelsNumber", "range": [3.0, 3.0]},
{"name": "FaceMidPointHorizontalPosition", "range": [0.45, 0.55]},
{"name": "FaceMidPointVerticalPosition", "range": [0.3, 0.5]},
{"name": "HeadWidthRatio", "range": [0.5, 0.75]},
{"name": "HeadHeightRatio", "range": [0.6, 0.9]},
{"name": "EyesDistance", "range": [90.0, 10000.0]},
{"name": "Yaw", "range": [-5.0, 5.0]},
{"name": "Pitch", "range": [-8.0, 8.0]},
{"name": "Roll", "range": [-5.0, 5.0]},
{"name": "BlurLevel", "range": [0.0, 0.15]},
{"name": "NoiseLevel", "range": [0.0, 0.20]},
{"name": "EyeRightClosed", "range": [0.0, 0.5]},
{"name": "EyeLeftClosed", "range": [0.0, 0.5]},
{"name": "EyeRightOccluded", "range": [0.0, 0.5]},
{"name": "EyeLeftOccluded", "range": [0.0, 0.5]},
{"name": "EyesRed", "range": [0.0, 0.5]},
{"name": "EyeRightCoveredWithHair", "range": [0.0, 0.05]},
{"name": "EyeLeftCoveredWithHair", "range": [0.0, 0.05]},
{"name": "OffGaze", "range": [0.0, 0.40]},
{"name": "FaceDynamicRange", "range": [7.0, 8.0]},
{"name": "UnnaturalSkinTone", "range": [0.0, 0.5]},
{"name": "TooDark", "range": [0.0, 0.38]},
{"name": "TooLight", "range": [0.0, 0.5]},
{"name": "FaceGlare", "range": [0.0, 0.01]},
{"name": "ShadowsOnFace", "range": [0.0, 0.5]},
{"name": "DarkGlasses", "range": [0.0, 0.5]},
{"name": "ReflectionOnGlasses", "range": [0.0, 0.5]},
{"name": "FramesTooHeavy", "range": [0.0, 6.0]},
{"name": "FaceOccluded", "range": [0.0, 0.06]},
{"name": "HeadCovering", "range": [0.0, 0.5]},
{"name": "BackgroundUniformity", "range": [0.9, 1.0]},
{"name": "ShadowsOnBackground", "range": [0.9, 1.0]},
{"name": "OtherFaces", "range": [1.0, 1.0]},
{"name": "ShouldersPose", "range": [0.6, 1.0]},
{"name": "ExpressionLevel", "range": [0.0, 0.84]},
{"name": "MouthOpen", "range": [0.0, 0.5]},
{"name": "ContactLenses", "range": [0.0, 0.5]},
{"name": "ForeheadCovering", "range": [0.0, 0.5]},
{"name": "Smile", "range": [0.0, 0.5]},
{"name": "MedicalMask", "range": [0.0, 0.5]},
{"name": "StrongMakeup", "range": [0.0, 0.5]},
{"name": "Headphones", "range": [0.0, 0.5]},
{"name": "BackgroundColorMatch", "range": [0.8, 1.0]},
{"name": "PaddingRatio", "range": [0.0, 0.05]},
{"name": "ArtFace", "range": [0.0, 0.5]}
]
}
},
QualityICAO
Checks the quality characteristics based on the ICAO standard.
See the `QualityICAO` configuration
{
"scenario": "QualityICAO",
"onlyCentralFace": true,
"outputImageParams": {
"crop": {"type": 0, "size": [480, 640], "padColor": [128, 128, 128]}
},
"quality": {
"backgroundMatchColor": [255, 255, 255],
"config": [
{"name": "ImageWidth", "range": [480.0, 10000.0]},
{"name": "ImageHeight", "range": [640.0, 10000.0]},
{"name": "ImageWidthToHeight", "range": [0.74, 0.80]},
{"name": "ImageChannelsNumber", "range": [3.0, 3.0]},
{"name": "FaceMidPointHorizontalPosition", "range": [0.45, 0.55]},
{"name": "FaceMidPointVerticalPosition", "range": [0.3, 0.5]},
{"name": "HeadWidthRatio", "range": [0.5, 0.75]},
{"name": "HeadHeightRatio", "range": [0.6, 0.9]},
{"name": "EyesDistance", "range": [90.0, 10000.0]},
{"name": "Yaw", "range": [-5.0, 5.0]},
{"name": "Pitch", "range": [-8.0, 8.0]},
{"name": "Roll", "range": [-5.0, 5.0]},
{"name": "BlurLevel", "range": [0.0, 0.15]},
{"name": "NoiseLevel", "range": [0.0, 0.20]},
{"name": "EyeRightClosed", "range": [0.0, 0.5]},
{"name": "EyeLeftClosed", "range": [0.0, 0.5]},
{"name": "EyeRightOccluded", "range": [0.0, 0.5]},
{"name": "EyeLeftOccluded", "range": [0.0, 0.5]},
{"name": "EyesRed", "range": [0.0, 0.5]},
{"name": "EyeRightCoveredWithHair", "range": [0.0, 0.05]},
{"name": "EyeLeftCoveredWithHair", "range": [0.0, 0.05]},
{"name": "OffGaze", "range": [0.0, 0.40]},
{"name": "FaceDynamicRange", "range": [7.0, 8.0]},
{"name": "UnnaturalSkinTone", "range": [0.0, 0.5]},
{"name": "TooDark", "range": [0.0, 0.38]},
{"name": "TooLight", "range": [0.0, 0.5]},
{"name": "FaceGlare", "range": [0.0, 0.5]},
{"name": "ShadowsOnFace", "range": [0.0, 0.5]},
{"name": "DarkGlasses", "range": [0.0, 0.5]},
{"name": "ReflectionOnGlasses", "range": [0.0, 0.5]},
{"name": "FramesTooHeavy", "range": [0.0, 6.0]},
{"name": "FaceOccluded", "range": [0.0, 0.06]},
{"name": "HeadCovering", "range": [0.0, 0.5]},
{"name": "BackgroundUniformity", "range": [0.9, 1.0]},
{"name": "ShadowsOnBackground", "range": [0.9, 1.0]},
{"name": "OtherFaces", "range": [1.0, 1.0]},
{"name": "ShouldersPose", "range": [0.6, 1.0]},
{"name": "ExpressionLevel", "range": [0.0, 0.84]},
{"name": "MouthOpen", "range": [0.0, 0.5]},
{"name": "ContactLenses", "range": [0.0, 0.5]},
{"name": "ForeheadCovering", "range": [0.0, 0.5]},
{"name": "Smile", "range": [0.0, 0.5]},
{"name": "StrongMakeup", "range": [0.0, 0.5]},
{"name": "Headphones", "range": [0.0, 0.5]},
{"name": "ArtFace", "range": [0.0, 0.5]}
]
}
},
QualityVisaSchengen
Checks the quality characteristics based on the Schengen visa standard.
See the `QualityVisaSchengen` configuration
{
"scenario": "QualityVisaSchengen",
"onlyCentralFace": true,
"outputImageParams": {
"crop": {"type": 4, "size": [420, 540], "padColor": [255, 255, 255]}
},
"quality": {
"backgroundMatchColor": [255, 255, 255],
"config": [
{"name": "ImageWidth", "range": [420.0, 10000.0]},
{"name": "ImageHeight", "range": [540.0, 10000.0]},
{"name": "ImageWidthToHeight", "range": [0.74, 0.80]},
{"name": "ImageChannelsNumber", "range": [3.0, 3.0]},
{"name": "FaceMidPointHorizontalPosition", "range": [0.45, 0.55]},
{"name": "FaceMidPointVerticalPosition", "range": [0.3, 0.5]},
{"name": "HeadWidthRatio", "range": [0.5, 0.75]},
{"name": "HeadHeightRatio", "range": [0.6, 0.9]},
{"name": "EyesDistance", "range": [90.0, 10000.0]},
{"name": "Yaw", "range": [-5.0, 5.0]},
{"name": "Pitch", "range": [-8.0, 8.0]},
{"name": "Roll", "range": [-5.0, 5.0]},
{"name": "BlurLevel", "range": [0.0, 0.15]},
{"name": "NoiseLevel", "range": [0.0, 0.20]},
{"name": "EyeRightClosed", "range": [0.0, 0.5]},
{"name": "EyeLeftClosed", "range": [0.0, 0.5]},
{"name": "EyeRightOccluded", "range": [0.0, 0.5]},
{"name": "EyeLeftOccluded", "range": [0.0, 0.5]},
{"name": "EyesRed", "range": [0.0, 0.5]},
{"name": "EyeRightCoveredWithHair", "range": [0.0, 0.05]},
{"name": "EyeLeftCoveredWithHair", "range": [0.0, 0.05]},
{"name": "OffGaze", "range": [0.0, 0.40]},
{"name": "FaceDynamicRange", "range": [7.0, 8.0]},
{"name": "UnnaturalSkinTone", "range": [0.0, 0.5]},
{"name": "TooDark", "range": [0.0, 0.38]},
{"name": "TooLight", "range": [0.0, 0.5]},
{"name": "FaceGlare", "range": [0.0, 0.5]},
{"name": "ShadowsOnFace", "range": [0.0, 0.5]},
{"name": "DarkGlasses", "range": [0.0, 0.5]},
{"name": "ReflectionOnGlasses", "range": [0.0, 0.5]},
{"name": "FramesTooHeavy", "range": [0.0, 6.0]},
{"name": "FaceOccluded", "range": [0.0, 0.06]},
{"name": "HeadCovering", "range": [0.0, 0.5]},
{"name": "BackgroundUniformity", "range": [0.9, 1.0]},
{"name": "ShadowsOnBackground", "range": [0.9, 1.0]},
{"name": "OtherFaces", "range": [1.0, 1.0]},
{"name": "ShouldersPose", "range": [0.6, 1.0]},
{"name": "ExpressionLevel", "range": [0.0, 0.84]},
{"name": "MouthOpen", "range": [0.0, 0.5]},
{"name": "ContactLenses", "range": [0.0, 0.5]},
{"name": "ForeheadCovering", "range": [0.0, 0.5]},
{"name": "Smile", "range": [0.0, 0.5]},
{"name": "StrongMakeup", "range": [0.0, 0.5]},
{"name": "Headphones", "range": [0.0, 0.5]}
]
}
},
QualityVisaUSA
Checks the quality characteristics based on the USA visa standard.
See the `QualityVisaUSA` configuration
{
"scenario": "QualityVisaUSA",
"onlyCentralFace": true,
"outputImageParams": {
"crop": {"type": 3, "size": [600, 600], "padColor": [255, 255, 255]}
},
"quality": {
"backgroundMatchColor": [255, 255, 255],
"config": [
{"name": "ImageWidth", "range": [600, 1200.0]},
{"name": "ImageHeight", "range": [600.0, 1200.0]},
{"name": "ImageWidthToHeight", "range": [1.0, 1.0]},
{"name": "ImageChannelsNumber", "range": [3.0, 3.0]},
{"name": "FaceMidPointHorizontalPosition", "range": [0.45, 0.55]},
{"name": "FaceMidPointVerticalPosition", "range": [0.3, 0.5]},
{"name": "HeadWidthRatio", "range": [0.5, 0.75]},
{"name": "HeadHeightRatio", "range": [0.6, 0.9]},
{"name": "EyesDistance", "range": [90.0, 10000.0]},
{"name": "Yaw", "range": [-5.0, 5.0]},
{"name": "Pitch", "range": [-8.0, 8.0]},
{"name": "Roll", "range": [-5.0, 5.0]},
{"name": "BlurLevel", "range": [0.0, 0.15]},
{"name": "NoiseLevel", "range": [0.0, 0.20]},
{"name": "EyeRightClosed", "range": [0.0, 0.5]},
{"name": "EyeLeftClosed", "range": [0.0, 0.5]},
{"name": "EyeRightOccluded", "range": [0.0, 0.5]},
{"name": "EyeLeftOccluded", "range": [0.0, 0.5]},
{"name": "EyesRed", "range": [0.0, 0.5]},
{"name": "EyeRightCoveredWithHair", "range": [0.0, 0.05]},
{"name": "EyeLeftCoveredWithHair", "range": [0.0, 0.05]},
{"name": "OffGaze", "range": [0.0, 0.40]},
{"name": "FaceDynamicRange", "range": [7.0, 8.0]},
{"name": "UnnaturalSkinTone", "range": [0.0, 0.5]},
{"name": "TooDark", "range": [0.0, 0.38]},
{"name": "TooLight", "range": [0.0, 0.5]},
{"name": "FaceGlare", "range": [0.0, 0.5]},
{"name": "ShadowsOnFace", "range": [0.0, 0.5]},
{"name": "DarkGlasses", "range": [0.0, 0.5]},
{"name": "ReflectionOnGlasses", "range": [0.0, 0.5]},
{"name": "FramesTooHeavy", "range": [0.0, 6.0]},
{"name": "FaceOccluded", "range": [0.0, 0.06]},
{"name": "HeadCovering", "range": [0.0, 0.5]},
{"name": "BackgroundUniformity", "range": [0.9, 1.0]},
{"name": "ShadowsOnBackground", "range": [0.9, 1.0]},
{"name": "OtherFaces", "range": [1.0, 1.0]},
{"name": "ShouldersPose", "range": [0.6, 1.0]},
{"name": "ExpressionLevel", "range": [0.0, 0.84]},
{"name": "MouthOpen", "range": [0.0, 0.5]},
{"name": "ContactLenses", "range": [0.0, 0.5]},
{"name": "ForeheadCovering", "range": [0.0, 0.5]},
{"name": "Smile", "range": [0.0, 0.5]},
{"name": "StrongMakeup", "range": [0.0, 0.5]},
{"name": "Headphones", "range": [0.0, 0.5]},
{"name": "BackgroundColorMatch", "range": [0.8, 1.0]}
]
}
},
CropCentralFace
Returns the cropped portrait of the person whose face is the most central in the photo.
If the head in the original image is tilted, for the returned portrait, it is aligned in a straight vertical line so that the dimensions ratio of the returned portrait would be 3x4.
In case the original size of the cropped portrait is insufficient for alignment, it will be supplemented, "padded" with the gray color (RGB 128, 128, 128).
If the original size of the image allows, the size of the returned portrait will be 300x400 px.
See the `CropCentralFace` configuration
{
"scenario": "CropCentralFace",
"outputImageParams": {
"crop": {"type": 0, "size": [300, 400], "padColor": [128, 128, 128]}
},
"onlyCentralFace": true
},
CropAllFaces
Returns the cropped portraits of all the people in the image.
If a head in the original image is tilted, for the returned portrait, it is aligned in a straight vertical line so that the dimensions ratio of the returned portrait would be 3x4.
In case the original size of the cropped portrait is insufficient for alignment, it will be supplemented, "padded" with the gray color (RGB 128, 128, 128).
If the original size of the image allows, the size of the returned portraits will be 300x400 px.
See the `CropAllFaces` configuration
{
"scenario": "CropAllFaces",
"outputImageParams": {
"crop": {"type": 0, "size": [300, 400], "padColor": [128, 128, 128]}
},
"onlyCentralFace": false
},
Thumbnail
The same as the CropCentralFace scenario but without any resize. Returns the cropped portrait of the person whose face is the most central in the photo.
If the head in the original image is tilted, for the returned portrait, it is aligned in a straight vertical line so that the dimensions ratio of the returned portrait would be 3x4.
In case the original size of the cropped portrait is insufficient for alignment, it will be supplemented, "padded" with the gray color (RGB 128, 128, 128).
See the `Thumbnail` configuration
{
"scenario": "Thumbnail",
"outputImageParams": {
"crop": {"type": 0, "padColor": [128, 128, 128]}
},
"onlyCentralFace": true
},
AttributesAll
Returns all the available attributes evaluation results.
See the `AttributesAll` configuration
{
"scenario": "AttributesAll",
"attributes": {
"config": [
{"name": "Age"},
{"name": "EyeRight"},
{"name": "EyeLeft"},
{"name": "Emotion"},
{"name": "Smile"},
{"name": "Glasses"},
{"name": "HeadCovering"},
{"name": "ForeheadCovering"},
{"name": "Mouth"},
{"name": "MedicalMask"},
{"name": "Occlusion"},
{"name": "StrongMakeup"},
{"name": "Headphones"}
]
},
How to add scenario
To add your named scenario, first, create a file with the new scenario's settings, it should be of the same structure as the Scenarios file.
Then add the path to this file with your scenario through the environment variable FACEAPI_CONFIG_FILE_PATH when loading the service.