birwatkar123/FacialDeviationAssessment

Facial Deviation Assessment

Experimental V1 Android application that quantifies facial symmetry and smile dynamics from the front camera in real time, using MediaPipe Face Landmarker (478 landmarks) and Jetpack Compose.

Important: This is an experimental V1 algorithmic prototype. It is NOT a clinically validated diagnostic tool and does not provide medical advice. Consult a healthcare professional for any medical concerns.

Download

• APK: app-debug.apk — 68.6 MB debug build (com.facialdeviation.assessment, v1.0.0, minSdk 24 / targetSdk 37)

Install on device:

adb install -r app-debug.apk

On first launch, grant the camera permission. Hold your face centered, keep the head near-frontal, and follow the on-screen instructions (neutral pose → smile).

Purpose

The app captures a short neutral-face sequence followed by a short smile sequence, then computes an Overall Symmetry score (0–100) from relative asymmetries of the mouth corners, mouth-line tilt, eyebrow heights, and eye openings, plus a separate Smile symmetry assessment derived from anatomical left/right mouth-corner excursion during the smile.

It is designed as a research/validation scaffold: ground-truth asymmetry can be induced (e.g., reduced one-sided smile movement) and compared against the reported metrics.

Architecture

• Language: Kotlin
• UI: Jetpack Compose (Material 3), single-Activity, state-driven navigation (HomeScreen, CameraScreen, ResultsScreen)
• State management: MVVM — AssessmentViewModel (AndroidViewModel) backed by StateFlow; AssessmentState drives the UI flow: HOME → PERMISSION_REQUEST → CALIBRATING → NEUTRAL_FACE → SMILE_TEST → RESULTS
• Camera: CameraX (Preview + ImageAnalysis, front camera, 640×480, RGBA_8888)
• Landmarking: MediaPipe Tasks Vision FaceLandmarker (tasks-vision:0.10.29), RunningMode.LIVE_STREAM, CPU delegate, model face_landmarker.task bundled in app/src/main/assets

Assessment flow

1. Neutral-face collection (~3 s, ≥ 30 valid frames) — head pose must be acceptable (yaw/pitch/roll within gate) with GOOD/FAIR tracking quality before a frame is accepted.
2. Smile collection (~3 s, ≥ 30 frames) — landmarks compared to the neutral mouth corners.
3. Results — neutral frames averaged, FacialSymmetryCalculator emits component metrics and weighted overall score.

Analyses

Module	Produces
HeadPoseAnalyzer	yaw / pitch / roll gating (acceptable), head-pose validity
TrackingQualityAnalyzer	GOOD / FAIR / POOR tracking quality
LandmarkSmoother	smoothed landmarks + temporal stability (0–1)
FacialSymmetryCalculator	mouth-corner asymmetry (%), mouth-line tilt (°), eyebrow-height asymmetry (%), eye-opening asymmetry (%), deviations, and the weighted Overall Symmetry score
SmileAnalyzer	smile symmetry (%), anatomical left/right excursion (%), excursion ratio
FaceLandmarkUtils	landmark index constants (NOSE_TIP=1, LEFT_EAR=234, LEFT/RIGHT_MOUTH=61/291, …) and geometric helpers

Overall Symmetry weights: mouth corners 0.30, mouth-line tilt 0.20, eyebrows 0.25, eyes 0.25. Each component normalized to 0–100 and combined; result clamped to [0, 100]. Smile symmetry is computed separately.

Current V1 status

• End-to-end flow works on device: neutral capture, gated head-pose/tracking, smile capture, and a fully populated Results screen.
• Repeatability & controlled asymmetry validation passed:

Control	smileSymmetry	leftExcursion %	rightExcursion %	excursionRatio
A – normal smile	82.1	9.06	10.84	0.91
B – reduced anatomical-left smile	12.9	3.28	8.35	0.56
C – reduced anatomical-right smile	0.0	12.22	3.59	0.45

• Diagnostic logging: each completed assessment writes a single RESULT_SUMMARY line (tag AssessmentViewModel) with component scores, smile metrics, tracking stability, FPS, and valid-frame counts.
• Unit tests: 31 passing, 0 failures, 0 errors.

Build

Requirements:

• JDK that can provide toolchain 25 (jvmToolchain(25)), e.g. JDK 25 or the JBR bundled with Android Studio
• Android SDK with compileSdk = 37
• Gradle 9.5.0

gradle wrapper --gradle-version 9.5.0   # once, if wrapper scripts missing
gradlew.bat assembleDebug
gradlew.bat testDebugUnitTest

APK output: app/build/outputs/apk/debug/app-debug.apk

Google Colab / Research Use

The full source tree in this repository is buildable as an Android Studio / Gradle project and can be used as a scaffold for validating algorithmic facial metrics against induced asymmetry.

Source

Full source lives on GitHub:

https://github.com/birwatkar123-collab/FacialDeviationAssessment

Limitations

• Experimental V1 — NOT a clinically validated diagnostic tool. Scores are algorithmic and may not reflect clinical assessment.
• Front camera only; portrait orientation only.
• Requires reasonably stable lighting and a centered, near-frontal face; frames outside the pose/tracking gates are discarded.
• The reported FPS is the instantaneous frame-to-frame rate (1000 ÷ last inter-frame gap), not an averaged throughput.
• Landmark-based geometry is sensitive to image resolution and distance from the camera.