UniFace: A Unified Face Analysis Library for Python | Detection, alignment, landmarks, face-mesh, recognition, parsing, gaze, attributes and anti-spoofing under one API.
Python computer-visiondeep-learningface-alignmentface-analysisface-anonymizationface-anti-spoofingface-attributesface-detectionface-meshface-parsingface-quality-assessmentface-recognitionface-segmentationface-trackingfacial-landmarksgaze-estimationhead-pose-estimationonnxruntimeportrait-mattingpython
feat: Common result dataclasses and refactoring several methods. (#50)
Yakhyokhuja Valikhujaevcbcd89b1674e
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yamlindex 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.0hooks:- 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.10hooks:- id: ruffargs: [--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.2hooks:- id: banditargs: [-c, pyproject.toml]diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 hashes3. **Export in `__init__.py`** files at both module and package levels4. **Write tests** in `tests/` directory-5. **Add example usage** in `scripts/` or update existing notebooks+5. **Add example usage** in `tools/` or update existing notebooks6. **Update documentation** if needed## Examplesdiff --git a/MODELS.md b/MODELS.mdindex 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 Emotionfrom uniface.constants import DDAMFNWeightspredictor = 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 RESNET34gaze_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 livenessfaces = 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.mdindex 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.mdindex 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 defaultfaces = 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.ipynbindex 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.mddeleted file mode 100644index 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.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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.pynew file mode 100644index 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.mdnew file mode 100644index 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.pynew file mode 100644index 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.pysimilarity index 92%rename from scripts/batch_process.pyrename to tools/batch_process.pyindex 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 argparsefrom pathlib import Pathdiff --git a/tools/detection.py b/tools/detection.pynew file mode 100644index 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.pysimilarity index 100%rename from scripts/download_model.pyrename to tools/download_model.pydiff --git a/tools/face_analyzer.py b/tools/face_analyzer.pynew file mode 100644index 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.pysimilarity index 54%rename from scripts/run_anonymization.pyrename to tools/face_anonymize.pyindex 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 annotationsimport argparseimport os+from pathlib import Pathimport cv2from uniface import RetinaFacefrom 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 facesfaces = detector.detect(image)print(f'Detected {len(faces)} face(s)')- # Optionally draw detection boxes before blurringif 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 previewcv2.imshow('Detections (Press any key to continue)', preview)cv2.waitKey(0)cv2.destroyAllWindows()- # Anonymize facesif faces:anonymized = blurrer.anonymize(image, faces)else:anonymized = image- # Save outputos.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}')returnprint("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 anonymizefaces = detector.detect(frame)if faces:frame = blurrer.anonymize(frame, faces, inplace=True)- # Display infocv2.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 methodparser.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 colorcolor_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.pynew file mode 100644index 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.pysimilarity index 52%rename from scripts/run_face_parsing.pyrename to tools/face_parsing.pyindex 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 annotationsimport argparseimport os@@ -14,6 +24,23 @@ from uniface.constants import ParsingWeightsfrom uniface.parsing import BiSeNetfrom 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 dimensionsface_width = x2 - x1face_height = y2 - y1- # Calculate expansion amountsexpand_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 boundariesnew_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 parsingx1, 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 facemask = parser.parse(face_crop)print(f' Face {i + 1}: parsed with {len(set(mask.flatten()))} unique classes')- # Visualize the parsing resultface_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 imageresult_image[y1:y2, x1:x2] = vis_result-- # Draw expanded bounding boxcv2.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}')returnprint("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 parsingx1, 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 facemask = parser.parse(face_crop)-- # Visualize the parsing resultface_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 frameframe[y1:y2, x1:x2] = vis_result-- # Draw expanded bounding boxcv2.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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pysimilarity index 91%rename from scripts/run_recognition.pyrename to tools/recognition.pyindex 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 argparsediff --git a/scripts/sha256_generate.py b/tools/sha256_generate.pysimilarity index 100%rename from scripts/sha256_generate.pyrename to tools/sha256_generate.pydiff --git a/tools/spoofing.py b/tools/spoofing.pynew file mode 100644index 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.pynew file mode 100644index 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__.pyindex c8ba0da..aa9b611 100644--- a/uniface/__init__.py+++ b/uniface/__init__.py@@ -36,7 +36,7 @@ from uniface.model_store import verify_model_weightsfrom uniface.visualization import draw_detections, vis_parsing_mapsfrom .analyzer import FaceAnalyzer-from .attribute import AgeGender, AttributeResult, FairFace+from .attribute import AgeGender, FairFacefrom .detection import (SCRFD,RetinaFace,@@ -45,13 +45,13 @@ from .detection import (detect_faces,list_available_detectors,)-from .face import Facefrom .gaze import MobileGaze, create_gaze_estimatorfrom .landmark import Landmark106, create_landmarkerfrom .parsing import BiSeNet, create_face_parserfrom .privacy import BlurFace, anonymize_facesfrom .recognition import ArcFace, MobileFace, SphereFace, create_recognizerfrom .spoofing import MiniFASNet, create_spoofer+from .types import AttributeResult, EmotionResult, Face, GazeResult, SpoofingResult# Optional: Emotion requires PyTorchEmotion: 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.pyindex 0816641..5c966e6 100644--- a/uniface/analyzer.py+++ b/uniface/analyzer.py@@ -9,9 +9,9 @@ import numpy as npfrom uniface.attribute.age_gender import AgeGenderfrom uniface.attribute.fairface import FairFacefrom uniface.detection.base import BaseDetector-from uniface.face import Facefrom uniface.log import Loggerfrom uniface.recognition.base import BaseRecognizer+from uniface.types import Face__all__ = ['FaceAnalyzer']diff --git a/uniface/attribute/__init__.py b/uniface/attribute/__init__.pyindex 3ce4dfe..7f96923 100644--- a/uniface/attribute/__init__.py+++ b/uniface/attribute/__init__.py@@ -9,10 +9,10 @@ from typing import Anyimport numpy as npfrom uniface.attribute.age_gender import AgeGender-from uniface.attribute.base import Attribute, AttributeResult+from uniface.attribute.base import Attributefrom uniface.attribute.fairface import FairFacefrom uniface.constants import AgeGenderWeights, DDAMFNWeights, FairFaceWeights-from uniface.face import Face+from uniface.types import AttributeResult, EmotionResult, Face# Emotion requires PyTorch - make it optionaltry:@@ -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: Attributface.age_group = result.age_groupface.race = result.raceelif 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.confidencereturn facesdiff --git a/uniface/attribute/age_gender.py b/uniface/attribute/age_gender.pyindex 4833790..cd5798d 100644--- a/uniface/attribute/age_gender.py+++ b/uniface/attribute/age_gender.py@@ -6,12 +6,13 @@import cv2import numpy as np-from uniface.attribute.base import Attribute, AttributeResult+from uniface.attribute.base import Attributefrom uniface.constants import AgeGenderWeightsfrom uniface.face_utils import bbox_center_alignmentfrom uniface.log import Loggerfrom uniface.model_store import verify_model_weightsfrom 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.pyindex 72afead..7287846 100644--- a/uniface/attribute/base.py+++ b/uniface/attribute/base.py@@ -3,57 +3,13 @@# GitHub: https://github.com/yakhyofrom abc import ABC, abstractmethod-from dataclasses import dataclassfrom typing import Anyimport 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.pyindex 1677aa6..a722427 100644--- a/uniface/attribute/emotion.py+++ b/uniface/attribute/emotion.py@@ -12,6 +12,7 @@ from uniface.constants import DDAMFNWeightsfrom uniface.face_utils import face_alignmentfrom uniface.log import Loggerfrom 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.pyindex e9521c4..abb8e42 100644--- a/uniface/attribute/fairface.py+++ b/uniface/attribute/fairface.py@@ -6,11 +6,12 @@import cv2import numpy as np-from uniface.attribute.base import Attribute, AttributeResult+from uniface.attribute.base import Attributefrom uniface.constants import FairFaceWeightsfrom uniface.log import Loggerfrom uniface.model_store import verify_model_weightsfrom 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__.pyindex d8a58bf..d7317ed 100644--- a/uniface/detection/__init__.py+++ b/uniface/detection/__init__.py@@ -8,7 +8,7 @@ from typing import Anyimport numpy as np-from uniface.face import Face+from uniface.types import Facefrom .base import BaseDetectorfrom .retinaface import RetinaFacediff --git a/uniface/detection/base.py b/uniface/detection/base.pyindex 05afd09..2b700f5 100644--- a/uniface/detection/base.py+++ b/uniface/detection/base.py@@ -9,7 +9,7 @@ from typing import Anyimport 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.pyindex 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 Facefrom uniface.log import Loggerfrom uniface.model_store import verify_model_weightsfrom uniface.onnx_utils import create_onnx_session+from uniface.types import Facefrom .base import BaseDetectordiff --git a/uniface/detection/scrfd.py b/uniface/detection/scrfd.pyindex 1eee8b9..7d5c750 100644--- a/uniface/detection/scrfd.py+++ b/uniface/detection/scrfd.py@@ -10,10 +10,10 @@ import numpy as npfrom uniface.common import distance2bbox, distance2kps, non_max_suppression, resize_imagefrom uniface.constants import SCRFDWeights-from uniface.face import Facefrom uniface.log import Loggerfrom uniface.model_store import verify_model_weightsfrom uniface.onnx_utils import create_onnx_session+from uniface.types import Facefrom .base import BaseDetectordiff --git a/uniface/detection/yolov5.py b/uniface/detection/yolov5.pyindex b952ab1..7f99771 100644--- a/uniface/detection/yolov5.py+++ b/uniface/detection/yolov5.py@@ -9,10 +9,10 @@ import numpy as npfrom uniface.common import non_max_suppressionfrom uniface.constants import YOLOv5FaceWeights-from uniface.face import Facefrom uniface.log import Loggerfrom uniface.model_store import verify_model_weightsfrom uniface.onnx_utils import create_onnx_session+from uniface.types import Facefrom .base import BaseDetectordiff --git a/uniface/face.py b/uniface/face.pydeleted file mode 100644index 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__.pyindex 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 BaseGazeEstimatorfrom .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) -> BaseGazeEstimraise 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.pyindex 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, abstractmethodimport 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.pyindex c0211d1..26c4a25 100644--- a/uniface/gaze/models.py+++ b/uniface/gaze/models.py@@ -10,6 +10,7 @@ from uniface.constants import GazeWeightsfrom uniface.log import Loggerfrom uniface.model_store import verify_model_weightsfrom uniface.onnx_utils import create_onnx_session+from uniface.types import GazeResultfrom .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.pyindex 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.pyindex 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 sessionexcept Exception as e:diff --git a/uniface/recognition/base.py b/uniface/recognition/base.pyindex 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__.pyindex 1da5136..2ffa6aa 100644--- a/uniface/spoofing/__init__.py+++ b/uniface/spoofing/__init__.py@@ -5,6 +5,7 @@from __future__ import annotationsfrom uniface.constants import MiniFASNetWeights+from uniface.types import SpoofingResultfrom .base import BaseSpooferfrom .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.pyindex 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, abstractmethodimport 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 modelsdetect 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.pyindex 6542307..f14b020 100644--- a/uniface/spoofing/minifasnet.py+++ b/uniface/spoofing/minifasnet.py@@ -10,6 +10,7 @@ from uniface.constants import MiniFASNetWeightsfrom uniface.log import Loggerfrom uniface.model_store import verify_model_weightsfrom uniface.onnx_utils import create_onnx_session+from uniface.types import SpoofingResultfrom .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."""# Preprocessinput_tensor = self.preprocess(image, bbox)diff --git a/uniface/types.py b/uniface/types.pynew file mode 100644index 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) + ')'