aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-10-20 11:44:30 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-10-20 11:44:30 +0200
commit9b9005101e6170a226acb265428aac429be6edbf (patch)
treef89c76f4a5c2a00a72abe9b92468ac9f15083b94 /README.md
downloadfacedet-9b9005101e6170a226acb265428aac429be6edbf.tar.gz
facedet-9b9005101e6170a226acb265428aac429be6edbf.zip
Init
Diffstat (limited to 'README.md')
-rw-r--r--README.md95
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.
+
+![Face detection example](./example.jpg)
+
+## 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`.