aboutsummaryrefslogtreecommitdiff

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.

Face detection example

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:

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.