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: Add MiniFasNet for Face Anti Spoofing (#41)
Yakhyokhuja Valikhujaev3389aa3e4c33
diff --git a/MODELS.md b/MODELS.mdindex 4fe4f96..64cbaa2 100644--- a/MODELS.md+++ b/MODELS.md@@ -404,6 +404,47 @@ print(f"Detected {len(np.unique(mask))} facial components")---+## Anti-Spoofing Models++### MiniFASNet Family++Lightweight face anti-spoofing models for liveness detection. Detect if a face is real (live) or fake (photo, video replay, mask).++| Model Name | Size | Scale | Use Case |+| ---------- | ------ | ----- | ----------------------------- |+| `V1SE` | 1.2 MB | 4.0 | Squeeze-and-excitation variant |+| `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++#### Usage++```python+from uniface import RetinaFace+from uniface.spoofing import MiniFASNet+from uniface.constants import MiniFASNetWeights++# Default (V2, recommended)+detector = RetinaFace()+spoofer = MiniFASNet()++# V1SE variant+spoofer = MiniFASNet(model_name=MiniFASNetWeights.V1SE)++# Detect and check liveness+faces = detector.detect(image)+for face in faces:+ label_idx, score = spoofer.predict(image, face['bbox'])+ # label_idx: 0 = Fake, 1 = Real+ label = 'Real' if label_idx == 1 else 'Fake'+ print(f"{label}: {score:.1%}")+```++**Note**: Requires face bounding box from a detector. Use with RetinaFace, SCRFD, or YOLOv5Face.++---+## Model UpdatesModels are automatically downloaded and cached on first use. Cache location: `~/.uniface/models/`@@ -445,6 +486,7 @@ python scripts/download_model.py --model MNET_V2- **Face Recognition Training**: [yakhyo/face-recognition](https://github.com/yakhyo/face-recognition) - ArcFace, MobileFace, SphereFace training code- **Gaze Estimation Training**: [yakhyo/gaze-estimation](https://github.com/yakhyo/gaze-estimation) - MobileGaze training code and pretrained weights- **Face Parsing Training**: [yakhyo/face-parsing](https://github.com/yakhyo/face-parsing) - BiSeNet training code and pretrained weights+- **Face Anti-Spoofing**: [yakhyo/face-anti-spoofing](https://github.com/yakhyo/face-anti-spoofing) - MiniFASNet ONNX inference (weights from [minivision-ai/Silent-Face-Anti-Spoofing](https://github.com/minivision-ai/Silent-Face-Anti-Spoofing))- **InsightFace**: [deepinsight/insightface](https://github.com/deepinsight/insightface) - Model architectures and pretrained weights### Papersdiff --git a/QUICKSTART.md b/QUICKSTART.mdindex ba01448..eb76c8b 100644--- a/QUICKSTART.md+++ b/QUICKSTART.md@@ -420,7 +420,46 @@ python scripts/run_anonymization.py --image photo.jpg --method gaussian --blur-s----## 10. Batch Processing (3 minutes)+## 10. Face Anti-Spoofing (2 minutes)++Detect if a face is real or fake (photo, video replay, mask):++```python+from uniface import RetinaFace+from uniface.spoofing import MiniFASNet++detector = RetinaFace()+spoofer = MiniFASNet() # Uses V2 by default++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%})")+```++**Output:**++```+Face 1: Real (98.5%)+```++**Command-line tool:**++```bash+# Image+python scripts/run_spoofing.py --image photo.jpg++# Webcam+python scripts/run_spoofing.py --source 0+```++---++## 11. Batch Processing (3 minutes)Process multiple images:@@ -453,7 +492,7 @@ print("Done!")----## 11. Model Selection+## 12. Model SelectionChoose the right model for your use case:diff --git a/README.md b/README.mdindex f1b1e5a..6d9e46d 100644--- a/README.md+++ b/README.md@@ -23,6 +23,7 @@- **Face Parsing**: BiSeNet-based semantic segmentation with 19 facial component classes- **Gaze Estimation**: Real-time gaze direction prediction with MobileGaze- **Attribute Analysis**: Age, gender, and emotion detection+- **Anti-Spoofing**: Face liveness detection with MiniFASNet models- **Face Anonymization**: Privacy-preserving face blurring with 5 methods (pixelate, gaussian, blackout, elliptical, median)- **Face Alignment**: Precise alignment for downstream tasks- **Hardware Acceleration**: ARM64 optimizations (Apple Silicon), CUDA (NVIDIA), CPU fallback@@ -199,6 +200,25 @@ vis_result = vis_parsing_maps(face_rgb, mask, save_image=False)print(f"Unique classes: {len(np.unique(mask))}")```+### Face Anti-Spoofing++Detect if a face is real or fake (photo, video replay, mask):++```python+from uniface import RetinaFace+from uniface.spoofing import MiniFASNet++detector = RetinaFace()+spoofer = MiniFASNet() # Uses V2 by default++faces = detector.detect(image)+for face in faces:+ label_idx, score = spoofer.predict(image, face['bbox'])+ # label_idx: 0 = Fake, 1 = Real+ label = 'Real' if label_idx == 1 else 'Fake'+ print(f"{label}: {score:.1%}")+```+### Face AnonymizationProtect privacy by blurring or pixelating faces with 5 different methods:@@ -364,6 +384,12 @@ faces = detect_faces(image, method='retinaface', conf_thresh=0.8) # methods: re| ---------- | ---------------------------------------- | ------------------------------------ || `BiSeNet` | `model_name=ParsingWeights.RESNET18`, `input_size=(512, 512)` | 19 facial component classes; BiSeNet architecture with ResNet backbone |+**Anti-Spoofing**++| Class | Key params (defaults) | Notes |+| ------------- | ----------------------------------------- | ------------------------------------ |+| `MiniFASNet` | `model_name=MiniFASNetWeights.V2` | Returns (label_idx, score); 0=Fake, 1=Real |+---## Model Performance@@ -606,6 +632,7 @@ uniface/│ ├── parsing/ # Face parsing│ ├── gaze/ # Gaze estimation│ ├── attribute/ # Age, gender, emotion+│ ├── spoofing/ # Face anti-spoofing│ ├── privacy/ # Face anonymization & blurring│ ├── onnx_utils.py # ONNX Runtime utilities│ ├── model_store.py # Model download & caching@@ -624,6 +651,7 @@ uniface/- **Face Recognition Training**: [yakhyo/face-recognition](https://github.com/yakhyo/face-recognition) - ArcFace, MobileFace, SphereFace training code- **Face Parsing Training**: [yakhyo/face-parsing](https://github.com/yakhyo/face-parsing) - BiSeNet face parsing training code and pretrained weights- **Gaze Estimation Training**: [yakhyo/gaze-estimation](https://github.com/yakhyo/gaze-estimation) - MobileGaze training code and pretrained weights+- **Face Anti-Spoofing**: [yakhyo/face-anti-spoofing](https://github.com/yakhyo/face-anti-spoofing) - MiniFASNet ONNX inference (weights from [minivision-ai/Silent-Face-Anti-Spoofing](https://github.com/minivision-ai/Silent-Face-Anti-Spoofing))- **InsightFace**: [deepinsight/insightface](https://github.com/deepinsight/insightface) - Model architectures and pretrained weights## Contributingdiff --git a/examples/face_anonymization.ipynb b/examples/face_anonymization.ipynbindex ac80fdd..686b89a 100644--- a/examples/face_anonymization.ipynb+++ b/examples/face_anonymization.ipynb@@ -159,7 +159,7 @@},{"cell_type": "code",- "execution_count": 5,+ "execution_count": null,"metadata": {},"outputs": [{diff --git a/scripts/run_anonymization.py b/scripts/run_anonymization.pyindex 1e2e00c..3c8d432 100644--- a/scripts/run_anonymization.py+++ b/scripts/run_anonymization.py@@ -205,3 +205,4 @@ Examples:if __name__ == '__main__':main()+diff --git a/scripts/run_spoofing.py b/scripts/run_spoofing.pynew file mode 100644index 0000000..e30bb9b--- /dev/null+++ b/scripts/run_spoofing.py@@ -0,0 +1,201 @@+# 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/uniface/__init__.py b/uniface/__init__.pyindex 2c9d42f..dc8ea3d 100644--- a/uniface/__init__.py+++ b/uniface/__init__.py@@ -42,6 +42,7 @@ from .landmark import Landmark106, create_landmarkerfrom .parsing import BiSeNet, create_face_parserfrom .privacy import BlurFace, anonymize_facesfrom .recognition import ArcFace, MobileFace, SphereFace, create_recognizer+from .spoofing import MiniFASNet, create_spoofer__all__ = ['__author__',@@ -56,6 +57,7 @@ __all__ = ['create_gaze_estimator','create_landmarker','create_recognizer',+ 'create_spoofer','detect_faces','list_available_detectors',# Detection models@@ -75,6 +77,8 @@ __all__ = [# Attribute models'AgeGender','Emotion',+ # Spoofing models+ 'MiniFASNet',# Privacy'BlurFace','anonymize_faces',diff --git a/uniface/constants.py b/uniface/constants.pyindex 9752513..7ad08f6 100644--- a/uniface/constants.py+++ b/uniface/constants.py@@ -119,6 +119,20 @@ class ParsingWeights(str, Enum):RESNET34 = "parsing_resnet34"+class MiniFASNetWeights(str, Enum):+ """+ MiniFASNet: Lightweight Face Anti-Spoofing models.+ Trained on face anti-spoofing datasets.+ https://github.com/yakhyo/face-anti-spoofing++ Model Variants:+ - V1SE: Uses scale=4.0 for face crop (squeese-and-excitation version)+ - V2: Uses scale=2.7 for face crop (improved version)+ """+ V1SE = "minifasnet_v1se"+ V2 = "minifasnet_v2"++MODEL_URLS: Dict[Enum, str] = {# RetinaFaceRetinaFaceWeights.MNET_025: 'https://github.com/yakhyo/uniface/releases/download/weights/retinaface_mv1_0.25.onnx',@@ -161,6 +175,9 @@ MODEL_URLS: Dict[Enum, str] = {# ParsingParsingWeights.RESNET18: 'https://github.com/yakhyo/face-parsing/releases/download/weights/resnet18.onnx',ParsingWeights.RESNET34: 'https://github.com/yakhyo/face-parsing/releases/download/weights/resnet34.onnx',+ # Anti-Spoofing (MiniFASNet)+ MiniFASNetWeights.V1SE: 'https://github.com/yakhyo/face-anti-spoofing/releases/download/weights/MiniFASNetV1SE.onnx',+ MiniFASNetWeights.V2: 'https://github.com/yakhyo/face-anti-spoofing/releases/download/weights/MiniFASNetV2.onnx',}MODEL_SHA256: Dict[Enum, str] = {@@ -205,6 +222,9 @@ MODEL_SHA256: Dict[Enum, str] = {# Face ParsingParsingWeights.RESNET18: '0d9bd318e46987c3bdbfacae9e2c0f461cae1c6ac6ea6d43bbe541a91727e33f',ParsingWeights.RESNET34: '5b805bba7b5660ab7070b5a381dcf75e5b3e04199f1e9387232a77a00095102e',+ # Anti-Spoofing (MiniFASNet)+ MiniFASNetWeights.V1SE: 'ebab7f90c7833fbccd46d3a555410e78d969db5438e169b6524be444862b3676',+ MiniFASNetWeights.V2: 'b32929adc2d9c34b9486f8c4c7bc97c1b69bc0ea9befefc380e4faae4e463907',}CHUNK_SIZE = 8192diff --git a/uniface/spoofing/__init__.py b/uniface/spoofing/__init__.pynew file mode 100644index 0000000..352140e--- /dev/null+++ b/uniface/spoofing/__init__.py@@ -0,0 +1,64 @@+# Copyright 2025 Yakhyokhuja Valikhujaev+# Author: Yakhyokhuja Valikhujaev+# GitHub: https://github.com/yakhyo++from typing import Optional++from uniface.constants import MiniFASNetWeights++from .base import BaseSpoofer+from .minifasnet import MiniFASNet++__all__ = [+ 'BaseSpoofer',+ 'MiniFASNet',+ 'MiniFASNetWeights',+ 'create_spoofer',+]+++def create_spoofer(+ model_name: MiniFASNetWeights = MiniFASNetWeights.V2,+ scale: Optional[float] = None,+) -> MiniFASNet:+ """+ Factory function to create a face anti-spoofing model.++ This is a convenience function that creates a MiniFASNet instance+ with the specified model variant and optional custom scale.++ Args:+ model_name (MiniFASNetWeights): The model variant to use.+ Options:+ - MiniFASNetWeights.V2: Improved version (default), uses scale=2.7+ - MiniFASNetWeights.V1SE: Squeeze-and-excitation version, uses scale=4.0+ Defaults to MiniFASNetWeights.V2.+ scale (Optional[float]): Custom crop scale factor for face region.+ If None, uses the default scale for the selected model variant.++ Returns:+ MiniFASNet: An initialized face anti-spoofing model.++ Example:+ >>> from uniface.spoofing import create_spoofer, MiniFASNetWeights+ >>> from uniface import RetinaFace+ >>>+ >>> # Create with default settings (V2 model)+ >>> spoofer = create_spoofer()+ >>>+ >>> # Create with V1SE model+ >>> spoofer = create_spoofer(model_name=MiniFASNetWeights.V1SE)+ >>>+ >>> # Create with custom scale+ >>> spoofer = create_spoofer(scale=3.0)+ >>>+ >>> # Use with face detector+ >>> detector = RetinaFace()+ >>> 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%}')+ """+ return MiniFASNet(model_name=model_name, scale=scale)diff --git a/uniface/spoofing/base.py b/uniface/spoofing/base.pynew file mode 100644index 0000000..b16decd--- /dev/null+++ b/uniface/spoofing/base.py@@ -0,0 +1,117 @@+# Copyright 2025 Yakhyokhuja Valikhujaev+# Author: Yakhyokhuja Valikhujaev+# GitHub: https://github.com/yakhyo++from abc import ABC, abstractmethod+from typing import List, Tuple, Union++import numpy as np+++class BaseSpoofer(ABC):+ """+ Abstract base class for all face anti-spoofing models.++ This class defines the common interface that all anti-spoofing models must implement,+ ensuring consistency across different spoofing detection methods. Anti-spoofing models+ detect whether a face is real (live person) or fake (photo, video, mask, etc.).++ The prediction returns a tuple of (label_idx, score):+ - label_idx: 0 = Fake (spoof), 1 = Real (live)+ - score: Confidence score for the predicted label (0.0 to 1.0)+ """++ @abstractmethod+ def _initialize_model(self) -> None:+ """+ Initialize the underlying model for inference.++ This method should handle loading model weights, creating the+ inference session (e.g., ONNX Runtime), and any necessary+ setup procedures to prepare the model for prediction.++ Raises:+ RuntimeError: If the model fails to load or initialize.+ """+ raise NotImplementedError('Subclasses must implement the _initialize_model method.')++ @abstractmethod+ def preprocess(self, image: np.ndarray, bbox: Union[List, np.ndarray]) -> np.ndarray:+ """+ Preprocess the input image for model inference.++ This method should crop the face region using the bounding box,+ resize it to the model's expected input size, and normalize+ the pixel values as required by the model.++ Args:+ image (np.ndarray): Input image in BGR format with shape (H, W, C).+ bbox (Union[List, np.ndarray]): Face bounding box in [x1, y1, x2, y2] format.++ Returns:+ np.ndarray: The preprocessed image tensor ready for inference,+ typically with shape (1, C, H, W).+ """+ raise NotImplementedError('Subclasses must implement the preprocess method.')++ @abstractmethod+ def postprocess(self, outputs: np.ndarray) -> Tuple[int, float]:+ """+ 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.++ 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)+ """+ raise NotImplementedError('Subclasses must implement the postprocess method.')++ @abstractmethod+ def predict(self, image: np.ndarray, bbox: Union[List, np.ndarray]) -> Tuple[int, float]:+ """+ Perform end-to-end anti-spoofing prediction on a face.++ This method orchestrates the full pipeline: preprocessing the input,+ running inference, and postprocessing to return the prediction.++ Args:+ image (np.ndarray): Input image in BGR format containing the face.+ bbox (Union[List, np.ndarray]): Face bounding box in [x1, y1, x2, y2] format.+ 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)++ 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%}')+ """+ raise NotImplementedError('Subclasses must implement the predict method.')++ def __call__(self, image: np.ndarray, bbox: Union[List, np.ndarray]) -> Tuple[int, float]:+ """+ Provides a convenient, callable shortcut for the `predict` method.++ Args:+ image (np.ndarray): Input image in BGR format.+ 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)+ """+ return self.predict(image, bbox)diff --git a/uniface/spoofing/minifasnet.py b/uniface/spoofing/minifasnet.pynew file mode 100644index 0000000..0a43885--- /dev/null+++ b/uniface/spoofing/minifasnet.py@@ -0,0 +1,225 @@+# Copyright 2025 Yakhyokhuja Valikhujaev+# Author: Yakhyokhuja Valikhujaev+# GitHub: https://github.com/yakhyo++from typing import List, Optional, Tuple, Union++import cv2+import numpy as np++from uniface.constants import MiniFASNetWeights+from uniface.log import Logger+from uniface.model_store import verify_model_weights+from uniface.onnx_utils import create_onnx_session++from .base import BaseSpoofer++__all__ = ['MiniFASNet']++# Default crop scales for each model variant+DEFAULT_SCALES = {+ MiniFASNetWeights.V1SE: 4.0,+ MiniFASNetWeights.V2: 2.7,+}+++class MiniFASNet(BaseSpoofer):+ """+ MiniFASNet: Lightweight Face Anti-Spoofing with ONNX Runtime.++ MiniFASNet is a face anti-spoofing model that detects whether a face is real+ (live person) or fake (photo, video replay, mask, etc.). It supports two model+ variants: V1SE (with squeeze-and-excitation) and V2 (improved version).++ The model takes a face region cropped from the image using a bounding box+ and predicts whether it's a real or spoofed face.++ Reference:+ https://github.com/yakhyo/face-anti-spoofing++ Args:+ model_name (MiniFASNetWeights): The enum specifying the model variant to load.+ Options: V1SE (scale=4.0), V2 (scale=2.7).+ Defaults to `MiniFASNetWeights.V2`.+ scale (Optional[float]): Custom crop scale factor for face region.+ If None, uses the default scale for the selected model variant.+ V1SE uses 4.0, V2 uses 2.7.++ Attributes:+ scale (float): Crop scale factor for face region extraction.+ input_size (Tuple[int, int]): Model input dimensions (width, height).++ Example:+ >>> from uniface.spoofing import MiniFASNet+ >>> from uniface import RetinaFace+ >>>+ >>> detector = RetinaFace()+ >>> spoofer = MiniFASNet()+ >>>+ >>> # 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%}')+ """++ def __init__(+ self,+ model_name: MiniFASNetWeights = MiniFASNetWeights.V2,+ scale: Optional[float] = None,+ ) -> None:+ Logger.info(f'Initializing MiniFASNet with model={model_name.name}')++ # Use default scale for the model variant if not specified+ self.scale = scale if scale is not None else DEFAULT_SCALES.get(model_name, 2.7)++ self.model_path = verify_model_weights(model_name)+ self._initialize_model()++ def _initialize_model(self) -> None:+ """+ Initialize the ONNX model from the stored model path.++ Raises:+ RuntimeError: If the model fails to load or initialize.+ """+ try:+ self.session = create_onnx_session(self.model_path)++ # Get input configuration+ input_cfg = self.session.get_inputs()[0]+ self.input_name = input_cfg.name+ # Input shape is (batch, channels, height, width) - we need (width, height)+ self.input_size = tuple(input_cfg.shape[2:4][::-1]) # (width, height)++ # Get output configuration+ output_cfg = self.session.get_outputs()[0]+ self.output_name = output_cfg.name++ Logger.info(f'MiniFASNet initialized with input size {self.input_size}, scale={self.scale}')++ except Exception as e:+ Logger.error(f"Failed to load MiniFASNet model from '{self.model_path}'", exc_info=True)+ raise RuntimeError(f'Failed to initialize MiniFASNet model: {e}') from e++ def _xyxy_to_xywh(self, bbox: Union[List, np.ndarray]) -> List[int]:+ """Convert bounding box from [x1, y1, x2, y2] to [x, y, w, h] format."""+ x1, y1, x2, y2 = bbox[:4]+ return [int(x1), int(y1), int(x2 - x1), int(y2 - y1)]++ def _crop_face(self, image: np.ndarray, bbox_xywh: List[int]) -> np.ndarray:+ """+ Crop and resize face region from image using scale factor.++ The crop is centered on the face bounding box and scaled to capture+ more context around the face, which is important for anti-spoofing.++ Args:+ image: Input image in BGR format.+ bbox_xywh: Face bounding box in [x, y, w, h] format.++ Returns:+ Cropped and resized face region.+ """+ src_h, src_w = image.shape[:2]+ x, y, box_w, box_h = bbox_xywh++ # Calculate the scale to apply based on image and face size+ scale = min((src_h - 1) / box_h, (src_w - 1) / box_w, self.scale)+ new_w = box_w * scale+ new_h = box_h * scale++ # Calculate center of the bounding box+ center_x = x + box_w / 2+ center_y = y + box_h / 2++ # Calculate new bounding box coordinates+ x1 = max(0, int(center_x - new_w / 2))+ y1 = max(0, int(center_y - new_h / 2))+ x2 = min(src_w - 1, int(center_x + new_w / 2))+ y2 = min(src_h - 1, int(center_y + new_h / 2))++ # Crop and resize+ cropped = image[y1 : y2 + 1, x1 : x2 + 1]+ resized = cv2.resize(cropped, self.input_size)++ return resized++ def preprocess(self, image: np.ndarray, bbox: Union[List, np.ndarray]) -> np.ndarray:+ """+ Preprocess the input image for model inference.++ Crops the face region, converts to float32, and arranges+ dimensions for the model (NCHW format).++ Args:+ image: Input image in BGR format with shape (H, W, C).+ bbox: Face bounding box in [x1, y1, x2, y2] format.++ Returns:+ Preprocessed image tensor with shape (1, C, H, W).+ """+ # Convert bbox format+ bbox_xywh = self._xyxy_to_xywh(bbox)++ # Crop and resize face region+ face = self._crop_face(image, bbox_xywh)++ # Convert to float32 (no normalization needed for this model)+ face = face.astype(np.float32)++ # HWC -> CHW -> NCHW+ face = np.transpose(face, (2, 0, 1))+ face = np.expand_dims(face, axis=0)++ return face++ def _softmax(self, x: np.ndarray) -> np.ndarray:+ """Apply softmax to logits along axis 1."""+ 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]:+ """+ Postprocess raw model outputs into prediction result.++ Applies softmax to convert logits to probabilities and+ returns the predicted label index 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)+ """+ probs = self._softmax(outputs)+ label_idx = int(np.argmax(probs))+ score = float(probs[0, label_idx])++ return label_idx, score++ def predict(self, image: np.ndarray, bbox: Union[List, np.ndarray]) -> Tuple[int, float]:+ """+ Perform end-to-end anti-spoofing prediction on a face.++ Args:+ image: Input image in BGR format containing the face.+ 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)+ """+ # Preprocess+ input_tensor = self.preprocess(image, bbox)++ # Run inference+ outputs = self.session.run([self.output_name], {self.input_name: input_tensor})[0]++ # Postprocess and return+ return self.postprocess(outputs)