| --- |
| 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. |
|
|
