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.
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.
./build/facedet photo.jpg > faces.json
Standard output contains one JSON object:
{
"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.

C API
Include facedet.h and link build/libfacedet.a with -lm.
- Create a context with
facedet_create(padded_width, padded_height). Both dimensions must be multiples of 32 in the range 32 through 4096. Check forNULL. - Fill it with
facedet_set_rgb, or fill the buffer returned byfacedet_inputwith float32 BGR CHW values in[0, 255]. - Call
facedet_run, thenfacedet_decodewith an output array and its capacity. Negative return values indicate errors. The output capacity limits returned detections, not the number of candidates considered. - Reuse the context for images with the same padded dimensions. Call
facedet_freewhen 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:
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
Pinned revision: 2b8e922362946a0db67e861bae0f77826980effd
Expected SHA-256:
ebafce4e3c118d6554634be5c27ab333b4c047a9a8c3faf1d7cf93101c22f0f0
Then run make model to generate model_data.h.
