Capture constraints and image quality

V3 adds a lighting-quality gate to the V2 face geometry checks. Capture starts only after the face passes distance, position, pose, and lighting validation.

Compare constraint versions

Version	Face geometry	Lighting quality	Use case
V1	Landmark validation	No	Compatibility with existing V1 integrations.
V2	Distance, position, and pose	No	Geometry-only capture.
V3	Distance, position, and pose	Yes	Recommended for new native integrations.

Selecting V3 does not change the captured media format. It changes which frames are accepted and records v3 in the result metadata.

Enable V3

val options = MBCaptureSessionOptions.Builder()
    .captureConstrains(MBCaptureConstrains.V3)
    .imageQualityLevel(MBImageQualityLevel.LEVEL_2)
    .build()

The Android public API uses the spelling MBCaptureConstrains and captureConstrains.

Choose a quality level

Level	Strictness	Suggested starting point
LEVEL_1	Most permissive	Difficult or highly variable lighting environments.
LEVEL_2	Balanced	General production testing.
LEVEL_3	Strictest and default	Controlled capture environments.

imageQualityLevel has no effect when V1 or V2 is selected.

V3 evaluates four lighting characteristics:

• overall brightness
• luminance variance
• underexposure
• illumination uniformity across the face

A frame fails the lighting gate when at least two measures are below the selected level.

Read validation status

For V2 and V3, implement MBBoundingBoxFaceValidatorListener:

override fun onValidating(
    faceBoxStatus: MBFaceBoundingBoxStatus,
    faceGeometry: MBFaceGeometryModel
) {
    when {
        faceBoxStatus.distanceError != null -> handle(faceBoxStatus.distanceError)
        !faceBoxStatus.positionErrors.isNullOrEmpty() ->
            handle(faceBoxStatus.positionErrors.first())
        !faceBoxStatus.poseErrors.isNullOrEmpty() ->
            handle(faceBoxStatus.poseErrors.first())
        else -> handle(faceBoxStatus.imageQualityStatus)
    }
}

MBFaceBoundingBoxStatus.isValid is true only when every active check passes.

Lighting statuses

Status	User action
CHECKING	Wait while the SDK obtains a fresh lighting measurement.
VALID	No lighting correction is required.
INSUFFICIENT_LIGHT	Move to a brighter area or add frontal light.
UNEVEN_LIGHTING	Use more even light on both sides of the face.

For the predefined UI, enable faceStatusLabel(true) to let the SDK display this guidance. For a custom UI, convert these statuses into your own visible messages.