aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 01942a29a44ee4232b1474f8d1ee5116c41ebb4f (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
# facedet

A CPU-only face detector using the YuNet `face_detection_yunet_2026may` model.

## Build and run

A C11 compiler (Clang or GCC), Make, and the system math library are required.

This builds a small command-line program and a static C library. Model weights are
embedded in the binary.

```sh
make
./build/facedet photo.jpg
./build/facedet photo.png 0.6 0.3
./build/facedet image.ppm
./build/facedet photo.jpg -o overlay.ppm > faces.json
./build/facedet --out overlay.ppm photo.png 0.6 0.3
```


The optional numbers are the score threshold and NMS intersection-over-union
threshold; their defaults are `0.6` and `0.3`. Both must be between 0 and 1.

Input is JPEG, PNG, or binary PPM (`P6`, RGB, maxval 255), with dimensions from
1 to 4096.

```sh
./build/facedet photo.jpg > faces.json
```

Standard output contains one JSON object:

```json
{
  "width": 640,
  "height": 480,
  "input_width": 640,
  "input_height": 480,
  "faces": []
}
```

Each face has `box: [x, y, width, height]`, `score`, and five `[x, y]` landmarks:
right eye, left eye, nose, right mouth corner, and left mouth corner.

`-o FILE`, `--out FILE`, or `--out=FILE` writes a binary P6 PPM containing the
decoded image with green face boxes, confidence labels, and five landmark dots.

![Face detection example](./example.jpg)

## C API

Include `facedet.h` and link `build/libfacedet.a` with `-lm`.

1. Create a context with `facedet_create(padded_width, padded_height)`. Both dimensions
   must be multiples of 32 in the range 32 through 4096. Check for `NULL`.
2. Fill it with `facedet_set_rgb`, or fill the buffer returned by `facedet_input` with
   float32 BGR CHW values in `[0, 255]`.
3. Call `facedet_run`, then `facedet_decode` with an output array and its capacity.
   Negative return values indicate errors. The output capacity limits returned
   detections, not the number of candidates considered.
4. Reuse the context for images with the same padded dimensions. Call `facedet_free`
   when finished. Use separate contexts for concurrent inference.

The command-line implementation in `main.c` demonstrates the complete flow.
`facedet_map` exposes raw CHW head tensors for numerical checks; classification and
objectness maps contain logits, so the decoder applies sigmoid before computing
`sqrt(classification * objectness)`.

`nn.c` contains the required convolution, pooling, addition, and resizing
operations. `gemm.c` uses AArch64 NEON or runtime-selected x86-64 AVX2/FMA,
with a portable C fallback. Define `FACEDET_SCALAR` to disable explicit SIMD kernels.

## Model and regeneration

To download the model manually:

```sh
curl -fL \
'https://huggingface.co/pollen-robotics/face_detection_yunet_2026may/resolve/2b8e922362946a0db67e861bae0f77826980effd/face_detection_yunet_2026may.onnx' \
   -o models/face_detection_yunet_2026may.onnx
```

Source: [pollen-robotics/face_detection_yunet_2026may](https://huggingface.co/pollen-robotics/face_detection_yunet_2026may)

Pinned revision: `2b8e922362946a0db67e861bae0f77826980effd`

Expected SHA-256:

```text
ebafce4e3c118d6554634be5c27ab333b4c047a9a8c3faf1d7cf93101c22f0f0
```

Then run `make model` to generate `model_data.h`.