similarfaces 1.0.0__tar.gz

similarfaces-1.0.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: similarfaces
+Version: 1.0.0
+Summary: A production-ready Face Recognition library powered by ONNX
+Author-email: Narek <your.email@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/narek/similarfaces
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: opencv-python>=4.5.1
+Requires-Dist: onnxruntime>=1.15.0
+Requires-Dist: scikit-image>=0.19.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: matplotlib>=3.5.0
+
+# similarfaces: High-Performance Face Recognition
+
+A production-ready, clean, and robust face recognition pipeline powered by ONNX Runtime.
+
+---
+
+## 🌟 Overview
+
+**similarfaces** is a streamlined, high-performance Python library for face detection, alignment, quality assessment, and recognition. Designed with modularity and ease of use in mind, it provides a functional API that leverages state-of-the-art models optimized for ONNX Runtime.
+
+### ✨ New Key Features
+
+- 🏗️ **Functional API**: Clean and intuitive functional wrappers (`detect_faces`, `extract_features`, `compare_faces`, `align_face`) without the need to manually manage processor objects.
+- 📦 **Structured Data Models**: All functions utilize a unified `Face` dataclass, ensuring type safety and easy access to bounding boxes, landmarks, quality scores, and embeddings.
+- 🎯 **Integrated Detection & Quality**: `detect_faces()` now performs both robust face localization and automatic quality assessment in a single, efficient pass.
+- 📐 **Optimal Alignment**: Similarity transforms for standardized 112x112 face cropping.
+- 🧠 **High-accuracy Recognition**: Extract deep feature embeddings for high-accuracy face comparison.
+- ⚡ **ONNX Powered**: Sub-millisecond inference speeds with minimal dependencies across CPU and GPU environments.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install -r requirements.txt
+pip install -e .  # Install in editable mode for development
+```
+
+### Basic Usage
+
+Compare two faces with high-quality filtering using the functional API:
+
+```python
+import cv2
+from similarfaces import detect_faces, extract_features, compare_faces
+
+# Load images (cv2 loads as BGR)
+img1 = cv2.imread("images/image1.png")
+img2 = cv2.imread("images/image2.png")
+
+# Detect faces (includes quality scores by default)
+faces1 = detect_faces(img1)
+faces2 = detect_faces(img2)
+
+if faces1 and faces2:
+    # Pick the best face from each image based on quality score
+    face1 = max(faces1, key=lambda x: x.quality_score)
+    face2 = max(faces2, key=lambda x: x.quality_score)
+
+    # Extract embeddings
+    face1.embedding = extract_features(img1, face1)
+    face2.embedding = extract_features(img2, face2)
+
+    # Compare faces
+    similarity = compare_faces(face1, face2)
+    print(f"Similarity: {similarity:.4f}")
+    
+    if similarity > 0.6:
+        print("Outcome: Matches (Same Person)")
+    else:
+        print("Outcome: No Match")
+else:
+    print("Error: Could not find faces in one or both images.")
+```
+
+---
+
+## 🛠 Project Structure
+
+The library is designed to be developer-friendly and easy to extend:
+
+- `similarfaces.detector`: High-performance face detection logic.
+- `similarfaces.aligner`: Face alignment and warping.
+- `similarfaces.scorer`: Quality assessment model.
+- `similarfaces.encoder`: Feature embedding extraction.
+- `similarfaces.models`: Data models including the unified `Face` dataclass.
+
+---
+
+## 📊 Performance
+
+| Module | Model | Input Size | Accuracy |
+| :--- | :--- | :--- | :--- |
+| **Detection** | MobileNet-based | 640x640 | High |
+| **Recognition** | IR50-based | 112x112 | SOTA |
+| **Quality** | FaceQuality-ONNX | 128x128 | Robust |
+
+---
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+<p align="center">
+  Developed with ❤️ by Narek Bektashyan
+</p>

similarfaces-1.0.0/README.md

@@ -0,0 +1,100 @@
+# similarfaces: High-Performance Face Recognition
+
+A production-ready, clean, and robust face recognition pipeline powered by ONNX Runtime.
+
+---
+
+## 🌟 Overview
+
+**similarfaces** is a streamlined, high-performance Python library for face detection, alignment, quality assessment, and recognition. Designed with modularity and ease of use in mind, it provides a functional API that leverages state-of-the-art models optimized for ONNX Runtime.
+
+### ✨ New Key Features
+
+- 🏗️ **Functional API**: Clean and intuitive functional wrappers (`detect_faces`, `extract_features`, `compare_faces`, `align_face`) without the need to manually manage processor objects.
+- 📦 **Structured Data Models**: All functions utilize a unified `Face` dataclass, ensuring type safety and easy access to bounding boxes, landmarks, quality scores, and embeddings.
+- 🎯 **Integrated Detection & Quality**: `detect_faces()` now performs both robust face localization and automatic quality assessment in a single, efficient pass.
+- 📐 **Optimal Alignment**: Similarity transforms for standardized 112x112 face cropping.
+- 🧠 **High-accuracy Recognition**: Extract deep feature embeddings for high-accuracy face comparison.
+- ⚡ **ONNX Powered**: Sub-millisecond inference speeds with minimal dependencies across CPU and GPU environments.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install -r requirements.txt
+pip install -e .  # Install in editable mode for development
+```
+
+### Basic Usage
+
+Compare two faces with high-quality filtering using the functional API:
+
+```python
+import cv2
+from similarfaces import detect_faces, extract_features, compare_faces
+
+# Load images (cv2 loads as BGR)
+img1 = cv2.imread("images/image1.png")
+img2 = cv2.imread("images/image2.png")
+
+# Detect faces (includes quality scores by default)
+faces1 = detect_faces(img1)
+faces2 = detect_faces(img2)
+
+if faces1 and faces2:
+    # Pick the best face from each image based on quality score
+    face1 = max(faces1, key=lambda x: x.quality_score)
+    face2 = max(faces2, key=lambda x: x.quality_score)
+
+    # Extract embeddings
+    face1.embedding = extract_features(img1, face1)
+    face2.embedding = extract_features(img2, face2)
+
+    # Compare faces
+    similarity = compare_faces(face1, face2)
+    print(f"Similarity: {similarity:.4f}")
+    
+    if similarity > 0.6:
+        print("Outcome: Matches (Same Person)")
+    else:
+        print("Outcome: No Match")
+else:
+    print("Error: Could not find faces in one or both images.")
+```
+
+---
+
+## 🛠 Project Structure
+
+The library is designed to be developer-friendly and easy to extend:
+
+- `similarfaces.detector`: High-performance face detection logic.
+- `similarfaces.aligner`: Face alignment and warping.
+- `similarfaces.scorer`: Quality assessment model.
+- `similarfaces.encoder`: Feature embedding extraction.
+- `similarfaces.models`: Data models including the unified `Face` dataclass.
+
+---
+
+## 📊 Performance
+
+| Module | Model | Input Size | Accuracy |
+| :--- | :--- | :--- | :--- |
+| **Detection** | MobileNet-based | 640x640 | High |
+| **Recognition** | IR50-based | 112x112 | SOTA |
+| **Quality** | FaceQuality-ONNX | 128x128 | Robust |
+
+---
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+<p align="center">
+  Developed with ❤️ by Narek Bektashyan
+</p>

similarfaces-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "similarfaces"
+version = "1.0.0"
+description = "A production-ready Face Recognition library powered by ONNX"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Narek", email = "your.email@example.com"}
+]
+dependencies = [
+    "numpy>=1.20.0",
+    "opencv-python>=4.5.1",
+    "onnxruntime>=1.15.0",
+    "scikit-image>=0.19.0",
+    "scipy>=1.7.0",
+    "Pillow>=9.0.0",
+    "matplotlib>=3.5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/narek/similarfaces"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["similarfaces*"]

similarfaces-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

similarfaces-1.0.0/similarfaces/__init__.py

@@ -0,0 +1,93 @@
+from .detector import FaceDetector
+from .encoder import FaceEncoder
+from .aligner import FaceAligner
+from .scorer import FaceQualityScorer
+from .models import Face
+
+__version__ = "1.0.0"
+
+# Lazy-loaded model instances
+_detector = None
+_encoder = None
+
+def _get_detector():
+    """Internal helper for lazy initialization of the FaceDetector."""
+    global _detector
+    if _detector is None:
+        _detector = FaceDetector()
+    return _detector
+
+def _get_encoder():
+    """Internal helper for lazy initialization of the FaceEncoder."""
+    global _encoder
+    if _encoder is None:
+        _encoder = FaceEncoder()
+    return _encoder
+
+def detect_faces(image: "np.ndarray", score_quality: bool = True) -> "List[Face]":
+    """
+    Detect faces in an image and calculate their quality scores.
+    
+    Args:
+        image (np.ndarray): Image in BGR format.
+        score_quality (bool): Whether to calculate quality scores (default: True).
+        
+    Returns:
+        List[Face]: List of detected faces with bounding boxes, landmarks, and quality.
+    """
+    return _get_detector().detect(image, score_quality=score_quality)
+
+def extract_features(image: "np.ndarray", face: "Face") -> "np.ndarray":
+    """
+    Extract facial features (512-d embedding) from an image.
+    
+    Args:
+        image (np.ndarray): Original full image (BGR).
+        face (Face): Face object containing landmarks.
+        
+    Returns:
+        np.ndarray: L2-normalized face embedding vector.
+    """
+    return _get_encoder().encode(image, face.landmarks)
+
+def align_face(image: "np.ndarray", face: "Face") -> "np.ndarray":
+    """
+    Align a face to a standard 112x112 size for identification tasks.
+    
+    Args:
+        image (np.ndarray): Original full image (BGR).
+        face (Face): Face object containing landmarks.
+        
+    Returns:
+        np.ndarray: Aligned 112x112 face image.
+    """
+    aligned, _ = _get_encoder().aligner.align(image, face.landmarks)
+    return aligned
+
+def compare_faces(face1: "Face", face2: "Face") -> float:
+    """
+    Compute similarity between two faces using their embeddings.
+    
+    Args:
+        face1 (Face): First face with embedding.
+        face2 (Face): Second face with embedding.
+        
+    Returns:
+        float: Similarity score (0.0 to 1.0).
+    """
+    if face1.embedding is None or face2.embedding is None:
+        raise ValueError("Both faces must have embeddings for comparison.")
+    import numpy as np
+    return float(np.dot(face1.embedding, face2.embedding))
+
+__all__ = [
+    "Face",
+    "FaceDetector",
+    "FaceEncoder",
+    "FaceAligner",
+    "FaceQualityScorer",
+    "detect_faces",
+    "extract_features",
+    "align_face",
+    "compare_faces"
+]

similarfaces-1.0.0/similarfaces/aligner.py

@@ -0,0 +1,57 @@
+import cv2
+import numpy as np
+from skimage.transform import SimilarityTransform
+from typing import Tuple, Optional
+
+
+class FaceAligner:
+    """
+    Face Alignement utility using 5-point facial landmarks.
+    """
+
+    # Standard 5-point facial landmark reference (ArcFace-style)
+    STANDARD_LANDMARK_TEMPLATE = np.array([
+        [38.2946, 51.6963],  # Left eye
+        [73.5318, 51.5014],  # Right eye
+        [56.0252, 71.7366],  # Nose tip
+        [41.5493, 92.3655],  # Left mouth corner
+        [70.7299, 92.2041],  # Right mouth corner
+    ], dtype=np.float32)
+
+    def __init__(self, target_size: int = 112) -> None:
+        self.target_size = target_size
+
+    def compute_alignment_matrix(self, points: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Compute the transformation matrix to align a face.
+        """
+        points = np.array(points, dtype=np.float32)
+        if points.shape != (5, 2):
+            raise ValueError(f"Expected 5-point landmarks, got {points.shape}")
+
+        scale = self.target_size / 112.0
+        ref_points = self.STANDARD_LANDMARK_TEMPLATE.copy() * scale
+        
+        transform = SimilarityTransform()
+        transform.estimate(points, ref_points)
+
+        affine = transform.params[:2, :]
+        affine_inv = np.linalg.inv(transform.params)[:2, :]
+        return affine, affine_inv
+
+    def align(self, image: np.ndarray, keypoints: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Perform facial alignment.
+        
+        Args:
+            image: Original image (HWC).
+            keypoints: 5-point landmarks (5, 2).
+            
+        Returns:
+            The aligned face image and the inverse affine matrix.
+        """
+        affine_matrix, inverse_matrix = self.compute_alignment_matrix(keypoints)
+        aligned_face = cv2.warpAffine(
+            image, affine_matrix, (self.target_size, self.target_size), borderValue=0.0
+        )
+        return aligned_face, inverse_matrix

similarfaces-1.0.0/similarfaces/detector.py

@@ -0,0 +1,238 @@
+import cv2
+import numpy as np
+import onnxruntime as ort
+from typing import List, Tuple, Any
+from .utils import get_model_path
+
+from .models import Face
+from .utils import get_model_path
+from .aligner import FaceAligner
+from .scorer import FaceQualityScorer
+
+
+def letterbox_resize(image: np.ndarray, target_size: Tuple[int, int]) -> Tuple[np.ndarray, float, Tuple[int, int]]:
+    """
+    Resize image with unchanged aspect ratio using padding (letterbox).
+    
+    Args:
+        image (np.ndarray): Input image in BGR format.
+        target_size (tuple): Target (width, height).
+        
+    Returns:
+        tuple: (padded_image, scale_factor, (dw, dh) padding).
+    """
+    img_h, img_w = image.shape[:2]
+    target_w, target_h = target_size
+
+    scale = min(target_w / img_w, target_h / img_h)
+    new_w = int(img_w * scale)
+    new_h = int(img_h * scale)
+
+    resized = cv2.resize(image, (new_w, new_h), interpolation=cv2.INTER_LINEAR)
+
+    dw = target_w - new_w
+    dh = target_h - new_h
+    top, bottom = dh // 2, dh - (dh // 2)
+    left, right = dw // 2, dw - (dw // 2)
+
+    padded = cv2.copyMakeBorder(
+        resized, top, bottom, left, right, cv2.BORDER_CONSTANT, value=(0, 0, 0)
+    )
+
+    return padded, scale, (dw, dh)
+
+
+class FaceDetector:
+    """
+    High-performance face detector for localization and landmark extraction.
+    Integrates quality scoring to provide a comprehensive detection result.
+    """
+
+    def __init__(
+        self,
+        model_path: str = None,
+        input_size: Tuple[int, int] = (640, 640),
+        score_threshold: float = 0.8,
+        nms_threshold: float = 0.4,
+        use_letterbox: bool = True,
+        providers: List[str] = ["CPUExecutionProvider"]
+    ):
+        """
+        Initialize the FaceDetector.
+        
+        Args:
+            model_path (str, optional): Path to the detection ONNX model.
+            input_size (tuple): Model input size (width, height). Defaults to (640, 640).
+            score_threshold (float): Confidence threshold for detection. Defaults to 0.8.
+            nms_threshold (float): Non-maximum suppression threshold. Defaults to 0.4.
+            use_letterbox (bool): Whether to use letterbox resizing. Defaults to True.
+            providers (list): ONNX Runtime execution providers.
+        """
+        self.model_path = model_path or get_model_path("detection.onnx")
+        self.input_width, self.input_height = input_size
+        self.score_threshold = score_threshold
+        self.nms_threshold = nms_threshold
+        self.use_letterbox = use_letterbox
+        self.providers = providers
+
+        # Anchor settings
+        self.min_sizes = [[16, 32], [64, 128], [256, 512]]
+        self.steps = [8, 16, 32]
+        self.variance = [0.1, 0.2]
+
+        # Core session
+        try:
+            self.session = ort.InferenceSession(self.model_path, providers=providers)
+            self.input_name = self.session.get_inputs()[0].name
+            self.output_names = [out.name for out in self.session.get_outputs()]
+        except Exception as e:
+            raise RuntimeError(f"Failed to load detection model: {e}")
+
+        # Lazy-loaded assistants for integrated quality scoring
+        self._aligner = None
+        self._scorer = None
+        
+        self.priors = self._generate_priors((self.input_height, self.input_width))
+
+    def _generate_priors(self, image_size: Tuple[int, int]) -> np.ndarray:
+        """Generate anchor boxes for detection."""
+        anchors = []
+        im_h, im_w = image_size
+
+        for k, step in enumerate(self.steps):
+            f_h = im_h // step
+            f_w = im_w // step
+            for i in range(f_h):
+                for j in range(f_w):
+                    for min_size in self.min_sizes[k]:
+                        s_kx = min_size / im_w
+                        s_ky = min_size / im_h
+                        cx = (j + 0.5) * step / im_w
+                        cy = (i + 0.5) * step / im_h
+                        anchors.append([cx, cy, s_kx, s_ky])
+        return np.array(anchors, dtype=np.float32)
+
+    def _decode_boxes(self, loc: np.ndarray, priors: np.ndarray) -> np.ndarray:
+        """Decode bounding boxes from model output and priors."""
+        boxes = np.concatenate([
+            priors[:, :2] + loc[:, :2] * self.variance[0] * priors[:, 2:],
+            priors[:, 2:] * np.exp(loc[:, 2:] * self.variance[1])
+        ], axis=1)
+        boxes[:, :2] -= boxes[:, 2:] / 2
+        boxes[:, 2:] += boxes[:, :2]
+        return boxes
+
+    def _decode_landmarks(self, ldm: np.ndarray, priors: np.ndarray) -> np.ndarray:
+        """Decode facial landmarks from model output and priors."""
+        landmarks = np.concatenate([
+            priors[:, :2] + ldm[:, i:i+2] * self.variance[0] * priors[:, 2:]
+            for i in range(0, 10, 2)
+        ], axis=1)
+        return landmarks.reshape(-1, 5, 2)
+
+    def preprocess(self, image: np.ndarray) -> Tuple[np.ndarray, float, Tuple[int, int]]:
+        """Preprocess image for detection."""
+        if self.use_letterbox:
+            resized, scale, pad = letterbox_resize(image, (self.input_width, self.input_height))
+        else:
+            resized = cv2.resize(image, (self.input_width, self.input_height))
+            scale = self.input_width / image.shape[1]
+            pad = (0, 0)
+
+        img = resized.astype(np.float32)
+        img -= np.array([104, 117, 123], dtype=np.float32)
+        img = img.transpose(2, 0, 1)
+        img = np.expand_dims(img, axis=0)
+        return img, scale, pad
+
+    def postprocess(
+        self,
+        outputs: List[np.ndarray],
+        scale: float,
+        pad: Tuple[int, int],
+        orig_shape: Tuple[int, int]
+    ) -> List[Face]:
+        """Convert model outputs into Face objects."""
+        loc, conf, landms = outputs[0][0], outputs[1][0], outputs[2][0]
+
+        scores = conf[:, 1]
+        mask = scores > self.score_threshold
+        if not np.any(mask):
+            return []
+
+        loc, scores, priors, landms = loc[mask], scores[mask], self.priors[mask], landms[mask]
+
+        boxes = self._decode_boxes(loc, priors)
+        landmarks = self._decode_landmarks(landms, priors)
+
+        # Rescale
+        boxes[:, [0, 2]] *= self.input_width
+        boxes[:, [1, 3]] *= self.input_height
+        landmarks[:, :, 0] *= self.input_width
+        landmarks[:, :, 1] *= self.input_height
+
+        # Subtract padding
+        dw, dh = pad
+        boxes[:, [0, 2]] -= dw // 2
+        boxes[:, [1, 3]] -= dh // 2
+        landmarks[:, :, 0] -= dw // 2
+        landmarks[:, :, 1] -= dh // 2
+
+        # Final scale
+        boxes /= scale
+        landmarks /= scale
+
+        # Clip
+        orig_h, orig_w = orig_shape
+        boxes[:, [0, 2]] = np.clip(boxes[:, [0, 2]], 0, orig_w)
+        boxes[:, [1, 3]] = np.clip(boxes[:, [1, 3]], 0, orig_h)
+        landmarks[:, :, 0] = np.clip(landmarks[:, :, 0], 0, orig_w)
+        landmarks[:, :, 1] = np.clip(landmarks[:, :, 1], 0, orig_h)
+
+        # NMS
+        keep = cv2.dnn.NMSBoxes(boxes.tolist(), scores.tolist(), 0.1, self.nms_threshold)
+        
+        results = []
+        if len(keep) > 0:
+            indices = np.array(keep).flatten()
+            for idx in indices:
+                results.append(Face(
+                    bbox=boxes[idx],
+                    score=float(scores[idx]),
+                    landmarks=landmarks[idx]
+                ))
+        return results
+
+    def detect(self, image: np.ndarray, score_quality: bool = True) -> List[Face]:
+        """
+        Detect faces and optionally assess their quality.
+        
+        Args:
+            image (np.ndarray): Image in BGR format.
+            score_quality (bool): Whether to calculate quality scores for each face.
+            
+        Returns:
+            List[Face]: Detected faces.
+        """
+        if image is None or image.size == 0:
+            return []
+
+        # 1. Base Detection
+        orig_shape = image.shape[:2]
+        input_tensor, scale, pad = self.preprocess(image)
+        outputs = self.session.run(self.output_names, {self.input_name: input_tensor})
+        faces = self.postprocess(outputs, scale, pad, orig_shape)
+
+        # 2. Integrated Quality Check
+        if score_quality and faces:
+            if self._aligner is None:
+                self._aligner = FaceAligner()
+            if self._scorer is None:
+                self._scorer = FaceQualityScorer(providers=self.providers)
+            
+            for face in faces:
+                aligned, _ = self._aligner.align(image, face.landmarks)
+                face.quality_score = self._scorer.score(aligned)
+                
+        return faces
+

similarfaces-1.0.0/similarfaces/encoder.py

@@ -0,0 +1,101 @@
+import os
+import cv2
+import numpy as np
+from onnxruntime import InferenceSession
+from typing import List, Optional
+from .utils import get_model_path
+from .aligner import FaceAligner
+
+from .models import Face
+from .utils import get_model_path
+from .aligner import FaceAligner
+
+
+class FaceEncoder:
+    """
+    Face Encoder for extracting robust face embeddings.
+    Uses ONNX Runtime for inference. Default embedding size is 512.
+    """
+
+    def __init__(self, model_path: Optional[str] = None, providers: List[str] = ["CPUExecutionProvider"]) -> None:
+        """
+        Initialize the FaceEncoder.
+        
+        Args:
+            model_path (str, optional): Path to the embedding ONNX model.
+            providers (list): ONNX Runtime execution providers.
+        """
+        self.model_path = model_path or get_model_path("features_extraction.onnx")
+        self.input_size = (112, 112)
+        self.normalization_mean = 127.5
+        self.normalization_scale = 127.5
+        self.aligner = FaceAligner()
+
+        try:
+            self.session = InferenceSession(self.model_path, providers=providers)
+            input_config = self.session.get_inputs()[0]
+            self.input_name = input_config.name
+            self.output_names = [o.name for o in self.session.get_outputs()]
+        except Exception as e:
+            raise RuntimeError(f"Failed to initialize Face Embedding model: {e}")
+
+    def preprocess(self, face_image: np.ndarray) -> np.ndarray:
+        """
+        Resize, normalize and convert cropped face to NCHW format.
+        
+        Args:
+            face_image (np.ndarray): Cropped face image (BGR).
+            
+        Returns:
+            np.ndarray: Preprocessed tensor (1, 3, 112, 112).
+        """
+        resized_face = cv2.resize(face_image, self.input_size)
+        face_blob = cv2.dnn.blobFromImage(
+            resized_face,
+            scalefactor=1.0 / self.normalization_scale,
+            size=self.input_size,
+            mean=(self.normalization_mean,) * 3,
+            swapRB=True
+        )
+        return face_blob
+
+    def encode_aligned(self, aligned_face: np.ndarray, normalize: bool = True) -> np.ndarray:
+        """
+        Extract embedding from an already aligned face image.
+        
+        Args:
+            aligned_face (np.ndarray): Aligned face image (112x112).
+            normalize (bool): Whether to L2-normalize the output vector.
+            
+        Returns:
+            np.ndarray: Face embedding vector (512-d).
+        """
+        face_blob = self.preprocess(aligned_face)
+        embedding = self.session.run(self.output_names, {self.input_name: face_blob})[0]
+        embedding = embedding.flatten()
+
+        if normalize:
+            norm = np.linalg.norm(embedding)
+            if norm > 1e-6:
+                embedding /= norm
+        return embedding
+
+    def encode(
+        self,
+        image: np.ndarray,
+        keypoints: np.ndarray,
+        normalize: bool = True
+    ) -> np.ndarray:
+        """
+        Align face and extract embedding in one step.
+        
+        Args:
+            image (np.ndarray): Full image in BGR.
+            keypoints (np.ndarray): 5-point facial landmarks.
+            normalize (bool): Whether to L2-normalize the output vector.
+            
+        Returns:
+            np.ndarray: Face embedding vector.
+        """
+        aligned_face, _ = self.aligner.align(image, keypoints)
+        return self.encode_aligned(aligned_face, normalize=normalize)

similarfaces-1.0.0/similarfaces/models.py

@@ -0,0 +1,59 @@
+from dataclasses import dataclass, field
+from typing import List, Optional, Union
+import numpy as np
+import cv2
+
+@dataclass
+class Face:
+    """
+    Structured representation of a detected face.
+    
+    Attributes:
+        bbox (np.ndarray): Bounding box in [x1, y1, x2, y2] format.
+        score (float): Confidence score of the detection.
+        landmarks (Optional[np.ndarray]): 5-point facial landmarks (eyes, nose, mouth corners).
+        quality_score (Optional[float]): Quality score of the face (0.0 to 1.0).
+        embedding (Optional[np.ndarray]): 512-dimensional face embedding (L2 normalized).
+    """
+    bbox: np.ndarray
+    score: float
+    landmarks: Optional[np.ndarray] = None
+    quality_score: Optional[float] = None
+    embedding: Optional[np.ndarray] = None
+
+    def to_dict(self) -> dict:
+        """Convert the Face object to a JSON-serializable dictionary."""
+        return {
+            "bbox": self.bbox.tolist(),
+            "score": float(self.score),
+            "landmarks": self.landmarks.tolist() if self.landmarks is not None else None,
+            "quality_score": float(self.quality_score) if self.quality_score is not None else None,
+            "embedding": self.embedding.tolist() if self.embedding is not None else None,
+        }
+
+    def draw(self, image: np.ndarray, color=(0, 255, 0), thickness=2) -> np.ndarray:
+        """
+        Draw bounding box and landmarks on the provided image.
+        
+        Args:
+            image (np.ndarray): Image to draw on (BGR).
+            color (tuple): BGR color for the box and points.
+            thickness (int): Line thickness.
+            
+        Returns:
+            np.ndarray: Image with visualizations.
+        """
+        img = image.copy()
+        x1, y1, x2, y2 = map(int, self.bbox)
+        cv2.rectangle(img, (x1, y1), (x2, y2), color, thickness)
+        
+        if self.landmarks is not None:
+            for pt in self.landmarks:
+                cv2.circle(img, (int(pt[0]), int(pt[1])), 2, color, -1)
+        
+        # Draw quality score if available
+        if self.quality_score is not None:
+            cv2.putText(img, f"Q: {self.quality_score:.2f}", (x1, y1 - 10),
+                        cv2.FONT_HERSHEY_SIMPLEX, 0.5, color, 1)
+            
+        return img

similarfaces-1.0.0/similarfaces/scorer.py

@@ -0,0 +1,96 @@
+import onnxruntime as ort
+import numpy as np
+import cv2
+from PIL import Image
+from typing import List, Union, Optional
+from .utils import get_model_path
+
+
+from .models import Face
+from .utils import get_model_path
+
+
+class FaceQualityScorer:
+    """
+    ONNX-based Face Quality Scorer.
+    Determines if a face image (aligned or cropped) is suitable for recognition.
+    A higher score (closer to 1.0) means higher quality.
+    """
+
+    def __init__(self, model_path: Optional[str] = None, providers: List[str] = ["CPUExecutionProvider"]):
+        """
+        Initialize the FaceQualityScorer.
+        
+        Args:
+            model_path (str, optional): Path to the quality assessment ONNX model.
+            providers (list): ONNX Runtime execution providers.
+        """
+        self.model_path = model_path or get_model_path("quality_assessment.onnx")
+        
+        # Ensure the external weights data file is downloaded
+        if not model_path:
+            get_model_path("model.onnx.data")
+        try:
+            self.session = ort.InferenceSession(self.model_path, providers=providers)
+            self.input_name = self.session.get_inputs()[0].name
+        except Exception as e:
+            raise RuntimeError(f"Failed to load quality model from {self.model_path}: {e}")
+
+        # Normalization parameters (ImageNet)
+        self.input_size = (128, 128)
+        self.mean = np.array([0.485, 0.456, 0.406], dtype=np.float32)
+        self.std = np.array([0.229, 0.224, 0.225], dtype=np.float32)
+
+    def _preprocess(self, image: Union[np.ndarray, Image.Image]) -> np.ndarray:
+        """
+        Preprocess single image for quality scoring.
+        
+        Args:
+            image (Union[np.ndarray, Image.Image]): Input image.
+            
+        Returns:
+            np.ndarray: Preprocessed tensor (1, 3, 128, 128).
+        """
+        # Handle color channel conversion (assuming BGR for numpy array from cv2)
+        if isinstance(image, np.ndarray):
+            image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+        elif isinstance(image, Image.Image):
+            image = np.array(image.convert("RGB"))
+        
+        # Resize
+        img = cv2.resize(image, self.input_size)
+        
+        # Normalize
+        img = img.astype(np.float32) / 255.0
+        img = (img - self.mean) / self.std
+        
+        # CHW + Batch
+        img = np.transpose(img, (2, 0, 1))
+        img = np.expand_dims(img, axis=0)
+        return img
+
+    def score(self, image: Union[np.ndarray, Image.Image]) -> float:
+        """
+        Predict quality score for a single face image.
+        
+        Args:
+            image (Union[np.ndarray, Image.Image]): Cropped or aligned face image.
+            
+        Returns:
+            float: Quality score, typically between 0.0 and 1.0.
+        """
+        input_tensor = self._preprocess(image)
+        outputs = self.session.run(None, {self.input_name: input_tensor})
+        return float(outputs[0][0, 0])
+
+    def score_batch(self, images: List[Union[np.ndarray, Image.Image]]) -> List[float]:
+        """
+        Predict quality scores for a batch of images.
+        
+        Args:
+            images (list): List of cropped/aligned face images.
+            
+        Returns:
+            List[float]: List of quality scores.
+        """
+        return [self.score(img) for img in images]

similarfaces-1.0.0/similarfaces/utils.py

@@ -0,0 +1,75 @@
+import numpy as np
+import cv2
+from pathlib import Path
+import os
+import sys
+import urllib.request
+
+HF_MODEL_REPOS = {
+    "detection.onnx": "https://huggingface.co/similarfaces/face-detector/resolve/main/",
+    "features_extraction.onnx": "https://huggingface.co/similarfaces/face-features/resolve/main/",
+    "quality_assessment.onnx": "https://huggingface.co/similarfaces/face-quality/resolve/main/",
+    "model.onnx.data": "https://huggingface.co/similarfaces/face-quality/resolve/main/",
+}
+
+def download_model(model_name: str, model_path: str):
+    """Download a model from Hugging Face if it doesn't exist locally."""
+    if not os.path.exists(model_path):
+        base_url = HF_MODEL_REPOS.get(model_name, "https://huggingface.co/similarfaces/face-quality/resolve/main/")
+        url = base_url + model_name
+        print(f"Downloading {model_name} from Hugging Face...")
+        try:
+            os.makedirs(os.path.dirname(model_path), exist_ok=True)
+            
+            def reporthook(count, block_size, total_size):
+                if total_size > 0:
+                    percent = int(count * block_size * 100 / total_size)
+                    sys.stdout.write(f"\rDownloading... {min(percent, 100)}%")
+                    sys.stdout.flush()
+            
+            urllib.request.urlretrieve(url, model_path, reporthook=reporthook)
+            print() # new line after progress
+        except Exception as e:
+            print(f"\nFailed to download {model_name}: {e}")
+            raise RuntimeError(f"Could not download model {model_name} from {url}: {e}")
+
+def get_model_path(model_name: str) -> str:
+    """Get the absolute path to a model file within the package."""
+    model_path = str(Path(__file__).parent / "models" / model_name)
+    download_model(model_name, model_path)
+    return model_path
+
+def crop_face(image: np.ndarray, box: np.ndarray) -> np.ndarray:
+    """
+    Crop face from image based on bounding box.
+    
+    Args:
+        image: Original image in BGR/RGB format.
+        box: [x1, y1, x2, y2] bounding box.
+        
+    Returns:
+        Cropped face image.
+    """
+    x1, y1, x2, y2 = map(int, box)
+    return image[max(0, y1):y2, max(0, x1):x2]
+
+def adjust_keypoints(keypoints: np.ndarray, crop_box: np.ndarray) -> np.ndarray:
+    """
+    Adjust keypoints from original image coordinates to cropped region coordinates.
+    
+    Args:
+        keypoints: Array of [x, y] points for the original image.
+        crop_box: [x1, y1, x2, y2] bounding box of the cropped region.
+    
+    Returns:
+        Adjusted keypoints for the cropped region.
+    """
+    x1, y1, _, _ = map(int, crop_box)
+    keypoints = np.array(keypoints, dtype=np.float32)
+    keypoints[:, 0] -= x1
+    keypoints[:, 1] -= y1
+    return keypoints
+
+def draw_point(image: np.ndarray, point: tuple, color=(0, 255, 0), radius=2):
+    """Draw a point on the image."""
+    cv2.circle(image, (int(point[0]), int(point[1])), radius, color, -1)

similarfaces-1.0.0/similarfaces.egg-info/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: similarfaces
+Version: 1.0.0
+Summary: A production-ready Face Recognition library powered by ONNX
+Author-email: Narek <your.email@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/narek/similarfaces
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: opencv-python>=4.5.1
+Requires-Dist: onnxruntime>=1.15.0
+Requires-Dist: scikit-image>=0.19.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: matplotlib>=3.5.0
+
+# similarfaces: High-Performance Face Recognition
+
+A production-ready, clean, and robust face recognition pipeline powered by ONNX Runtime.
+
+---
+
+## 🌟 Overview
+
+**similarfaces** is a streamlined, high-performance Python library for face detection, alignment, quality assessment, and recognition. Designed with modularity and ease of use in mind, it provides a functional API that leverages state-of-the-art models optimized for ONNX Runtime.
+
+### ✨ New Key Features
+
+- 🏗️ **Functional API**: Clean and intuitive functional wrappers (`detect_faces`, `extract_features`, `compare_faces`, `align_face`) without the need to manually manage processor objects.
+- 📦 **Structured Data Models**: All functions utilize a unified `Face` dataclass, ensuring type safety and easy access to bounding boxes, landmarks, quality scores, and embeddings.
+- 🎯 **Integrated Detection & Quality**: `detect_faces()` now performs both robust face localization and automatic quality assessment in a single, efficient pass.
+- 📐 **Optimal Alignment**: Similarity transforms for standardized 112x112 face cropping.
+- 🧠 **High-accuracy Recognition**: Extract deep feature embeddings for high-accuracy face comparison.
+- ⚡ **ONNX Powered**: Sub-millisecond inference speeds with minimal dependencies across CPU and GPU environments.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install -r requirements.txt
+pip install -e .  # Install in editable mode for development
+```
+
+### Basic Usage
+
+Compare two faces with high-quality filtering using the functional API:
+
+```python
+import cv2
+from similarfaces import detect_faces, extract_features, compare_faces
+
+# Load images (cv2 loads as BGR)
+img1 = cv2.imread("images/image1.png")
+img2 = cv2.imread("images/image2.png")
+
+# Detect faces (includes quality scores by default)
+faces1 = detect_faces(img1)
+faces2 = detect_faces(img2)
+
+if faces1 and faces2:
+    # Pick the best face from each image based on quality score
+    face1 = max(faces1, key=lambda x: x.quality_score)
+    face2 = max(faces2, key=lambda x: x.quality_score)
+
+    # Extract embeddings
+    face1.embedding = extract_features(img1, face1)
+    face2.embedding = extract_features(img2, face2)
+
+    # Compare faces
+    similarity = compare_faces(face1, face2)
+    print(f"Similarity: {similarity:.4f}")
+    
+    if similarity > 0.6:
+        print("Outcome: Matches (Same Person)")
+    else:
+        print("Outcome: No Match")
+else:
+    print("Error: Could not find faces in one or both images.")
+```
+
+---
+
+## 🛠 Project Structure
+
+The library is designed to be developer-friendly and easy to extend:
+
+- `similarfaces.detector`: High-performance face detection logic.
+- `similarfaces.aligner`: Face alignment and warping.
+- `similarfaces.scorer`: Quality assessment model.
+- `similarfaces.encoder`: Feature embedding extraction.
+- `similarfaces.models`: Data models including the unified `Face` dataclass.
+
+---
+
+## 📊 Performance
+
+| Module | Model | Input Size | Accuracy |
+| :--- | :--- | :--- | :--- |
+| **Detection** | MobileNet-based | 640x640 | High |
+| **Recognition** | IR50-based | 112x112 | SOTA |
+| **Quality** | FaceQuality-ONNX | 128x128 | Robust |
+
+---
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+<p align="center">
+  Developed with ❤️ by Narek Bektashyan
+</p>

similarfaces-1.0.0/similarfaces.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+similarfaces/__init__.py
+similarfaces/aligner.py
+similarfaces/detector.py
+similarfaces/encoder.py
+similarfaces/models.py
+similarfaces/scorer.py
+similarfaces/utils.py
+similarfaces.egg-info/PKG-INFO
+similarfaces.egg-info/SOURCES.txt
+similarfaces.egg-info/dependency_links.txt
+similarfaces.egg-info/requires.txt
+similarfaces.egg-info/top_level.txt

similarfaces-1.0.0/similarfaces.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

similarfaces-1.0.0/similarfaces.egg-info/requires.txt

@@ -0,0 +1,7 @@
+numpy>=1.20.0
+opencv-python>=4.5.1
+onnxruntime>=1.15.0
+scikit-image>=0.19.0
+scipy>=1.7.0
+Pillow>=9.0.0
+matplotlib>=3.5.0

similarfaces-1.0.0/similarfaces.egg-info/top_level.txt

@@ -0,0 +1 @@
+similarfaces