Photo Compliance Studio
Upload a photo. Get compliance checks, error codes, and a corrected output crop by country profile.
Upload & Rules
Loading profile...
Result Overview
Status: -
Resolution: -
Segmentation: -
Error Codes: -
Original
Processed
Color Correction Comparison
No Color Correction
Color Correction Applied
What To Fix
Check Results
| 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 background tone.
Segmentation backend is MediaPipe in this build.
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.
- MediaPipe segmentation provides fast CPU-friendly person/background separation.
- OpenCV compositing adds edge-safe cleanup on top of the MediaPipe mask.
- OpenCV handles crop geometry, compositing, and background correction.
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 MediaPipe selfie segmentation and get foreground probability mask.
- Boundary guards protect shoulders/hair near frame edges during whitening.
Backend Selection
- `MediaPipe`: CPU-friendly segmentation backend used for all requests.
- Backend details are still logged in Result Overview and check rows.
- If MediaPipe is unavailable, segmentation-dependent checks become manual.
- No external model file path is required for segmentation.
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 only for compliance checks; processed output does not synthesize or repaint subject edges.
- 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 + MediaPipe segmentation + OpenCV post-process.
- Post-process: OpenCV crop + tonal cleanup + 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
- Segmentation backend is fixed to MediaPipe.
- 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).