# Face Detection
`Image.FaceDetection` answers "where are the faces in this image?". It returns a list of bounding boxes, confidence scores, and five facial landmarks (right eye, left eye, nose tip, right mouth corner, left mouth corner) per detected face.
## Basic detection
```elixir
iex> image = Image.open!("group.jpg")
iex> faces = Image.FaceDetection.detect(image)
iex> hd(faces)
%{
box: {412, 88, 96, 124},
score: 0.94,
landmarks: [{438.2, 130.1}, {478.7, 129.6}, {458.0, 152.3}, {442.1, 178.5}, {475.0, 178.2}]
}
```
Each detection is a map with:
- `:box` — `{x, y, width, height}` in pixel coordinates of the original image
- `:score` — confidence score in `[0.0, 1.0]`
- `:landmarks` — a list of five `{x, y}` tuples: right eye, left eye, nose tip, right mouth corner, left mouth corner — in that order
Results are sorted by descending confidence.
## Filtering by confidence
The default minimum score is `0.6`. Raise it for stricter detections:
```elixir
iex> Image.FaceDetection.detect(image, min_score: 0.8)
```
`:nms_iou` (default `0.3`) controls how aggressively overlapping boxes are collapsed by non-maximum suppression. Lower values keep fewer overlapping faces.
## Boxes only
When landmarks aren't needed, `boxes/2` skips them:
```elixir
iex> Image.FaceDetection.boxes(image)
[{412, 88, 96, 124}, {612, 102, 84, 110}]
```
## Drawing detections
`draw_boxes/3` overlays bounding boxes, the score as a percentage label, and the five landmark dots:
```elixir
iex> faces = Image.FaceDetection.detect(image)
iex> annotated = Image.FaceDetection.draw_boxes(faces, image)
iex> Image.write!(annotated, "annotated.jpg")
```
Pipeline form:
```elixir
iex> image
...> |> Image.FaceDetection.detect()
...> |> Image.FaceDetection.draw_boxes(image)
...> |> Image.write!("annotated.jpg")
```
Drawing options include `:color`, `:stroke_width`, `:landmark_radius`, `:font_size`, and `:show_landmarks?` (set to `false` to skip the dots).
## Face-aware crop
`crop_largest/2` is a convenience for the common "crop to the most prominent face" case (the wire-in point for face-aware crop bias used by `gravity: :face` in `image_plug`, ImageKit `z-`, and Cloudflare `face-zoom`):
```elixir
iex> {:ok, portrait} = Image.FaceDetection.crop_largest(image, padding: 0.2)
```
The largest face is chosen by bounding-box area. `:padding` is a fraction of each face dimension — `0.0` is a tight crop, `0.5` adds 50% on each side, `1.0` doubles the box. The expanded crop is clipped to the image bounds.
When no face meets the score threshold, `crop_largest/2` returns `{:error, :no_face_detected}`.
## Default model
[YuNet](https://github.com/opencv/opencv_zoo/tree/main/models/face_detection_yunet) (`opencv/face_detection_yunet`) — the OpenCV team's production face detector. Roughly **340 KB on disk**, MIT licensed, real-time on CPU. The 2023-March export produces decoded boxes, keypoints, and scores directly.
Model weights are downloaded on first call and cached. Configure the cache directory with:
```elixir
config :image_vision, :cache_dir, "/path/to/cache"
```
## Using a different model
`detect/2` accepts `:repo` and `:model_file` to swap in a different YuNet ONNX export:
```elixir
iex> Image.FaceDetection.detect(image,
...> repo: "opencv/face_detection_yunet",
...> model_file: "face_detection_yunet_2023mar.onnx"
...> )
```
### Caveat: post-processor is YuNet 2023-March specific
The output decoder assumes YuNet's 2023-March 12-tensor convention (`cls_*`, `obj_*`, `bbox_*`, `kps_*` at strides 8/16/32, fixed 640×640 input). `SCRFD`, `BlazeFace`, and other face-detector exports produce different output shapes and need a different post-processor — they will not work as a drop-in replacement.
## Dependencies
Face detection requires `:ortex`. Add to `mix.exs`:
```elixir
{:ortex, "~> 0.1"}
```
