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.

feat: Common result dataclasses and refactoring several methods. (#50)

Yakhyokhuja Valikhujaevcbcd89b1674e
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c371834..c023331 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -5,7 +5,7 @@
repos:
# General file checks
- repo: https://github.com/pre-commit/pre-commit-hooks
- rev: v4.6.0
+ rev: v6.0.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
@@ -19,7 +19,7 @@ repos:
# Ruff - Fast Python linter and formatter
- repo: https://github.com/astral-sh/ruff-pre-commit
- rev: v0.8.4
+ rev: v0.14.10
hooks:
- id: ruff
args: [--fix, --unsafe-fixes, --exit-non-zero-on-fix]
@@ -27,7 +27,7 @@ repos:
# Security checks
- repo: https://github.com/PyCQA/bandit
- rev: 1.7.10
+ rev: 1.9.2
hooks:
- id: bandit
args: [-c, pyproject.toml]
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2d4ed22..d4de5a9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -167,7 +167,7 @@ When adding a new model or feature:
2. **Add weight constants** to `uniface/constants.py` with URLs and SHA256 hashes
3. **Export in `__init__.py`** files at both module and package levels
4. **Write tests** in `tests/` directory
-5. **Add example usage** in `scripts/` or update existing notebooks
+5. **Add example usage** in `tools/` or update existing notebooks
6. **Update documentation** if needed
## Examples
diff --git a/MODELS.md b/MODELS.md
index aa8fbb7..e977fc3 100644
--- a/MODELS.md
+++ b/MODELS.md
@@ -20,7 +20,7 @@ RetinaFace models are trained on the WIDER FACE dataset and provide excellent ac
| `RESNET34` | 24.8M | 56MB | 94.16% | 93.12% | 88.90% | Maximum accuracy |
**Accuracy**: WIDER FACE validation set (Easy/Medium/Hard subsets) - from [RetinaFace paper](https://arxiv.org/abs/1905.00641)
-**Speed**: Benchmark on your own hardware using `scripts/run_detection.py --iterations 100`
+**Speed**: Benchmark on your own hardware using `tools/detection.py --source <image> --iterations 100`
#### Usage
@@ -52,7 +52,7 @@ SCRFD (Sample and Computation Redistribution for Efficient Face Detection) model
| `SCRFD_10G` ⭐ | 4.2M | 17MB | 95.16% | 93.87% | 83.05% | **High accuracy + speed** |
**Accuracy**: WIDER FACE validation set - from [SCRFD paper](https://arxiv.org/abs/2105.04714)
-**Speed**: Benchmark on your own hardware using `scripts/run_detection.py --iterations 100`
+**Speed**: Benchmark on your own hardware using `tools/detection.py --source <image> --iterations 100`
#### Usage
@@ -87,7 +87,7 @@ YOLOv5-Face models provide excellent detection accuracy with 5-point facial land
| `YOLOV5M` | 82MB | 95.30% | 93.76% | 85.28% | High accuracy |
**Accuracy**: WIDER FACE validation set - from [YOLOv5-Face paper](https://arxiv.org/abs/2105.12931)
-**Speed**: Benchmark on your own hardware using `scripts/run_detection.py --iterations 100`
+**Speed**: Benchmark on your own hardware using `tools/detection.py --source <image> --iterations 100`
**Note**: Fixed input size of 640×640. Models exported to ONNX from [deepcam-cn/yolov5-face](https://github.com/deepcam-cn/yolov5-face)
#### Usage
@@ -317,7 +317,9 @@ from uniface import Emotion
from uniface.constants import DDAMFNWeights
predictor = Emotion(model_name=DDAMFNWeights.AFFECNET7)
-emotion, confidence = predictor.predict(image, landmarks)
+result = predictor.predict(image, landmarks)
+# result.emotion: predicted emotion label
+# result.confidence: confidence score
```
---
@@ -355,8 +357,8 @@ gaze_estimator = MobileGaze() # Uses RESNET34
gaze_estimator = MobileGaze(model_name=GazeWeights.MOBILEONE_S0)
# Estimate gaze from face crop
-pitch, yaw = gaze_estimator.estimate(face_crop)
-print(f"Pitch: {np.degrees(pitch):.1f}°, Yaw: {np.degrees(yaw):.1f}°")
+result = gaze_estimator.estimate(face_crop)
+print(f"Pitch: {np.degrees(result.pitch):.1f}°, Yaw: {np.degrees(result.yaw):.1f}°")
```
**Note**: Requires face crop as input. Use face detection first to obtain bounding boxes.
@@ -447,7 +449,7 @@ Lightweight face anti-spoofing models for liveness detection. Detect if a face i
| `V2` ⭐ | 1.2 MB | 2.7 | **Recommended default** |
**Dataset**: Trained on face anti-spoofing datasets
-**Output**: Returns (label_idx, score) where label_idx: 0=Fake, 1=Real
+**Output**: Returns `SpoofingResult(is_real, confidence)` where is_real: True=Real, False=Fake
#### Usage
@@ -466,10 +468,10 @@ spoofer = MiniFASNet(model_name=MiniFASNetWeights.V1SE)
# Detect and check liveness
faces = detector.detect(image)
for face in faces:
- label_idx, score = spoofer.predict(image, face.bbox)
- # label_idx: 0 = Fake, 1 = Real
- label = 'Real' if label_idx == 1 else 'Fake'
- print(f"{label}: {score:.1%}")
+ result = spoofer.predict(image, face.bbox)
+ # result.is_real: True for real, False for fake
+ label = 'Real' if result.is_real else 'Fake'
+ print(f"{label}: {result.confidence:.1%}")
```
**Note**: Requires face bounding box from a detector. Use with RetinaFace, SCRFD, or YOLOv5Face.
@@ -499,10 +501,10 @@ model_path = verify_model_weights(
```bash
# Using the provided script
-python scripts/download_model.py
+python tools/download_model.py
# Download specific model
-python scripts/download_model.py --model MNET_V2
+python tools/download_model.py --model MNET_V2
```
---
diff --git a/QUICKSTART.md b/QUICKSTART.md
index 0439b5f..436725e 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -307,11 +307,11 @@ for i, face in enumerate(faces):
face_crop = image[y1:y2, x1:x2]
if face_crop.size > 0:
- pitch, yaw = gaze_estimator.estimate(face_crop)
- print(f"Face {i+1}: pitch={np.degrees(pitch):.1f}°, yaw={np.degrees(yaw):.1f}°")
+ result = gaze_estimator.estimate(face_crop)
+ print(f"Face {i+1}: pitch={np.degrees(result.pitch):.1f}°, yaw={np.degrees(result.yaw):.1f}°")
# Draw gaze direction
- draw_gaze(image, face.bbox, pitch, yaw)
+ draw_gaze(image, face.bbox, result.pitch, result.yaw)
cv2.imwrite("gaze_output.jpg", image)
```
@@ -449,13 +449,13 @@ cv2.destroyAllWindows()
```bash
# Anonymize image with pixelation
-python scripts/run_anonymization.py --image photo.jpg
+python tools/face_anonymize.py --source photo.jpg
# Real-time webcam anonymization
-python scripts/run_anonymization.py --webcam --method gaussian
+python tools/face_anonymize.py --source 0 --method gaussian
# Custom blur strength
-python scripts/run_anonymization.py --image photo.jpg --method gaussian --blur-strength 5.0
+python tools/face_anonymize.py --source photo.jpg --method gaussian --blur-strength 5.0
```
---
@@ -475,10 +475,10 @@ image = cv2.imread("photo.jpg")
faces = detector.detect(image)
for i, face in enumerate(faces):
- label_idx, score = spoofer.predict(image, face.bbox)
- # label_idx: 0 = Fake, 1 = Real
- label = 'Real' if label_idx == 1 else 'Fake'
- print(f"Face {i+1}: {label} ({score:.1%})")
+ result = spoofer.predict(image, face.bbox)
+ # result.is_real: True for real, False for fake
+ label = 'Real' if result.is_real else 'Fake'
+ print(f"Face {i+1}: {label} ({result.confidence:.1%})")
```
**Output:**
@@ -491,10 +491,10 @@ Face 1: Real (98.5%)
```bash
# Image
-python scripts/run_spoofing.py --image photo.jpg
+python tools/spoofing.py --source photo.jpg
# Webcam
-python scripts/run_spoofing.py --source 0
+python tools/spoofing.py --source 0
```
---
diff --git a/README.md b/README.md
index a092d78..cbd867c 100644
--- a/README.md
+++ b/README.md
@@ -194,11 +194,11 @@ for face in faces:
x1, y1, x2, y2 = map(int, face.bbox[:4])
face_crop = image[y1:y2, x1:x2]
- pitch, yaw = gaze_estimator.estimate(face_crop)
- print(f"Gaze: pitch={np.degrees(pitch):.1f}°, yaw={np.degrees(yaw):.1f}°")
+ result = gaze_estimator.estimate(face_crop)
+ print(f"Gaze: pitch={np.degrees(result.pitch):.1f}°, yaw={np.degrees(result.yaw):.1f}°")
# Visualize
- draw_gaze(image, face.bbox, pitch, yaw)
+ draw_gaze(image, face.bbox, result.pitch, result.yaw)
```
### Face Parsing
@@ -235,10 +235,11 @@ spoofer = MiniFASNet() # Uses V2 by default
faces = detector.detect(image)
for face in faces:
- label_idx, score = spoofer.predict(image, face.bbox)
- # label_idx: 0 = Fake, 1 = Real
- label = 'Real' if label_idx == 1 else 'Fake'
- print(f"{label}: {score:.1%}")
+ result = spoofer.predict(image, face.bbox)
+ # result.is_real: True for real, False for fake
+ # result.confidence: confidence score
+ label = 'Real' if result.is_real else 'Fake'
+ print(f"{label}: {result.confidence:.1%}")
```
### Face Anonymization
@@ -399,7 +400,7 @@ faces = detect_faces(image, method='retinaface', confidence_threshold=0.8) # me
| Class | Key params (defaults) | Notes |
| ------------- | ------------------------------------------ | ------------------------------------ |
-| `MobileGaze` | `model_name=GazeWeights.RESNET34` | Returns (pitch, yaw) angles in radians; trained on Gaze360 |
+| `MobileGaze` | `model_name=GazeWeights.RESNET34` | Returns `GazeResult(pitch, yaw)` in radians; trained on Gaze360 |
**Face Parsing**
@@ -411,7 +412,7 @@ faces = detect_faces(image, method='retinaface', confidence_threshold=0.8) # me
| Class | Key params (defaults) | Notes |
| ------------- | ----------------------------------------- | ------------------------------------ |
-| `MiniFASNet` | `model_name=MiniFASNetWeights.V2` | Returns (label_idx, score); 0=Fake, 1=Real |
+| `MiniFASNet` | `model_name=MiniFASNetWeights.V2` | Returns `SpoofingResult(is_real, confidence)` |
---
@@ -435,7 +436,7 @@ _Accuracy values from original papers: [RetinaFace](https://arxiv.org/abs/1905.0
**Benchmark on your hardware:**
```bash
-python scripts/run_detection.py --image assets/test.jpg --iterations 100
+python tools/detection.py --source assets/test.jpg --iterations 100
```
See [MODELS.md](MODELS.md) for detailed model information and selection guide.
@@ -662,7 +663,7 @@ uniface/
│ └── visualization.py # Drawing utilities
├── tests/ # Unit tests
├── examples/ # Example notebooks
-└── scripts/ # Utility scripts
+└── tools/ # CLI utilities
```
---
diff --git a/examples/08_gaze_estimation.ipynb b/examples/08_gaze_estimation.ipynb
index b99500f..f5deb46 100644
--- a/examples/08_gaze_estimation.ipynb
+++ b/examples/08_gaze_estimation.ipynb
@@ -103,7 +103,7 @@
},
{
"cell_type": "code",
- "execution_count": 4,
+ "execution_count": null,
"metadata": {},
"outputs": [
{
diff --git a/scripts/README.md b/scripts/README.md
deleted file mode 100644
index 376270d..0000000
--- a/scripts/README.md
+++ /dev/null
@@ -1,85 +0,0 @@
-# Scripts
-
-Scripts for testing UniFace features.
-
-## Available Scripts
-
-| Script | Description |
-|--------|-------------|
-| `run_detection.py` | Face detection on image or webcam |
-| `run_anonymization.py` | Face anonymization/blurring for privacy |
-| `run_age_gender.py` | Age and gender prediction |
-| `run_emotion.py` | Emotion detection (7 or 8 emotions) |
-| `run_gaze_estimation.py` | Gaze direction estimation |
-| `run_landmarks.py` | 106-point facial landmark detection |
-| `run_recognition.py` | Face embedding extraction and comparison |
-| `run_face_analyzer.py` | Complete face analysis (detection + recognition + attributes) |
-| `run_face_search.py` | Real-time face matching against reference |
-| `run_video_detection.py` | Face detection on video files |
-| `batch_process.py` | Batch process folder of images |
-| `download_model.py` | Download model weights |
-| `sha256_generate.py` | Generate SHA256 hash for model files |
-
-## Usage Examples
-
-```bash
-# Face detection
-python scripts/run_detection.py --image assets/test.jpg
-python scripts/run_detection.py --webcam
-
-# Face anonymization
-python scripts/run_anonymization.py --image assets/test.jpg --method pixelate
-python scripts/run_anonymization.py --webcam --method gaussian
-python scripts/run_anonymization.py --image photo.jpg --method pixelate --pixel-blocks 5
-
-# Age and gender
-python scripts/run_age_gender.py --image assets/test.jpg
-python scripts/run_age_gender.py --webcam
-
-# Emotion detection
-python scripts/run_emotion.py --image assets/test.jpg
-python scripts/run_emotion.py --webcam
-
-# Gaze estimation
-python scripts/run_gaze_estimation.py --image assets/test.jpg
-python scripts/run_gaze_estimation.py --webcam
-
-# Landmarks
-python scripts/run_landmarks.py --image assets/test.jpg
-python scripts/run_landmarks.py --webcam
-
-# Face recognition (extract embedding)
-python scripts/run_recognition.py --image assets/test.jpg
-
-# Face comparison
-python scripts/run_recognition.py --image1 face1.jpg --image2 face2.jpg
-
-# Face search (match webcam against reference)
-python scripts/run_face_search.py --image reference.jpg
-
-# Video processing
-python scripts/run_video_detection.py --input video.mp4 --output output.mp4
-
-# Batch processing
-python scripts/batch_process.py --input images/ --output results/
-
-# Download models
-python scripts/download_model.py --model-type retinaface
-python scripts/download_model.py # downloads all
-```
-
-## Common Options
-
-| Option | Description |
-|--------|-------------|
-| `--image` | Path to input image |
-| `--webcam` | Use webcam instead of image |
-| `--method` | Choose detector: `retinaface`, `scrfd`, `yolov5face` |
-| `--threshold` | Visualization confidence threshold (default: 0.25) |
-| `--save_dir` | Output directory (default: `outputs`) |
-
-## Quick Test
-
-```bash
-python scripts/run_detection.py --image assets/test.jpg
-```
diff --git a/scripts/run_age_gender.py b/scripts/run_age_gender.py
deleted file mode 100644
index 79d9926..0000000
--- a/scripts/run_age_gender.py
+++ /dev/null
@@ -1,128 +0,0 @@
-# Age and gender prediction on detected faces
-# Usage: python run_age_gender.py --image path/to/image.jpg
-# python run_age_gender.py --webcam
-
-import argparse
-import os
-from pathlib import Path
-
-import cv2
-
-from uniface import SCRFD, AgeGender, RetinaFace
-from uniface.visualization import draw_detections
-
-
-def draw_age_gender_label(image, bbox, sex: str, age: int):
- """Draw age/gender label above the bounding box."""
- x1, y1 = int(bbox[0]), int(bbox[1])
- text = f'{sex}, {age}y'
- (tw, th), _ = cv2.getTextSize(text, cv2.FONT_HERSHEY_SIMPLEX, 0.6, 2)
- cv2.rectangle(image, (x1, y1 - th - 10), (x1 + tw + 10, y1), (0, 255, 0), -1)
- cv2.putText(image, text, (x1 + 5, y1 - 5), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 0, 0), 2)
-
-
-def process_image(
- detector,
- age_gender,
- image_path: str,
- save_dir: str = 'outputs',
- threshold: float = 0.6,
-):
- image = cv2.imread(image_path)
- if image is None:
- print(f"Error: Failed to load image from '{image_path}'")
- return
-
- faces = detector.detect(image)
- print(f'Detected {len(faces)} face(s)')
-
- if not faces:
- return
-
- bboxes = [f.bbox for f in faces]
- scores = [f.confidence for f in faces]
- landmarks = [f.landmarks for f in faces]
- draw_detections(
- image=image, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
- )
-
- for i, face in enumerate(faces):
- result = age_gender.predict(image, face.bbox)
- print(f' Face {i + 1}: {result.sex}, {result.age} years old')
- draw_age_gender_label(image, face.bbox, result.sex, result.age)
-
- os.makedirs(save_dir, exist_ok=True)
- output_path = os.path.join(save_dir, f'{Path(image_path).stem}_age_gender.jpg')
- cv2.imwrite(output_path, image)
- print(f'Output saved: {output_path}')
-
-
-def run_webcam(detector, age_gender, threshold: float = 0.6):
- cap = cv2.VideoCapture(0) # 0 = default webcam
- if not cap.isOpened():
- print('Cannot open webcam')
- return
-
- print("Press 'q' to quit")
-
- while True:
- ret, frame = cap.read()
- frame = cv2.flip(frame, 1) # mirror for natural interaction
- if not ret:
- break
-
- faces = detector.detect(frame)
-
- # unpack face data for visualization
- bboxes = [f.bbox for f in faces]
- scores = [f.confidence for f in faces]
- landmarks = [f.landmarks for f in faces]
- draw_detections(
- image=frame, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
- )
-
- for face in faces:
- result = age_gender.predict(frame, face.bbox)
- draw_age_gender_label(frame, face.bbox, result.sex, result.age)
-
- cv2.putText(
- frame,
- f'Faces: {len(faces)}',
- (10, 30),
- cv2.FONT_HERSHEY_SIMPLEX,
- 1,
- (0, 255, 0),
- 2,
- )
- cv2.imshow('Age & Gender Detection', frame)
-
- if cv2.waitKey(1) & 0xFF == ord('q'):
- break
-
- cap.release()
- cv2.destroyAllWindows()
-
-
-def main():
- parser = argparse.ArgumentParser(description='Run age and gender detection')
- parser.add_argument('--image', type=str, help='Path to input image')
- parser.add_argument('--webcam', action='store_true', help='Use webcam')
- parser.add_argument('--detector', type=str, default='retinaface', choices=['retinaface', 'scrfd'])
- parser.add_argument('--threshold', type=float, default=0.6, help='Visualization threshold')
- parser.add_argument('--save_dir', type=str, default='outputs')
- args = parser.parse_args()
-
- if not args.image and not args.webcam:
- parser.error('Either --image or --webcam must be specified')
-
- detector = RetinaFace() if args.detector == 'retinaface' else SCRFD()
- age_gender = AgeGender()
-
- if args.webcam:
- run_webcam(detector, age_gender, args.threshold)
- else:
- process_image(detector, age_gender, args.image, args.save_dir, args.threshold)
-
-
-if __name__ == '__main__':
- main()
diff --git a/scripts/run_detection.py b/scripts/run_detection.py
deleted file mode 100644
index c53b1ce..0000000
--- a/scripts/run_detection.py
+++ /dev/null
@@ -1,119 +0,0 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
-# Author: Yakhyokhuja Valikhujaev
-# GitHub: https://github.com/yakhyo
-
-"""Face detection on image or webcam.
-
-Usage:
- python run_detection.py --image path/to/image.jpg
- python run_detection.py --webcam
-"""
-
-from __future__ import annotations
-
-import argparse
-import os
-
-import cv2
-
-from uniface.detection import SCRFD, RetinaFace, YOLOv5Face
-from uniface.visualization import draw_detections
-
-
-def process_image(detector, image_path: str, threshold: float = 0.6, save_dir: str = 'outputs'):
- image = cv2.imread(image_path)
- if image is None:
- print(f"Error: Failed to load image from '{image_path}'")
- return
-
- faces = detector.detect(image)
-
- if faces:
- bboxes = [face.bbox for face in faces]
- scores = [face.confidence for face in faces]
- landmarks = [face.landmarks for face in faces]
- draw_detections(image, bboxes, scores, landmarks, vis_threshold=threshold)
-
- os.makedirs(save_dir, exist_ok=True)
- output_path = os.path.join(save_dir, f'{os.path.splitext(os.path.basename(image_path))[0]}_out.jpg')
- cv2.imwrite(output_path, image)
- print(f'Output saved: {output_path}')
-
-
-def run_webcam(detector, threshold: float = 0.6):
- cap = cv2.VideoCapture(0) # 0 = default webcam
- if not cap.isOpened():
- print('Cannot open webcam')
- return
-
- print("Press 'q' to quit")
-
- while True:
- ret, frame = cap.read()
- frame = cv2.flip(frame, 1) # mirror for natural interaction
- if not ret:
- break
-
- faces = detector.detect(frame)
-
- # unpack face data for visualization
- bboxes = [f.bbox for f in faces]
- scores = [f.confidence for f in faces]
- landmarks = [f.landmarks for f in faces]
- draw_detections(
- image=frame,
- bboxes=bboxes,
- scores=scores,
- landmarks=landmarks,
- vis_threshold=threshold,
- draw_score=True,
- fancy_bbox=True,
- )
-
- cv2.putText(
- frame,
- f'Faces: {len(faces)}',
- (10, 30),
- cv2.FONT_HERSHEY_SIMPLEX,
- 1,
- (0, 255, 0),
- 2,
- )
- cv2.imshow('Face Detection', frame)
-
- if cv2.waitKey(1) & 0xFF == ord('q'):
- break
-
- cap.release()
- cv2.destroyAllWindows()
-
-
-def main():
- parser = argparse.ArgumentParser(description='Run face detection')
- parser.add_argument('--image', type=str, help='Path to input image')
- parser.add_argument('--webcam', action='store_true', help='Use webcam')
- parser.add_argument('--method', type=str, default='retinaface', choices=['retinaface', 'scrfd', 'yolov5face'])
- parser.add_argument('--threshold', type=float, default=0.25, help='Visualization threshold')
- parser.add_argument('--save_dir', type=str, default='outputs')
- args = parser.parse_args()
-
- if not args.image and not args.webcam:
- parser.error('Either --image or --webcam must be specified')
-
- if args.method == 'retinaface':
- detector = RetinaFace()
- elif args.method == 'scrfd':
- detector = SCRFD()
- else:
- from uniface.constants import YOLOv5FaceWeights
-
- detector = YOLOv5Face(model_name=YOLOv5FaceWeights.YOLOV5M)
-
- if args.webcam:
- run_webcam(detector, args.threshold)
- else:
- process_image(detector, args.image, args.threshold, args.save_dir)
-
-
-if __name__ == '__main__':
- main()
diff --git a/scripts/run_emotion.py b/scripts/run_emotion.py
deleted file mode 100644
index e13b319..0000000
--- a/scripts/run_emotion.py
+++ /dev/null
@@ -1,128 +0,0 @@
-# Emotion detection on detected faces
-# Usage: python run_emotion.py --image path/to/image.jpg
-# python run_emotion.py --webcam
-
-import argparse
-import os
-from pathlib import Path
-
-import cv2
-
-from uniface import SCRFD, Emotion, RetinaFace
-from uniface.visualization import draw_detections
-
-
-def draw_emotion_label(image, bbox, emotion: str, confidence: float):
- """Draw emotion label above the bounding box."""
- x1, y1 = int(bbox[0]), int(bbox[1])
- text = f'{emotion} ({confidence:.2f})'
- (tw, th), _ = cv2.getTextSize(text, cv2.FONT_HERSHEY_SIMPLEX, 0.6, 2)
- cv2.rectangle(image, (x1, y1 - th - 10), (x1 + tw + 10, y1), (255, 0, 0), -1)
- cv2.putText(image, text, (x1 + 5, y1 - 5), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 255, 255), 2)
-
-
-def process_image(
- detector,
- emotion_predictor,
- image_path: str,
- save_dir: str = 'outputs',
- threshold: float = 0.6,
-):
- image = cv2.imread(image_path)
- if image is None:
- print(f"Error: Failed to load image from '{image_path}'")
- return
-
- faces = detector.detect(image)
- print(f'Detected {len(faces)} face(s)')
-
- if not faces:
- return
-
- bboxes = [f.bbox for f in faces]
- scores = [f.confidence for f in faces]
- landmarks = [f.landmarks for f in faces]
- draw_detections(
- image=image, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
- )
-
- for i, face in enumerate(faces):
- emotion, confidence = emotion_predictor.predict(image, face.landmarks)
- print(f' Face {i + 1}: {emotion} (confidence: {confidence:.3f})')
- draw_emotion_label(image, face.bbox, emotion, confidence)
-
- os.makedirs(save_dir, exist_ok=True)
- output_path = os.path.join(save_dir, f'{Path(image_path).stem}_emotion.jpg')
- cv2.imwrite(output_path, image)
- print(f'Output saved: {output_path}')
-
-
-def run_webcam(detector, emotion_predictor, threshold: float = 0.6):
- cap = cv2.VideoCapture(0) # 0 = default webcam
- if not cap.isOpened():
- print('Cannot open webcam')
- return
-
- print("Press 'q' to quit")
-
- while True:
- ret, frame = cap.read()
- frame = cv2.flip(frame, 1) # mirror for natural interaction
- if not ret:
- break
-
- faces = detector.detect(frame)
-
- # unpack face data for visualization
- bboxes = [f.bbox for f in faces]
- scores = [f.confidence for f in faces]
- landmarks = [f.landmarks for f in faces]
- draw_detections(
- image=frame, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
- )
-
- for face in faces:
- emotion, confidence = emotion_predictor.predict(frame, face.landmarks)
- draw_emotion_label(frame, face.bbox, emotion, confidence)
-
- cv2.putText(
- frame,
- f'Faces: {len(faces)}',
- (10, 30),
- cv2.FONT_HERSHEY_SIMPLEX,
- 1,
- (0, 255, 0),
- 2,
- )
- cv2.imshow('Emotion Detection', frame)
-
- if cv2.waitKey(1) & 0xFF == ord('q'):
- break
-
- cap.release()
- cv2.destroyAllWindows()
-
-
-def main():
- parser = argparse.ArgumentParser(description='Run emotion detection')
- parser.add_argument('--image', type=str, help='Path to input image')
- parser.add_argument('--webcam', action='store_true', help='Use webcam')
- parser.add_argument('--detector', type=str, default='retinaface', choices=['retinaface', 'scrfd'])
- parser.add_argument('--threshold', type=float, default=0.6, help='Visualization threshold')
- parser.add_argument('--save_dir', type=str, default='outputs')
- args = parser.parse_args()
-
- if not args.image and not args.webcam:
- parser.error('Either --image or --webcam must be specified')
-
- detector = RetinaFace() if args.detector == 'retinaface' else SCRFD()
- emotion_predictor = Emotion()
-
- if args.webcam:
- run_webcam(detector, emotion_predictor, args.threshold)
- else:
- process_image(detector, emotion_predictor, args.image, args.save_dir, args.threshold)
-
-
-if __name__ == '__main__':
- main()
diff --git a/scripts/run_face_analyzer.py b/scripts/run_face_analyzer.py
deleted file mode 100644
index fabe6e4..0000000
--- a/scripts/run_face_analyzer.py
+++ /dev/null
@@ -1,116 +0,0 @@
-# Face analysis using FaceAnalyzer
-# Usage: python run_face_analyzer.py --image path/to/image.jpg
-
-import argparse
-import os
-from pathlib import Path
-
-import cv2
-import numpy as np
-
-from uniface import AgeGender, ArcFace, FaceAnalyzer, RetinaFace
-from uniface.visualization import draw_detections
-
-
-def draw_face_info(image, face, face_id):
- """Draw face ID and attributes above bounding box."""
- x1, y1, x2, y2 = map(int, face.bbox)
- lines = [f'ID: {face_id}', f'Conf: {face.confidence:.2f}']
- if face.age and face.sex:
- lines.append(f'{face.sex}, {face.age}y')
-
- for i, line in enumerate(lines):
- y_pos = y1 - 10 - (len(lines) - 1 - i) * 25
- if y_pos < 20:
- y_pos = y2 + 20 + i * 25
- (tw, th), _ = cv2.getTextSize(line, cv2.FONT_HERSHEY_SIMPLEX, 0.6, 2)
- cv2.rectangle(image, (x1, y_pos - th - 5), (x1 + tw + 10, y_pos + 5), (0, 255, 0), -1)
- cv2.putText(image, line, (x1 + 5, y_pos), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 0, 0), 2)
-
-
-def process_image(analyzer, image_path: str, save_dir: str = 'outputs', show_similarity: bool = True):
- image = cv2.imread(image_path)
- if image is None:
- print(f"Error: Failed to load image from '{image_path}'")
- return
-
- faces = analyzer.analyze(image)
- print(f'Detected {len(faces)} face(s)')
-
- if not faces:
- return
-
- for i, face in enumerate(faces, 1):
- info = f' Face {i}: {face.sex}, {face.age}y' if face.age and face.sex else f' Face {i}'
- if face.embedding is not None:
- info += f' (embedding: {face.embedding.shape})'
- print(info)
-
- if show_similarity and len(faces) >= 2:
- print('\nSimilarity Matrix:')
- n = len(faces)
- sim_matrix = np.zeros((n, n))
-
- for i in range(n):
- for j in range(i, n):
- if i == j:
- sim_matrix[i][j] = 1.0
- else:
- sim = faces[i].compute_similarity(faces[j])
- sim_matrix[i][j] = sim
- sim_matrix[j][i] = sim
-
- print(' ', end='')
- for i in range(n):
- print(f' F{i + 1:2d} ', end='')
- print('\n ' + '-' * (7 * n))
-
- for i in range(n):
- print(f'F{i + 1:2d} | ', end='')
- for j in range(n):
- print(f'{sim_matrix[i][j]:6.3f} ', end='')
- print()
-
- pairs = [(i, j, sim_matrix[i][j]) for i in range(n) for j in range(i + 1, n)]
- pairs.sort(key=lambda x: x[2], reverse=True)
-
- print('\nTop matches (>0.4 = same person):')
- for i, j, sim in pairs[:3]:
- status = 'Same' if sim > 0.4 else 'Different'
- print(f' Face {i + 1} ↔ Face {j + 1}: {sim:.3f} ({status})')
-
- bboxes = [f.bbox for f in faces]
- scores = [f.confidence for f in faces]
- landmarks = [f.landmarks for f in faces]
- draw_detections(image=image, bboxes=bboxes, scores=scores, landmarks=landmarks, fancy_bbox=True)
-
- for i, face in enumerate(faces, 1):
- draw_face_info(image, face, i)
-
- os.makedirs(save_dir, exist_ok=True)
- output_path = os.path.join(save_dir, f'{Path(image_path).stem}_analysis.jpg')
- cv2.imwrite(output_path, image)
- print(f'Output saved: {output_path}')
-
-
-def main():
- parser = argparse.ArgumentParser(description='Face analysis with detection, recognition, and attributes')
- parser.add_argument('--image', type=str, required=True, help='Path to input image')
- parser.add_argument('--save_dir', type=str, default='outputs', help='Output directory')
- parser.add_argument('--no-similarity', action='store_true', help='Skip similarity matrix computation')
- args = parser.parse_args()
-
- if not os.path.exists(args.image):
- print(f'Error: Image not found: {args.image}')
- return
-
- detector = RetinaFace()
- recognizer = ArcFace()
- age_gender = AgeGender()
- analyzer = FaceAnalyzer(detector, recognizer, age_gender)
-
- process_image(analyzer, args.image, args.save_dir, show_similarity=not args.no_similarity)
-
-
-if __name__ == '__main__':
- main()
diff --git a/scripts/run_face_search.py b/scripts/run_face_search.py
deleted file mode 100644
index 0ea958f..0000000
--- a/scripts/run_face_search.py
+++ /dev/null
@@ -1,97 +0,0 @@
-# Real-time face search: match webcam faces against a reference image
-# Usage: python run_face_search.py --image reference.jpg
-
-import argparse
-
-import cv2
-import numpy as np
-
-from uniface.detection import SCRFD, RetinaFace
-from uniface.face_utils import compute_similarity
-from uniface.recognition import ArcFace, MobileFace, SphereFace
-
-
-def get_recognizer(name: str):
- if name == 'arcface':
- return ArcFace()
- elif name == 'mobileface':
- return MobileFace()
- else:
- return SphereFace()
-
-
-def extract_reference_embedding(detector, recognizer, image_path: str) -> np.ndarray:
- image = cv2.imread(image_path)
- if image is None:
- raise RuntimeError(f'Failed to load image: {image_path}')
-
- faces = detector.detect(image)
- if not faces:
- raise RuntimeError('No faces found in reference image.')
-
- landmarks = faces[0].landmarks
- return recognizer.get_normalized_embedding(image, landmarks)
-
-
-def run_webcam(detector, recognizer, ref_embedding: np.ndarray, threshold: float = 0.4):
- cap = cv2.VideoCapture(0) # 0 = default webcam
- if not cap.isOpened():
- raise RuntimeError('Webcam could not be opened.')
-
- print("Press 'q' to quit")
-
- while True:
- ret, frame = cap.read()
- frame = cv2.flip(frame, 1) # mirror for natural interaction
- if not ret:
- break
-
- faces = detector.detect(frame)
-
- for face in faces:
- bbox = face.bbox
- landmarks = face.landmarks
- x1, y1, x2, y2 = map(int, bbox)
-
- embedding = recognizer.get_normalized_embedding(frame, landmarks)
- sim = compute_similarity(ref_embedding, embedding) # compare with reference
-
- # green = match, red = unknown
- label = f'Match ({sim:.2f})' if sim > threshold else f'Unknown ({sim:.2f})'
- color = (0, 255, 0) if sim > threshold else (0, 0, 255)
-
- cv2.rectangle(frame, (x1, y1), (x2, y2), color, 2)
- cv2.putText(frame, label, (x1, y1 - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.6, color, 2)
-
- cv2.imshow('Face Recognition', frame)
- if cv2.waitKey(1) & 0xFF == ord('q'):
- break
-
- cap.release()
- cv2.destroyAllWindows()
-
-
-def main():
- parser = argparse.ArgumentParser(description='Face search using a reference image')
- parser.add_argument('--image', type=str, required=True, help='Reference face image')
- parser.add_argument('--threshold', type=float, default=0.4, help='Match threshold')
- parser.add_argument('--detector', type=str, default='scrfd', choices=['retinaface', 'scrfd'])
- parser.add_argument(
- '--recognizer',
- type=str,
- default='arcface',
- choices=['arcface', 'mobileface', 'sphereface'],
- )
- args = parser.parse_args()
-
- detector = RetinaFace() if args.detector == 'retinaface' else SCRFD()
- recognizer = get_recognizer(args.recognizer)
-
- print(f'Loading reference: {args.image}')
- ref_embedding = extract_reference_embedding(detector, recognizer, args.image)
-
- run_webcam(detector, recognizer, ref_embedding, args.threshold)
-
-
-if __name__ == '__main__':
- main()
diff --git a/scripts/run_fairface.py b/scripts/run_fairface.py
deleted file mode 100644
index 319ac28..0000000
--- a/scripts/run_fairface.py
+++ /dev/null
@@ -1,129 +0,0 @@
-# FairFace attribute prediction (race, gender, age) on detected faces
-# Usage: python run_fairface.py --image path/to/image.jpg
-# python run_fairface.py --webcam
-
-import argparse
-import os
-from pathlib import Path
-
-import cv2
-
-from uniface import SCRFD, RetinaFace
-from uniface.attribute import FairFace
-from uniface.visualization import draw_detections
-
-
-def draw_fairface_label(image, bbox, sex: str, age_group: str, race: str):
- """Draw FairFace attributes above the bounding box."""
- x1, y1 = int(bbox[0]), int(bbox[1])
- text = f'{sex}, {age_group}, {race}'
- (tw, th), _ = cv2.getTextSize(text, cv2.FONT_HERSHEY_SIMPLEX, 0.5, 2)
- cv2.rectangle(image, (x1, y1 - th - 10), (x1 + tw + 10, y1), (0, 255, 0), -1)
- cv2.putText(image, text, (x1 + 5, y1 - 5), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 0, 0), 2)
-
-
-def process_image(
- detector,
- fairface,
- image_path: str,
- save_dir: str = 'outputs',
- threshold: float = 0.6,
-):
- image = cv2.imread(image_path)
- if image is None:
- print(f"Error: Failed to load image from '{image_path}'")
- return
-
- faces = detector.detect(image)
- print(f'Detected {len(faces)} face(s)')
-
- if not faces:
- return
-
- bboxes = [f.bbox for f in faces]
- scores = [f.confidence for f in faces]
- landmarks = [f.landmarks for f in faces]
- draw_detections(
- image=image, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
- )
-
- for i, face in enumerate(faces):
- result = fairface.predict(image, face.bbox)
- print(f' Face {i + 1}: {result.sex}, {result.age_group}, {result.race}')
- draw_fairface_label(image, face.bbox, result.sex, result.age_group, result.race)
-
- os.makedirs(save_dir, exist_ok=True)
- output_path = os.path.join(save_dir, f'{Path(image_path).stem}_fairface.jpg')
- cv2.imwrite(output_path, image)
- print(f'Output saved: {output_path}')
-
-
-def run_webcam(detector, fairface, threshold: float = 0.6):
- cap = cv2.VideoCapture(0) # 0 = default webcam
- if not cap.isOpened():
- print('Cannot open webcam')
- return
-
- print("Press 'q' to quit")
-
- while True:
- ret, frame = cap.read()
- frame = cv2.flip(frame, 1) # mirror for natural interaction
- if not ret:
- break
-
- faces = detector.detect(frame)
-
- # unpack face data for visualization
- bboxes = [f.bbox for f in faces]
- scores = [f.confidence for f in faces]
- landmarks = [f.landmarks for f in faces]
- draw_detections(
- image=frame, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
- )
-
- for face in faces:
- result = fairface.predict(frame, face.bbox)
- draw_fairface_label(frame, face.bbox, result.sex, result.age_group, result.race)
-
- cv2.putText(
- frame,
- f'Faces: {len(faces)}',
- (10, 30),
- cv2.FONT_HERSHEY_SIMPLEX,
- 1,
- (0, 255, 0),
- 2,
- )
- cv2.imshow('FairFace Detection', frame)
-
- if cv2.waitKey(1) & 0xFF == ord('q'):
- break
-
- cap.release()
- cv2.destroyAllWindows()
-
-
-def main():
- parser = argparse.ArgumentParser(description='Run FairFace attribute prediction (race, gender, age)')
- parser.add_argument('--image', type=str, help='Path to input image')
- parser.add_argument('--webcam', action='store_true', help='Use webcam')
- parser.add_argument('--detector', type=str, default='retinaface', choices=['retinaface', 'scrfd'])
- parser.add_argument('--threshold', type=float, default=0.6, help='Visualization threshold')
- parser.add_argument('--save_dir', type=str, default='outputs')
- args = parser.parse_args()
-
- if not args.image and not args.webcam:
- parser.error('Either --image or --webcam must be specified')
-
- detector = RetinaFace() if args.detector == 'retinaface' else SCRFD()
- fairface = FairFace()
-
- if args.webcam:
- run_webcam(detector, fairface, args.threshold)
- else:
- process_image(detector, fairface, args.image, args.save_dir, args.threshold)
-
-
-if __name__ == '__main__':
- main()
diff --git a/scripts/run_gaze_estimation.py b/scripts/run_gaze_estimation.py
deleted file mode 100644
index dd3356f..0000000
--- a/scripts/run_gaze_estimation.py
+++ /dev/null
@@ -1,104 +0,0 @@
-# Gaze estimation on detected faces
-# Usage: python run_gaze_estimation.py --image path/to/image.jpg
-# python run_gaze_estimation.py --webcam
-
-import argparse
-import os
-from pathlib import Path
-
-import cv2
-import numpy as np
-
-from uniface import RetinaFace
-from uniface.gaze import MobileGaze
-from uniface.visualization import draw_gaze
-
-
-def process_image(detector, gaze_estimator, image_path: str, save_dir: str = 'outputs'):
- image = cv2.imread(image_path)
- if image is None:
- print(f"Error: Failed to load image from '{image_path}'")
- return
-
- faces = detector.detect(image)
- print(f'Detected {len(faces)} face(s)')
-
- for i, face in enumerate(faces):
- bbox = face.bbox
- x1, y1, x2, y2 = map(int, bbox[:4])
- face_crop = image[y1:y2, x1:x2]
-
- if face_crop.size == 0:
- continue
-
- pitch, yaw = gaze_estimator.estimate(face_crop)
- print(f' Face {i + 1}: pitch={np.degrees(pitch):.1f}°, yaw={np.degrees(yaw):.1f}°')
-
- # Draw both bbox and gaze arrow with angle text
- draw_gaze(image, bbox, pitch, yaw, draw_angles=True)
-
- os.makedirs(save_dir, exist_ok=True)
- output_path = os.path.join(save_dir, f'{Path(image_path).stem}_gaze.jpg')
- cv2.imwrite(output_path, image)
- print(f'Output saved: {output_path}')
-
-
-def run_webcam(detector, gaze_estimator):
- cap = cv2.VideoCapture(0)
- if not cap.isOpened():
- print('Cannot open webcam')
- return
-
- print("Press 'q' to quit")
-
- while True:
- ret, frame = cap.read()
- if not ret:
- break
-
- frame = cv2.flip(frame, 1)
- faces = detector.detect(frame)
-
- for face in faces:
- bbox = face.bbox
- x1, y1, x2, y2 = map(int, bbox[:4])
- face_crop = frame[y1:y2, x1:x2]
-
- if face_crop.size == 0:
- continue
-
- pitch, yaw = gaze_estimator.estimate(face_crop)
- # Draw both bbox and gaze arrow
- draw_gaze(frame, bbox, pitch, yaw)
-
- cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
- cv2.imshow('Gaze Estimation', frame)
-
- if cv2.waitKey(1) & 0xFF == ord('q'):
- break
-
- cap.release()
- cv2.destroyAllWindows()
-
-
-def main():
- parser = argparse.ArgumentParser(description='Run gaze estimation')
- parser.add_argument('--image', type=str, help='Path to input image')
- parser.add_argument('--webcam', action='store_true', help='Use webcam')
- parser.add_argument('--save_dir', type=str, default='outputs')
- args = parser.parse_args()
-
- if not args.image and not args.webcam:
- parser.error('Either --image or --webcam must be specified')
-
- detector = RetinaFace()
- gaze_estimator = MobileGaze()
-
- if args.webcam:
- run_webcam(detector, gaze_estimator)
- else:
- process_image(detector, gaze_estimator, args.image, args.save_dir)
-
-
-if __name__ == '__main__':
- main()
diff --git a/scripts/run_landmarks.py b/scripts/run_landmarks.py
deleted file mode 100644
index 81f74cb..0000000
--- a/scripts/run_landmarks.py
+++ /dev/null
@@ -1,117 +0,0 @@
-# 106-point facial landmark detection
-# Usage: python run_landmarks.py --image path/to/image.jpg
-# python run_landmarks.py --webcam
-
-import argparse
-import os
-from pathlib import Path
-
-import cv2
-
-from uniface import SCRFD, Landmark106, RetinaFace
-
-
-def process_image(detector, landmarker, image_path: str, save_dir: str = 'outputs'):
- image = cv2.imread(image_path)
- if image is None:
- print(f"Error: Failed to load image from '{image_path}'")
- return
-
- faces = detector.detect(image)
- print(f'Detected {len(faces)} face(s)')
-
- if not faces:
- return
-
- for i, face in enumerate(faces):
- bbox = face.bbox
- x1, y1, x2, y2 = map(int, bbox)
- cv2.rectangle(image, (x1, y1), (x2, y2), (0, 255, 0), 2)
-
- landmarks = landmarker.get_landmarks(image, bbox)
- print(f' Face {i + 1}: {len(landmarks)} landmarks')
-
- for x, y in landmarks.astype(int):
- cv2.circle(image, (x, y), 1, (0, 255, 0), -1)
-
- cv2.putText(
- image,
- f'Face {i + 1}',
- (x1, y1 - 10),
- cv2.FONT_HERSHEY_SIMPLEX,
- 0.5,
- (0, 255, 0),
- 2,
- )
-
- os.makedirs(save_dir, exist_ok=True)
- output_path = os.path.join(save_dir, f'{Path(image_path).stem}_landmarks.jpg')
- cv2.imwrite(output_path, image)
- print(f'Output saved: {output_path}')
-
-
-def run_webcam(detector, landmarker):
- cap = cv2.VideoCapture(0) # 0 = default webcam
- if not cap.isOpened():
- print('Cannot open webcam')
- return
-
- print("Press 'q' to quit")
-
- while True:
- ret, frame = cap.read()
- frame = cv2.flip(frame, 1) # mirror for natural interaction
- if not ret:
- break
-
- faces = detector.detect(frame)
-
- for face in faces:
- bbox = face.bbox
- x1, y1, x2, y2 = map(int, bbox)
- cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2)
-
- landmarks = landmarker.get_landmarks(frame, bbox) # 106 points
- for x, y in landmarks.astype(int):
- cv2.circle(frame, (x, y), 1, (0, 255, 0), -1)
-
- cv2.putText(
- frame,
- f'Faces: {len(faces)}',
- (10, 30),
- cv2.FONT_HERSHEY_SIMPLEX,
- 1,
- (0, 255, 0),
- 2,
- )
- cv2.imshow('106-Point Landmarks', frame)
-
- if cv2.waitKey(1) & 0xFF == ord('q'):
- break
-
- cap.release()
- cv2.destroyAllWindows()
-
-
-def main():
- parser = argparse.ArgumentParser(description='Run facial landmark detection')
- parser.add_argument('--image', type=str, help='Path to input image')
- parser.add_argument('--webcam', action='store_true', help='Use webcam')
- parser.add_argument('--detector', type=str, default='retinaface', choices=['retinaface', 'scrfd'])
- parser.add_argument('--save_dir', type=str, default='outputs')
- args = parser.parse_args()
-
- if not args.image and not args.webcam:
- parser.error('Either --image or --webcam must be specified')
-
- detector = RetinaFace() if args.detector == 'retinaface' else SCRFD()
- landmarker = Landmark106()
-
- if args.webcam:
- run_webcam(detector, landmarker)
- else:
- process_image(detector, landmarker, args.image, args.save_dir)
-
-
-if __name__ == '__main__':
- main()
diff --git a/scripts/run_spoofing.py b/scripts/run_spoofing.py
deleted file mode 100644
index 07ab94f..0000000
--- a/scripts/run_spoofing.py
+++ /dev/null
@@ -1,201 +0,0 @@
-# Face Anti-Spoofing Detection
-# Usage:
-# Image: python run_spoofing.py --image path/to/image.jpg
-# Video: python run_spoofing.py --video path/to/video.mp4
-# Webcam: python run_spoofing.py --source 0
-
-import argparse
-import os
-from pathlib import Path
-
-import cv2
-import numpy as np
-
-from uniface import RetinaFace
-from uniface.constants import MiniFASNetWeights
-from uniface.spoofing import create_spoofer
-
-
-def draw_spoofing_result(
- image: np.ndarray,
- bbox: list,
- label_idx: int,
- score: float,
- thickness: int = 2,
-) -> None:
- """Draw bounding box with anti-spoofing result.
-
- Args:
- image: Input image to draw on.
- bbox: Bounding box in [x1, y1, x2, y2] format.
- label_idx: Prediction label index (0 = Fake, 1 = Real).
- score: Confidence score (0.0 to 1.0).
- thickness: Line thickness for bounding box.
- """
- x1, y1, x2, y2 = map(int, bbox[:4])
-
- # Color based on result (green for real, red for fake)
- is_real = label_idx == 1
- color = (0, 255, 0) if is_real else (0, 0, 255)
-
- # Draw bounding box
- cv2.rectangle(image, (x1, y1), (x2, y2), color, thickness)
-
- # Prepare label
- label = 'Real' if is_real else 'Fake'
- text = f'{label}: {score:.1%}'
-
- # Draw label background
- (tw, th), baseline = cv2.getTextSize(text, cv2.FONT_HERSHEY_SIMPLEX, 0.7, 2)
- cv2.rectangle(image, (x1, y1 - th - 10), (x1 + tw + 10, y1), color, -1)
-
- # Draw label text
- cv2.putText(image, text, (x1 + 5, y1 - 5), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (255, 255, 255), 2)
-
-
-def process_image(detector, spoofer, image_path: str, save_dir: str = 'outputs') -> None:
- """Process a single image for face anti-spoofing detection."""
- image = cv2.imread(image_path)
- if image is None:
- print(f"Error: Failed to load image from '{image_path}'")
- return
-
- # Detect faces
- faces = detector.detect(image)
- print(f'Detected {len(faces)} face(s)')
-
- if not faces:
- print('No faces detected in the image.')
- return
-
- # Run anti-spoofing on each face
- for i, face in enumerate(faces, 1):
- label_idx, score = spoofer.predict(image, face.bbox)
- # label_idx: 0 = Fake, 1 = Real
- label = 'Real' if label_idx == 1 else 'Fake'
- print(f' Face {i}: {label} ({score:.1%})')
-
- # Draw result on image
- draw_spoofing_result(image, face.bbox, label_idx, score)
-
- # Save output
- os.makedirs(save_dir, exist_ok=True)
- output_path = os.path.join(save_dir, f'{Path(image_path).stem}_spoofing.jpg')
- cv2.imwrite(output_path, image)
- print(f'Output saved: {output_path}')
-
-
-def process_video(detector, spoofer, source, save_dir: str = 'outputs') -> None:
- """Process video or webcam stream for face anti-spoofing detection."""
- # Handle webcam or video file
- if isinstance(source, int) or source.isdigit():
- cap = cv2.VideoCapture(int(source))
- is_webcam = True
- output_name = 'webcam_spoofing.mp4'
- else:
- cap = cv2.VideoCapture(source)
- is_webcam = False
- output_name = f'{Path(source).stem}_spoofing.mp4'
-
- if not cap.isOpened():
- print(f'Error: Failed to open video source: {source}')
- return
-
- # Get video properties
- fps = int(cap.get(cv2.CAP_PROP_FPS)) if not is_webcam else 30
- width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
- height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
-
- # Setup video writer
- os.makedirs(save_dir, exist_ok=True)
- output_path = os.path.join(save_dir, output_name)
- fourcc = cv2.VideoWriter_fourcc(*'mp4v')
- writer = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
-
- print("Processing video... Press 'q' to quit")
- frame_count = 0
-
- try:
- while cap.isOpened():
- ret, frame = cap.read()
- if not ret:
- break
-
- frame_count += 1
-
- # Detect faces
- faces = detector.detect(frame)
-
- # Run anti-spoofing on each face
- for face in faces:
- label_idx, score = spoofer.predict(frame, face.bbox)
- draw_spoofing_result(frame, face.bbox, label_idx, score)
-
- # Write frame
- writer.write(frame)
-
- # Display frame
- cv2.imshow('Face Anti-Spoofing', frame)
- if cv2.waitKey(1) & 0xFF == ord('q'):
- print('Stopped by user.')
- break
-
- finally:
- cap.release()
- writer.release()
- cv2.destroyAllWindows()
-
- print(f'Processed {frame_count} frames')
- if not is_webcam:
- print(f'Output saved: {output_path}')
-
-
-def main():
- parser = argparse.ArgumentParser(description='Face Anti-Spoofing Detection')
- parser.add_argument('--image', type=str, help='Path to input image')
- parser.add_argument('--video', type=str, help='Path to input video')
- parser.add_argument('--source', type=str, help='Video source (0 for webcam)')
- parser.add_argument(
- '--model',
- type=str,
- default='v2',
- choices=['v1se', 'v2'],
- help='Model variant: v1se or v2 (default: v2)',
- )
- parser.add_argument('--scale', type=float, default=None, help='Custom crop scale (default: auto)')
- parser.add_argument('--save_dir', type=str, default='outputs', help='Output directory')
- args = parser.parse_args()
-
- # Check that at least one input source is provided
- if not any([args.image, args.video, args.source]):
- parser.print_help()
- print('\nError: Please provide --image, --video, or --source')
- return
-
- # Select model variant
- model_name = MiniFASNetWeights.V1SE if args.model == 'v1se' else MiniFASNetWeights.V2
-
- # Initialize models
- print(f'Initializing models (MiniFASNet {args.model.upper()})...')
- detector = RetinaFace()
- spoofer = create_spoofer(model_name=model_name, scale=args.scale)
-
- # Process input
- if args.image:
- if not os.path.exists(args.image):
- print(f'Error: Image not found: {args.image}')
- return
- process_image(detector, spoofer, args.image, args.save_dir)
-
- elif args.video:
- if not os.path.exists(args.video):
- print(f'Error: Video not found: {args.video}')
- return
- process_video(detector, spoofer, args.video, args.save_dir)
-
- elif args.source:
- process_video(detector, spoofer, args.source, args.save_dir)
-
-
-if __name__ == '__main__':
- main()
diff --git a/scripts/run_video_detection.py b/scripts/run_video_detection.py
deleted file mode 100644
index 46e6528..0000000
--- a/scripts/run_video_detection.py
+++ /dev/null
@@ -1,109 +0,0 @@
-# Face detection on video files
-# Usage: python run_video_detection.py --input video.mp4 --output output.mp4
-
-import argparse
-from pathlib import Path
-
-import cv2
-from tqdm import tqdm
-
-from uniface import SCRFD, RetinaFace
-from uniface.visualization import draw_detections
-
-
-def process_video(
- detector,
- input_path: str,
- output_path: str,
- threshold: float = 0.6,
- show_preview: bool = False,
-):
- cap = cv2.VideoCapture(input_path)
- if not cap.isOpened():
- print(f"Error: Cannot open video file '{input_path}'")
- return
-
- # get video properties
- total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
- fps = cap.get(cv2.CAP_PROP_FPS)
- width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
- height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
-
- print(f'Input: {input_path} ({width}x{height}, {fps:.1f} fps, {total_frames} frames)')
- print(f'Output: {output_path}')
-
- fourcc = cv2.VideoWriter_fourcc(*'mp4v') # codec for .mp4
- out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
-
- if not out.isOpened():
- print(f"Error: Cannot create output video '{output_path}'")
- cap.release()
- return
-
- frame_count = 0
- total_faces = 0
-
- for _ in tqdm(range(total_frames), desc='Processing', unit='frames'):
- ret, frame = cap.read()
- if not ret:
- break
-
- frame_count += 1
- faces = detector.detect(frame)
- total_faces += len(faces)
-
- bboxes = [f.bbox for f in faces]
- scores = [f.confidence for f in faces]
- landmarks = [f.landmarks for f in faces]
- draw_detections(
- image=frame, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
- )
-
- cv2.putText(
- frame,
- f'Faces: {len(faces)}',
- (10, 30),
- cv2.FONT_HERSHEY_SIMPLEX,
- 1,
- (0, 255, 0),
- 2,
- )
- out.write(frame)
-
- if show_preview:
- cv2.imshow("Processing - Press 'q' to cancel", frame)
- if cv2.waitKey(1) & 0xFF == ord('q'):
- print('\nCancelled by user')
- break
-
- cap.release()
- out.release()
- if show_preview:
- cv2.destroyAllWindows()
-
- avg_faces = total_faces / frame_count if frame_count > 0 else 0
- print(f'\nDone! {frame_count} frames, {total_faces} faces ({avg_faces:.1f} avg/frame)')
- print(f'Saved: {output_path}')
-
-
-def main():
- parser = argparse.ArgumentParser(description='Process video with face detection')
- parser.add_argument('--input', type=str, required=True, help='Input video path')
- parser.add_argument('--output', type=str, required=True, help='Output video path')
- parser.add_argument('--detector', type=str, default='retinaface', choices=['retinaface', 'scrfd'])
- parser.add_argument('--threshold', type=float, default=0.6, help='Visualization threshold')
- parser.add_argument('--preview', action='store_true', help='Show live preview')
- args = parser.parse_args()
-
- if not Path(args.input).exists():
- print(f"Error: Input file '{args.input}' does not exist")
- return
-
- Path(args.output).parent.mkdir(parents=True, exist_ok=True)
-
- detector = RetinaFace() if args.detector == 'retinaface' else SCRFD()
- process_video(detector, args.input, args.output, args.threshold, args.preview)
-
-
-if __name__ == '__main__':
- main()
diff --git a/tests/test_types.py b/tests/test_types.py
new file mode 100644
index 0000000..97a06ca
--- /dev/null
+++ b/tests/test_types.py
@@ -0,0 +1,282 @@
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Tests for UniFace type definitions (dataclasses)."""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from uniface.types import AttributeResult, EmotionResult, Face, GazeResult, SpoofingResult
+
+
+class TestGazeResult:
+ """Tests for GazeResult dataclass."""
+
+ def test_creation(self):
+ result = GazeResult(pitch=0.1, yaw=-0.2)
+ assert result.pitch == 0.1
+ assert result.yaw == -0.2
+
+ def test_immutability(self):
+ result = GazeResult(pitch=0.1, yaw=-0.2)
+ with pytest.raises(AttributeError):
+ result.pitch = 0.5 # type: ignore
+
+ def test_repr(self):
+ result = GazeResult(pitch=0.1234, yaw=-0.5678)
+ repr_str = repr(result)
+ assert 'GazeResult' in repr_str
+ assert '0.1234' in repr_str
+ assert '-0.5678' in repr_str
+
+ def test_equality(self):
+ result1 = GazeResult(pitch=0.1, yaw=-0.2)
+ result2 = GazeResult(pitch=0.1, yaw=-0.2)
+ assert result1 == result2
+
+ def test_hashable(self):
+ """Frozen dataclasses should be hashable."""
+ result = GazeResult(pitch=0.1, yaw=-0.2)
+ # Should not raise
+ hash(result)
+ # Can be used in sets/dicts
+ result_set = {result}
+ assert result in result_set
+
+
+class TestSpoofingResult:
+ """Tests for SpoofingResult dataclass."""
+
+ def test_creation_real(self):
+ result = SpoofingResult(is_real=True, confidence=0.95)
+ assert result.is_real is True
+ assert result.confidence == 0.95
+
+ def test_creation_fake(self):
+ result = SpoofingResult(is_real=False, confidence=0.87)
+ assert result.is_real is False
+ assert result.confidence == 0.87
+
+ def test_immutability(self):
+ result = SpoofingResult(is_real=True, confidence=0.95)
+ with pytest.raises(AttributeError):
+ result.is_real = False # type: ignore
+
+ def test_repr_real(self):
+ result = SpoofingResult(is_real=True, confidence=0.9512)
+ repr_str = repr(result)
+ assert 'SpoofingResult' in repr_str
+ assert 'Real' in repr_str
+ assert '0.9512' in repr_str
+
+ def test_repr_fake(self):
+ result = SpoofingResult(is_real=False, confidence=0.8765)
+ repr_str = repr(result)
+ assert 'Fake' in repr_str
+
+ def test_hashable(self):
+ result = SpoofingResult(is_real=True, confidence=0.95)
+ hash(result)
+
+
+class TestEmotionResult:
+ """Tests for EmotionResult dataclass."""
+
+ def test_creation(self):
+ result = EmotionResult(emotion='Happy', confidence=0.92)
+ assert result.emotion == 'Happy'
+ assert result.confidence == 0.92
+
+ def test_immutability(self):
+ result = EmotionResult(emotion='Sad', confidence=0.75)
+ with pytest.raises(AttributeError):
+ result.emotion = 'Happy' # type: ignore
+
+ def test_repr(self):
+ result = EmotionResult(emotion='Angry', confidence=0.8123)
+ repr_str = repr(result)
+ assert 'EmotionResult' in repr_str
+ assert 'Angry' in repr_str
+ assert '0.8123' in repr_str
+
+ def test_various_emotions(self):
+ emotions = ['Neutral', 'Happy', 'Sad', 'Surprise', 'Fear', 'Disgust', 'Angry']
+ for emotion in emotions:
+ result = EmotionResult(emotion=emotion, confidence=0.5)
+ assert result.emotion == emotion
+
+ def test_hashable(self):
+ result = EmotionResult(emotion='Happy', confidence=0.92)
+ hash(result)
+
+
+class TestAttributeResult:
+ """Tests for AttributeResult dataclass."""
+
+ def test_age_gender_result(self):
+ result = AttributeResult(gender=1, age=25)
+ assert result.gender == 1
+ assert result.age == 25
+ assert result.age_group is None
+ assert result.race is None
+ assert result.sex == 'Male'
+
+ def test_fairface_result(self):
+ result = AttributeResult(gender=0, age_group='20-29', race='East Asian')
+ assert result.gender == 0
+ assert result.age is None
+ assert result.age_group == '20-29'
+ assert result.race == 'East Asian'
+ assert result.sex == 'Female'
+
+ def test_sex_property_female(self):
+ result = AttributeResult(gender=0)
+ assert result.sex == 'Female'
+
+ def test_sex_property_male(self):
+ result = AttributeResult(gender=1)
+ assert result.sex == 'Male'
+
+ def test_immutability(self):
+ result = AttributeResult(gender=1, age=30)
+ with pytest.raises(AttributeError):
+ result.age = 31 # type: ignore
+
+ def test_repr_age_gender(self):
+ result = AttributeResult(gender=1, age=25)
+ repr_str = repr(result)
+ assert 'AttributeResult' in repr_str
+ assert 'Male' in repr_str
+ assert 'age=25' in repr_str
+
+ def test_repr_fairface(self):
+ result = AttributeResult(gender=0, age_group='30-39', race='White')
+ repr_str = repr(result)
+ assert 'Female' in repr_str
+ assert 'age_group=30-39' in repr_str
+ assert 'race=White' in repr_str
+
+ def test_hashable(self):
+ result = AttributeResult(gender=1, age=25)
+ hash(result)
+
+
+class TestFace:
+ """Tests for Face dataclass."""
+
+ @pytest.fixture
+ def sample_face(self):
+ return Face(
+ bbox=np.array([100, 100, 200, 200]),
+ confidence=0.95,
+ landmarks=np.array([[120, 130], [180, 130], [150, 160], [130, 180], [170, 180]]),
+ )
+
+ def test_creation(self, sample_face):
+ assert sample_face.confidence == 0.95
+ assert sample_face.bbox.shape == (4,)
+ assert sample_face.landmarks.shape == (5, 2)
+
+ def test_optional_attributes_default_none(self, sample_face):
+ assert sample_face.embedding is None
+ assert sample_face.gender is None
+ assert sample_face.age is None
+ assert sample_face.age_group is None
+ assert sample_face.race is None
+ assert sample_face.emotion is None
+ assert sample_face.emotion_confidence is None
+
+ def test_mutability(self, sample_face):
+ """Face should be mutable for FaceAnalyzer enrichment."""
+ sample_face.gender = 1
+ sample_face.age = 25
+ sample_face.embedding = np.random.randn(512)
+
+ assert sample_face.gender == 1
+ assert sample_face.age == 25
+ assert sample_face.embedding.shape == (512,)
+
+ def test_sex_property_none(self, sample_face):
+ assert sample_face.sex is None
+
+ def test_sex_property_female(self, sample_face):
+ sample_face.gender = 0
+ assert sample_face.sex == 'Female'
+
+ def test_sex_property_male(self, sample_face):
+ sample_face.gender = 1
+ assert sample_face.sex == 'Male'
+
+ def test_bbox_xyxy(self, sample_face):
+ bbox_xyxy = sample_face.bbox_xyxy
+ np.testing.assert_array_equal(bbox_xyxy, [100, 100, 200, 200])
+
+ def test_bbox_xywh(self, sample_face):
+ bbox_xywh = sample_face.bbox_xywh
+ np.testing.assert_array_equal(bbox_xywh, [100, 100, 100, 100])
+
+ def test_to_dict(self, sample_face):
+ result = sample_face.to_dict()
+ assert isinstance(result, dict)
+ assert 'bbox' in result
+ assert 'confidence' in result
+ assert 'landmarks' in result
+
+ def test_repr_minimal(self, sample_face):
+ repr_str = repr(sample_face)
+ assert 'Face' in repr_str
+ assert 'confidence=0.950' in repr_str
+
+ def test_repr_with_attributes(self, sample_face):
+ sample_face.gender = 1
+ sample_face.age = 30
+ sample_face.emotion = 'Happy'
+
+ repr_str = repr(sample_face)
+ assert 'age=30' in repr_str
+ assert 'sex=Male' in repr_str
+ assert 'emotion=Happy' in repr_str
+
+ def test_compute_similarity_no_embeddings(self, sample_face):
+ other_face = Face(
+ bbox=np.array([50, 50, 150, 150]),
+ confidence=0.90,
+ landmarks=np.random.randn(5, 2),
+ )
+ with pytest.raises(ValueError, match='Both faces must have embeddings'):
+ sample_face.compute_similarity(other_face)
+
+ def test_compute_similarity_with_embeddings(self, sample_face):
+ # Create normalized embeddings
+ sample_face.embedding = np.random.randn(512)
+ sample_face.embedding /= np.linalg.norm(sample_face.embedding)
+
+ other_face = Face(
+ bbox=np.array([50, 50, 150, 150]),
+ confidence=0.90,
+ landmarks=np.random.randn(5, 2),
+ )
+ other_face.embedding = np.random.randn(512)
+ other_face.embedding /= np.linalg.norm(other_face.embedding)
+
+ similarity = sample_face.compute_similarity(other_face)
+ assert isinstance(similarity, float)
+ assert -1 <= similarity <= 1
+
+ def test_compute_similarity_same_embedding(self, sample_face):
+ embedding = np.random.randn(512)
+ embedding /= np.linalg.norm(embedding)
+ sample_face.embedding = embedding.copy()
+
+ other_face = Face(
+ bbox=np.array([50, 50, 150, 150]),
+ confidence=0.90,
+ landmarks=np.random.randn(5, 2),
+ embedding=embedding.copy(),
+ )
+
+ similarity = sample_face.compute_similarity(other_face)
+ assert similarity == pytest.approx(1.0, abs=1e-5)
diff --git a/tools/README.md b/tools/README.md
new file mode 100644
index 0000000..e17d060
--- /dev/null
+++ b/tools/README.md
@@ -0,0 +1,121 @@
+# Tools
+
+CLI utilities for testing and running UniFace features.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `detection.py` | Face detection on image, video, or webcam |
+| `face_anonymize.py` | Face anonymization/blurring for privacy |
+| `age_gender.py` | Age and gender prediction |
+| `face_emotion.py` | Emotion detection (7 or 8 emotions) |
+| `gaze_estimation.py` | Gaze direction estimation |
+| `landmarks.py` | 106-point facial landmark detection |
+| `recognition.py` | Face embedding extraction and comparison |
+| `face_analyzer.py` | Complete face analysis (detection + recognition + attributes) |
+| `face_search.py` | Real-time face matching against reference |
+| `fairface.py` | FairFace attribute prediction (race, gender, age) |
+| `spoofing.py` | Face anti-spoofing detection |
+| `face_parsing.py` | Face semantic segmentation |
+| `video_detection.py` | Face detection on video files with progress bar |
+| `batch_process.py` | Batch process folder of images |
+| `download_model.py` | Download model weights |
+| `sha256_generate.py` | Generate SHA256 hash for model files |
+
+## Unified `--source` Pattern
+
+All tools use a unified `--source` argument that accepts:
+- **Image path**: `--source photo.jpg`
+- **Video path**: `--source video.mp4`
+- **Camera ID**: `--source 0` (default webcam), `--source 1` (external camera)
+
+## Usage Examples
+
+```bash
+# Face detection
+python tools/detection.py --source assets/test.jpg # image
+python tools/detection.py --source video.mp4 # video
+python tools/detection.py --source 0 # webcam
+
+# Face anonymization
+python tools/face_anonymize.py --source assets/test.jpg --method pixelate
+python tools/face_anonymize.py --source video.mp4 --method gaussian
+python tools/face_anonymize.py --source 0 --method pixelate
+
+# Age and gender
+python tools/age_gender.py --source assets/test.jpg
+python tools/age_gender.py --source 0
+
+# Emotion detection
+python tools/face_emotion.py --source assets/test.jpg
+python tools/face_emotion.py --source 0
+
+# Gaze estimation
+python tools/gaze_estimation.py --source assets/test.jpg
+python tools/gaze_estimation.py --source 0
+
+# Landmarks
+python tools/landmarks.py --source assets/test.jpg
+python tools/landmarks.py --source 0
+
+# FairFace attributes
+python tools/fairface.py --source assets/test.jpg
+python tools/fairface.py --source 0
+
+# Face parsing
+python tools/face_parsing.py --source assets/test.jpg
+python tools/face_parsing.py --source 0
+
+# Face anti-spoofing
+python tools/spoofing.py --source assets/test.jpg
+python tools/spoofing.py --source 0
+
+# Face analyzer
+python tools/face_analyzer.py --source assets/test.jpg
+python tools/face_analyzer.py --source 0
+
+# Face recognition (extract embedding)
+python tools/recognition.py --image assets/test.jpg
+
+# Face comparison
+python tools/recognition.py --image1 face1.jpg --image2 face2.jpg
+
+# Face search (match against reference)
+python tools/face_search.py --reference person.jpg --source 0
+python tools/face_search.py --reference person.jpg --source video.mp4
+
+# Video processing with progress bar
+python tools/video_detection.py --source video.mp4
+python tools/video_detection.py --source video.mp4 --output output.mp4
+
+# Batch processing
+python tools/batch_process.py --input images/ --output results/
+
+# Download models
+python tools/download_model.py --model-type retinaface
+python tools/download_model.py # downloads all
+```
+
+## Common Options
+
+| Option | Description |
+|--------|-------------|
+| `--source` | Input source: image/video path or camera ID (0, 1, ...) |
+| `--detector` | Choose detector: `retinaface`, `scrfd`, `yolov5face` |
+| `--threshold` | Visualization confidence threshold (default: varies) |
+| `--save-dir` | Output directory (default: `outputs`) |
+
+## Supported Formats
+
+**Images:** `.jpg`, `.jpeg`, `.png`, `.bmp`, `.webp`, `.tiff`
+
+**Videos:** `.mp4`, `.avi`, `.mov`, `.mkv`, `.webm`, `.flv`
+
+**Camera:** Use integer IDs (`0`, `1`, `2`, ...)
+
+## Quick Test
+
+```bash
+python tools/detection.py --source assets/test.jpg
+```
diff --git a/tools/age_gender.py b/tools/age_gender.py
new file mode 100644
index 0000000..ab634c6
--- /dev/null
+++ b/tools/age_gender.py
@@ -0,0 +1,213 @@
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Age and gender prediction on detected faces.
+
+Usage:
+ python tools/age_gender.py --source path/to/image.jpg
+ python tools/age_gender.py --source path/to/video.mp4
+ python tools/age_gender.py --source 0 # webcam
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+import cv2
+
+from uniface import SCRFD, AgeGender, RetinaFace
+from uniface.visualization import draw_detections
+
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.webp', '.tiff'}
+VIDEO_EXTENSIONS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv'}
+
+
+def get_source_type(source: str) -> str:
+ """Determine if source is image, video, or camera."""
+ if source.isdigit():
+ return 'camera'
+ path = Path(source)
+ suffix = path.suffix.lower()
+ if suffix in IMAGE_EXTENSIONS:
+ return 'image'
+ elif suffix in VIDEO_EXTENSIONS:
+ return 'video'
+ else:
+ return 'unknown'
+
+
+def draw_age_gender_label(image, bbox, sex: str, age: int):
+ """Draw age/gender label above the bounding box."""
+ x1, y1 = int(bbox[0]), int(bbox[1])
+ text = f'{sex}, {age}y'
+ (tw, th), _ = cv2.getTextSize(text, cv2.FONT_HERSHEY_SIMPLEX, 0.6, 2)
+ cv2.rectangle(image, (x1, y1 - th - 10), (x1 + tw + 10, y1), (0, 255, 0), -1)
+ cv2.putText(image, text, (x1 + 5, y1 - 5), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 0, 0), 2)
+
+
+def process_image(
+ detector,
+ age_gender,
+ image_path: str,
+ save_dir: str = 'outputs',
+ threshold: float = 0.6,
+):
+ """Process a single image."""
+ image = cv2.imread(image_path)
+ if image is None:
+ print(f"Error: Failed to load image from '{image_path}'")
+ return
+
+ faces = detector.detect(image)
+ print(f'Detected {len(faces)} face(s)')
+
+ if not faces:
+ return
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(
+ image=image, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
+ )
+
+ for i, face in enumerate(faces):
+ result = age_gender.predict(image, face.bbox)
+ print(f' Face {i + 1}: {result.sex}, {result.age} years old')
+ draw_age_gender_label(image, face.bbox, result.sex, result.age)
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(image_path).stem}_age_gender.jpg')
+ cv2.imwrite(output_path, image)
+ print(f'Output saved: {output_path}')
+
+
+def process_video(
+ detector,
+ age_gender,
+ video_path: str,
+ save_dir: str = 'outputs',
+ threshold: float = 0.6,
+):
+ """Process a video file."""
+ cap = cv2.VideoCapture(video_path)
+ if not cap.isOpened():
+ print(f"Error: Cannot open video file '{video_path}'")
+ return
+
+ fps = cap.get(cv2.CAP_PROP_FPS)
+ width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+ height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+ total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(video_path).stem}_age_gender.mp4')
+ fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+ out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+ print(f'Processing video: {video_path} ({total_frames} frames)')
+ frame_count = 0
+
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame_count += 1
+ faces = detector.detect(frame)
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(
+ image=frame, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
+ )
+
+ for face in faces:
+ result = age_gender.predict(frame, face.bbox)
+ draw_age_gender_label(frame, face.bbox, result.sex, result.age)
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ out.write(frame)
+
+ if frame_count % 100 == 0:
+ print(f' Processed {frame_count}/{total_frames} frames...')
+
+ cap.release()
+ out.release()
+ print(f'Done! Output saved: {output_path}')
+
+
+def run_camera(detector, age_gender, camera_id: int = 0, threshold: float = 0.6):
+ """Run real-time detection on webcam."""
+ cap = cv2.VideoCapture(camera_id)
+ if not cap.isOpened():
+ print(f'Cannot open camera {camera_id}')
+ return
+
+ print("Press 'q' to quit")
+
+ while True:
+ ret, frame = cap.read()
+ frame = cv2.flip(frame, 1)
+ if not ret:
+ break
+
+ faces = detector.detect(frame)
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(
+ image=frame, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
+ )
+
+ for face in faces:
+ result = age_gender.predict(frame, face.bbox)
+ draw_age_gender_label(frame, face.bbox, result.sex, result.age)
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ cv2.imshow('Age & Gender Detection', frame)
+
+ if cv2.waitKey(1) & 0xFF == ord('q'):
+ break
+
+ cap.release()
+ cv2.destroyAllWindows()
+
+
+def main():
+ parser = argparse.ArgumentParser(description='Run age and gender detection')
+ parser.add_argument('--source', type=str, required=True, help='Image/video path or camera ID (0, 1, ...)')
+ parser.add_argument('--detector', type=str, default='retinaface', choices=['retinaface', 'scrfd'])
+ parser.add_argument('--threshold', type=float, default=0.6, help='Visualization threshold')
+ parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
+ args = parser.parse_args()
+
+ detector = RetinaFace() if args.detector == 'retinaface' else SCRFD()
+ age_gender = AgeGender()
+
+ source_type = get_source_type(args.source)
+
+ if source_type == 'camera':
+ run_camera(detector, age_gender, int(args.source), args.threshold)
+ elif source_type == 'image':
+ if not os.path.exists(args.source):
+ print(f'Error: Image not found: {args.source}')
+ return
+ process_image(detector, age_gender, args.source, args.save_dir, args.threshold)
+ elif source_type == 'video':
+ if not os.path.exists(args.source):
+ print(f'Error: Video not found: {args.source}')
+ return
+ process_video(detector, age_gender, args.source, args.save_dir, args.threshold)
+ else:
+ print(f"Error: Unknown source type for '{args.source}'")
+ print('Supported formats: images (.jpg, .png, ...), videos (.mp4, .avi, ...), or camera ID (0, 1, ...)')
+
+
+if __name__ == '__main__':
+ main()
diff --git a/scripts/batch_process.py b/tools/batch_process.py
similarity index 92%
rename from scripts/batch_process.py
rename to tools/batch_process.py
index ba21642..140a351 100644
--- a/scripts/batch_process.py
+++ b/tools/batch_process.py
@@ -1,5 +1,12 @@
-# Batch face detection on a folder of images
-# Usage: python batch_process.py --input images/ --output results/
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Batch face detection on a folder of images.
+
+Usage:
+ python tools/batch_process.py --input images/ --output results/
+"""
import argparse
from pathlib import Path
diff --git a/tools/detection.py b/tools/detection.py
new file mode 100644
index 0000000..1b0465d
--- /dev/null
+++ b/tools/detection.py
@@ -0,0 +1,196 @@
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Face detection on image, video, or webcam.
+
+Usage:
+ python tools/detection.py --source path/to/image.jpg
+ python tools/detection.py --source path/to/video.mp4
+ python tools/detection.py --source 0 # webcam
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+import cv2
+
+from uniface.detection import SCRFD, RetinaFace, YOLOv5Face
+from uniface.visualization import draw_detections
+
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.webp', '.tiff'}
+VIDEO_EXTENSIONS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv'}
+
+
+def get_source_type(source: str) -> str:
+ """Determine if source is image, video, or camera."""
+ if source.isdigit():
+ return 'camera'
+ path = Path(source)
+ suffix = path.suffix.lower()
+ if suffix in IMAGE_EXTENSIONS:
+ return 'image'
+ elif suffix in VIDEO_EXTENSIONS:
+ return 'video'
+ else:
+ return 'unknown'
+
+
+def process_image(detector, image_path: str, threshold: float = 0.6, save_dir: str = 'outputs'):
+ """Process a single image."""
+ image = cv2.imread(image_path)
+ if image is None:
+ print(f"Error: Failed to load image from '{image_path}'")
+ return
+
+ faces = detector.detect(image)
+
+ if faces:
+ bboxes = [face.bbox for face in faces]
+ scores = [face.confidence for face in faces]
+ landmarks = [face.landmarks for face in faces]
+ draw_detections(image, bboxes, scores, landmarks, vis_threshold=threshold)
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{os.path.splitext(os.path.basename(image_path))[0]}_out.jpg')
+ cv2.imwrite(output_path, image)
+ print(f'Detected {len(faces)} face(s). Output saved: {output_path}')
+
+
+def process_video(detector, video_path: str, threshold: float = 0.6, save_dir: str = 'outputs'):
+ """Process a video file."""
+ cap = cv2.VideoCapture(video_path)
+ if not cap.isOpened():
+ print(f"Error: Cannot open video file '{video_path}'")
+ return
+
+ # Get video properties
+ fps = cap.get(cv2.CAP_PROP_FPS)
+ width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+ height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+ total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(video_path).stem}_out.mp4')
+ fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+ out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+ print(f'Processing video: {video_path} ({total_frames} frames)')
+ frame_count = 0
+
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame_count += 1
+ faces = detector.detect(frame)
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(
+ image=frame,
+ bboxes=bboxes,
+ scores=scores,
+ landmarks=landmarks,
+ vis_threshold=threshold,
+ draw_score=True,
+ fancy_bbox=True,
+ )
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ out.write(frame)
+
+ # Show progress
+ if frame_count % 100 == 0:
+ print(f' Processed {frame_count}/{total_frames} frames...')
+
+ cap.release()
+ out.release()
+ print(f'Done! Output saved: {output_path}')
+
+
+def run_camera(detector, camera_id: int = 0, threshold: float = 0.6):
+ """Run real-time detection on webcam."""
+ cap = cv2.VideoCapture(camera_id)
+ if not cap.isOpened():
+ print(f'Cannot open camera {camera_id}')
+ return
+
+ print("Press 'q' to quit")
+
+ while True:
+ ret, frame = cap.read()
+ frame = cv2.flip(frame, 1) # mirror for natural interaction
+ if not ret:
+ break
+
+ faces = detector.detect(frame)
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(
+ image=frame,
+ bboxes=bboxes,
+ scores=scores,
+ landmarks=landmarks,
+ vis_threshold=threshold,
+ draw_score=True,
+ fancy_bbox=True,
+ )
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ cv2.imshow('Face Detection', frame)
+
+ if cv2.waitKey(1) & 0xFF == ord('q'):
+ break
+
+ cap.release()
+ cv2.destroyAllWindows()
+
+
+def main():
+ parser = argparse.ArgumentParser(description='Run face detection')
+ parser.add_argument('--source', type=str, required=True, help='Image/video path or camera ID (0, 1, ...)')
+ parser.add_argument('--method', type=str, default='retinaface', choices=['retinaface', 'scrfd', 'yolov5face'])
+ parser.add_argument('--threshold', type=float, default=0.25, help='Visualization threshold')
+ parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
+ args = parser.parse_args()
+
+ # Initialize detector
+ if args.method == 'retinaface':
+ detector = RetinaFace()
+ elif args.method == 'scrfd':
+ detector = SCRFD()
+ else:
+ from uniface.constants import YOLOv5FaceWeights
+
+ detector = YOLOv5Face(model_name=YOLOv5FaceWeights.YOLOV5M)
+
+ # Determine source type and process
+ source_type = get_source_type(args.source)
+
+ if source_type == 'camera':
+ run_camera(detector, int(args.source), args.threshold)
+ elif source_type == 'image':
+ if not os.path.exists(args.source):
+ print(f'Error: Image not found: {args.source}')
+ return
+ process_image(detector, args.source, args.threshold, args.save_dir)
+ elif source_type == 'video':
+ if not os.path.exists(args.source):
+ print(f'Error: Video not found: {args.source}')
+ return
+ process_video(detector, args.source, args.threshold, args.save_dir)
+ else:
+ print(f"Error: Unknown source type for '{args.source}'")
+ print('Supported formats: images (.jpg, .png, ...), videos (.mp4, .avi, ...), or camera ID (0, 1, ...)')
+
+
+if __name__ == '__main__':
+ main()
diff --git a/scripts/download_model.py b/tools/download_model.py
similarity index 100%
rename from scripts/download_model.py
rename to tools/download_model.py
diff --git a/tools/face_analyzer.py b/tools/face_analyzer.py
new file mode 100644
index 0000000..fa03836
--- /dev/null
+++ b/tools/face_analyzer.py
@@ -0,0 +1,239 @@
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Face analysis using FaceAnalyzer.
+
+Usage:
+ python tools/face_analyzer.py --source path/to/image.jpg
+ python tools/face_analyzer.py --source path/to/video.mp4
+ python tools/face_analyzer.py --source 0 # webcam
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+from uniface import AgeGender, ArcFace, FaceAnalyzer, RetinaFace
+from uniface.visualization import draw_detections
+
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.webp', '.tiff'}
+VIDEO_EXTENSIONS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv'}
+
+
+def get_source_type(source: str) -> str:
+ """Determine if source is image, video, or camera."""
+ if source.isdigit():
+ return 'camera'
+ path = Path(source)
+ suffix = path.suffix.lower()
+ if suffix in IMAGE_EXTENSIONS:
+ return 'image'
+ elif suffix in VIDEO_EXTENSIONS:
+ return 'video'
+ else:
+ return 'unknown'
+
+
+def draw_face_info(image, face, face_id):
+ """Draw face ID and attributes above bounding box."""
+ x1, y1, _x2, y2 = map(int, face.bbox)
+ lines = [f'ID: {face_id}', f'Conf: {face.confidence:.2f}']
+ if face.age and face.sex:
+ lines.append(f'{face.sex}, {face.age}y')
+
+ for i, line in enumerate(lines):
+ y_pos = y1 - 10 - (len(lines) - 1 - i) * 25
+ if y_pos < 20:
+ y_pos = y2 + 20 + i * 25
+ (tw, th), _ = cv2.getTextSize(line, cv2.FONT_HERSHEY_SIMPLEX, 0.6, 2)
+ cv2.rectangle(image, (x1, y_pos - th - 5), (x1 + tw + 10, y_pos + 5), (0, 255, 0), -1)
+ cv2.putText(image, line, (x1 + 5, y_pos), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 0, 0), 2)
+
+
+def process_image(analyzer, image_path: str, save_dir: str = 'outputs', show_similarity: bool = True):
+ """Process a single image."""
+ image = cv2.imread(image_path)
+ if image is None:
+ print(f"Error: Failed to load image from '{image_path}'")
+ return
+
+ faces = analyzer.analyze(image)
+ print(f'Detected {len(faces)} face(s)')
+
+ if not faces:
+ return
+
+ for i, face in enumerate(faces, 1):
+ info = f' Face {i}: {face.sex}, {face.age}y' if face.age and face.sex else f' Face {i}'
+ if face.embedding is not None:
+ info += f' (embedding: {face.embedding.shape})'
+ print(info)
+
+ if show_similarity and len(faces) >= 2:
+ print('\nSimilarity Matrix:')
+ n = len(faces)
+ sim_matrix = np.zeros((n, n))
+
+ for i in range(n):
+ for j in range(i, n):
+ if i == j:
+ sim_matrix[i][j] = 1.0
+ else:
+ sim = faces[i].compute_similarity(faces[j])
+ sim_matrix[i][j] = sim
+ sim_matrix[j][i] = sim
+
+ print(' ', end='')
+ for i in range(n):
+ print(f' F{i + 1:2d} ', end='')
+ print('\n ' + '-' * (7 * n))
+
+ for i in range(n):
+ print(f'F{i + 1:2d} | ', end='')
+ for j in range(n):
+ print(f'{sim_matrix[i][j]:6.3f} ', end='')
+ print()
+
+ pairs = [(i, j, sim_matrix[i][j]) for i in range(n) for j in range(i + 1, n)]
+ pairs.sort(key=lambda x: x[2], reverse=True)
+
+ print('\nTop matches (>0.4 = same person):')
+ for i, j, sim in pairs[:3]:
+ status = 'Same' if sim > 0.4 else 'Different'
+ print(f' Face {i + 1} ↔ Face {j + 1}: {sim:.3f} ({status})')
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(image=image, bboxes=bboxes, scores=scores, landmarks=landmarks, fancy_bbox=True)
+
+ for i, face in enumerate(faces, 1):
+ draw_face_info(image, face, i)
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(image_path).stem}_analysis.jpg')
+ cv2.imwrite(output_path, image)
+ print(f'Output saved: {output_path}')
+
+
+def process_video(analyzer, video_path: str, save_dir: str = 'outputs'):
+ """Process a video file."""
+ cap = cv2.VideoCapture(video_path)
+ if not cap.isOpened():
+ print(f"Error: Cannot open video file '{video_path}'")
+ return
+
+ fps = cap.get(cv2.CAP_PROP_FPS)
+ width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+ height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+ total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(video_path).stem}_analysis.mp4')
+ fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+ out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+ print(f'Processing video: {video_path} ({total_frames} frames)')
+ frame_count = 0
+
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame_count += 1
+ faces = analyzer.analyze(frame)
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(image=frame, bboxes=bboxes, scores=scores, landmarks=landmarks, fancy_bbox=True)
+
+ for i, face in enumerate(faces, 1):
+ draw_face_info(frame, face, i)
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ out.write(frame)
+
+ if frame_count % 100 == 0:
+ print(f' Processed {frame_count}/{total_frames} frames...')
+
+ cap.release()
+ out.release()
+ print(f'Done! Output saved: {output_path}')
+
+
+def run_camera(analyzer, camera_id: int = 0):
+ """Run real-time analysis on webcam."""
+ cap = cv2.VideoCapture(camera_id)
+ if not cap.isOpened():
+ print(f'Cannot open camera {camera_id}')
+ return
+
+ print("Press 'q' to quit")
+
+ while True:
+ ret, frame = cap.read()
+ frame = cv2.flip(frame, 1)
+ if not ret:
+ break
+
+ faces = analyzer.analyze(frame)
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(image=frame, bboxes=bboxes, scores=scores, landmarks=landmarks, fancy_bbox=True)
+
+ for i, face in enumerate(faces, 1):
+ draw_face_info(frame, face, i)
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ cv2.imshow('Face Analyzer', frame)
+
+ if cv2.waitKey(1) & 0xFF == ord('q'):
+ break
+
+ cap.release()
+ cv2.destroyAllWindows()
+
+
+def main():
+ parser = argparse.ArgumentParser(description='Face analysis with detection, recognition, and attributes')
+ parser.add_argument('--source', type=str, required=True, help='Image/video path or camera ID (0, 1, ...)')
+ parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
+ parser.add_argument('--no-similarity', action='store_true', help='Skip similarity matrix computation')
+ args = parser.parse_args()
+
+ detector = RetinaFace()
+ recognizer = ArcFace()
+ age_gender = AgeGender()
+ analyzer = FaceAnalyzer(detector, recognizer, age_gender)
+
+ source_type = get_source_type(args.source)
+
+ if source_type == 'camera':
+ run_camera(analyzer, int(args.source))
+ elif source_type == 'image':
+ if not os.path.exists(args.source):
+ print(f'Error: Image not found: {args.source}')
+ return
+ process_image(analyzer, args.source, args.save_dir, show_similarity=not args.no_similarity)
+ elif source_type == 'video':
+ if not os.path.exists(args.source):
+ print(f'Error: Video not found: {args.source}')
+ return
+ process_video(analyzer, args.source, args.save_dir)
+ else:
+ print(f"Error: Unknown source type for '{args.source}'")
+ print('Supported formats: images (.jpg, .png, ...), videos (.mp4, .avi, ...), or camera ID (0, 1, ...)')
+
+
+if __name__ == '__main__':
+ main()
diff --git a/scripts/run_anonymization.py b/tools/face_anonymize.py
similarity index 54%
rename from scripts/run_anonymization.py
rename to tools/face_anonymize.py
index 4640388..a413569 100644
--- a/scripts/run_anonymization.py
+++ b/tools/face_anonymize.py
@@ -1,15 +1,43 @@
-# Face anonymization/blurring for privacy
-# Usage: python run_anonymization.py --image path/to/image.jpg --method pixelate
-# python run_anonymization.py --webcam --method gaussian
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Face anonymization/blurring for privacy.
+
+Usage:
+ python tools/face_anonymize.py --source path/to/image.jpg --method pixelate
+ python tools/face_anonymize.py --source path/to/video.mp4 --method gaussian
+ python tools/face_anonymize.py --source 0 --method pixelate # webcam
+"""
+
+from __future__ import annotations
import argparse
import os
+from pathlib import Path
import cv2
from uniface import RetinaFace
from uniface.privacy import BlurFace
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.webp', '.tiff'}
+VIDEO_EXTENSIONS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv'}
+
+
+def get_source_type(source: str) -> str:
+ """Determine if source is image, video, or camera."""
+ if source.isdigit():
+ return 'camera'
+ path = Path(source)
+ suffix = path.suffix.lower()
+ if suffix in IMAGE_EXTENSIONS:
+ return 'image'
+ elif suffix in VIDEO_EXTENSIONS:
+ return 'video'
+ else:
+ return 'unknown'
+
def process_image(
detector,
@@ -24,11 +52,9 @@ def process_image(
print(f"Error: Failed to load image from '{image_path}'")
return
- # Detect faces
faces = detector.detect(image)
print(f'Detected {len(faces)} face(s)')
- # Optionally draw detection boxes before blurring
if show_detections and faces:
from uniface.visualization import draw_detections
@@ -38,18 +64,15 @@ def process_image(
landmarks = [face.landmarks for face in faces]
draw_detections(preview, bboxes, scores, landmarks)
- # Show preview
cv2.imshow('Detections (Press any key to continue)', preview)
cv2.waitKey(0)
cv2.destroyAllWindows()
- # Anonymize faces
if faces:
anonymized = blurrer.anonymize(image, faces)
else:
anonymized = image
- # Save output
os.makedirs(save_dir, exist_ok=True)
basename = os.path.splitext(os.path.basename(image_path))[0]
output_path = os.path.join(save_dir, f'{basename}_anonymized.jpg')
@@ -57,27 +80,71 @@ def process_image(
print(f'Output saved: {output_path}')
-def run_webcam(detector, blurrer: BlurFace):
+def process_video(
+ detector,
+ blurrer: BlurFace,
+ video_path: str,
+ save_dir: str = 'outputs',
+):
+ """Process a video file."""
+ cap = cv2.VideoCapture(video_path)
+ if not cap.isOpened():
+ print(f"Error: Cannot open video file '{video_path}'")
+ return
+
+ fps = cap.get(cv2.CAP_PROP_FPS)
+ width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+ height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+ total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(video_path).stem}_anonymized.mp4')
+ fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+ out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+ print(f'Processing video: {video_path} ({total_frames} frames)')
+ frame_count = 0
+
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame_count += 1
+ faces = detector.detect(frame)
+
+ if faces:
+ frame = blurrer.anonymize(frame, faces, inplace=True)
+
+ out.write(frame)
+
+ if frame_count % 100 == 0:
+ print(f' Processed {frame_count}/{total_frames} frames...')
+
+ cap.release()
+ out.release()
+ print(f'Done! Output saved: {output_path}')
+
+
+def run_camera(detector, blurrer: BlurFace, camera_id: int = 0):
"""Run real-time anonymization on webcam."""
- cap = cv2.VideoCapture(0)
+ cap = cv2.VideoCapture(camera_id)
if not cap.isOpened():
- print('Cannot open webcam')
+ print(f'Cannot open camera {camera_id}')
return
print("Press 'q' to quit")
while True:
ret, frame = cap.read()
- frame = cv2.flip(frame, 1) # mirror for natural interaction
+ frame = cv2.flip(frame, 1)
if not ret:
break
- # Detect and anonymize
faces = detector.detect(frame)
if faces:
frame = blurrer.anonymize(frame, faces, inplace=True)
- # Display info
cv2.putText(
frame,
f'Faces blurred: {len(faces)} | Method: {blurrer.method}',
@@ -104,26 +171,25 @@ def main():
epilog="""
Examples:
# Anonymize image with pixelation (default)
- python run_anonymization.py --image photo.jpg
+ python run_anonymization.py --source photo.jpg
# Use Gaussian blur with custom strength
- python run_anonymization.py --image photo.jpg --method gaussian --blur-strength 5.0
+ python run_anonymization.py --source photo.jpg --method gaussian --blur-strength 5.0
# Real-time webcam anonymization
- python run_anonymization.py --webcam --method pixelate
+ python run_anonymization.py --source 0 --method pixelate
# Black boxes for maximum privacy
- python run_anonymization.py --image photo.jpg --method blackout
+ python run_anonymization.py --source photo.jpg --method blackout
# Custom pixelation intensity
- python run_anonymization.py --image photo.jpg --method pixelate --pixel-blocks 5
+ python run_anonymization.py --source photo.jpg --method pixelate --pixel-blocks 5
""",
)
# Input/output
- parser.add_argument('--image', type=str, help='Path to input image')
- parser.add_argument('--webcam', action='store_true', help='Use webcam for real-time anonymization')
- parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory (default: outputs)')
+ parser.add_argument('--source', type=str, required=True, help='Image/video path or camera ID (0, 1, ...)')
+ parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
# Blur method
parser.add_argument(
@@ -145,7 +211,7 @@ Examples:
'--pixel-blocks',
type=int,
default=20,
- help='Number of pixel blocks for pixelate (default: 10, lower=more pixelated)',
+ help='Number of pixel blocks for pixelate (default: 20, lower=more pixelated)',
)
parser.add_argument(
'--color',
@@ -172,10 +238,6 @@ Examples:
args = parser.parse_args()
- # Validate input
- if not args.image and not args.webcam:
- parser.error('Either --image or --webcam must be specified')
-
# Parse color
color_values = [int(x) for x in args.color.split(',')]
if len(color_values) != 3:
@@ -196,11 +258,23 @@ Examples:
margin=args.margin,
)
- # Run
- if args.webcam:
- run_webcam(detector, blurrer)
+ source_type = get_source_type(args.source)
+
+ if source_type == 'camera':
+ run_camera(detector, blurrer, int(args.source))
+ elif source_type == 'image':
+ if not os.path.exists(args.source):
+ print(f'Error: Image not found: {args.source}')
+ return
+ process_image(detector, blurrer, args.source, args.save_dir, args.show_detections)
+ elif source_type == 'video':
+ if not os.path.exists(args.source):
+ print(f'Error: Video not found: {args.source}')
+ return
+ process_video(detector, blurrer, args.source, args.save_dir)
else:
- process_image(detector, blurrer, args.image, args.save_dir, args.show_detections)
+ print(f"Error: Unknown source type for '{args.source}'")
+ print('Supported formats: images (.jpg, .png, ...), videos (.mp4, .avi, ...), or camera ID (0, 1, ...)')
if __name__ == '__main__':
diff --git a/tools/face_emotion.py b/tools/face_emotion.py
new file mode 100644
index 0000000..68997a4
--- /dev/null
+++ b/tools/face_emotion.py
@@ -0,0 +1,213 @@
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Emotion detection on detected faces.
+
+Usage:
+ python tools/face_emotion.py --source path/to/image.jpg
+ python tools/face_emotion.py --source path/to/video.mp4
+ python tools/face_emotion.py --source 0 # webcam
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+import cv2
+
+from uniface import SCRFD, Emotion, RetinaFace
+from uniface.visualization import draw_detections
+
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.webp', '.tiff'}
+VIDEO_EXTENSIONS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv'}
+
+
+def get_source_type(source: str) -> str:
+ """Determine if source is image, video, or camera."""
+ if source.isdigit():
+ return 'camera'
+ path = Path(source)
+ suffix = path.suffix.lower()
+ if suffix in IMAGE_EXTENSIONS:
+ return 'image'
+ elif suffix in VIDEO_EXTENSIONS:
+ return 'video'
+ else:
+ return 'unknown'
+
+
+def draw_emotion_label(image, bbox, emotion: str, confidence: float):
+ """Draw emotion label above the bounding box."""
+ x1, y1 = int(bbox[0]), int(bbox[1])
+ text = f'{emotion} ({confidence:.2f})'
+ (tw, th), _ = cv2.getTextSize(text, cv2.FONT_HERSHEY_SIMPLEX, 0.6, 2)
+ cv2.rectangle(image, (x1, y1 - th - 10), (x1 + tw + 10, y1), (255, 0, 0), -1)
+ cv2.putText(image, text, (x1 + 5, y1 - 5), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 255, 255), 2)
+
+
+def process_image(
+ detector,
+ emotion_predictor,
+ image_path: str,
+ save_dir: str = 'outputs',
+ threshold: float = 0.6,
+):
+ """Process a single image."""
+ image = cv2.imread(image_path)
+ if image is None:
+ print(f"Error: Failed to load image from '{image_path}'")
+ return
+
+ faces = detector.detect(image)
+ print(f'Detected {len(faces)} face(s)')
+
+ if not faces:
+ return
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(
+ image=image, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
+ )
+
+ for i, face in enumerate(faces):
+ result = emotion_predictor.predict(image, face.landmarks)
+ print(f' Face {i + 1}: {result.emotion} (confidence: {result.confidence:.3f})')
+ draw_emotion_label(image, face.bbox, result.emotion, result.confidence)
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(image_path).stem}_emotion.jpg')
+ cv2.imwrite(output_path, image)
+ print(f'Output saved: {output_path}')
+
+
+def process_video(
+ detector,
+ emotion_predictor,
+ video_path: str,
+ save_dir: str = 'outputs',
+ threshold: float = 0.6,
+):
+ """Process a video file."""
+ cap = cv2.VideoCapture(video_path)
+ if not cap.isOpened():
+ print(f"Error: Cannot open video file '{video_path}'")
+ return
+
+ fps = cap.get(cv2.CAP_PROP_FPS)
+ width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+ height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+ total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(video_path).stem}_emotion.mp4')
+ fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+ out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+ print(f'Processing video: {video_path} ({total_frames} frames)')
+ frame_count = 0
+
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame_count += 1
+ faces = detector.detect(frame)
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(
+ image=frame, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
+ )
+
+ for face in faces:
+ result = emotion_predictor.predict(frame, face.landmarks)
+ draw_emotion_label(frame, face.bbox, result.emotion, result.confidence)
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ out.write(frame)
+
+ if frame_count % 100 == 0:
+ print(f' Processed {frame_count}/{total_frames} frames...')
+
+ cap.release()
+ out.release()
+ print(f'Done! Output saved: {output_path}')
+
+
+def run_camera(detector, emotion_predictor, camera_id: int = 0, threshold: float = 0.6):
+ """Run real-time detection on webcam."""
+ cap = cv2.VideoCapture(camera_id)
+ if not cap.isOpened():
+ print(f'Cannot open camera {camera_id}')
+ return
+
+ print("Press 'q' to quit")
+
+ while True:
+ ret, frame = cap.read()
+ frame = cv2.flip(frame, 1)
+ if not ret:
+ break
+
+ faces = detector.detect(frame)
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(
+ image=frame, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
+ )
+
+ for face in faces:
+ result = emotion_predictor.predict(frame, face.landmarks)
+ draw_emotion_label(frame, face.bbox, result.emotion, result.confidence)
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ cv2.imshow('Emotion Detection', frame)
+
+ if cv2.waitKey(1) & 0xFF == ord('q'):
+ break
+
+ cap.release()
+ cv2.destroyAllWindows()
+
+
+def main():
+ parser = argparse.ArgumentParser(description='Run emotion detection')
+ parser.add_argument('--source', type=str, required=True, help='Image/video path or camera ID (0, 1, ...)')
+ parser.add_argument('--detector', type=str, default='retinaface', choices=['retinaface', 'scrfd'])
+ parser.add_argument('--threshold', type=float, default=0.6, help='Visualization threshold')
+ parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
+ args = parser.parse_args()
+
+ detector = RetinaFace() if args.detector == 'retinaface' else SCRFD()
+ emotion_predictor = Emotion()
+
+ source_type = get_source_type(args.source)
+
+ if source_type == 'camera':
+ run_camera(detector, emotion_predictor, int(args.source), args.threshold)
+ elif source_type == 'image':
+ if not os.path.exists(args.source):
+ print(f'Error: Image not found: {args.source}')
+ return
+ process_image(detector, emotion_predictor, args.source, args.save_dir, args.threshold)
+ elif source_type == 'video':
+ if not os.path.exists(args.source):
+ print(f'Error: Video not found: {args.source}')
+ return
+ process_video(detector, emotion_predictor, args.source, args.save_dir, args.threshold)
+ else:
+ print(f"Error: Unknown source type for '{args.source}'")
+ print('Supported formats: images (.jpg, .png, ...), videos (.mp4, .avi, ...), or camera ID (0, 1, ...)')
+
+
+if __name__ == '__main__':
+ main()
diff --git a/scripts/run_face_parsing.py b/tools/face_parsing.py
similarity index 52%
rename from scripts/run_face_parsing.py
rename to tools/face_parsing.py
index 3d20316..799bc9d 100644
--- a/scripts/run_face_parsing.py
+++ b/tools/face_parsing.py
@@ -1,6 +1,16 @@
-# Face parsing on detected faces
-# Usage: python run_face_parsing.py --image path/to/image.jpg
-# python run_face_parsing.py --webcam
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Face parsing on detected faces.
+
+Usage:
+ python tools/face_parsing.py --source path/to/image.jpg
+ python tools/face_parsing.py --source path/to/video.mp4
+ python tools/face_parsing.py --source 0 # webcam
+"""
+
+from __future__ import annotations
import argparse
import os
@@ -14,6 +24,23 @@ from uniface.constants import ParsingWeights
from uniface.parsing import BiSeNet
from uniface.visualization import vis_parsing_maps
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.webp', '.tiff'}
+VIDEO_EXTENSIONS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv'}
+
+
+def get_source_type(source: str) -> str:
+ """Determine if source is image, video, or camera."""
+ if source.isdigit():
+ return 'camera'
+ path = Path(source)
+ suffix = path.suffix.lower()
+ if suffix in IMAGE_EXTENSIONS:
+ return 'image'
+ elif suffix in VIDEO_EXTENSIONS:
+ return 'video'
+ else:
+ return 'unknown'
+
def expand_bbox(
bbox: np.ndarray,
@@ -39,16 +66,13 @@ def expand_bbox(
x1, y1, x2, y2 = map(int, bbox[:4])
height, width = image_shape[:2]
- # Calculate face dimensions
face_width = x2 - x1
face_height = y2 - y1
- # Calculate expansion amounts
expand_x = int(face_width * expand_ratio)
expand_y_bottom = int(face_height * expand_ratio)
expand_y_top = int(face_height * expand_top_ratio)
- # Expand and clamp to image boundaries
new_x1 = max(0, x1 - expand_x)
new_y1 = max(0, y1 - expand_y_top)
new_x2 = min(width, x2 + expand_x)
@@ -58,6 +82,7 @@ def expand_bbox(
def process_image(detector, parser, image_path: str, save_dir: str = 'outputs', expand_ratio: float = 0.2):
+ """Process a single image."""
image = cv2.imread(image_path)
if image is None:
print(f"Error: Failed to load image from '{image_path}'")
@@ -69,25 +94,19 @@ def process_image(detector, parser, image_path: str, save_dir: str = 'outputs',
result_image = image.copy()
for i, face in enumerate(faces):
- # Expand bbox to include full head for parsing
x1, y1, x2, y2 = expand_bbox(face.bbox, image.shape, expand_ratio=expand_ratio)
face_crop = image[y1:y2, x1:x2]
if face_crop.size == 0:
continue
- # Parse the face
mask = parser.parse(face_crop)
print(f' Face {i + 1}: parsed with {len(set(mask.flatten()))} unique classes')
- # Visualize the parsing result
face_crop_rgb = cv2.cvtColor(face_crop, cv2.COLOR_BGR2RGB)
vis_result = vis_parsing_maps(face_crop_rgb, mask, save_image=False)
- # Place the visualization back on the original image
result_image[y1:y2, x1:x2] = vis_result
-
- # Draw expanded bounding box
cv2.rectangle(result_image, (x1, y1), (x2, y2), (0, 255, 0), 2)
os.makedirs(save_dir, exist_ok=True)
@@ -96,10 +115,64 @@ def process_image(detector, parser, image_path: str, save_dir: str = 'outputs',
print(f'Output saved: {output_path}')
-def run_webcam(detector, parser, expand_ratio: float = 0.2):
- cap = cv2.VideoCapture(0)
+def process_video(detector, parser, video_path: str, save_dir: str = 'outputs', expand_ratio: float = 0.2):
+ """Process a video file."""
+ cap = cv2.VideoCapture(video_path)
if not cap.isOpened():
- print('Cannot open webcam')
+ print(f"Error: Cannot open video file '{video_path}'")
+ return
+
+ fps = cap.get(cv2.CAP_PROP_FPS)
+ width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+ height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+ total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(video_path).stem}_parsing.mp4')
+ fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+ out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+ print(f'Processing video: {video_path} ({total_frames} frames)')
+ frame_count = 0
+
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame_count += 1
+ faces = detector.detect(frame)
+
+ for face in faces:
+ x1, y1, x2, y2 = expand_bbox(face.bbox, frame.shape, expand_ratio=expand_ratio)
+ face_crop = frame[y1:y2, x1:x2]
+
+ if face_crop.size == 0:
+ continue
+
+ mask = parser.parse(face_crop)
+ face_crop_rgb = cv2.cvtColor(face_crop, cv2.COLOR_BGR2RGB)
+ vis_result = vis_parsing_maps(face_crop_rgb, mask, save_image=False)
+
+ frame[y1:y2, x1:x2] = vis_result
+ cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2)
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ out.write(frame)
+
+ if frame_count % 100 == 0:
+ print(f' Processed {frame_count}/{total_frames} frames...')
+
+ cap.release()
+ out.release()
+ print(f'Done! Output saved: {output_path}')
+
+
+def run_camera(detector, parser, camera_id: int = 0, expand_ratio: float = 0.2):
+ """Run real-time detection on webcam."""
+ cap = cv2.VideoCapture(camera_id)
+ if not cap.isOpened():
+ print(f'Cannot open camera {camera_id}')
return
print("Press 'q' to quit")
@@ -113,24 +186,17 @@ def run_webcam(detector, parser, expand_ratio: float = 0.2):
faces = detector.detect(frame)
for face in faces:
- # Expand bbox to include full head for parsing
x1, y1, x2, y2 = expand_bbox(face.bbox, frame.shape, expand_ratio=expand_ratio)
face_crop = frame[y1:y2, x1:x2]
if face_crop.size == 0:
continue
- # Parse the face
mask = parser.parse(face_crop)
-
- # Visualize the parsing result
face_crop_rgb = cv2.cvtColor(face_crop, cv2.COLOR_BGR2RGB)
vis_result = vis_parsing_maps(face_crop_rgb, mask, save_image=False)
- # Place the visualization back on the frame
frame[y1:y2, x1:x2] = vis_result
-
- # Draw expanded bounding box
cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2)
cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
@@ -145,9 +211,8 @@ def run_webcam(detector, parser, expand_ratio: float = 0.2):
def main():
parser_arg = argparse.ArgumentParser(description='Run face parsing')
- parser_arg.add_argument('--image', type=str, help='Path to input image')
- parser_arg.add_argument('--webcam', action='store_true', help='Use webcam')
- parser_arg.add_argument('--save_dir', type=str, default='outputs')
+ parser_arg.add_argument('--source', type=str, required=True, help='Image/video path or camera ID (0, 1, ...)')
+ parser_arg.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
parser_arg.add_argument(
'--model', type=str, default=ParsingWeights.RESNET18, choices=[ParsingWeights.RESNET18, ParsingWeights.RESNET34]
)
@@ -159,16 +224,26 @@ def main():
)
args = parser_arg.parse_args()
- if not args.image and not args.webcam:
- parser_arg.error('Either --image or --webcam must be specified')
-
detector = RetinaFace()
parser = BiSeNet(model_name=ParsingWeights.RESNET34)
- if args.webcam:
- run_webcam(detector, parser, expand_ratio=args.expand_ratio)
+ source_type = get_source_type(args.source)
+
+ if source_type == 'camera':
+ run_camera(detector, parser, int(args.source), expand_ratio=args.expand_ratio)
+ elif source_type == 'image':
+ if not os.path.exists(args.source):
+ print(f'Error: Image not found: {args.source}')
+ return
+ process_image(detector, parser, args.source, args.save_dir, expand_ratio=args.expand_ratio)
+ elif source_type == 'video':
+ if not os.path.exists(args.source):
+ print(f'Error: Video not found: {args.source}')
+ return
+ process_video(detector, parser, args.source, args.save_dir, expand_ratio=args.expand_ratio)
else:
- process_image(detector, parser, args.image, args.save_dir, expand_ratio=args.expand_ratio)
+ print(f"Error: Unknown source type for '{args.source}'")
+ print('Supported formats: images (.jpg, .png, ...), videos (.mp4, .avi, ...), or camera ID (0, 1, ...)')
if __name__ == '__main__':
diff --git a/tools/face_search.py b/tools/face_search.py
new file mode 100644
index 0000000..b82f10f
--- /dev/null
+++ b/tools/face_search.py
@@ -0,0 +1,190 @@
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Real-time face search: match faces against a reference image.
+
+Usage:
+ python tools/face_search.py --reference person.jpg --source 0 # webcam
+ python tools/face_search.py --reference person.jpg --source video.mp4
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+from uniface.detection import SCRFD, RetinaFace
+from uniface.face_utils import compute_similarity
+from uniface.recognition import ArcFace, MobileFace, SphereFace
+
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.webp', '.tiff'}
+VIDEO_EXTENSIONS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv'}
+
+
+def get_source_type(source: str) -> str:
+ """Determine if source is image, video, or camera."""
+ if source.isdigit():
+ return 'camera'
+ path = Path(source)
+ suffix = path.suffix.lower()
+ if suffix in IMAGE_EXTENSIONS:
+ return 'image'
+ elif suffix in VIDEO_EXTENSIONS:
+ return 'video'
+ else:
+ return 'unknown'
+
+
+def get_recognizer(name: str):
+ """Get recognizer by name."""
+ if name == 'arcface':
+ return ArcFace()
+ elif name == 'mobileface':
+ return MobileFace()
+ else:
+ return SphereFace()
+
+
+def extract_reference_embedding(detector, recognizer, image_path: str) -> np.ndarray:
+ """Extract embedding from reference image."""
+ image = cv2.imread(image_path)
+ if image is None:
+ raise RuntimeError(f'Failed to load image: {image_path}')
+
+ faces = detector.detect(image)
+ if not faces:
+ raise RuntimeError('No faces found in reference image.')
+
+ landmarks = faces[0].landmarks
+ return recognizer.get_normalized_embedding(image, landmarks)
+
+
+def process_frame(frame, detector, recognizer, ref_embedding: np.ndarray, threshold: float = 0.4):
+ """Process a single frame and return annotated frame."""
+ faces = detector.detect(frame)
+
+ for face in faces:
+ bbox = face.bbox
+ landmarks = face.landmarks
+ x1, y1, x2, y2 = map(int, bbox)
+
+ embedding = recognizer.get_normalized_embedding(frame, landmarks)
+ sim = compute_similarity(ref_embedding, embedding)
+
+ label = f'Match ({sim:.2f})' if sim > threshold else f'Unknown ({sim:.2f})'
+ color = (0, 255, 0) if sim > threshold else (0, 0, 255)
+
+ cv2.rectangle(frame, (x1, y1), (x2, y2), color, 2)
+ cv2.putText(frame, label, (x1, y1 - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.6, color, 2)
+
+ return frame
+
+
+def process_video(detector, recognizer, ref_embedding: np.ndarray, video_path: str, save_dir: str, threshold: float):
+ """Process a video file."""
+ cap = cv2.VideoCapture(video_path)
+ if not cap.isOpened():
+ print(f"Error: Cannot open video file '{video_path}'")
+ return
+
+ fps = cap.get(cv2.CAP_PROP_FPS)
+ width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+ height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+ total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(video_path).stem}_search.mp4')
+ fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+ out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+ print(f'Processing video: {video_path} ({total_frames} frames)')
+ frame_count = 0
+
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame_count += 1
+ frame = process_frame(frame, detector, recognizer, ref_embedding, threshold)
+ out.write(frame)
+
+ if frame_count % 100 == 0:
+ print(f' Processed {frame_count}/{total_frames} frames...')
+
+ cap.release()
+ out.release()
+ print(f'Done! Output saved: {output_path}')
+
+
+def run_camera(detector, recognizer, ref_embedding: np.ndarray, camera_id: int = 0, threshold: float = 0.4):
+ """Run real-time face search on webcam."""
+ cap = cv2.VideoCapture(camera_id)
+ if not cap.isOpened():
+ print(f'Cannot open camera {camera_id}')
+ return
+
+ print("Press 'q' to quit")
+
+ while True:
+ ret, frame = cap.read()
+ frame = cv2.flip(frame, 1)
+ if not ret:
+ break
+
+ frame = process_frame(frame, detector, recognizer, ref_embedding, threshold)
+
+ cv2.imshow('Face Recognition', frame)
+ if cv2.waitKey(1) & 0xFF == ord('q'):
+ break
+
+ cap.release()
+ cv2.destroyAllWindows()
+
+
+def main():
+ parser = argparse.ArgumentParser(description='Face search using a reference image')
+ parser.add_argument('--reference', type=str, required=True, help='Reference face image')
+ parser.add_argument('--source', type=str, required=True, help='Video path or camera ID (0, 1, ...)')
+ parser.add_argument('--threshold', type=float, default=0.4, help='Match threshold')
+ parser.add_argument('--detector', type=str, default='scrfd', choices=['retinaface', 'scrfd'])
+ parser.add_argument(
+ '--recognizer',
+ type=str,
+ default='arcface',
+ choices=['arcface', 'mobileface', 'sphereface'],
+ )
+ parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
+ args = parser.parse_args()
+
+ if not os.path.exists(args.reference):
+ print(f'Error: Reference image not found: {args.reference}')
+ return
+
+ detector = RetinaFace() if args.detector == 'retinaface' else SCRFD()
+ recognizer = get_recognizer(args.recognizer)
+
+ print(f'Loading reference: {args.reference}')
+ ref_embedding = extract_reference_embedding(detector, recognizer, args.reference)
+
+ source_type = get_source_type(args.source)
+
+ if source_type == 'camera':
+ run_camera(detector, recognizer, ref_embedding, int(args.source), args.threshold)
+ elif source_type == 'video':
+ if not os.path.exists(args.source):
+ print(f'Error: Video not found: {args.source}')
+ return
+ process_video(detector, recognizer, ref_embedding, args.source, args.save_dir, args.threshold)
+ else:
+ print(f"Error: Source must be a video file or camera ID, not '{args.source}'")
+ print('Supported formats: videos (.mp4, .avi, ...) or camera ID (0, 1, ...)')
+
+
+if __name__ == '__main__':
+ main()
diff --git a/tools/fairface.py b/tools/fairface.py
new file mode 100644
index 0000000..5abad94
--- /dev/null
+++ b/tools/fairface.py
@@ -0,0 +1,214 @@
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""FairFace attribute prediction (race, gender, age) on detected faces.
+
+Usage:
+ python tools/fairface.py --source path/to/image.jpg
+ python tools/fairface.py --source path/to/video.mp4
+ python tools/fairface.py --source 0 # webcam
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+import cv2
+
+from uniface import SCRFD, RetinaFace
+from uniface.attribute import FairFace
+from uniface.visualization import draw_detections
+
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.webp', '.tiff'}
+VIDEO_EXTENSIONS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv'}
+
+
+def get_source_type(source: str) -> str:
+ """Determine if source is image, video, or camera."""
+ if source.isdigit():
+ return 'camera'
+ path = Path(source)
+ suffix = path.suffix.lower()
+ if suffix in IMAGE_EXTENSIONS:
+ return 'image'
+ elif suffix in VIDEO_EXTENSIONS:
+ return 'video'
+ else:
+ return 'unknown'
+
+
+def draw_fairface_label(image, bbox, sex: str, age_group: str, race: str):
+ """Draw FairFace attributes above the bounding box."""
+ x1, y1 = int(bbox[0]), int(bbox[1])
+ text = f'{sex}, {age_group}, {race}'
+ (tw, th), _ = cv2.getTextSize(text, cv2.FONT_HERSHEY_SIMPLEX, 0.5, 2)
+ cv2.rectangle(image, (x1, y1 - th - 10), (x1 + tw + 10, y1), (0, 255, 0), -1)
+ cv2.putText(image, text, (x1 + 5, y1 - 5), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 0, 0), 2)
+
+
+def process_image(
+ detector,
+ fairface,
+ image_path: str,
+ save_dir: str = 'outputs',
+ threshold: float = 0.6,
+):
+ """Process a single image."""
+ image = cv2.imread(image_path)
+ if image is None:
+ print(f"Error: Failed to load image from '{image_path}'")
+ return
+
+ faces = detector.detect(image)
+ print(f'Detected {len(faces)} face(s)')
+
+ if not faces:
+ return
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(
+ image=image, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
+ )
+
+ for i, face in enumerate(faces):
+ result = fairface.predict(image, face.bbox)
+ print(f' Face {i + 1}: {result.sex}, {result.age_group}, {result.race}')
+ draw_fairface_label(image, face.bbox, result.sex, result.age_group, result.race)
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(image_path).stem}_fairface.jpg')
+ cv2.imwrite(output_path, image)
+ print(f'Output saved: {output_path}')
+
+
+def process_video(
+ detector,
+ fairface,
+ video_path: str,
+ save_dir: str = 'outputs',
+ threshold: float = 0.6,
+):
+ """Process a video file."""
+ cap = cv2.VideoCapture(video_path)
+ if not cap.isOpened():
+ print(f"Error: Cannot open video file '{video_path}'")
+ return
+
+ fps = cap.get(cv2.CAP_PROP_FPS)
+ width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+ height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+ total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(video_path).stem}_fairface.mp4')
+ fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+ out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+ print(f'Processing video: {video_path} ({total_frames} frames)')
+ frame_count = 0
+
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame_count += 1
+ faces = detector.detect(frame)
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(
+ image=frame, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
+ )
+
+ for face in faces:
+ result = fairface.predict(frame, face.bbox)
+ draw_fairface_label(frame, face.bbox, result.sex, result.age_group, result.race)
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ out.write(frame)
+
+ if frame_count % 100 == 0:
+ print(f' Processed {frame_count}/{total_frames} frames...')
+
+ cap.release()
+ out.release()
+ print(f'Done! Output saved: {output_path}')
+
+
+def run_camera(detector, fairface, camera_id: int = 0, threshold: float = 0.6):
+ """Run real-time detection on webcam."""
+ cap = cv2.VideoCapture(camera_id)
+ if not cap.isOpened():
+ print(f'Cannot open camera {camera_id}')
+ return
+
+ print("Press 'q' to quit")
+
+ while True:
+ ret, frame = cap.read()
+ frame = cv2.flip(frame, 1)
+ if not ret:
+ break
+
+ faces = detector.detect(frame)
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(
+ image=frame, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
+ )
+
+ for face in faces:
+ result = fairface.predict(frame, face.bbox)
+ draw_fairface_label(frame, face.bbox, result.sex, result.age_group, result.race)
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ cv2.imshow('FairFace Detection', frame)
+
+ if cv2.waitKey(1) & 0xFF == ord('q'):
+ break
+
+ cap.release()
+ cv2.destroyAllWindows()
+
+
+def main():
+ parser = argparse.ArgumentParser(description='Run FairFace attribute prediction (race, gender, age)')
+ parser.add_argument('--source', type=str, required=True, help='Image/video path or camera ID (0, 1, ...)')
+ parser.add_argument('--detector', type=str, default='retinaface', choices=['retinaface', 'scrfd'])
+ parser.add_argument('--threshold', type=float, default=0.6, help='Visualization threshold')
+ parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
+ args = parser.parse_args()
+
+ detector = RetinaFace() if args.detector == 'retinaface' else SCRFD()
+ fairface = FairFace()
+
+ source_type = get_source_type(args.source)
+
+ if source_type == 'camera':
+ run_camera(detector, fairface, int(args.source), args.threshold)
+ elif source_type == 'image':
+ if not os.path.exists(args.source):
+ print(f'Error: Image not found: {args.source}')
+ return
+ process_image(detector, fairface, args.source, args.save_dir, args.threshold)
+ elif source_type == 'video':
+ if not os.path.exists(args.source):
+ print(f'Error: Video not found: {args.source}')
+ return
+ process_video(detector, fairface, args.source, args.save_dir, args.threshold)
+ else:
+ print(f"Error: Unknown source type for '{args.source}'")
+ print('Supported formats: images (.jpg, .png, ...), videos (.mp4, .avi, ...), or camera ID (0, 1, ...)')
+
+
+if __name__ == '__main__':
+ main()
diff --git a/tools/gaze_estimation.py b/tools/gaze_estimation.py
new file mode 100644
index 0000000..d0d6292
--- /dev/null
+++ b/tools/gaze_estimation.py
@@ -0,0 +1,190 @@
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Gaze estimation on detected faces.
+
+Usage:
+ python tools/gaze_estimation.py --source path/to/image.jpg
+ python tools/gaze_estimation.py --source path/to/video.mp4
+ python tools/gaze_estimation.py --source 0 # webcam
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+from uniface import RetinaFace
+from uniface.gaze import MobileGaze
+from uniface.visualization import draw_gaze
+
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.webp', '.tiff'}
+VIDEO_EXTENSIONS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv'}
+
+
+def get_source_type(source: str) -> str:
+ """Determine if source is image, video, or camera."""
+ if source.isdigit():
+ return 'camera'
+ path = Path(source)
+ suffix = path.suffix.lower()
+ if suffix in IMAGE_EXTENSIONS:
+ return 'image'
+ elif suffix in VIDEO_EXTENSIONS:
+ return 'video'
+ else:
+ return 'unknown'
+
+
+def process_image(detector, gaze_estimator, image_path: str, save_dir: str = 'outputs'):
+ """Process a single image."""
+ image = cv2.imread(image_path)
+ if image is None:
+ print(f"Error: Failed to load image from '{image_path}'")
+ return
+
+ faces = detector.detect(image)
+ print(f'Detected {len(faces)} face(s)')
+
+ for i, face in enumerate(faces):
+ bbox = face.bbox
+ x1, y1, x2, y2 = map(int, bbox[:4])
+ face_crop = image[y1:y2, x1:x2]
+
+ if face_crop.size == 0:
+ continue
+
+ result = gaze_estimator.estimate(face_crop)
+ print(f' Face {i + 1}: pitch={np.degrees(result.pitch):.1f}°, yaw={np.degrees(result.yaw):.1f}°')
+
+ draw_gaze(image, bbox, result.pitch, result.yaw, draw_angles=True)
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(image_path).stem}_gaze.jpg')
+ cv2.imwrite(output_path, image)
+ print(f'Output saved: {output_path}')
+
+
+def process_video(detector, gaze_estimator, video_path: str, save_dir: str = 'outputs'):
+ """Process a video file."""
+ cap = cv2.VideoCapture(video_path)
+ if not cap.isOpened():
+ print(f"Error: Cannot open video file '{video_path}'")
+ return
+
+ fps = cap.get(cv2.CAP_PROP_FPS)
+ width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+ height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+ total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(video_path).stem}_gaze.mp4')
+ fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+ out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+ print(f'Processing video: {video_path} ({total_frames} frames)')
+ frame_count = 0
+
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame_count += 1
+ faces = detector.detect(frame)
+
+ for face in faces:
+ bbox = face.bbox
+ x1, y1, x2, y2 = map(int, bbox[:4])
+ face_crop = frame[y1:y2, x1:x2]
+
+ if face_crop.size == 0:
+ continue
+
+ result = gaze_estimator.estimate(face_crop)
+ draw_gaze(frame, bbox, result.pitch, result.yaw)
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ out.write(frame)
+
+ if frame_count % 100 == 0:
+ print(f' Processed {frame_count}/{total_frames} frames...')
+
+ cap.release()
+ out.release()
+ print(f'Done! Output saved: {output_path}')
+
+
+def run_camera(detector, gaze_estimator, camera_id: int = 0):
+ """Run real-time detection on webcam."""
+ cap = cv2.VideoCapture(camera_id)
+ if not cap.isOpened():
+ print(f'Cannot open camera {camera_id}')
+ return
+
+ print("Press 'q' to quit")
+
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame = cv2.flip(frame, 1)
+ faces = detector.detect(frame)
+
+ for face in faces:
+ bbox = face.bbox
+ x1, y1, x2, y2 = map(int, bbox[:4])
+ face_crop = frame[y1:y2, x1:x2]
+
+ if face_crop.size == 0:
+ continue
+
+ result = gaze_estimator.estimate(face_crop)
+ draw_gaze(frame, bbox, result.pitch, result.yaw)
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ cv2.imshow('Gaze Estimation', frame)
+
+ if cv2.waitKey(1) & 0xFF == ord('q'):
+ break
+
+ cap.release()
+ cv2.destroyAllWindows()
+
+
+def main():
+ parser = argparse.ArgumentParser(description='Run gaze estimation')
+ parser.add_argument('--source', type=str, required=True, help='Image/video path or camera ID (0, 1, ...)')
+ parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
+ args = parser.parse_args()
+
+ detector = RetinaFace()
+ gaze_estimator = MobileGaze()
+
+ source_type = get_source_type(args.source)
+
+ if source_type == 'camera':
+ run_camera(detector, gaze_estimator, int(args.source))
+ elif source_type == 'image':
+ if not os.path.exists(args.source):
+ print(f'Error: Image not found: {args.source}')
+ return
+ process_image(detector, gaze_estimator, args.source, args.save_dir)
+ elif source_type == 'video':
+ if not os.path.exists(args.source):
+ print(f'Error: Video not found: {args.source}')
+ return
+ process_video(detector, gaze_estimator, args.source, args.save_dir)
+ else:
+ print(f"Error: Unknown source type for '{args.source}'")
+ print('Supported formats: images (.jpg, .png, ...), videos (.mp4, .avi, ...), or camera ID (0, 1, ...)')
+
+
+if __name__ == '__main__':
+ main()
diff --git a/tools/landmarks.py b/tools/landmarks.py
new file mode 100644
index 0000000..48199e5
--- /dev/null
+++ b/tools/landmarks.py
@@ -0,0 +1,187 @@
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""106-point facial landmark detection.
+
+Usage:
+ python tools/landmarks.py --source path/to/image.jpg
+ python tools/landmarks.py --source path/to/video.mp4
+ python tools/landmarks.py --source 0 # webcam
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+import cv2
+
+from uniface import SCRFD, Landmark106, RetinaFace
+
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.webp', '.tiff'}
+VIDEO_EXTENSIONS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv'}
+
+
+def get_source_type(source: str) -> str:
+ """Determine if source is image, video, or camera."""
+ if source.isdigit():
+ return 'camera'
+ path = Path(source)
+ suffix = path.suffix.lower()
+ if suffix in IMAGE_EXTENSIONS:
+ return 'image'
+ elif suffix in VIDEO_EXTENSIONS:
+ return 'video'
+ else:
+ return 'unknown'
+
+
+def process_image(detector, landmarker, image_path: str, save_dir: str = 'outputs'):
+ """Process a single image."""
+ image = cv2.imread(image_path)
+ if image is None:
+ print(f"Error: Failed to load image from '{image_path}'")
+ return
+
+ faces = detector.detect(image)
+ print(f'Detected {len(faces)} face(s)')
+
+ if not faces:
+ return
+
+ for i, face in enumerate(faces):
+ bbox = face.bbox
+ x1, y1, x2, y2 = map(int, bbox)
+ cv2.rectangle(image, (x1, y1), (x2, y2), (0, 255, 0), 2)
+
+ landmarks = landmarker.get_landmarks(image, bbox)
+ print(f' Face {i + 1}: {len(landmarks)} landmarks')
+
+ for x, y in landmarks.astype(int):
+ cv2.circle(image, (x, y), 1, (0, 255, 0), -1)
+
+ cv2.putText(image, f'Face {i + 1}', (x1, y1 - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 2)
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(image_path).stem}_landmarks.jpg')
+ cv2.imwrite(output_path, image)
+ print(f'Output saved: {output_path}')
+
+
+def process_video(detector, landmarker, video_path: str, save_dir: str = 'outputs'):
+ """Process a video file."""
+ cap = cv2.VideoCapture(video_path)
+ if not cap.isOpened():
+ print(f"Error: Cannot open video file '{video_path}'")
+ return
+
+ fps = cap.get(cv2.CAP_PROP_FPS)
+ width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+ height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+ total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(video_path).stem}_landmarks.mp4')
+ fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+ out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+ print(f'Processing video: {video_path} ({total_frames} frames)')
+ frame_count = 0
+
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame_count += 1
+ faces = detector.detect(frame)
+
+ for face in faces:
+ bbox = face.bbox
+ x1, y1, x2, y2 = map(int, bbox)
+ cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2)
+
+ landmarks = landmarker.get_landmarks(frame, bbox)
+ for x, y in landmarks.astype(int):
+ cv2.circle(frame, (x, y), 1, (0, 255, 0), -1)
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ out.write(frame)
+
+ if frame_count % 100 == 0:
+ print(f' Processed {frame_count}/{total_frames} frames...')
+
+ cap.release()
+ out.release()
+ print(f'Done! Output saved: {output_path}')
+
+
+def run_camera(detector, landmarker, camera_id: int = 0):
+ """Run real-time detection on webcam."""
+ cap = cv2.VideoCapture(camera_id)
+ if not cap.isOpened():
+ print(f'Cannot open camera {camera_id}')
+ return
+
+ print("Press 'q' to quit")
+
+ while True:
+ ret, frame = cap.read()
+ frame = cv2.flip(frame, 1)
+ if not ret:
+ break
+
+ faces = detector.detect(frame)
+
+ for face in faces:
+ bbox = face.bbox
+ x1, y1, x2, y2 = map(int, bbox)
+ cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2)
+
+ landmarks = landmarker.get_landmarks(frame, bbox)
+ for x, y in landmarks.astype(int):
+ cv2.circle(frame, (x, y), 1, (0, 255, 0), -1)
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ cv2.imshow('106-Point Landmarks', frame)
+
+ if cv2.waitKey(1) & 0xFF == ord('q'):
+ break
+
+ cap.release()
+ cv2.destroyAllWindows()
+
+
+def main():
+ parser = argparse.ArgumentParser(description='Run facial landmark detection')
+ parser.add_argument('--source', type=str, required=True, help='Image/video path or camera ID (0, 1, ...)')
+ parser.add_argument('--detector', type=str, default='retinaface', choices=['retinaface', 'scrfd'])
+ parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
+ args = parser.parse_args()
+
+ detector = RetinaFace() if args.detector == 'retinaface' else SCRFD()
+ landmarker = Landmark106()
+
+ source_type = get_source_type(args.source)
+
+ if source_type == 'camera':
+ run_camera(detector, landmarker, int(args.source))
+ elif source_type == 'image':
+ if not os.path.exists(args.source):
+ print(f'Error: Image not found: {args.source}')
+ return
+ process_image(detector, landmarker, args.source, args.save_dir)
+ elif source_type == 'video':
+ if not os.path.exists(args.source):
+ print(f'Error: Video not found: {args.source}')
+ return
+ process_video(detector, landmarker, args.source, args.save_dir)
+ else:
+ print(f"Error: Unknown source type for '{args.source}'")
+ print('Supported formats: images (.jpg, .png, ...), videos (.mp4, .avi, ...), or camera ID (0, 1, ...)')
+
+
+if __name__ == '__main__':
+ main()
diff --git a/scripts/run_recognition.py b/tools/recognition.py
similarity index 91%
rename from scripts/run_recognition.py
rename to tools/recognition.py
index f3a88f6..e64566b 100644
--- a/scripts/run_recognition.py
+++ b/tools/recognition.py
@@ -1,6 +1,13 @@
-# Face recognition: extract embeddings or compare two faces
-# Usage: python run_recognition.py --image path/to/image.jpg
-# python run_recognition.py --image1 face1.jpg --image2 face2.jpg
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Face recognition: extract embeddings or compare two faces.
+
+Usage:
+ python tools/recognition.py --image path/to/image.jpg
+ python tools/recognition.py --image1 face1.jpg --image2 face2.jpg
+"""
import argparse
diff --git a/scripts/sha256_generate.py b/tools/sha256_generate.py
similarity index 100%
rename from scripts/sha256_generate.py
rename to tools/sha256_generate.py
diff --git a/tools/spoofing.py b/tools/spoofing.py
new file mode 100644
index 0000000..e7a6cb3
--- /dev/null
+++ b/tools/spoofing.py
@@ -0,0 +1,214 @@
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Face Anti-Spoofing Detection.
+
+Usage:
+ python tools/spoofing.py --source path/to/image.jpg
+ python tools/spoofing.py --source path/to/video.mp4
+ python tools/spoofing.py --source 0 # webcam
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+from uniface import RetinaFace
+from uniface.constants import MiniFASNetWeights
+from uniface.spoofing import create_spoofer
+
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.webp', '.tiff'}
+VIDEO_EXTENSIONS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv'}
+
+
+def get_source_type(source: str) -> str:
+ """Determine if source is image, video, or camera."""
+ if source.isdigit():
+ return 'camera'
+ path = Path(source)
+ suffix = path.suffix.lower()
+ if suffix in IMAGE_EXTENSIONS:
+ return 'image'
+ elif suffix in VIDEO_EXTENSIONS:
+ return 'video'
+ else:
+ return 'unknown'
+
+
+def draw_spoofing_result(
+ image: np.ndarray,
+ bbox: list,
+ is_real: bool,
+ confidence: float,
+ thickness: int = 2,
+) -> None:
+ """Draw bounding box with anti-spoofing result.
+
+ Args:
+ image: Input image to draw on.
+ bbox: Bounding box in [x1, y1, x2, y2] format.
+ is_real: True if real face, False if fake.
+ confidence: Confidence score (0.0 to 1.0).
+ thickness: Line thickness for bounding box.
+ """
+ x1, y1, x2, y2 = map(int, bbox[:4])
+
+ color = (0, 255, 0) if is_real else (0, 0, 255)
+
+ cv2.rectangle(image, (x1, y1), (x2, y2), color, thickness)
+
+ label = 'Real' if is_real else 'Fake'
+ text = f'{label}: {confidence:.1%}'
+
+ (tw, th), _baseline = cv2.getTextSize(text, cv2.FONT_HERSHEY_SIMPLEX, 0.7, 2)
+ cv2.rectangle(image, (x1, y1 - th - 10), (x1 + tw + 10, y1), color, -1)
+ cv2.putText(image, text, (x1 + 5, y1 - 5), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (255, 255, 255), 2)
+
+
+def process_image(detector, spoofer, image_path: str, save_dir: str = 'outputs') -> None:
+ """Process a single image for face anti-spoofing detection."""
+ image = cv2.imread(image_path)
+ if image is None:
+ print(f"Error: Failed to load image from '{image_path}'")
+ return
+
+ faces = detector.detect(image)
+ print(f'Detected {len(faces)} face(s)')
+
+ if not faces:
+ print('No faces detected in the image.')
+ return
+
+ for i, face in enumerate(faces, 1):
+ result = spoofer.predict(image, face.bbox)
+ label = 'Real' if result.is_real else 'Fake'
+ print(f' Face {i}: {label} ({result.confidence:.1%})')
+
+ draw_spoofing_result(image, face.bbox, result.is_real, result.confidence)
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(image_path).stem}_spoofing.jpg')
+ cv2.imwrite(output_path, image)
+ print(f'Output saved: {output_path}')
+
+
+def process_video(detector, spoofer, video_path: str, save_dir: str = 'outputs') -> None:
+ """Process a video file for face anti-spoofing detection."""
+ cap = cv2.VideoCapture(video_path)
+ if not cap.isOpened():
+ print(f"Error: Cannot open video file '{video_path}'")
+ return
+
+ fps = cap.get(cv2.CAP_PROP_FPS)
+ width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+ height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+ total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+ os.makedirs(save_dir, exist_ok=True)
+ output_path = os.path.join(save_dir, f'{Path(video_path).stem}_spoofing.mp4')
+ fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+ out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+ print(f'Processing video: {video_path} ({total_frames} frames)')
+ frame_count = 0
+
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame_count += 1
+ faces = detector.detect(frame)
+
+ for face in faces:
+ result = spoofer.predict(frame, face.bbox)
+ draw_spoofing_result(frame, face.bbox, result.is_real, result.confidence)
+
+ out.write(frame)
+
+ if frame_count % 100 == 0:
+ print(f' Processed {frame_count}/{total_frames} frames...')
+
+ cap.release()
+ out.release()
+ print(f'Done! Output saved: {output_path}')
+
+
+def run_camera(detector, spoofer, camera_id: int = 0) -> None:
+ """Run real-time anti-spoofing detection on webcam."""
+ cap = cv2.VideoCapture(camera_id)
+ if not cap.isOpened():
+ print(f'Cannot open camera {camera_id}')
+ return
+
+ print("Press 'q' to quit")
+
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame = cv2.flip(frame, 1)
+ faces = detector.detect(frame)
+
+ for face in faces:
+ result = spoofer.predict(frame, face.bbox)
+ draw_spoofing_result(frame, face.bbox, result.is_real, result.confidence)
+
+ cv2.imshow('Face Anti-Spoofing', frame)
+ if cv2.waitKey(1) & 0xFF == ord('q'):
+ break
+
+ cap.release()
+ cv2.destroyAllWindows()
+
+
+def main():
+ parser = argparse.ArgumentParser(description='Face Anti-Spoofing Detection')
+ parser.add_argument('--source', type=str, required=True, help='Image/video path or camera ID (0, 1, ...)')
+ parser.add_argument(
+ '--model',
+ type=str,
+ default='v2',
+ choices=['v1se', 'v2'],
+ help='Model variant: v1se or v2 (default: v2)',
+ )
+ parser.add_argument('--scale', type=float, default=None, help='Custom crop scale (default: auto)')
+ parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory')
+ args = parser.parse_args()
+
+ # Select model variant
+ model_name = MiniFASNetWeights.V1SE if args.model == 'v1se' else MiniFASNetWeights.V2
+
+ # Initialize models
+ print(f'Initializing models (MiniFASNet {args.model.upper()})...')
+ detector = RetinaFace()
+ spoofer = create_spoofer(model_name=model_name, scale=args.scale)
+
+ source_type = get_source_type(args.source)
+
+ if source_type == 'camera':
+ run_camera(detector, spoofer, int(args.source))
+ elif source_type == 'image':
+ if not os.path.exists(args.source):
+ print(f'Error: Image not found: {args.source}')
+ return
+ process_image(detector, spoofer, args.source, args.save_dir)
+ elif source_type == 'video':
+ if not os.path.exists(args.source):
+ print(f'Error: Video not found: {args.source}')
+ return
+ process_video(detector, spoofer, args.source, args.save_dir)
+ else:
+ print(f"Error: Unknown source type for '{args.source}'")
+ print('Supported formats: images (.jpg, .png, ...), videos (.mp4, .avi, ...), or camera ID (0, 1, ...)')
+
+
+if __name__ == '__main__':
+ main()
diff --git a/tools/video_detection.py b/tools/video_detection.py
new file mode 100644
index 0000000..e69e81b
--- /dev/null
+++ b/tools/video_detection.py
@@ -0,0 +1,180 @@
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Face detection on video files with progress tracking.
+
+Usage:
+ python tools/video_detection.py --source video.mp4
+ python tools/video_detection.py --source video.mp4 --output output.mp4
+ python tools/video_detection.py --source 0 # webcam
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+import cv2
+from tqdm import tqdm
+
+from uniface import SCRFD, RetinaFace
+from uniface.visualization import draw_detections
+
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.webp', '.tiff'}
+VIDEO_EXTENSIONS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv'}
+
+
+def get_source_type(source: str) -> str:
+ """Determine if source is image, video, or camera."""
+ if source.isdigit():
+ return 'camera'
+ path = Path(source)
+ suffix = path.suffix.lower()
+ if suffix in IMAGE_EXTENSIONS:
+ return 'image'
+ elif suffix in VIDEO_EXTENSIONS:
+ return 'video'
+ else:
+ return 'unknown'
+
+
+def process_video(
+ detector,
+ input_path: str,
+ output_path: str,
+ threshold: float = 0.6,
+ show_preview: bool = False,
+):
+ """Process a video file with progress bar."""
+ cap = cv2.VideoCapture(input_path)
+ if not cap.isOpened():
+ print(f"Error: Cannot open video file '{input_path}'")
+ return
+
+ total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+ fps = cap.get(cv2.CAP_PROP_FPS)
+ width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+ height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+
+ print(f'Input: {input_path} ({width}x{height}, {fps:.1f} fps, {total_frames} frames)')
+ print(f'Output: {output_path}')
+
+ Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+ fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+ out = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+ if not out.isOpened():
+ print(f"Error: Cannot create output video '{output_path}'")
+ cap.release()
+ return
+
+ frame_count = 0
+ total_faces = 0
+
+ for _ in tqdm(range(total_frames), desc='Processing', unit='frames'):
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame_count += 1
+ faces = detector.detect(frame)
+ total_faces += len(faces)
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(
+ image=frame, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
+ )
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ out.write(frame)
+
+ if show_preview:
+ cv2.imshow("Processing - Press 'q' to cancel", frame)
+ if cv2.waitKey(1) & 0xFF == ord('q'):
+ print('\nCancelled by user')
+ break
+
+ cap.release()
+ out.release()
+ if show_preview:
+ cv2.destroyAllWindows()
+
+ avg_faces = total_faces / frame_count if frame_count > 0 else 0
+ print(f'\nDone! {frame_count} frames, {total_faces} faces ({avg_faces:.1f} avg/frame)')
+ print(f'Saved: {output_path}')
+
+
+def run_camera(detector, camera_id: int = 0, threshold: float = 0.6):
+ """Run real-time detection on webcam."""
+ cap = cv2.VideoCapture(camera_id)
+ if not cap.isOpened():
+ print(f'Cannot open camera {camera_id}')
+ return
+
+ print("Press 'q' to quit")
+
+ while True:
+ ret, frame = cap.read()
+ frame = cv2.flip(frame, 1)
+ if not ret:
+ break
+
+ faces = detector.detect(frame)
+
+ bboxes = [f.bbox for f in faces]
+ scores = [f.confidence for f in faces]
+ landmarks = [f.landmarks for f in faces]
+ draw_detections(
+ image=frame, bboxes=bboxes, scores=scores, landmarks=landmarks, vis_threshold=threshold, fancy_bbox=True
+ )
+
+ cv2.putText(frame, f'Faces: {len(faces)}', (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
+ cv2.imshow('Face Detection', frame)
+
+ if cv2.waitKey(1) & 0xFF == ord('q'):
+ break
+
+ cap.release()
+ cv2.destroyAllWindows()
+
+
+def main():
+ parser = argparse.ArgumentParser(description='Process video with face detection')
+ parser.add_argument('--source', type=str, required=True, help='Video path or camera ID (0, 1, ...)')
+ parser.add_argument('--output', type=str, default=None, help='Output video path (auto-generated if not specified)')
+ parser.add_argument('--detector', type=str, default='retinaface', choices=['retinaface', 'scrfd'])
+ parser.add_argument('--threshold', type=float, default=0.6, help='Visualization threshold')
+ parser.add_argument('--preview', action='store_true', help='Show live preview')
+ parser.add_argument('--save-dir', type=str, default='outputs', help='Output directory (if --output not specified)')
+ args = parser.parse_args()
+
+ detector = RetinaFace() if args.detector == 'retinaface' else SCRFD()
+
+ source_type = get_source_type(args.source)
+
+ if source_type == 'camera':
+ run_camera(detector, int(args.source), args.threshold)
+ elif source_type == 'video':
+ if not os.path.exists(args.source):
+ print(f'Error: Video not found: {args.source}')
+ return
+
+ # Determine output path
+ if args.output:
+ output_path = args.output
+ else:
+ os.makedirs(args.save_dir, exist_ok=True)
+ output_path = os.path.join(args.save_dir, f'{Path(args.source).stem}_detected.mp4')
+
+ process_video(detector, args.source, output_path, args.threshold, args.preview)
+ else:
+ print(f"Error: Unknown source type for '{args.source}'")
+ print('Supported formats: videos (.mp4, .avi, ...) or camera ID (0, 1, ...)')
+
+
+if __name__ == '__main__':
+ main()
diff --git a/uniface/__init__.py b/uniface/__init__.py
index c8ba0da..aa9b611 100644
--- a/uniface/__init__.py
+++ b/uniface/__init__.py
@@ -36,7 +36,7 @@ from uniface.model_store import verify_model_weights
from uniface.visualization import draw_detections, vis_parsing_maps
from .analyzer import FaceAnalyzer
-from .attribute import AgeGender, AttributeResult, FairFace
+from .attribute import AgeGender, FairFace
from .detection import (
SCRFD,
RetinaFace,
@@ -45,13 +45,13 @@ from .detection import (
detect_faces,
list_available_detectors,
)
-from .face import Face
from .gaze import MobileGaze, create_gaze_estimator
from .landmark import Landmark106, create_landmarker
from .parsing import BiSeNet, create_face_parser
from .privacy import BlurFace, anonymize_faces
from .recognition import ArcFace, MobileFace, SphereFace, create_recognizer
from .spoofing import MiniFASNet, create_spoofer
+from .types import AttributeResult, EmotionResult, Face, GazeResult, SpoofingResult
# Optional: Emotion requires PyTorch
Emotion: type | None
@@ -88,6 +88,7 @@ __all__ = [
# Landmark models
'Landmark106',
# Gaze models
+ 'GazeResult',
'MobileGaze',
# Parsing models
'BiSeNet',
@@ -95,9 +96,11 @@ __all__ = [
'AgeGender',
'AttributeResult',
'Emotion',
+ 'EmotionResult',
'FairFace',
# Spoofing models
'MiniFASNet',
+ 'SpoofingResult',
# Privacy
'BlurFace',
'anonymize_faces',
diff --git a/uniface/analyzer.py b/uniface/analyzer.py
index 0816641..5c966e6 100644
--- a/uniface/analyzer.py
+++ b/uniface/analyzer.py
@@ -9,9 +9,9 @@ import numpy as np
from uniface.attribute.age_gender import AgeGender
from uniface.attribute.fairface import FairFace
from uniface.detection.base import BaseDetector
-from uniface.face import Face
from uniface.log import Logger
from uniface.recognition.base import BaseRecognizer
+from uniface.types import Face
__all__ = ['FaceAnalyzer']
diff --git a/uniface/attribute/__init__.py b/uniface/attribute/__init__.py
index 3ce4dfe..7f96923 100644
--- a/uniface/attribute/__init__.py
+++ b/uniface/attribute/__init__.py
@@ -9,10 +9,10 @@ from typing import Any
import numpy as np
from uniface.attribute.age_gender import AgeGender
-from uniface.attribute.base import Attribute, AttributeResult
+from uniface.attribute.base import Attribute
from uniface.attribute.fairface import FairFace
from uniface.constants import AgeGenderWeights, DDAMFNWeights, FairFaceWeights
-from uniface.face import Face
+from uniface.types import AttributeResult, EmotionResult, Face
# Emotion requires PyTorch - make it optional
try:
@@ -28,6 +28,7 @@ __all__ = [
'AgeGender',
'AttributeResult',
'Emotion',
+ 'EmotionResult',
'FairFace',
'create_attribute_predictor',
'predict_attributes',
@@ -106,8 +107,8 @@ def predict_attributes(image: np.ndarray, faces: list[Face], predictor: Attribut
face.age_group = result.age_group
face.race = result.race
elif isinstance(predictor, Emotion):
- emotion, confidence = predictor(image, face.landmarks)
- face.emotion = emotion
- face.emotion_confidence = confidence
+ result = predictor(image, face.landmarks)
+ face.emotion = result.emotion
+ face.emotion_confidence = result.confidence
return faces
diff --git a/uniface/attribute/age_gender.py b/uniface/attribute/age_gender.py
index 4833790..cd5798d 100644
--- a/uniface/attribute/age_gender.py
+++ b/uniface/attribute/age_gender.py
@@ -6,12 +6,13 @@
import cv2
import numpy as np
-from uniface.attribute.base import Attribute, AttributeResult
+from uniface.attribute.base import Attribute
from uniface.constants import AgeGenderWeights
from uniface.face_utils import bbox_center_alignment
from uniface.log import Logger
from uniface.model_store import verify_model_weights
from uniface.onnx_utils import create_onnx_session
+from uniface.types import AttributeResult
__all__ = ['AgeGender']
diff --git a/uniface/attribute/base.py b/uniface/attribute/base.py
index 72afead..7287846 100644
--- a/uniface/attribute/base.py
+++ b/uniface/attribute/base.py
@@ -3,57 +3,13 @@
# GitHub: https://github.com/yakhyo
from abc import ABC, abstractmethod
-from dataclasses import dataclass
from typing import Any
import numpy as np
-__all__ = ['Attribute', 'AttributeResult']
+from uniface.types import AttributeResult, EmotionResult
-
-@dataclass(slots=True)
-class AttributeResult:
- """
- Unified result structure for face attribute prediction.
-
- This dataclass provides a consistent return type across different attribute
- prediction models (e.g., AgeGender, FairFace), enabling interoperability
- and unified handling of results.
-
- Attributes:
- gender: Predicted gender (0=Female, 1=Male).
- age: Exact age in years. Provided by AgeGender model, None for FairFace.
- age_group: Age range string like "20-29". Provided by FairFace, None for AgeGender.
- race: Race/ethnicity label. Provided by FairFace only.
-
- Properties:
- sex: Gender as a human-readable string ("Female" or "Male").
-
- Examples:
- >>> # AgeGender result
- >>> result = AttributeResult(gender=1, age=25)
- >>> result.sex
- 'Male'
- >>> result.age
- 25
-
- >>> # FairFace result
- >>> result = AttributeResult(gender=0, age_group='20-29', race='East Asian')
- >>> result.sex
- 'Female'
- >>> result.race
- 'East Asian'
- """
-
- gender: int
- age: int | None = None
- age_group: str | None = None
- race: str | None = None
-
- @property
- def sex(self) -> str:
- """Get gender as a string label (Female or Male)."""
- return 'Female' if self.gender == 0 else 'Male'
+__all__ = ['Attribute', 'AttributeResult', 'EmotionResult']
class Attribute(ABC):
diff --git a/uniface/attribute/emotion.py b/uniface/attribute/emotion.py
index 1677aa6..a722427 100644
--- a/uniface/attribute/emotion.py
+++ b/uniface/attribute/emotion.py
@@ -12,6 +12,7 @@ from uniface.constants import DDAMFNWeights
from uniface.face_utils import face_alignment
from uniface.log import Logger
from uniface.model_store import verify_model_weights
+from uniface.types import EmotionResult
__all__ = ['Emotion']
@@ -105,7 +106,7 @@ class Emotion(Attribute):
return torch.from_numpy(transposed_image).unsqueeze(0).to(self.device)
- def postprocess(self, prediction: torch.Tensor) -> tuple[str, float]:
+ def postprocess(self, prediction: torch.Tensor) -> EmotionResult:
"""
Processes the raw model output to get the emotion label and confidence score.
"""
@@ -113,9 +114,9 @@ class Emotion(Attribute):
pred_index = np.argmax(probabilities)
emotion_label = self.emotion_labels[pred_index]
confidence = float(probabilities[pred_index])
- return emotion_label, confidence
+ return EmotionResult(emotion=emotion_label, confidence=confidence)
- def predict(self, image: np.ndarray, landmark: list | np.ndarray) -> tuple[str, float]:
+ def predict(self, image: np.ndarray, landmark: list | np.ndarray) -> EmotionResult:
"""
Predicts the emotion from a single face specified by its landmarks.
"""
diff --git a/uniface/attribute/fairface.py b/uniface/attribute/fairface.py
index e9521c4..abb8e42 100644
--- a/uniface/attribute/fairface.py
+++ b/uniface/attribute/fairface.py
@@ -6,11 +6,12 @@
import cv2
import numpy as np
-from uniface.attribute.base import Attribute, AttributeResult
+from uniface.attribute.base import Attribute
from uniface.constants import FairFaceWeights
from uniface.log import Logger
from uniface.model_store import verify_model_weights
from uniface.onnx_utils import create_onnx_session
+from uniface.types import AttributeResult
__all__ = ['AGE_LABELS', 'RACE_LABELS', 'FairFace']
diff --git a/uniface/detection/__init__.py b/uniface/detection/__init__.py
index d8a58bf..d7317ed 100644
--- a/uniface/detection/__init__.py
+++ b/uniface/detection/__init__.py
@@ -8,7 +8,7 @@ from typing import Any
import numpy as np
-from uniface.face import Face
+from uniface.types import Face
from .base import BaseDetector
from .retinaface import RetinaFace
diff --git a/uniface/detection/base.py b/uniface/detection/base.py
index 05afd09..2b700f5 100644
--- a/uniface/detection/base.py
+++ b/uniface/detection/base.py
@@ -9,7 +9,7 @@ from typing import Any
import numpy as np
-from uniface.face import Face
+from uniface.types import Face
__all__ = ['BaseDetector']
@@ -107,3 +107,15 @@ class BaseDetector(ABC):
'supports_landmarks': self._supports_landmarks,
'config': self.config,
}
+
+ def __call__(self, image: np.ndarray, **kwargs: Any) -> list[Face]:
+ """Callable shortcut for the `detect` method.
+
+ Args:
+ image: Input image as numpy array with shape (H, W, C) in BGR format.
+ **kwargs: Additional detection parameters.
+
+ Returns:
+ List of detected Face objects.
+ """
+ return self.detect(image, **kwargs)
diff --git a/uniface/detection/retinaface.py b/uniface/detection/retinaface.py
index 6a91deb..d8d11b6 100644
--- a/uniface/detection/retinaface.py
+++ b/uniface/detection/retinaface.py
@@ -16,10 +16,10 @@ from uniface.common import (
resize_image,
)
from uniface.constants import RetinaFaceWeights
-from uniface.face import Face
from uniface.log import Logger
from uniface.model_store import verify_model_weights
from uniface.onnx_utils import create_onnx_session
+from uniface.types import Face
from .base import BaseDetector
diff --git a/uniface/detection/scrfd.py b/uniface/detection/scrfd.py
index 1eee8b9..7d5c750 100644
--- a/uniface/detection/scrfd.py
+++ b/uniface/detection/scrfd.py
@@ -10,10 +10,10 @@ import numpy as np
from uniface.common import distance2bbox, distance2kps, non_max_suppression, resize_image
from uniface.constants import SCRFDWeights
-from uniface.face import Face
from uniface.log import Logger
from uniface.model_store import verify_model_weights
from uniface.onnx_utils import create_onnx_session
+from uniface.types import Face
from .base import BaseDetector
diff --git a/uniface/detection/yolov5.py b/uniface/detection/yolov5.py
index b952ab1..7f99771 100644
--- a/uniface/detection/yolov5.py
+++ b/uniface/detection/yolov5.py
@@ -9,10 +9,10 @@ import numpy as np
from uniface.common import non_max_suppression
from uniface.constants import YOLOv5FaceWeights
-from uniface.face import Face
from uniface.log import Logger
from uniface.model_store import verify_model_weights
from uniface.onnx_utils import create_onnx_session
+from uniface.types import Face
from .base import BaseDetector
diff --git a/uniface/face.py b/uniface/face.py
deleted file mode 100644
index 732d102..0000000
--- a/uniface/face.py
+++ /dev/null
@@ -1,97 +0,0 @@
-# Copyright 2025 Yakhyokhuja Valikhujaev
-# Author: Yakhyokhuja Valikhujaev
-# GitHub: https://github.com/yakhyo
-
-from __future__ import annotations
-
-from dataclasses import dataclass, fields
-
-import numpy as np
-
-from uniface.face_utils import compute_similarity
-
-__all__ = ['Face']
-
-
-@dataclass(slots=True)
-class Face:
- """
- Detected face with analysis results.
-
- This dataclass represents a single detected face along with optional
- analysis results such as embeddings, age, gender, and race predictions.
-
- Attributes:
- bbox: Bounding box coordinates [x1, y1, x2, y2].
- confidence: Detection confidence score.
- landmarks: Facial landmark coordinates (typically 5 points).
- embedding: Face embedding vector for recognition (optional).
- gender: Predicted gender, 0=Female, 1=Male (optional).
- age: Predicted exact age in years (optional, from AgeGender model).
- age_group: Predicted age range like "20-29" (optional, from FairFace).
- race: Predicted race/ethnicity (optional, from FairFace).
- emotion: Predicted emotion label (optional, from Emotion model).
- emotion_confidence: Confidence score for emotion prediction (optional).
-
- Properties:
- sex: Gender as a human-readable string ("Female" or "Male").
- bbox_xyxy: Bounding box in (x1, y1, x2, y2) format.
- bbox_xywh: Bounding box in (x1, y1, width, height) format.
- """
-
- # Required attributes
- bbox: np.ndarray
- confidence: float
- landmarks: np.ndarray
-
- # Optional attributes
- embedding: np.ndarray | None = None
- gender: int | None = None
- age: int | None = None
- age_group: str | None = None
- race: str | None = None
- emotion: str | None = None
- emotion_confidence: float | None = None
-
- def compute_similarity(self, other: Face) -> float:
- """Compute cosine similarity with another face."""
- if self.embedding is None or other.embedding is None:
- raise ValueError('Both faces must have embeddings for similarity computation')
- return float(compute_similarity(self.embedding, other.embedding))
-
- def to_dict(self) -> dict:
- """Convert to dictionary."""
- return {f.name: getattr(self, f.name) for f in fields(self)}
-
- @property
- def sex(self) -> str | None:
- """Get gender as a string label (Female or Male)."""
- if self.gender is None:
- return None
- return 'Female' if self.gender == 0 else 'Male'
-
- @property
- def bbox_xyxy(self) -> np.ndarray:
- """Get bounding box coordinates in (x1, y1, x2, y2) format."""
- return self.bbox.copy()
-
- @property
- def bbox_xywh(self) -> np.ndarray:
- """Get bounding box coordinates in (x1, y1, w, h) format."""
- return np.array([self.bbox[0], self.bbox[1], self.bbox[2] - self.bbox[0], self.bbox[3] - self.bbox[1]])
-
- def __repr__(self) -> str:
- parts = [f'Face(confidence={self.confidence:.3f}']
- if self.age is not None:
- parts.append(f'age={self.age}')
- if self.age_group is not None:
- parts.append(f'age_group={self.age_group}')
- if self.gender is not None:
- parts.append(f'sex={self.sex}')
- if self.race is not None:
- parts.append(f'race={self.race}')
- if self.emotion is not None:
- parts.append(f'emotion={self.emotion}')
- if self.embedding is not None:
- parts.append(f'embedding_dim={self.embedding.shape[0]}')
- return ', '.join(parts) + ')'
diff --git a/uniface/gaze/__init__.py b/uniface/gaze/__init__.py
index bb21234..a1a7571 100644
--- a/uniface/gaze/__init__.py
+++ b/uniface/gaze/__init__.py
@@ -2,6 +2,8 @@
# Author: Yakhyokhuja Valikhujaev
# GitHub: https://github.com/yakhyo
+from uniface.types import GazeResult
+
from .base import BaseGazeEstimator
from .models import MobileGaze
@@ -37,7 +39,8 @@ def create_gaze_estimator(method: str = 'mobilegaze', **kwargs) -> BaseGazeEstim
>>> estimator = create_gaze_estimator('mobilegaze', model_name=GazeWeights.MOBILENET_V2)
>>> # Use the estimator
- >>> pitch, yaw = estimator.estimate(face_crop)
+ >>> result = estimator.estimate(face_crop)
+ >>> print(f'Pitch: {result.pitch}, Yaw: {result.yaw}')
"""
method = method.lower()
@@ -48,4 +51,4 @@ def create_gaze_estimator(method: str = 'mobilegaze', **kwargs) -> BaseGazeEstim
raise ValueError(f"Unsupported gaze estimation method: '{method}'. Available: {available}")
-__all__ = ['BaseGazeEstimator', 'MobileGaze', 'create_gaze_estimator']
+__all__ = ['BaseGazeEstimator', 'GazeResult', 'MobileGaze', 'create_gaze_estimator']
diff --git a/uniface/gaze/base.py b/uniface/gaze/base.py
index 51159cf..525fc2d 100644
--- a/uniface/gaze/base.py
+++ b/uniface/gaze/base.py
@@ -2,10 +2,16 @@
# Author: Yakhyokhuja Valikhujaev
# GitHub: https://github.com/yakhyo
+from __future__ import annotations
+
from abc import ABC, abstractmethod
import numpy as np
+from uniface.types import GazeResult
+
+__all__ = ['BaseGazeEstimator', 'GazeResult']
+
class BaseGazeEstimator(ABC):
"""
@@ -53,7 +59,7 @@ class BaseGazeEstimator(ABC):
raise NotImplementedError('Subclasses must implement the preprocess method.')
@abstractmethod
- def postprocess(self, outputs: tuple[np.ndarray, np.ndarray]) -> tuple[float, float]:
+ def postprocess(self, outputs: tuple[np.ndarray, np.ndarray]) -> GazeResult:
"""
Postprocess raw model outputs into gaze angles.
@@ -65,12 +71,12 @@ class BaseGazeEstimator(ABC):
on the specific model architecture.
Returns:
- Tuple[float, float]: A tuple of (pitch, yaw) angles in radians.
+ GazeResult: Result containing pitch and yaw angles in radians.
"""
raise NotImplementedError('Subclasses must implement the postprocess method.')
@abstractmethod
- def estimate(self, face_image: np.ndarray) -> tuple[float, float]:
+ def estimate(self, face_image: np.ndarray) -> GazeResult:
"""
Perform end-to-end gaze estimation on a face image.
@@ -83,18 +89,18 @@ class BaseGazeEstimator(ABC):
well-framed within the image.
Returns:
- Tuple[float, float]: A tuple of (pitch, yaw) angles in radians:
+ GazeResult: Result containing pitch and yaw angles in radians:
- pitch: Vertical gaze angle (positive = up, negative = down)
- yaw: Horizontal gaze angle (positive = right, negative = left)
Example:
>>> estimator = create_gaze_estimator()
- >>> pitch, yaw = estimator.estimate(face_crop)
- >>> print(f'Looking: pitch={np.degrees(pitch):.1f}°, yaw={np.degrees(yaw):.1f}°')
+ >>> result = estimator.estimate(face_crop)
+ >>> print(f'Looking: pitch={np.degrees(result.pitch):.1f}°, yaw={np.degrees(result.yaw):.1f}°')
"""
raise NotImplementedError('Subclasses must implement the estimate method.')
- def __call__(self, face_image: np.ndarray) -> tuple[float, float]:
+ def __call__(self, face_image: np.ndarray) -> GazeResult:
"""
Provides a convenient, callable shortcut for the `estimate` method.
@@ -102,6 +108,6 @@ class BaseGazeEstimator(ABC):
face_image (np.ndarray): A cropped face image in BGR format.
Returns:
- Tuple[float, float]: A tuple of (pitch, yaw) angles in radians.
+ GazeResult: Result containing pitch and yaw angles in radians.
"""
return self.estimate(face_image)
diff --git a/uniface/gaze/models.py b/uniface/gaze/models.py
index c0211d1..26c4a25 100644
--- a/uniface/gaze/models.py
+++ b/uniface/gaze/models.py
@@ -10,6 +10,7 @@ from uniface.constants import GazeWeights
from uniface.log import Logger
from uniface.model_store import verify_model_weights
from uniface.onnx_utils import create_onnx_session
+from uniface.types import GazeResult
from .base import BaseGazeEstimator
@@ -56,8 +57,8 @@ class MobileGaze(BaseGazeEstimator):
... bbox = face.bbox
... x1, y1, x2, y2 = map(int, bbox[:4])
... face_crop = image[y1:y2, x1:x2]
- ... pitch, yaw = gaze_estimator.estimate(face_crop)
- ... print(f'Gaze: pitch={np.degrees(pitch):.1f}°, yaw={np.degrees(yaw):.1f}°')
+ ... result = gaze_estimator.estimate(face_crop)
+ ... print(f'Gaze: pitch={np.degrees(result.pitch):.1f}°, yaw={np.degrees(result.yaw):.1f}°')
"""
def __init__(
@@ -142,7 +143,7 @@ class MobileGaze(BaseGazeEstimator):
e_x = np.exp(x - np.max(x, axis=1, keepdims=True))
return e_x / e_x.sum(axis=1, keepdims=True)
- def postprocess(self, outputs: tuple[np.ndarray, np.ndarray]) -> tuple[np.ndarray, np.ndarray]:
+ def postprocess(self, outputs: tuple[np.ndarray, np.ndarray]) -> GazeResult:
"""
Postprocess raw model outputs into gaze angles.
@@ -154,7 +155,7 @@ class MobileGaze(BaseGazeEstimator):
on the specific model architecture.
Returns:
- Tuple[np.ndarray, np.ndarray]: A tuple of (pitch, yaw) angles in radians.
+ GazeResult: Result containing pitch and yaw angles in radians.
"""
pitch_logits, yaw_logits = outputs
@@ -167,12 +168,12 @@ class MobileGaze(BaseGazeEstimator):
yaw_deg = np.sum(yaw_probs * self._idx_tensor, axis=1) * self._binwidth - self._angle_offset
# Convert degrees to radians
- pitch = np.radians(pitch_deg[0])
- yaw = np.radians(yaw_deg[0])
+ pitch = float(np.radians(pitch_deg[0]))
+ yaw = float(np.radians(yaw_deg[0]))
- return pitch, yaw
+ return GazeResult(pitch=pitch, yaw=yaw)
- def estimate(self, face_image: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+ def estimate(self, face_image: np.ndarray) -> GazeResult:
"""
Perform end-to-end gaze estimation on a face image.
@@ -181,6 +182,5 @@ class MobileGaze(BaseGazeEstimator):
"""
input_tensor = self.preprocess(face_image)
outputs = self.session.run(self.output_names, {self.input_name: input_tensor})
- pitch, yaw = self.postprocess((outputs[0], outputs[1]))
- return pitch, yaw
+ return self.postprocess((outputs[0], outputs[1]))
diff --git a/uniface/landmark/base.py b/uniface/landmark/base.py
index 5e33978..d167906 100644
--- a/uniface/landmark/base.py
+++ b/uniface/landmark/base.py
@@ -30,3 +30,15 @@ class BaseLandmarker(ABC):
where N is the number of landmarks.
"""
raise NotImplementedError
+
+ def __call__(self, image: np.ndarray, bbox: np.ndarray) -> np.ndarray:
+ """Callable shortcut for the `get_landmarks` method.
+
+ Args:
+ image (np.ndarray): The full source image in BGR format.
+ bbox (np.ndarray): A bounding box of a face [x1, y1, x2, y2].
+
+ Returns:
+ np.ndarray: An array of predicted landmark points with shape (N, 2).
+ """
+ return self.get_landmarks(image, bbox)
diff --git a/uniface/onnx_utils.py b/uniface/onnx_utils.py
index 7881c71..6df21d9 100644
--- a/uniface/onnx_utils.py
+++ b/uniface/onnx_utils.py
@@ -98,8 +98,7 @@ def create_onnx_session(
'CPUExecutionProvider': 'CPU',
}
provider_display = provider_names.get(active_provider, active_provider)
- Logger.debug(f'Model loaded with provider: {active_provider}')
- print(f'✓ Model loaded ({provider_display})')
+ Logger.info(f'✓ Model loaded ({provider_display})')
return session
except Exception as e:
diff --git a/uniface/recognition/base.py b/uniface/recognition/base.py
index 7145bd4..57f3588 100644
--- a/uniface/recognition/base.py
+++ b/uniface/recognition/base.py
@@ -161,3 +161,15 @@ class BaseRecognizer(ABC):
embedding = self.get_embedding(image, landmarks)
norm = np.linalg.norm(embedding)
return embedding / norm if norm > 0 else embedding
+
+ def __call__(self, image: np.ndarray, landmarks: np.ndarray) -> np.ndarray:
+ """Callable shortcut for the `get_normalized_embedding` method.
+
+ Args:
+ image: Input face image in BGR format.
+ landmarks: Facial landmarks (5 points for alignment).
+
+ Returns:
+ L2-normalized face embedding vector (typically 512-dimensional).
+ """
+ return self.get_normalized_embedding(image, landmarks)
diff --git a/uniface/spoofing/__init__.py b/uniface/spoofing/__init__.py
index 1da5136..2ffa6aa 100644
--- a/uniface/spoofing/__init__.py
+++ b/uniface/spoofing/__init__.py
@@ -5,6 +5,7 @@
from __future__ import annotations
from uniface.constants import MiniFASNetWeights
+from uniface.types import SpoofingResult
from .base import BaseSpoofer
from .minifasnet import MiniFASNet
@@ -13,6 +14,7 @@ __all__ = [
'BaseSpoofer',
'MiniFASNet',
'MiniFASNetWeights',
+ 'SpoofingResult',
'create_spoofer',
]
@@ -39,7 +41,7 @@ def create_spoofer(
Example:
>>> from uniface.spoofing import create_spoofer, MiniFASNetWeights
>>> spoofer = create_spoofer()
- >>> label_idx, score = spoofer.predict(image, face.bbox)
- >>> # label_idx: 0 = Fake, 1 = Real
+ >>> result = spoofer.predict(image, face.bbox)
+ >>> print(f'Is real: {result.is_real}, Confidence: {result.confidence:.2%}')
"""
return MiniFASNet(model_name=model_name, scale=scale)
diff --git a/uniface/spoofing/base.py b/uniface/spoofing/base.py
index 458b9c5..7f41b01 100644
--- a/uniface/spoofing/base.py
+++ b/uniface/spoofing/base.py
@@ -2,10 +2,16 @@
# Author: Yakhyokhuja Valikhujaev
# GitHub: https://github.com/yakhyo
+from __future__ import annotations
+
from abc import ABC, abstractmethod
import numpy as np
+from uniface.types import SpoofingResult
+
+__all__ = ['BaseSpoofer', 'SpoofingResult']
+
class BaseSpoofer(ABC):
"""
@@ -14,10 +20,6 @@ class BaseSpoofer(ABC):
This class defines the common interface that all anti-spoofing models must implement,
ensuring consistency across different spoofing detection methods. Anti-spoofing models
detect whether a face is real (live person) or fake (photo, video, mask, etc.).
-
- The prediction returns a tuple of (label_idx, score):
- - label_idx: 0 = Fake (spoof), 1 = Real (live)
- - score: Confidence score for the predicted label (0.0 to 1.0)
"""
@abstractmethod
@@ -54,25 +56,23 @@ class BaseSpoofer(ABC):
raise NotImplementedError('Subclasses must implement the preprocess method.')
@abstractmethod
- def postprocess(self, outputs: np.ndarray) -> tuple[int, float]:
+ def postprocess(self, outputs: np.ndarray) -> SpoofingResult:
"""
Postprocess raw model outputs into prediction result.
This method takes the raw output from the model's inference and
- converts it into a label index and confidence score.
+ converts it into a SpoofingResult.
Args:
outputs (np.ndarray): Raw outputs from the model inference (logits).
Returns:
- Tuple[int, float]: A tuple of (label_idx, score) where:
- - label_idx: 0 = Fake (spoof), 1 = Real (live)
- - score: Confidence score for the predicted label (0.0 to 1.0)
+ SpoofingResult: Result containing is_real flag and confidence score.
"""
raise NotImplementedError('Subclasses must implement the postprocess method.')
@abstractmethod
- def predict(self, image: np.ndarray, bbox: list | np.ndarray) -> tuple[int, float]:
+ def predict(self, image: np.ndarray, bbox: list | np.ndarray) -> SpoofingResult:
"""
Perform end-to-end anti-spoofing prediction on a face.
@@ -85,22 +85,20 @@ class BaseSpoofer(ABC):
This is typically obtained from a face detector.
Returns:
- Tuple[int, float]: A tuple of (label_idx, score) where:
- - label_idx: 0 = Fake (spoof), 1 = Real (live)
- - score: Confidence score for the predicted label (0.0 to 1.0)
+ SpoofingResult: Result containing is_real flag and confidence score.
Example:
>>> spoofer = MiniFASNet()
>>> detector = RetinaFace()
>>> faces = detector.detect(image)
>>> for face in faces:
- ... label_idx, score = spoofer.predict(image, face.bbox)
- ... label = 'Real' if label_idx == 1 else 'Fake'
- ... print(f'{label}: {score:.2%}')
+ ... result = spoofer.predict(image, face.bbox)
+ ... label = 'Real' if result.is_real else 'Fake'
+ ... print(f'{label}: {result.confidence:.2%}')
"""
raise NotImplementedError('Subclasses must implement the predict method.')
- def __call__(self, image: np.ndarray, bbox: list | np.ndarray) -> tuple[int, float]:
+ def __call__(self, image: np.ndarray, bbox: list | np.ndarray) -> SpoofingResult:
"""
Provides a convenient, callable shortcut for the `predict` method.
@@ -109,8 +107,6 @@ class BaseSpoofer(ABC):
bbox (Union[List, np.ndarray]): Face bounding box in [x1, y1, x2, y2] format.
Returns:
- Tuple[int, float]: A tuple of (label_idx, score) where:
- - label_idx: 0 = Fake (spoof), 1 = Real (live)
- - score: Confidence score for the predicted label (0.0 to 1.0)
+ SpoofingResult: Result containing is_real flag and confidence score.
"""
return self.predict(image, bbox)
diff --git a/uniface/spoofing/minifasnet.py b/uniface/spoofing/minifasnet.py
index 6542307..f14b020 100644
--- a/uniface/spoofing/minifasnet.py
+++ b/uniface/spoofing/minifasnet.py
@@ -10,6 +10,7 @@ from uniface.constants import MiniFASNetWeights
from uniface.log import Logger
from uniface.model_store import verify_model_weights
from uniface.onnx_utils import create_onnx_session
+from uniface.types import SpoofingResult
from .base import BaseSpoofer
@@ -58,10 +59,9 @@ class MiniFASNet(BaseSpoofer):
>>> # Detect faces and check if they are real
>>> faces = detector.detect(image)
>>> for face in faces:
- ... label_idx, score = spoofer.predict(image, face.bbox)
- ... # label_idx: 0 = Fake, 1 = Real
- ... label = 'Real' if label_idx == 1 else 'Fake'
- ... print(f'{label}: {score:.2%}')
+ ... result = spoofer.predict(image, face.bbox)
+ ... label = 'Real' if result.is_real else 'Fake'
+ ... print(f'{label}: {result.confidence:.2%}')
"""
def __init__(
@@ -180,28 +180,26 @@ class MiniFASNet(BaseSpoofer):
e_x = np.exp(x - np.max(x, axis=1, keepdims=True))
return e_x / e_x.sum(axis=1, keepdims=True)
- def postprocess(self, outputs: np.ndarray) -> tuple[int, float]:
+ def postprocess(self, outputs: np.ndarray) -> SpoofingResult:
"""
Postprocess raw model outputs into prediction result.
Applies softmax to convert logits to probabilities and
- returns the predicted label index and confidence score.
+ returns the SpoofingResult with is_real flag and confidence score.
Args:
outputs: Raw outputs from the model inference (logits).
Returns:
- Tuple[int, float]: A tuple of (label_idx, score) where:
- - label_idx: 0 = Fake (spoof), 1 = Real (live)
- - score: Confidence score for the predicted label (0.0 to 1.0)
+ SpoofingResult: Result containing is_real flag and confidence score.
"""
probs = self._softmax(outputs)
label_idx = int(np.argmax(probs))
- score = float(probs[0, label_idx])
+ confidence = float(probs[0, label_idx])
- return label_idx, score
+ return SpoofingResult(is_real=(label_idx == 1), confidence=confidence)
- def predict(self, image: np.ndarray, bbox: list | np.ndarray) -> tuple[int, float]:
+ def predict(self, image: np.ndarray, bbox: list | np.ndarray) -> SpoofingResult:
"""
Perform end-to-end anti-spoofing prediction on a face.
@@ -210,9 +208,7 @@ class MiniFASNet(BaseSpoofer):
bbox: Face bounding box in [x1, y1, x2, y2] format.
Returns:
- Tuple[int, float]: A tuple of (label_idx, score) where:
- - label_idx: 0 = Fake (spoof), 1 = Real (live)
- - score: Confidence score for the predicted label (0.0 to 1.0)
+ SpoofingResult: Result containing is_real flag and confidence score.
"""
# Preprocess
input_tensor = self.preprocess(image, bbox)
diff --git a/uniface/types.py b/uniface/types.py
new file mode 100644
index 0000000..1581e22
--- /dev/null
+++ b/uniface/types.py
@@ -0,0 +1,216 @@
+# Copyright 2025 Yakhyokhuja Valikhujaev
+# Author: Yakhyokhuja Valikhujaev
+# GitHub: https://github.com/yakhyo
+
+"""Unified type definitions for UniFace.
+
+This module centralizes all result dataclasses used across the library,
+providing consistent and immutable return types for model predictions.
+
+Note on mutability:
+- Result dataclasses (GazeResult, SpoofingResult, EmotionResult, AttributeResult)
+ are frozen (immutable) since they represent computation outputs that shouldn't change.
+- Face dataclass is mutable because FaceAnalyzer enriches it with additional
+ attributes (embedding, age, gender, etc.) after initial detection.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+
+import numpy as np
+
+from uniface.face_utils import compute_similarity
+
+__all__ = [
+ 'AttributeResult',
+ 'EmotionResult',
+ 'Face',
+ 'GazeResult',
+ 'SpoofingResult',
+]
+
+
+@dataclass(slots=True, frozen=True)
+class GazeResult:
+ """Result of gaze estimation.
+
+ Attributes:
+ pitch: Vertical gaze angle in radians (positive = up, negative = down).
+ yaw: Horizontal gaze angle in radians (positive = right, negative = left).
+ """
+
+ pitch: float
+ yaw: float
+
+ def __repr__(self) -> str:
+ return f'GazeResult(pitch={self.pitch:.4f}, yaw={self.yaw:.4f})'
+
+
+@dataclass(slots=True, frozen=True)
+class SpoofingResult:
+ """Result of face anti-spoofing detection.
+
+ Attributes:
+ is_real: True if the face is real/live, False if fake/spoof.
+ confidence: Confidence score for the prediction (0.0 to 1.0).
+ """
+
+ is_real: bool
+ confidence: float
+
+ def __repr__(self) -> str:
+ label = 'Real' if self.is_real else 'Fake'
+ return f'SpoofingResult({label}, confidence={self.confidence:.4f})'
+
+
+@dataclass(slots=True, frozen=True)
+class EmotionResult:
+ """Result of emotion recognition.
+
+ Attributes:
+ emotion: Predicted emotion label (e.g., 'Happy', 'Sad', 'Angry').
+ confidence: Confidence score for the prediction (0.0 to 1.0).
+ """
+
+ emotion: str
+ confidence: float
+
+ def __repr__(self) -> str:
+ return f"EmotionResult('{self.emotion}', confidence={self.confidence:.4f})"
+
+
+@dataclass(slots=True, frozen=True)
+class AttributeResult:
+ """Unified result structure for face attribute prediction.
+
+ This dataclass provides a consistent return type across different attribute
+ prediction models (e.g., AgeGender, FairFace), enabling interoperability
+ and unified handling of results.
+
+ Attributes:
+ gender: Predicted gender (0=Female, 1=Male).
+ age: Exact age in years. Provided by AgeGender model, None for FairFace.
+ age_group: Age range string like "20-29". Provided by FairFace, None for AgeGender.
+ race: Race/ethnicity label. Provided by FairFace only.
+
+ Properties:
+ sex: Gender as a human-readable string ("Female" or "Male").
+
+ Examples:
+ >>> # AgeGender result
+ >>> result = AttributeResult(gender=1, age=25)
+ >>> result.sex
+ 'Male'
+
+ >>> # FairFace result
+ >>> result = AttributeResult(gender=0, age_group='20-29', race='East Asian')
+ >>> result.sex
+ 'Female'
+ """
+
+ gender: int
+ age: int | None = None
+ age_group: str | None = None
+ race: str | None = None
+
+ @property
+ def sex(self) -> str:
+ """Get gender as a string label (Female or Male)."""
+ return 'Female' if self.gender == 0 else 'Male'
+
+ def __repr__(self) -> str:
+ parts = [f'gender={self.sex}']
+ if self.age is not None:
+ parts.append(f'age={self.age}')
+ if self.age_group is not None:
+ parts.append(f'age_group={self.age_group}')
+ if self.race is not None:
+ parts.append(f'race={self.race}')
+ return f'AttributeResult({", ".join(parts)})'
+
+
+@dataclass(slots=True)
+class Face:
+ """Detected face with analysis results.
+
+ This dataclass represents a single detected face along with optional
+ analysis results such as embeddings, age, gender, and race predictions.
+
+ Note: This dataclass is mutable (not frozen) because FaceAnalyzer enriches
+ Face objects with additional attributes after initial detection.
+
+ Attributes:
+ bbox: Bounding box coordinates [x1, y1, x2, y2].
+ confidence: Detection confidence score.
+ landmarks: Facial landmark coordinates (typically 5 points).
+ embedding: Face embedding vector for recognition (optional).
+ gender: Predicted gender, 0=Female, 1=Male (optional).
+ age: Predicted exact age in years (optional, from AgeGender model).
+ age_group: Predicted age range like "20-29" (optional, from FairFace).
+ race: Predicted race/ethnicity (optional, from FairFace).
+ emotion: Predicted emotion label (optional, from Emotion model).
+ emotion_confidence: Confidence score for emotion prediction (optional).
+
+ Properties:
+ sex: Gender as a human-readable string ("Female" or "Male").
+ bbox_xyxy: Bounding box in (x1, y1, x2, y2) format.
+ bbox_xywh: Bounding box in (x1, y1, width, height) format.
+ """
+
+ # Required attributes (from detection)
+ bbox: np.ndarray
+ confidence: float
+ landmarks: np.ndarray
+
+ # Optional attributes (enriched by analyzers)
+ embedding: np.ndarray | None = None
+ gender: int | None = None
+ age: int | None = None
+ age_group: str | None = None
+ race: str | None = None
+ emotion: str | None = None
+ emotion_confidence: float | None = None
+
+ def compute_similarity(self, other: Face) -> float:
+ """Compute cosine similarity with another face."""
+ if self.embedding is None or other.embedding is None:
+ raise ValueError('Both faces must have embeddings for similarity computation')
+ return float(compute_similarity(self.embedding, other.embedding))
+
+ def to_dict(self) -> dict:
+ """Convert to dictionary."""
+ return {f.name: getattr(self, f.name) for f in fields(self)}
+
+ @property
+ def sex(self) -> str | None:
+ """Get gender as a string label (Female or Male)."""
+ if self.gender is None:
+ return None
+ return 'Female' if self.gender == 0 else 'Male'
+
+ @property
+ def bbox_xyxy(self) -> np.ndarray:
+ """Get bounding box coordinates in (x1, y1, x2, y2) format."""
+ return self.bbox.copy()
+
+ @property
+ def bbox_xywh(self) -> np.ndarray:
+ """Get bounding box coordinates in (x1, y1, w, h) format."""
+ return np.array([self.bbox[0], self.bbox[1], self.bbox[2] - self.bbox[0], self.bbox[3] - self.bbox[1]])
+
+ def __repr__(self) -> str:
+ parts = [f'Face(confidence={self.confidence:.3f}']
+ if self.age is not None:
+ parts.append(f'age={self.age}')
+ if self.age_group is not None:
+ parts.append(f'age_group={self.age_group}')
+ if self.gender is not None:
+ parts.append(f'sex={self.sex}')
+ if self.race is not None:
+ parts.append(f'race={self.race}')
+ if self.emotion is not None:
+ parts.append(f'emotion={self.emotion}')
+ if self.embedding is not None:
+ parts.append(f'embedding_dim={self.embedding.shape[0]}')
+ return ', '.join(parts) + ')'