Skip to content

UniFace: A Unified Face Analysis Library for Python | Detection, alignment, landmarks, face-mesh, recognition, parsing, gaze, attributes and anti-spoofing under one API.

docs: Fix old documentation issues (#124)

Yakhyokhuja Valikhujaevb12c929f9db5
diff --git a/docs/concepts/coordinate-systems.md b/docs/concepts/coordinate-systems.md
index c7c2460..9f1b2fb 100644
--- a/docs/concepts/coordinate-systems.md
+++ b/docs/concepts/coordinate-systems.md
@@ -199,8 +199,8 @@ Face alignment uses 5-point landmarks to normalize face orientation:
from uniface.face_utils import face_alignment
# Align face to standard template
-aligned_face = face_alignment(image, face.landmarks)
-# Output: 112x112 aligned face image
+aligned_face, _ = face_alignment(image, face.landmarks)
+# Output: (112x112 aligned face image, inverse transform matrix)
```
The alignment transforms faces to a canonical pose for better recognition accuracy.
diff --git a/docs/concepts/execution-providers.md b/docs/concepts/execution-providers.md
index 715fb6b..fa7d634 100644
--- a/docs/concepts/execution-providers.md
+++ b/docs/concepts/execution-providers.md
@@ -1,6 +1,6 @@
# Execution Providers
-UniFace uses ONNX Runtime for model inference, which supports multiple hardware acceleration backends.
+UniFace automatically runs each model on the best available hardware — Apple Silicon (CoreML), NVIDIA GPU (CUDA), or CPU. Under the hood this is handled by ONNX Runtime execution providers.
---
diff --git a/docs/concepts/model-cache-offline.md b/docs/concepts/model-cache-offline.md
index 6aebfa9..6519f3c 100644
--- a/docs/concepts/model-cache-offline.md
+++ b/docs/concepts/model-cache-offline.md
@@ -76,7 +76,7 @@ from uniface.constants import (
AgeGenderWeights,
)
-# Download multiple models concurrently (up to 4 threads by default)
+# Download multiple models concurrently (defaults to min(CPU count, 8) threads)
paths = download_models([
RetinaFaceWeights.MNET_V2,
ArcFaceWeights.MNET,
@@ -218,7 +218,7 @@ print(get_cache_dir()) # shows the active cache path
rm -rf ~/.uniface/models/
# Remove specific model
-rm ~/.uniface/models/retinaface_mv2.onnx
+rm ~/.uniface/models/retinaface_mnet_v2.onnx
```
Models will be re-downloaded on next use.
diff --git a/docs/concepts/overview.md b/docs/concepts/overview.md
index 2d0715c..6fa15bc 100644
--- a/docs/concepts/overview.md
+++ b/docs/concepts/overview.md
@@ -68,7 +68,7 @@ graph TB
### 1. Cross-Platform Inference
-UniFace uses portable model runtimes to provide consistent inference across macOS, Linux, and Windows. Most core components run through ONNX Runtime, while optional components may use PyTorch where appropriate.
+UniFace gives you consistent, hardware-accelerated face analysis across macOS, Linux, and Windows from a single API. The optimal hardware backend is selected automatically; models run on ONNX Runtime, with PyTorch for a few optional ones.
- **Cross-platform**: Same models work on macOS, Linux, Windows
- **Hardware acceleration**: Automatic selection of optimal provider
@@ -81,11 +81,14 @@ Core dependencies are kept minimal:
```
numpy # Array operations
opencv-python # Image processing
-onnxruntime # Model inference
+scikit-image # Geometric transforms (face alignment)
+scipy # Scientific computing
requests # Model download
tqdm # Progress bars
```
+ONNX Runtime is installed separately via the `uniface[cpu]` or `uniface[gpu]` extra (see [Installation](../installation.md)).
+
### 3. Simple API
Direct class instantiation:
diff --git a/docs/concepts/thresholds-calibration.md b/docs/concepts/thresholds-calibration.md
index 99ad77d..336e410 100644
--- a/docs/concepts/thresholds-calibration.md
+++ b/docs/concepts/thresholds-calibration.md
@@ -128,7 +128,7 @@ def calibrate_threshold(same_pairs, diff_pairs, recognizer, detector):
if faces1 and faces2:
emb1 = recognizer.get_normalized_embedding(img1, faces1[0].landmarks)
emb2 = recognizer.get_normalized_embedding(img2, faces2[0].landmarks)
- same_scores.append(np.dot(emb1, emb2.T)[0][0])
+ same_scores.append(float(np.dot(emb1, emb2)))
# Compute similarities for different-person pairs
for img1_path, img2_path in diff_pairs:
@@ -183,7 +183,7 @@ else:
### Emotion
```python
-result = emotion_predictor.predict(image, landmarks)
+result = emotion_predictor.predict(image, face)
# Filter low-confidence predictions
if result.confidence > 0.6:
diff --git a/docs/index.md b/docs/index.md
index 04b3ad2..ca0b362 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -102,7 +102,7 @@ FAISS-backed embedding store for fast multi-identity face search.
## Installation
-UniFace uses portable model runtimes for consistent inference across macOS, Linux, and Windows. Most core components run through **ONNX Runtime**, while optional components may use **PyTorch** where appropriate.
+UniFace runs out of the box on macOS, Linux, and Windows, with automatic hardware acceleration on Apple Silicon, NVIDIA CUDA, and CPU. Inference runs on **ONNX Runtime** (with **PyTorch** for a few optional models) — installed automatically by the extra you choose below.
**CPU / Apple Silicon**
```bash
diff --git a/docs/modules/landmarks.md b/docs/modules/landmarks.md
index 3e60142..518dd1d 100644
--- a/docs/modules/landmarks.md
+++ b/docs/modules/landmarks.md
@@ -205,8 +205,8 @@ def draw_landmarks_with_connections(image, landmarks):
from uniface.face_utils import face_alignment
# Align face using 5-point landmarks
-aligned = face_alignment(image, faces[0].landmarks)
-# Returns: 112x112 aligned face
+aligned, _ = face_alignment(image, faces[0].landmarks)
+# Returns: (112x112 aligned face, inverse transform matrix)
```
### Eye Aspect Ratio (Blink Detection)
diff --git a/docs/modules/matting.md b/docs/modules/matting.md
index 15af3b3..1c5f978 100644
--- a/docs/modules/matting.md
+++ b/docs/modules/matting.md
@@ -108,8 +108,9 @@ cv2.imwrite("custom_bg.jpg", result)
import cv2
import numpy as np
from uniface.matting import MODNet
+from uniface.constants import MODNetWeights
-matting = MODNet(model_name="modnet_webcam")
+matting = MODNet(model_name=MODNetWeights.WEBCAM)
cap = cv2.VideoCapture(0)
while True:
diff --git a/docs/modules/privacy.md b/docs/modules/privacy.md
index 8f50a7b..b4a52ae 100644
--- a/docs/modules/privacy.md
+++ b/docs/modules/privacy.md
@@ -199,7 +199,7 @@ def anonymize_except(image, all_faces, exclude_embeddings, recognizer, threshold
# Check if should be excluded
should_exclude = False
for ref_emb in exclude_embeddings:
- similarity = np.dot(embedding, ref_emb.T)[0][0]
+ similarity = np.dot(embedding, ref_emb)
if similarity > threshold:
should_exclude = True
break
diff --git a/docs/modules/recognition.md b/docs/modules/recognition.md
index 8cbccda..eda2683 100644
--- a/docs/modules/recognition.md
+++ b/docs/modules/recognition.md
@@ -40,7 +40,7 @@ faces = detector.detect(image)
# Extract embedding
if faces:
embedding = recognizer.get_normalized_embedding(image, faces[0].landmarks)
- print(f"Embedding shape: {embedding.shape}") # (1, 512)
+ print(f"Embedding shape: {embedding.shape}") # (512,)
```
### Model Variants
@@ -88,7 +88,7 @@ faces = detector.detect(image)
# Extract embedding
if faces:
embedding = recognizer.get_normalized_embedding(image, faces[0].landmarks)
- print(f"Embedding shape: {embedding.shape}") # (1, 512)
+ print(f"Embedding shape: {embedding.shape}") # (512,)
```
### Model Variants
@@ -251,8 +251,8 @@ emb2 = recognizer.get_normalized_embedding(image2, landmarks2)
# Method 1: Using utility function
similarity = compute_similarity(emb1, emb2)
-# Method 2: Direct computation
-similarity = np.dot(emb1, emb2.T)[0][0]
+# Method 2: Direct computation (embeddings are L2-normalized 1-D vectors)
+similarity = np.dot(emb1, emb2)
print(f"Similarity: {similarity:.4f}")
```
@@ -279,8 +279,8 @@ embedding = recognizer.get_normalized_embedding(image, landmarks)
# Or manually align
from uniface.face_utils import face_alignment
-aligned_face = face_alignment(image, landmarks)
-# Returns: 112x112 aligned face image
+aligned_face, _ = face_alignment(image, landmarks)
+# Returns: (112x112 aligned face, inverse transform matrix)
```
---
@@ -326,7 +326,7 @@ def search_face(query_embedding, database, threshold=0.6):
best_similarity = -1
for person_id, db_embedding in database.items():
- similarity = np.dot(query_embedding, db_embedding.T)[0][0]
+ similarity = np.dot(query_embedding, db_embedding)
if similarity > best_similarity and similarity > threshold:
best_similarity = similarity
diff --git a/docs/recipes/anonymize-stream.md b/docs/recipes/anonymize-stream.md
index 228d0f6..202deaa 100644
--- a/docs/recipes/anonymize-stream.md
+++ b/docs/recipes/anonymize-stream.md
@@ -52,7 +52,7 @@ w, h = int(cap.get(3)), int(cap.get(4))
out = cv2.VideoWriter('output.mp4', cv2.VideoWriter_fourcc(*'mp4v'), fps, (w, h))
-while cap.read()[0]:
+while True:
ret, frame = cap.read()
if not ret:
break
diff --git a/docs/recipes/video-webcam.md b/docs/recipes/video-webcam.md
index 5e8b1d8..3ad7a06 100644
--- a/docs/recipes/video-webcam.md
+++ b/docs/recipes/video-webcam.md
@@ -59,7 +59,7 @@ def process_video(input_path, output_path):
fourcc = cv2.VideoWriter_fourcc(*'mp4v')
out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
- while cap.read()[0]:
+ while True:
ret, frame = cap.read()
if not ret:
break