[MS-1343] MFID lighting conditions assessment hints for OCR

[alex-vt]

JIRA ticket
Will be released in: 2026.2.0

Notable changes

When capturing an ID card when MFID (External credential) is enabled, a hint is shown for the user under the camera viewfinder target area, when the lighting conditions are deemed difficult for OCR of text on a card.

Hints for abnormal lighting conditions are:

• "Not enough light": it's so dim overall, that contrast is impacted heavily
• "Too bright light": it's so bright overall, that contrast is impacted heavily
• "Too bright light": there are light reflection glares, at and near which contrast is impacted heavily

Hints are displayed not only after the Scan button is pressed, but also before - in the preview. This guides the user to better lighting early, and aims for a smoother UX.

In these examples:

• On the left: glare reflection detected, before scanning
• On the right: low light conditions, while scanning

This feature is experimental. It needs to be enabled in the Custom Configs for the project with MFID.

The simplest custom config:

{"mfidLightingConditionsAssessmentEnabled":true}

Full reference:

Parameter	Description	Default
mfidLightingConditionsAssessmentEnabled	Boolean to enable lighting conditions assessment hints in the MFID OCR scan flow. When enabled, SID analyses the live document image and can show hints: "Not enough light" or "Too bright light".	false
mfidLightingConditionsAssessmentPadding	Percentage of the image border ignored before assessing lighting conditions, to reduce the effect of background outside the document. Min: 0. Max: 30.	5
mfidLightingConditionsAssessmentLowContrast	Contrast threshold used together with brightness checks to detect underexposed, overexposed, and glare-washed images. Min: 0. Max: 50.	30
mfidLightingConditionsAssessmentLowBrightness	Median brightness threshold below which a low-contrast document image is classified as too dim. Min: 0. Max: 50.	25
mfidLightingConditionsAssessmentHighBrightness	Median brightness threshold above which a low-contrast document image is classified as too bright. Min: 50. Max: 100.	95
mfidLightingConditionsAssessmentGlareBrightness	Brightness threshold above which a low-contrast area is treated as glare and the image is classified as too bright. Min: 50. Max: 100.	99
mfidLightingConditionsAssessmentGlareSensitivity	Minimum grid dimension to divide the document image into areas to look for glare hotspots. Min: 1. Max: 20.	6

There's no user-controlled on/off switch for this feature, because it is an advisory hint only, not affecting user flows.

Code changes

• The existing pipeline for image processing is used, to avoid doing it twice when both OCR and lighting conditions assessment are active.
• The lifecycle of image processing is expanded to preview - before the Scan button is pressed. Only the lighting conditions assessment is active before the Scan press, not OCR.

Testing guidance

• On a project with MFID and the feature enabled, reach the external credential scanning viewfinder, and simulate dim, bright and glare-affected lighting conditions to see the hints.

Additional work checklist

• Effect on other features and security has been considered
• Design document marked as "In development" (if applicable)
• External (Gitbook) and internal (Confluence) Documentation is up to date (or ticket created)
• Test cases in Testiny are up to date (or ticket created)
• Other teams notified about the changes (if applicable)

[alex-vt]

The test cards below, rendered:

Normal	Dim	Bright	Glare

[BurningAXE]

Does it make sense to move the config initialization in the use case? This will clean up the VM and will allow easier reuse for QR scanning. For the case when lightning assessment is disabled, the use case can simply return a null and have the flow be optional - if null, no hint to display.