diff options
| author | Onur Gündüz <ogunduz@gmail.com> | 2026-10-20 11:44:30 +0200 |
|---|---|---|
| committer | Onur Gündüz <ogunduz@gmail.com> | 2026-10-20 11:44:30 +0200 |
| commit | 9b9005101e6170a226acb265428aac429be6edbf (patch) | |
| tree | f89c76f4a5c2a00a72abe9b92468ac9f15083b94 /README.md | |
| download | facedet-9b9005101e6170a226acb265428aac429be6edbf.tar.gz facedet-9b9005101e6170a226acb265428aac429be6edbf.zip | |
Init
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..bdc75dc --- /dev/null +++ b/README.md @@ -0,0 +1,95 @@ +# YuNet 2026may + +A CPU-only face detector for `face_detection_yunet_2026may`. + +## 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/yunet photo.jpg +./build/yunet photo.png 0.6 0.3 +./build/yunet image.ppm +./build/yunet photo.jpg -o overlay.ppm > faces.json +./build/yunet --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/yunet 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. + + + +## C API + +Include `yunet.h` and link `build/libyunet.a` with `-lm`. + +1. Create a context with `yunet_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 `yunet_set_rgb`, or fill the buffer returned by `yunet_input` with + float32 BGR CHW values in `[0, 255]`. +3. Call `yunet_run`, then `yunet_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 `yunet_free` + when finished. Use separate contexts for concurrent inference. + +The command-line implementation in `main.c` demonstrates the complete flow. +`yunet_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 `YUNET_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`. |
