File size: 3,726 Bytes
b7c4af3 eafa15a b7c4af3 eafa15a | 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 | ---
license: apache-2.0
library_name: onnx
tags:
- face-detection
- face-landmark
- mediapipe
- blazeface
- onnx
base_model: google/mediapipe
pipeline_tag: object-detection
---
# MediaPipe Face — Detection + 6-point Landmarks (ONNX)
Commercial-clean face pipeline bundling both precision variants of Google's MediaPipe Face Detection + Face Landmark models. Apache-2.0 throughout the entire chain: Google MediaPipe → zmurez/MediaPipePyTorch port → Qualcomm AI Hub ONNX export.
Two-stage pipeline:
1. **Face detector** (BlazeFace-derived) — finds face bounding boxes
2. **Face landmark detector** — for each detected face, returns 6 keypoints (left eye, right eye, nose tip, mouth, left eye tragion, right eye tragion)
Re-hosted under Heliosoph as a single bundled repo for convenience — float + int8 variants live in separate subfolders.
Credit: Google MediaPipe team (original models), Zak Murez (PyTorch port), Qualcomm AI Hub (ONNX export).
## What this repo contains
```
float/ # fp32 — recommended default
face_detector.onnx # 78 KB graph
face_detector.data # 517 KB external weights
face_landmark_detector.onnx # 58 KB graph
face_landmark_detector.data # 2.4 MB external weights
metadata.json
int8/ # W8A8 — quantized, smaller/faster
face_detector.onnx
face_detector.data
face_landmark_detector.onnx
face_landmark_detector.data
metadata.json
LICENSE
README.md
```
**Important: external weights pattern.** Each `.onnx` file is paired with a `.data` file holding the actual tensor weights. Both files must be in the same directory at load time — ONNX Runtime resolves the `.data` file by relative path from the `.onnx`.
## How to use
```python
import onnxruntime as ort
import numpy as np
# Stage 1: detect faces
detector = ort.InferenceSession("float/face_detector.onnx")
# Input: 128×128 RGB, normalized to [-1, 1]
detections = detector.run(None, {"image": preprocessed_128x128_image})
# Stage 2: landmark each detected face
landmarker = ort.InferenceSession("float/face_landmark_detector.onnx")
# Input: 192×192 RGB crop around each detected face
landmarks = landmarker.run(None, {"image": face_crop_192x192})
```
Reference preprocessing + decoding: [zmurez/MediaPipePyTorch](https://github.com/zmurez/MediaPipePyTorch) has the canonical Python implementation.
## float vs int8 — which to pick
| Variant | Size | Best for |
|---|---|---|
| `float/` (this default) | ~3 MB | GPU, max accuracy. Recommended general default. |
| `int8/` | ~1.5 MB | CPU, NPU (OpenVINO), mobile. Some accuracy loss on small/distant faces; near-identical on close portraits. |
Catalog entries: `mediapipe-face` (float) and `mediapipe-face-int8` (int8). Both reference this single repo with different `include` patterns.
## Why MediaPipe over alternatives
- **vs InsightFace SCRFD** — SCRFD's released weights are non-commercial-research-only (WIDER FACE dataset terms). MediaPipe was trained by Google on commercial-friendly data and released under permissive terms.
- **vs YuNet** — YuNet is technically also encumbered by WIDER FACE; upstream just doesn't surface that. MediaPipe is unambiguous.
- **vs YOLOv8-Face** — Ultralytics AGPL-3.0. MediaPipe is Apache-2.0.
If you need higher accuracy on small faces in dense scenes (crowd photos, surveillance angles), MediaPipe will underperform RetinaFace-class detectors. For the common case (close portraits, video conferencing, photo tagging), MediaPipe is the right default.
## License
**Apache-2.0** — same as upstream (Google MediaPipe). `LICENSE` file included; chain of attribution is documented above.
|