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
MBCaptureConstraints.V1	Landmark validation	No	Compatibility with existing V1 integrations.
MBCaptureConstraints.V2	Distance, position, and pose	No	Geometry-only capture.
MBCaptureConstraints.V3	Distance, position, and pose	Yes	Recommended for new integrations.

Selecting V3 does not change the result format. It changes which frames are accepted.

Enable V3

Set the same options for the predefined UI and the custom UI:

// Predefined UI
launch({
  captureConstrains: MBCaptureConstraints.V3,
  imageQualityLevel: MBImageQualityLevel.LEVEL_2,
  cameraPermissionAlert,
});

// Custom UI
const options = setCaptureSessionOptions({
  captureConstrains: MBCaptureConstraints.V3,
  imageQualityLevel: MBImageQualityLevel.LEVEL_2,
});

Choose a quality level

Level	Strictness	Suggested starting point
MBImageQualityLevel.LEVEL_1	Most permissive	Difficult or highly variable lighting environments.
MBImageQualityLevel.LEVEL_2	Balanced	General production testing.
MBImageQualityLevel.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

In the custom UI, V2 and V3 report every validation result through onFaceBoundingBoxValidating:

onFaceBoundingBoxValidating={(
  facePoses: FacePose[] | null,
  faceDistance: FaceDistance | null,
  facePositions: FacePosition[] | null,
  imageQualityStatus: MBImageQualityStatus | null,
  isValid: boolean
) => {
  // Show one instruction at a time: position, distance, pose, then lighting.
}}

Argument	Values
facePoses	FacePose.yaw, FacePose.pitch, FacePose.roll. null or empty when the pose is valid.
faceDistance	FaceDistance.too_close, FaceDistance.too_far_away. null when the distance is valid.
facePositions	FacePosition.too_far_up, too_far_down, too_far_left, too_far_right, not_found. null or empty when the position is valid.
imageQualityStatus	V3 lighting status, see below. null with V2.
isValid	true only when every active check passes.

Handlers written for earlier versions that accept only the first three arguments continue to work.

V1 reports a single status through the deprecated onFaceValidating(faceStatus: FaceStatus) prop.

Lighting statuses

Status	User action
MBImageQualityStatus.CHECKING	Wait while the SDK obtains a fresh lighting measurement.
MBImageQualityStatus.VALID	No lighting correction is required.
MBImageQualityStatus.INSUFFICIENT_LIGHT	Move to a brighter area or add frontal light.
MBImageQualityStatus.UNEVEN_LIGHTING	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.