Photo Compliance Studio

Error Code	Status	Message	Recommended Action
Upload an image to run checks.

Guide & Workflow

This section explains what the system does, what each model computes, and how pass/fail decisions are made.

SG Profile Non-Generative Toggleable Segmentation

End-to-End Processing Flow

Hard fail checks run first. Example: mouth open means FAIL even if enhancement looks good.

Edits are non-generative. The app only adjusts crop, exposure, mask compositing, and deterministic background whitening.

Segmentation prefers rembg for difficult backgrounds, with MediaPipe fallback.

System Goal

Primary output is a compliance decision with clear reasons.
Image enhancement is secondary and does not override failed checks.
Same input should produce the same output (deterministic pipeline).
Country rules are config-driven, so thresholds can be updated safely.

Model Choice

FaceMesh gives dense landmarks for pose, eye, mouth, and framing checks.
rembg improves person/background separation on non-flat backgrounds.
OpenCV compositing adds confidence gating and border guards on top of the selected segmentation mask.
OpenCV handles crop geometry, vertical rebalance, and assist background whitening.

Inference Internals

FaceMesh runs once per image and returns landmark points in image coordinates.
From landmarks, the app computes inter-eye distance, roll, yaw proxy, pitch proxy, and mouth gap ratio.
Segmentation path: run rembg first; use MediaPipe fallback if rembg is unavailable.
Crop pass includes iterative eye-line recentering plus segmentation-aware vertical rebalance.
Boundary guards protect shoulders/hair near frame edges during whitening.

Backend Selection

`rembg`: best quality on complex backgrounds (higher memory footprint).
`MediaPipe`: lightweight fallback when rembg is disabled or unavailable.
Backend details are logged in Result Overview and check rows.
If both are unavailable, segmentation-dependent checks become manual.

Fallback Matrix

If segmentation backend is unavailable: run checks without segmentation-dependent steps.
If crop cannot fit in bounds: return `CROP_OUT_OF_BOUNDS` and no processed output.
If face is not detected: stop geometric checks and return `NO_FACE_DETECTED`.
If there are multiple faces: return `MULTIPLE_FACES_DETECTED` and stop.
Backend used is always logged in result chips and check details.

Thought Process Per Step

Decode + EXIF first so orientation and mirrored selfie flags are handled before any geometry logic.
Run face geometry before enhancement so pass/fail is based on source photo quality, not edited output.
Use segmentation for compliance checks and assist whitening; output never uses generative repaint.
Run crop after quality checks so the output matches country dimensions and head-size constraints.
Apply beautify last and keep it optional so compliance and appearance remain separate decisions.

Capture Checklist

Use eye-level camera with full frontal face and eyes looking at lens.
Maintain neutral expression with mouth closed.
Include full hair and shoulders with some chest area.
Use plain bright background and soft front lighting.
Upload original files and avoid compressed screenshots.

Validation Layers

Input checks: file type, source resolution, and capture-date metadata.
Face checks: pose, eye visibility, mouth closed, and face size.
Background checks: brightness, saturation, lighting spread, text/watermark.
Crop checks: target aspect, head size in output, and bounds safety.
For each failed/warned check, the app returns an action message.

Key Formulas

EAR (eye openness) = (|p2-p6| + |p3-p5|) / (2 * |p1-p4|).
Mouth score = |upper_lip - lower_lip| / inter_eye_distance.
Yaw proxy = horizontal nose offset from eye midpoint, normalized by eye width.
Pitch proxy = vertical nose position between eye line and mouth line.
Blur score = variance(Laplacian(face ROI)); lower value means blurrier image.

System Architecture

Frontend: single-page HTML/CSS/JS, no framework dependency.
API: FastAPI `/api/analyze` and `/api/countries`.
CV: MediaPipe FaceMesh + rembg/MediaPipe segmentation + OpenCV post-process.
Post-process: OpenCV crop + assist whitening (when mask exists) + optional beautify (no subject-edge repaint).
Deploy: one service container via Uvicorn behind HTTPS.

Performance Strategy

Large images are downscaled before model inference to reduce CPU and memory cost.
Source metadata and source resolution are still tracked for rule checks.
Output size is fixed by profile (SG is 400x514).
Preview image is capped to reduce response payload size.
Caps are set via env vars (`MAX_PROCESSING_LONG_SIDE`, `MAX_PROCESSING_MEGAPIXELS`, `MAX_PREVIEW_LONG_SIDE`).

Runbook

rembg can be enabled for quality and configured to unload after idle timeout.
If status is `FAIL`, fix fail codes first, then do visual tuning.
If shoulders/hair edges look wrong, retake instead of forcing synthetic cleanup.
Retake if hair/shoulders are clipped instead of forcing cleanup.
Review top fail codes regularly and tune thresholds with real samples.

Practical note: the cleanest results still come from good source capture (front light, plain wall, stable camera).