Skip to content

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:

  • scenario is the name of the scenario.
  • outputImageParams are the preprocessing parameters: cut, background fill, resize.
  • onlyCentralFace is for defining whether to check only the central face on the image or all the faces.
  • quality includes the image quality assessment parameters.
  • attributes includes 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.