Bulk editing LUNA ID parameters via a file#

LUNA ID allows you to configure runtime parameters in two ways:

Programmatically in your code
Declaratively via a configuration file

Important: These approaches are mutually exclusive at runtime. Changing parameter values in your code will not automatically change them in a configuration file.

In LUNA ID for Android#

Configuration file#

LUNA ID allows you to set LunaConfig and ShowCameraParams by passing a valid JSON file containing the corresponding objects and configuration parameter values.

Validation rules#

Missing fields#

Missing configuration fields are allowed. Unspecified parameters will use the LUNA ID default values. For example:

{
"LunaConfig": {},
"ShowCameraParams": {
    "recordVideo": true,
    "recordingTimeMillis": 10000
}
}

Here, all omitted LunaConfig fields and the omitted ShowCameraParams fields (other than recordVideo and recordingTimeMillis) assume their default values.

Mandatory objects#

Both LunaConfig and ShowCameraParams objects must be present. If either is missing, the IllegalArgumentException exception is thrown. For example:

{
  "ShowCameraParams": {
    "recordVideo": true,
    "recordingTimeMillis": 10000
  }
}

Unknown fields#

Including fields not defined in the configuration objects will trigger IllegalArgumentException. For example:

{
  "ShowCameraParams": {
    "someUnexistedField": "someValue"
  }
}

Implementation#

Setting LunaConfig via file#

fun initEngine(
  context: Context,
  configFile: File,
  apiHumanConfig: ApiHumanConfig? = null,
  license: File? = null,
  timeoutMillis: Long = 30_000L
)

Setting ShowCameraParams via file#

fun showCamera(
  context: Context,
  configFile: File,
  interactions: Interactions = Interactions(),
  commands: Commands = Commands(),
  enterAnim: Int = 0,
  exitAnim: Int = 0
)

File structure#

Example structure of the configuration file

Below is an example structure of the file:

{
"LunaConfig": {
    "livenessFormat": "JPEG",
    "compressionQuality": 50,
    "detectorStep": 7,
    "skipFrames": 18,
    "minimalTrackLength": 1,
    "bestShotsCount": 1,
    "bestShotInterval": 500,
    "headPitch": 25.0,
    "headYaw": 25.0,
    "headRoll": 25.0,
    "ags": 0.5,
    "livenessType": "None",
    "acceptOneEyed": false,
    "acceptOccludedFaces": true,
    "acceptMask": true,
    "foundFaceDelayMs": 0,
    "interactionDelayMs": 0,
    "acceptEyesClosed": false,
    "glassesChecks": [
        "GLASSES_CHECK_SUN",
        "GLASSES_CHECK_DIOPTER"
    ],
    "usePrimaryFaceTracking": true,
    "faceSimilarityThreshold": 0.5,
    "livenessQuality": 0.5,
    "livenessNetVersion": "MOBILE",
    "multipartBestShotsEnabled": false,
    "eyesAggregationEnabled": true,
    "glassesAggregationEnabled": true,
    "faceOcclusionAggregationEnabled": true,
    "savingInteractionFrames": false,
    "strictlyMinSize": false,
    "blurThreshold": 0.61,
    "lightThreshold": 0.57,
    "darknessThreshold": 0.5,
    "minFaceSize": 50,
    "descriptorVersion": 60,
    "useDescriptors": true,
    "trackAggregationEnabled": true,
    "cloudDeviceCheckEnabled": true
},
"ShowCameraParams": {
    "recordVideo": false,
    "recordingTimeMillis": 0,
    "ignoreVideoWithoutFace": true,
    "borderDistanceStrategy": {
        "type": "Default"
    },
    "autoFocus": true,
    "checkSecurity": false,
    "minFaceSideToMinScreenSide": 0.3,
    "previewResolutionSelector": {
        "width": 640,
        "height": 480,
        "fallbackRule": "CLOSEST_HIGHER",
        "aspectRatio": "RATIO_16_9"
    },
    "analysisResolutionSelector": {
        "width": 640,
        "height": 480,
        "fallbackRule": "CLOSEST_HIGHER",
        "aspectRatio": "RATIO_16_9"
    },
    "videoQualitySelector": "SD"
}
}

Configuration parameters#

The parameters listed in the configuration file are as follows:

LunaConfig parameters#

Parameter	Default value	Description
`livenessFormat`	`JPEG`	Specifies the image compression format used for OneShotLiveness estimation. Possible values: `JPEG` `PNG` `WEBP` `WEBP_LOSSY` `WEBP_LOSSLESS`
`compressionQuality`	50	Specifies a quality of the image to be sent to OneShotLiveness estimation. Value 0 represents the maximum compression.
`detectorStep`	7	Specifies a number of frames between frames with full face detection.
`skipFrames`	18	Specifies a number of frames to wait until a face is detected in the face recognition area before video recording is stopped.
`minimalTrackLength`	1	Specifies the minimum number of detections to consider there is a real face in a video track.
`bestShotsCount`	1	Specifies a number of best shots that need to be collected for a OneShotLiveness estimation.
`bestShotInterval`	500	Specifies a minimum time interval between best shots.
`headPitch`	25.0	Specifies the head rotation angle along the X axis.
`headYaw`	25.0	Specifies the head rotation angle along the Z axis.
`headRoll`	25.0	Specifies the head rotation angle along the Y axis.
`ags`	0.5	Specifies the AGS threshold for further descriptor extraction and matching. For details, see AGS estimation.
`livenessType`	`None`	Specifies a OneShotLiveness estimation type. Possible values: `None` - Disables OneShotLiveness estimation. `Online` - Enables the Online OneShotLiveness estimation. `Offline` - Enables the Offline OneShotLiveness estimation.
`acceptOneEyed`	`false`	Enables or disables the Dynamic Liveness estimation interaction via blinking with one eye.
`acceptOccludedFaces`	`true`	Specifies whether an image with an occluded face will be considered the best shot.
`acceptMask`	`true`	Specifies whether faces wearing medical masks are allowed in best shot selection.
`foundFaceDelayMs`	0	Specifies a delay, in milliseconds, to define for how long a user's face should be placed in the face detection bounding box before the best shot is taken.
`interactionDelayMs`	0	Specifies a timeout between Dynamic Liveness estimation interactions, in milliseconds. This means that a new interaction will start after the preceding one ends after the timeout has passed.
`acceptEyesClosed`	`false`	Specifies whether an image with two closed eyes will be considered the best shot.
`glassesChecks`	`["GLASSES_CHECK_SUN", "GLASSES_CHECK_DIOPTER"]`	Specifies what images with glasses can be best shots. For details, see Getting the best shot with faces with occluded eyes.
`usePrimaryFaceTracking`	`true`	Specifies whether to track the face that was detected in the face recognition area first. For details, see Tracking face identity.
`faceSimilarityThreshold`	0.5	Specifies a threshold that determines whether the face that was first detected in the face recognition area remains the same when tracking face identity.
`livenessQuality`	0.5	Specifies a OneShotLiveness estimation threshold lower which the system will consider the result as a presentation attack.
`livenessNetVersion`	`MOBILE`	Specifies a OneShotLiveness estimation network version. For details, see Performing Offline OneShotLiveness estimation. Possible values: `LITE` - Loads the neural network models: oneshot_rgb_liveness_v13_model_4_arm.plan oneshot_rgb_liveness_v13_model_5_arm.plan `MOBILE` - Loads only the oneshot_rgb_liveness_v13_model_6_arm.plan model. Recommended for devices with lower performance.
`multipartBestShotsEnabled`	`false`	Enables or disables collecting of multiple best shots. For details, see Sending multiple frames for estimation aggregation to the backend.
`eyesAggregationEnabled`	`true`	Enables or disables eye status estimation aggregation.
`glassesAggregationEnabled`	`true`	Enables or disables glasses estimation aggregation.
`faceOcclusionAggregationEnabled`	`true`	Enables or disables face occlusion estimation aggregation.
`savingInteractionFrames`	`false`	Enables or disables saving of Dynamic Liveness interaction frames.
`strictlyMinSize`	`false`	Specifies whether the `minFaceSize` parameter will be considered during face detection.
`blurThreshold`	0.61	Specifies a threshold that determines whether the image is blurred.
`lightThreshold`	0.57	Specifies a threshold that determines whether the image is overexposed, that is, too light.
`darknessThreshold`	0.5	Specifies a threshold that determines whether the image is underexposed, that is, too dark.
`minFaceSize`	50	Specifies the minimum acceptable size, in pixels, for a detected face. Faces smaller than this size will be ignored during the detection process. The parameter values range from 20 to 350. When set to a higher value, it ensures that only larger, more prominent faces are processed, which can improve performance and reduce noise from distant or small faces. When set to a lower value, it allows for the detection of smaller faces but may increase processing time and the likelihood of detecting irrelevant faces.
`descriptorVersion`	60	Determines the model version used for descriptor generation or comparison.
`useDescriptors`	`true`	Enables or disables descriptor-related functionality.
`trackAggregationEnabled`	`true`	Enables or disables aggregation in TrackEngine.
`cloudDeviceCheckEnabled`	`true`	Enables or disables cloud device detection during security checks.

ShowCameraParams parameters#

Parameter	Default value	Description
`recordVideo`	`false`	Enables or disables video recording.
`recordingTimeMillis`	0	Limits a video stream's duration. The parameter is mandatory if `recordVideo` is set to `true`.
`ignoreVideoWithoutFace`	`true`	Specifies whether to record a video stream only with the face detected.
`borderDistanceStrategy`	`{"type": "Default"}`	Defines the strategy to be used to specify face recognition area borders. It depends on the `type` property: `Default` - No additional padding: `"borderDistanceStrategy": { "type": "Default" }` `WithDp` - Specifies padding in density-independent pixels (dp): `"borderDistanceStrategy": { "type": "WithDp", "topPaddingInDp": 8, "bottomPaddingInDp": 8, "leftPaddingInDp": 8, " rightPaddingInDp": 8 }`
`autoFocus`	`true`	Enables or disables continuous autofocus.
`checkSecurity`	`false`	Enables or disables the virtual camera usage check.
`minFaceSideToMinScreenSide`	0.3	Defines the minimum face-to-screen ratio [0.0..1.0].
`previewResolutionSelector`	`{ "width": 640, "height": 480, "fallbackRule": "CLOSEST_HIGHER", "aspectRatio": "RATIO_16_9" }`	Sets the resolution of the video stream displayed on the device screen (UI preview). `width` - Desired width (in pixels). `height` Desired height (in pixels). `fallbackRule` - Strategy when exact resolution is unavailable: `CLOSEST_HIGHER` or `CLOSEST_LOWER`. `aspectRatio` - Preferred aspect ratio: `RATIO_16_9` or `RATIO_4_3`.
`analysisResolutionSelector`	`{ "width": 640, "height": 480, "fallbackRule": "CLOSEST_HIGHER", "aspectRatio": "RATIO_16_9" }`	Defines the resolution of frames sent to the LUNA ID detector for facial analysis (for example, liveness, attribute estimation). `width` - Desired width (in pixels). `height` Desired height (in pixels). `fallbackRule` - Strategy when exact resolution is unavailable: `CLOSEST_HIGHER` or `CLOSEST_LOWER`. `aspectRatio` - Preferred aspect ratio: `RATIO_16_9` or `RATIO_4_3`.
`videoQualitySelector`	`SD`	Determines the quality of the recorded video output. Possible values: `SD` `HD` `FHD` `UHD`

In LUNA ID for iOS#

Configuration file#

Using the LCLunaConfiguration.plist file allows you to bulk edit all the LUNA ID parameters in one place. The file is located in the following directory:

.\luna-id-sdk_ios_v.X.X.X\frameworks\LunaCore.xcframework\ios-arm64\LunaCore.framework\LCLunaConfiguration.plist

Implementation#

To apply the parameters, pass them to the LCLunaConfiguration object:

LCLunaConfiguration(plistFromDocuments: plist)

File structure#

Example structure of LCLunaConfiguration.plist

Below is an example structure of the file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>LCLunaConfiguration</key>
    <dict>
        <key>multipartBestShotsEnabled</key>
        <false/>
        <key>glassesCheckEnabled</key>
        <false/>
        <key>aggregationEnabled</key>
        <false/>
        <key>ocrEnabled</key>
        <false/>
        <key>interactionEnabled</key>
        <true/>
        <key>saveOnlyFaceVideo</key>
        <false/>
        <key>trackFaceIdentity</key>
        <false/>
        <key>occludeCheck</key>
        <true/>
        <key>advancedSunglasses</key>
        <false/>
        <key>eyeInjury</key>
        <true/>
        <key>startDelay</key>
        <integer>0</integer>
        <key>faceTime</key>
        <integer>0</integer>
        <key>compressionQuality</key>
        <real>0.8</real>
        <key>documentVerificationMatch</key>
        <real>0.7</real>
        <key>primaryFaceMatching</key>
        <real>0.7</real>
        <key>plistLicenseFileName</key>
        <string>vllicense.plist</string>
        <key>videoRecordLength</key>
        <integer>0</integer>
        <key>emptyFrameTime</key>
        <integer>0</integer>
    </dict>
    <key>LCBestShotConfiguration</key>
    <dict>
        <key>livenessType</key>
        <integer>1</integer>
        <key>eyesCheck</key>
        <true/>
        <key>borderDistance</key>
        <integer>10</integer>
        <key>minDetSize</key>
        <integer>200</integer>
        <key>minFaceSize</key>
        <integer>200</integer>
        <key>numberOfBestShots</key>
        <integer>3</integer>
        <key>bestShotInterval</key>
        <integer>5</integer>
        <key>livenessQuality</key>
        <integer>0</integer>
    </dict>
    <key>LCInteractionsConfig</key>
    <dict>
        <key>stepsNumber</key>
        <integer>3</integer>
        <key>interactionTimeout</key>
        <integer>5</integer>
        <key>timeoutBetweenInteractions</key>
        <integer>0</integer>
    </dict>
    <key>LCEstimationThreshold</key>
    <dict>
        <key>headPitch</key>
        <integer>25</integer>
        <key>headYaw</key>
        <integer>25</integer>
        <key>headRoll</key>
        <integer>25</integer>
        <key>ags</key>
        <real>0.5</real>
    </dict>
</dict>
</plist>

Configuration parameters#

The parameters listed in LCLunaConfiguration.plist are as follows:

LCLunaConfiguration section#

Parameter	Default value	Description
`multipartBestShotsEnabled`	`false`	Enables or disables the capture of multiple best shots during a single session. For details, see Sending multiple frames for estimation aggregation to the backend.
`emptyFrameTime`	0	Specifies a timeout within which a face should appear in the frame, otherwise the video session will be terminated.
`glassesCheckEnabled`	`false`	Specifies whether the glasses estimation is enabled.
`aggregationEnabled`	`false`	Specifies whether aggregation for sunglasses and eye state estimation is enabled.
`ocrEnabled`	`false`	Specifies whether OCR (Optical Character Recognition) is enabled.
`interactionEnabled`	`true`	Specifies whether Dynamic Liveness interactions with a camera are enabled.
`saveOnlyFaceVideo`	`false`	Specifies whether to save video files only with a face detected.
`trackFaceIdentity`	`false`	Specifies whether face identity tracking is enabled.
`occludeCheck`	`true`	Specifies whether the face occlusion estimation is enabled.
`advancedSunglasses`	`false`	Enables or disables advanced sunglasses detection logic. For details, see Getting the best shot with faces with occluded eyes.
`videoRecordLength`	5	Specifies a video stream length, in seconds.
`eyeInjury`	`true`	Specifies whether images with a closed eye can be considered the best shots. For details, see Getting the best shot with faces with closed eyes.
`startDelay`	0	Specifies a timeout, in seconds, before face recognition begins.
`faceTime`	0	Specifies a delay, in seconds, to define for how long a user's face should be placed in the face detection bounding box before the best shot is taken.
`plistLicenseFileName`	`vllicense.plist`	Specifies the license file.
`compressionQuality`	0.8	Controls the JPEG compression quality of captured best-shot images, with values typically ranging from 0.0 (lowest quality, smallest file size) to 1.0 (highest quality, largest file size).
`documentVerificationMatch`	0.7	Determines the match threshold between a face and a photo in a document (when using OCR).
`primaryFaceMatching`	0.7	Specifies the comparison threshold for 1:1 user verification.

LCBestShotConfiguration section#

Parameter	Default value	Description
`livenessType`	1	Specifies the type of OneShotLiveness estimation.
`eyesCheck`	`true`	Enables or disables eye state estimation.
`borderDistance`	10	Specifies the distance from the frame edges and is based on the face detection bounding box size estimation.
`minDetSize`	200	Specifies a bounding box size.
`minFaceSize`	200	Specifies the minimum face size in pixels.
`numberOfBestShots`	3	Specifies the number of frames from which the best shot will be selected.
`bestShotInterval`	5	Specifies the time interval between attempts to obtain the best shot.
`livenessQuality`	0	Defines the threshold below which the system will consider the result to be an attempted spoofing attack.

LCInteractionsConfig section#

Parameter	Default value	Description
`stepsNumber`	3	Specifies a number of Dynamic Liveness interactions to be performed.
`interactionTimeout`	5	Specifies a timeout for every Dynamic Liveness interaction to be performed in a random sequence.
`timeoutBetweenInteractions`	0	Specifies a timeout between Dynamic Liveness interactions.

LCEstimationThreshold section#

Parameter	Default value	Description
`headPitch`	25	Specifies the head rotation along the X axis.
`headYaw`	25	Specifies the head rotation along the Y axis.
`headRoll`	25	Specifies the head rotation along the Z axis.
`ags`	0,2	Specifies the source image score for further descriptor extraction and matching.