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

let options = MBCaptureSessionOptions(
    captureConstraints: .v3,
    imageQualityLevel: .level2
)

Choose a quality level

Level	Strictness	Suggested starting point
.level1	Most permissive	Difficult or highly variable lighting environments.
.level2	Balanced	General production testing.
.level3	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 MBBoundingBoxFaceValidatorDelegate:

func onValidating(
    _ faceStatus: Result<MBFaceGeometryModel, MBFaceBoundingBoxStatus>
) {
    switch faceStatus {
    case .success(let geometry):
        // Geometry and the active V3 lighting gate are valid.

    case .failure(let status):
        if let distance = status.distanceError {
            handle(distance)
        } else if let position = status.positionalError?.first {
            handle(position)
        } else if let pose = status.poseError?.first {
            handle(pose)
        } else if let lighting = status.imageQualityStatus {
            handle(lighting)
        }
    }
}

MBFaceBoundingBoxStatus.isValidStatus 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.
.insufficientLight	Move to a brighter area or add frontal light.
.unevenLighting	Use more even light on both sides of the face.

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