tessl/pypi-insightface

A comprehensive 2D and 3D face analysis toolkit with state-of-the-art algorithms for face recognition, detection, and alignment.

—

Pending

Overview

Eval results

Files

Model Zoo

Name: tessl/pypi-insightface
Author: tessl

Collection of pre-trained ONNX models for specific face analysis tasks including detection, recognition, landmark detection, and attribute prediction. Models can be used individually or automatically managed through the FaceAnalysis pipeline.

Capabilities

Model Factory

Central function for loading and instantiating models from the model zoo.

def get_model(name, **kwargs):
    """
    Load a model from the model zoo.
    
    Parameters:
    - name: str, model name or path to ONNX file
    - root: str, model storage directory (default: '~/.insightface')
    - download: bool, auto-download if model not found (default: True)
    - download_zip: bool, download as zip archive (default: False)
    - providers: list, ONNX execution providers (default: ['CPUExecutionProvider'])
    - provider_options: list, provider-specific options for execution providers
    - session: onnxruntime.InferenceSession, pre-existing ONNX session (optional)
    
    Returns:
    Model instance (ArcFaceONNX, RetinaFace, SCRFD, Landmark, Attribute, or INSwapper)
    based on automatic detection from model input shape and filename patterns
    """

Face Recognition Models

Models for generating face embeddings and computing face similarity.

class ArcFaceONNX:
    def __init__(self, model_file=None, session=None):
        """Initialize ArcFace recognition model."""
    
    def prepare(self, ctx_id, **kwargs):
        """
        Prepare model for inference.
        
        Parameters:
        - ctx_id: int, device context ID
        """
    
    def get(self, img, face) -> np.ndarray:
        """
        Extract face embedding from cropped face region.
        
        Parameters:
        - img: np.ndarray, input image
        - face: Face object with bbox and kps
        
        Returns:
        np.ndarray: face embedding vector (typically 512-dimensional)
        """
    
    def compute_sim(self, feat1, feat2) -> float:
        """
        Compute similarity between two face embeddings.
        
        Parameters:
        - feat1, feat2: np.ndarray, face embedding vectors
        
        Returns:
        float: cosine similarity score (-1 to 1)
        """
    
    def get_feat(self, imgs) -> np.ndarray:
        """
        Extract features from multiple face images.
        
        Parameters:
        - imgs: np.ndarray, batch of aligned face images
        
        Returns:
        np.ndarray: batch of face embeddings
        """
    
    def forward(self, batch_data) -> np.ndarray:
        """Forward pass through the model."""
    
    # Attributes
    taskname = 'recognition'
    input_size: tuple        # Model input size (height, width)
    input_shape: tuple       # Model input shape (batch, channels, height, width)
    input_mean: float        # Input normalization mean
    input_std: float         # Input normalization standard deviation

Face Detection Models

Models for detecting faces and facial landmarks in images.

class RetinaFace:
    def __init__(self, model_file=None, session=None):
        """Initialize RetinaFace detection model."""
    
    def prepare(self, ctx_id, **kwargs):
        """
        Prepare model for inference.
        
        Parameters:
        - ctx_id: int, device context ID
        - input_size: tuple, detection input size
        - det_thresh: float, detection threshold
        - nms_thresh: float, NMS threshold
        """
    
    def detect(self, img, input_size=None, max_num=0, metric='default') -> Tuple[np.ndarray, np.ndarray]:
        """
        Detect faces in image.
        
        Parameters:
        - img: np.ndarray, input image
        - input_size: tuple, resize image to this size for detection
        - max_num: int, maximum number of faces to return
        - metric: str, distance metric for NMS
        
        Returns:
        tuple: (bboxes, keypoints)
        - bboxes: np.ndarray, shape (N, 5) [x1, y1, x2, y2, score]
        - keypoints: np.ndarray, shape (N, 5, 2) 5-point facial landmarks
        """
    
    def forward(self, img, threshold):
        """Forward pass through detection model."""
    
    def nms(self, dets):
        """Apply non-maximum suppression to detections."""
    
    # Attributes
    taskname = 'detection'
    det_thresh: float        # Detection confidence threshold
    nms_thresh: float        # Non-maximum suppression threshold
    input_size: tuple        # Model input size
    use_kps: bool           # Whether model outputs keypoints

class SCRFD:
    def __init__(self, model_file=None, session=None):
        """Initialize SCRFD (Sample and Computation Redistributed Face Detection) model."""
    
    def prepare(self, ctx_id, **kwargs):
        """Prepare model for inference."""
    
    def detect(self, img, input_size=None, max_num=0, metric='default') -> Tuple[np.ndarray, np.ndarray]:
        """
        Detect faces using SCRFD algorithm.
        
        Parameters and returns same as RetinaFace.detect()
        """
    
    def forward(self, img, threshold):
        """Forward pass through SCRFD model."""
    
    def nms(self, dets):
        """Apply non-maximum suppression."""
    
    # Attributes  
    taskname = 'detection'
    batched: bool           # Whether model supports batch processing
    det_thresh: float       # Detection threshold
    nms_thresh: float       # NMS threshold

def get_scrfd(name, download=False, root='~/.insightface/models', **kwargs):
    """
    Load SCRFD model with automatic download support.
    
    Parameters:
    - name: str, model name or path to ONNX file
    - download: bool, whether to auto-download if model not found
    - root: str, model storage directory
    - **kwargs: additional arguments passed to SCRFD constructor
    
    Returns:
    SCRFD: initialized SCRFD model instance
    """

def scrfd_2p5gkps(**kwargs):
    """Load SCRFD 2.5G model with keypoints support."""

def softmax(z) -> np.ndarray:
    """
    Apply softmax function to 2D array.
    
    Parameters:
    - z: np.ndarray, input array of shape (N, C)
    
    Returns:
    np.ndarray: softmax probabilities
    """

def distance2bbox(points, distance, max_shape=None) -> np.ndarray:
    """
    Decode distance prediction to bounding box coordinates.
    
    Parameters:
    - points: np.ndarray, center points, shape (n, 2) [x, y]
    - distance: np.ndarray, distances to 4 boundaries [left, top, right, bottom]
    - max_shape: tuple, optional image shape for clamping
    
    Returns:
    np.ndarray: decoded bounding boxes [x1, y1, x2, y2]
    """

def distance2kps(points, distance, max_shape=None) -> np.ndarray:
    """
    Decode distance prediction to keypoint coordinates.
    
    Parameters:
    - points: np.ndarray, reference points, shape (n, 2)
    - distance: np.ndarray, distance predictions to keypoints
    - max_shape: tuple, optional image shape for clamping
    
    Returns:
    np.ndarray: decoded keypoint coordinates
    """

Landmark Detection Models

Models for detecting detailed facial landmarks.

class Landmark:
    def __init__(self, model_file=None, session=None):
        """Initialize landmark detection model."""
    
    def prepare(self, ctx_id, **kwargs):
        """Prepare model for inference."""
    
    def get(self, img, face) -> np.ndarray:
        """
        Detect facial landmarks.
        
        Parameters:
        - img: np.ndarray, input image
        - face: Face object with bbox
        
        Returns:
        np.ndarray: landmark coordinates, shape depends on model
        - 2D landmarks: (N, 2) 
        - 3D landmarks: (N, 3)
        """
    
    # Attributes
    taskname: str           # e.g., 'landmark_2d_68', 'landmark_3d_68', 'landmark_2d_106'
    lmk_dim: int           # Landmark dimension: 2 or 3
    lmk_num: int           # Number of landmarks: 68, 106, etc.
    require_pose: bool     # Whether model requires pose estimation

Attribute Prediction Models

Models for predicting face attributes like age and gender.

class Attribute:
    def __init__(self, model_file=None, session=None):
        """Initialize attribute prediction model."""
    
    def prepare(self, ctx_id, **kwargs):
        """Prepare model for inference."""
    
    def get(self, img, face) -> Union[Tuple[int, int], np.ndarray]:
        """
        Predict face attributes.
        
        Parameters:
        - img: np.ndarray, input image
        - face: Face object with bbox
        
        Returns:
        For genderage models: tuple (gender, age) where gender is 0/1, age is int
        For other attribute models: np.ndarray of predictions
        """
    
    # Attributes
    taskname: str          # e.g., 'genderage', 'attribute_N'

Face Swapping Models

Models for face swapping and identity transfer.

class INSwapper:
    def __init__(self, model_file=None, session=None):
        """Initialize INSwapper face swapping model."""
    
    def forward(self, img, latent) -> np.ndarray:
        """
        Forward pass with latent representation.
        
        Parameters:
        - img: np.ndarray, target face image
        - latent: np.ndarray, source face latent representation
        
        Returns:
        np.ndarray: swapped face image
        """
    
    def get(self, img, target_face, source_face, paste_back=True) -> np.ndarray:
        """
        Perform face swapping.
        
        Parameters:
        - img: np.ndarray, input image containing target face
        - target_face: Face object, face to be replaced
        - source_face: Face object, source face for swapping
        - paste_back: bool, whether to paste result back to original image
        
        Returns:
        np.ndarray: result image with swapped face
        """

Usage Examples

Individual Model Usage

from insightface.model_zoo import get_model
import cv2

# Load specific detection model
detector = get_model('retinaface_r50_v1')
detector.prepare(ctx_id=0, det_thresh=0.5)

# Detect faces
img = cv2.imread('group_photo.jpg')
bboxes, kpss = detector.detect(img)

print(f"Detected {len(bboxes)} faces")
for i, (bbox, kps) in enumerate(zip(bboxes, kpss)):
    x1, y1, x2, y2, score = bbox
    print(f"Face {i+1}: confidence={score:.3f}, box=({x1}, {y1}, {x2}, {y2})")

Recognition Model Usage

# Load recognition model
recognizer = get_model('arcface_r100_v1')
recognizer.prepare(ctx_id=0)

# Extract embeddings from detected faces
embeddings = []
for bbox, kps in zip(bboxes, kpss):
    # Create Face object
    face = Face(bbox=bbox, kps=kps, det_score=bbox[4])
    
    # Extract embedding
    embedding = recognizer.get(img, face)
    embeddings.append(embedding)

# Compare faces
if len(embeddings) >= 2:
    similarity = recognizer.compute_sim(embeddings[0], embeddings[1])
    print(f"Similarity between face 1 and 2: {similarity:.3f}")

Model Download Management

# Download specific model pack
model_path = get_model('buffalo_s', download=True, root='./models')

# Use with custom providers (GPU acceleration)
detector = get_model('scrfd_10g_bnkps', 
                    providers=['CUDAExecutionProvider', 'CPUExecutionProvider'])
detector.prepare(ctx_id=0)

Attribute Prediction

# Load gender/age prediction model
attr_model = get_model('genderage_v1')
attr_model.prepare(ctx_id=0)

# Predict attributes for detected faces
for bbox, kps in zip(bboxes, kpss):
    face = Face(bbox=bbox, kps=kps)
    gender, age = attr_model.get(img, face)
    
    gender_str = 'M' if gender == 1 else 'F'
    print(f"Face: {gender_str}, Age: {age}")

Landmark Detection

# Load 68-point landmark model
landmark_model = get_model('2d106det')
landmark_model.prepare(ctx_id=0)

# Detect detailed landmarks
for bbox, kps in zip(bboxes, kpss):
    face = Face(bbox=bbox, kps=kps)
    landmarks = landmark_model.get(img, face)
    
    print(f"Detected {len(landmarks)} landmarks")
    # landmarks shape: (106, 2) for 2D coordinates

Available Model Packs

Common pre-trained model packs available for download:

buffalo_l: Large model pack with detection, recognition, landmarks, and attributes
buffalo_m: Medium-sized model pack for balanced performance
buffalo_s: Small model pack for fast inference
antelopev2: High-accuracy model pack with advanced features

Individual models: