name: face-alignment description: Face alignment, landmark extraction, and quality gating. Use when debugging alignment issues, reviewing rejected faces, or tuning quality thresholds.

Face Alignment Skill

Use this skill to debug face alignment artifacts and embedding gating behavior.

When to Use

• Faces being rejected but you don't know why
• Identity fragmentation that might be alignment-related
• Need to adjust alignment quality thresholds
• Debugging how alignment_quality is computed and consumed
• Planning promotion/integration (FEATURE sandbox → production)

Sub-agents

Key Skills

Run FAN alignment on a face bbox

Run alignment on detected face boxes (produces 68-point landmarks; optional aligned crop).

from FEATURES.face_alignment.src.run_fan_alignment import FANAligner, align_face_crop

aligner = FANAligner(model_type="2d", landmarks_type="2D", device="cpu")
landmarks = aligner.align_face(image, bbox)  # 68 x 2
aligned_crop = align_face_crop(image, landmarks, output_size=112)

Compute alignment_quality (heuristic today)

Get a per-face quality score (0–1). Current implementation is heuristic-based.

from FEATURES.face_alignment.src.alignment_quality import compute_alignment_quality

quality = compute_alignment_quality(bbox=bbox, landmarks_68=landmarks)

Generate episode artifacts

python -m FEATURES.face_alignment --episode-id <EP_ID>

Config Reference

Alignment Artifact Config: config/pipeline/face_alignment.yaml

Embedding Gating Config: config/pipeline/embedding.yaml

Common Issues

Faces unexpectedly skipped before embedding

Cause: Face below quality threshold

Check: alignment_quality in data/manifests/{ep_id}/face_alignment/aligned_faces.jsonl

Fix: Lower threshold in config/pipeline/embedding.yaml:

face_alignment:
  min_alignment_quality: 0.2  # default is 0.3

High landmark_jitter

Cause: Unstable landmarks across frames

Check: Per-frame landmark variance in track

Fix:

• Ensure FAN model loaded correctly
• Check input face crop quality
• May need temporal smoothing

3D head pose / profile gating isn’t available

Cause: 3DDFA_V2 isn’t implemented yet (planned).

Diagnostic Output

{
  "face_id": "F_42_100",
  "alignment_quality": 0.72,
  "landmarks_detected": 68,
  "head_pose": {
    "yaw": -25.5,
    "pitch": 10.2,
    "roll": 3.1
  },
  "quality_breakdown": {
    "eyes": 0.85,
    "nose": 0.80,
    "mouth": 0.65,
    "chin": 0.55
  },
  "aligner_used": "fan_2d"
}

Key Files

Related Skills

• pipeline-insights - General pipeline debugging
• cluster-quality - Clustering metrics