Landmark Detection

---
name: landmark-detection
description: "Routes face landmark prediction on single images, batches, and
  directories with FaceAlignment."
disable-model-invocation: true
metadata:
  disco-role: operating
license: BSD 3-Clause
---

# Landmark Detection

Use this sub-skill when a user wants to detect facial landmarks from an image path, NumPy array, torch tensor, batch tensor, or directory of images. It covers 2D, 2.5D, and 3D landmark outputs, `get_landmarks` / `get_landmarks_from_image`, and the device / compile / batch-size knobs that affect inference.

## Common triggers

- `detect face landmarks`
- `run face_alignment on an image`
- `process a directory of faces`
- `compare 2D vs 3D landmarks`
- `return landmark scores`
- `return bounding boxes`
- `disable compile`
- `reduce batch size`

## Read first

- `references/workflows.md` for end-to-end image, batch, and directory recipes.
- `references/troubleshooting.md` when inference fails, no faces are detected, compile slows startup, or batch size causes memory pressure.
- `../../references/api-reference.md` for the exact constructor and method signatures.
- `scripts/detect_landmarks.py` for a reusable smoke / demo helper.

## Workflow

1. Pick `LandmarksType.TWO_D`, `LandmarksType.TWO_HALF_D`, or `LandmarksType.THREE_D`.
2. Choose `device='cpu'`, `device='cuda'`, or `device='mps'` explicitly.
3. Use `flip_input=True` for accuracy and `compile=False` when you want fast startup or a simpler smoke path.
4. Pass a small `max_batch_size` if the detector finds many faces or the host is memory constrained.
5. Prefer `get_landmarks_from_image` for one image and `get_landmarks_from_directory` for image trees; `get_landmarks` is only a deprecated alias.

## Output reminders

- Landmarks are returned as a list of faces.
- 2D and 2.5D results are shaped `(68, 2)`.
- 3D results are shaped `(68, 3)`.
- When no faces are found, the API returns `None` or `(None, None, None)` depending on `return_bboxes` and `return_landmark_score`.

## Handoff to detectors

If the user is choosing or troubleshooting a backend, route to `../detectors/` instead of changing landmark logic here.