Appearance
Photo quality check
The Photo Quality Check feature validates captured or uploaded photos before they are submitted for analysis. It combines preset-specific live guidance with post-capture preview validation for the presets that support it.
The public configuration surface consists of:
quality-checkquality-check-sourcesignored-quality-checksocclusion-detection
For the full public API surface, see the API Reference.
Supported behavior
LIQA currently supports quality-related behavior in the following way:
face: live guidance during capture and post-capture preview validation.face-180: live guidance during the 3-step capture flow and post-capture preview validation for the front image only.hair: uses its own guided capture flow and is documented separately in the Presets guide rather than as part of thequality-checkfeature.
For supported presets, LIQA still keeps a minimal no-face guard on uploaded images even when quality-check="off".
Configuration
quality-check
Controls whether LIQA evaluates photo quality and whether failed validation blocks submission.
For supported presets, this already includes the built-in glasses and forehead checks in both live guidance and post-capture preview validation.
| Option | Description |
|---|---|
off | Disables the configurable quality-check policy. |
normal | Shows detected issues to the user, but still allows submission. |
strict | Shows detected issues and blocks submission until the required checks pass. |
Default: off
quality-check-sources
Limits where the quality-check policy is enforced.
| Source | Description |
|---|---|
front_camera | Applies quality-check to front-camera captures. |
back_camera | Applies quality-check to back-camera captures. |
upload | Applies quality-check to uploaded images. |
companion | Applies quality-check to images captured through the companion flow. |
Default: ["front_camera", "back_camera", "upload", "companion"]
occlusion-detection
Controls the standalone occlusion-focused checks used for glasses and forehead visibility.
Use this flag when you do not want to enable full quality-check, but still want LIQA to validate glasses and forehead visibility.
If quality-check is already enabled, LIQA already includes glasses and forehead checks in both live and post-capture validation for supported presets. In that case, occlusion-detection is only needed when you want to control occlusion validation separately from the rest of the quality-check flow.
| Option | Description |
|---|---|
off | Disables occlusion detection. |
normal | Shows occlusion-related issues but does not block submission. |
strict | Blocks submission when occlusion-related issues are detected. |
live | Uses the lightweight live occlusion pipeline during camera capture. For non-camera sources, occlusion checks still run after capture. |
Default: off
ignored-quality-checks
Excludes selected post-capture quality checks from preview issues, blocking logic, and the resulting quality_check payload.
Use this when you want LIQA to keep measuring a signal for analytics, but not use that signal in the post-capture decision layer.
This option does not change live guidance, live occlusion stages, or auto-capture behavior.
| Alias | Effect |
|---|---|
enough_skin | Ignores the enough-skin requirement in post-capture validation. |
pose | Ignores the post-capture face-pose requirement. |
resolution | Ignores the post-capture resolution check. |
blur | Ignores the post-capture blur check. |
occlusions | Ignores the generic occlusion signal in post-capture validation. |
glasses | Ignores the glasses detection signal in post-capture validation. |
forehead | Ignores the forehead / bangs occlusion signal in post-capture validation. |
exposure | Ignores the aggregate exposure signal in post-capture validation. |
uniform_illumination | Ignores uneven / colored lighting in post-capture validation. |
shadows | Ignores strong shadows in post-capture validation. |
Default: []
Source scoping
quality-check-sources only scopes the behavior of quality-check.
If you explicitly enable occlusion-detection, it is resolved separately from quality-check-sources.
Post-capture only
ignored-quality-checks is applied after capture during preview/postprocess evaluation only.
It does not remove the corresponding live guidance signals while the user is framing the photo.
What LIQA checks
Depending on the enabled mode, preset, and source, LIQA can evaluate the following signals:
- Face presence
- Enough visible skin
- Face pose / angle
- Resolution
- Blur
- Exposure
- Uneven or colored lighting
- Strong shadows
- Generic skin occlusion
- Glasses
- Forehead coverage by bangs, hat brim, or similar occlusions
Ignored quality check aliases
The ignored-quality-checks attribute accepts short aliases, while the underlying measured quality fields keep their canonical names in analytics and internal contracts.
| Alias | Canonical signal(s) |
|---|---|
enough_skin | has_enough_skin |
pose | has_valid_pose |
resolution | has_good_resolution |
blur | has_no_blur |
occlusions | has_no_occlusions |
glasses | has_no_eyeglasses |
forehead | has_no_hair_bangs |
exposure | has_good_exposure |
uniform_illumination | has_uniform_illumination |
shadows | has_no_shadows |
Preset and source matrix
| Preset | Live capture guidance | Post-capture preview validation | Notes |
|---|---|---|---|
face | Yes | Yes | Supports quality-check and occlusion-detection. |
face-180 | Yes | Front image only | Side captures are still part of the guided flow, but preview validation is only kept for the front image. |
hair | Separate guided flow | Not part of the quality-check feature page | See the Presets guide. |
Current UI examples
The exact preview title and issue list depend on the measured problems and the enabled validation mode.
A current `strict` mode preview example. LIQA shows the detected issues and keeps the submission action blocked until the blocking checks pass.
A current `normal` mode preview example. LIQA still lists the detected issues, but the user can submit the image after reviewing the warning.
Analytics
When LIQA records a reportable post-capture quality outcome, it can emit the quality_check_result analytics event with the measured fields that were actually evaluated.
If ignored-quality-checks is configured, the analytics payload still contains the measured quality fields and additionally includes the ignored_quality_checks array to show which post-capture checks were excluded from the decision layer.
Use the generated API Reference for the complete event payload contract instead of duplicating the full field list in this guide.