tessl/pypi-insightface

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

InsightFace

Name: tessl/pypi-insightface
Author: tessl

A comprehensive 2D and 3D face analysis toolkit that provides state-of-the-art algorithms for face recognition, face detection, and face alignment. Built primarily on ONNX Runtime for efficient inference, InsightFace offers pre-trained models, easy-to-use Python APIs, and capabilities for face swapping, pose estimation, and attribute analysis.

Package Information

Package Name: insightface
Language: Python
Installation: pip install insightface
Dependencies: onnxruntime, opencv-python, numpy, scikit-image

Core Imports

import insightface
from insightface.app import FaceAnalysis

For specific model usage:

from insightface.model_zoo import get_model

For utilities:

from insightface.utils import download, ensure_available

Basic Usage

import insightface
from insightface.app import FaceAnalysis
import cv2

# Initialize face analysis with default model pack
app = FaceAnalysis(name='buffalo_l')
app.prepare(ctx_id=0, det_size=(640, 640))

# Load an image
img = cv2.imread('path/to/image.jpg')

# Analyze faces in the image
faces = app.get(img)

# Process each detected face
for face in faces:
    print(f"Age: {face.age}, Gender: {face.sex}")
    print(f"Detection confidence: {face.det_score}")
    print(f"Embedding shape: {face.embedding.shape}")
    
    # Access face coordinates and landmarks
    bbox = face.bbox.astype(int)
    print(f"Face location: {bbox}")
    
    if face.kps is not None:
        print(f"Facial landmarks: {face.kps.shape}")

# Draw detection results on image
result_img = app.draw_on(img, faces)
cv2.imwrite('result.jpg', result_img)

Architecture

InsightFace is organized around a modular architecture:

FaceAnalysis: High-level interface that orchestrates multiple models for complete face analysis
Model Zoo: Collection of pre-trained ONNX models for specific tasks (detection, recognition, landmarks, attributes)
Face Object: Dynamic result container that accumulates analysis results from different models
Utils: Download, storage, and preprocessing utilities
Data: Sample data and object loading utilities

The design allows flexible model selection and task-specific analysis while maintaining a simple high-level API.

Capabilities

Face Analysis Pipeline

High-level interface for complete face analysis including detection, recognition, landmark detection, and attribute prediction. Automatically manages multiple models and provides unified results.

class FaceAnalysis:
    def __init__(self, name='buffalo_l', root='~/.insightface', allowed_modules=None, **kwargs): ...
    def prepare(self, ctx_id, det_thresh=0.5, det_size=(640, 640)): ...
    def get(self, img, max_num=0) -> List[Face]: ...
    def draw_on(self, img, faces) -> np.ndarray: ...

Face Analysis

Model Zoo

Collection of pre-trained models for specific face analysis tasks including detection (RetinaFace, SCRFD), recognition (ArcFace), landmark detection, and attribute prediction.

def get_model(name, **kwargs): ...

class ArcFaceONNX:
    def prepare(self, ctx_id, **kwargs): ...
    def get(self, img, face) -> np.ndarray: ...
    def compute_sim(self, feat1, feat2) -> float: ...

class RetinaFace:
    def prepare(self, ctx_id, **kwargs): ...
    def detect(self, img, input_size=None, max_num=0, metric='default') -> Tuple[np.ndarray, np.ndarray]: ...

Model Zoo

Face Processing Utilities

Utilities for face alignment, transformation, and preprocessing including normalization, cropping, and coordinate transformations.

def norm_crop(img, landmark, image_size=112, mode='arcface') -> np.ndarray: ...
def estimate_norm(lmk, image_size=112, mode='arcface') -> np.ndarray: ...
def transform(data, center, output_size, scale, rotation) -> Tuple[np.ndarray, np.ndarray]: ...

Face Processing

3D Mask Rendering

Advanced 3D face mask rendering using morphable models for face swapping, virtual try-on, and augmented reality applications.

class MaskRenderer:
    def __init__(self, name='buffalo_l', root='~/.insightface', insfa=None): ...
    def prepare(self, ctx_id=0, det_thresh=0.5, det_size=(128, 128)): ...
    def render_mask(self, face_image, mask_image, params, input_is_rgb=False, auto_blend=True, positions=[0.1, 0.33, 0.9, 0.7]): ...

3D Mask Rendering

Model Management

Download, storage, and management utilities for pre-trained models and model packs.

def download(sub_dir, name, force=False, root='~/.insightface') -> str: ...
def ensure_available(sub_dir, name, root='~/.insightface') -> str: ...
def get_model_dir(name, root='~/.insightface') -> str: ...

Model Management

Sample Data and Objects

Utilities for loading sample images and objects for testing and development.

def get_image(name, to_rgb=False) -> np.ndarray: ...
def get_object(name) -> Any: ...

Sample Data

Command Line Interface

CLI commands for model management and dataset processing operations.

class ModelDownloadCommand:
    def __init__(self, model: str, root: str, force: bool): ...
    def run(self) -> None: ...

def main() -> None: ...  # CLI entry point

Command Line Interface

3D Morphable Face Models

Advanced 3D face modeling capabilities using morphable models for face reconstruction, pose estimation, and 3D face analysis.

class MorphabelModel:
    def __init__(self, model_path, model_type='BFM'): ...
    def generate_vertices(self, shape_para, exp_para) -> np.ndarray: ...
    def generate_colors(self, tex_para) -> np.ndarray: ...
    def transform(self, vertices, s, angles, t3d) -> np.ndarray: ...
    def fit(self, x, X_ind, max_iter=4, isShow=False) -> Tuple[np.ndarray, ...]: ...

3D Morphable Models

Types

class Face(dict):
    """Face detection and analysis result object with dynamic attributes."""
    def __init__(self, d=None, **kwargs): ...
    
    # Properties
    @property
    def embedding_norm -> float: ...
    @property  
    def normed_embedding -> np.ndarray: ...
    @property
    def sex -> str: ...  # 'M' or 'F'
    
    # Dynamic attributes set by models:
    # bbox: np.ndarray - Bounding box [x1, y1, x2, y2]
    # kps: np.ndarray - Facial keypoints/landmarks
    # det_score: float - Detection confidence score
    # embedding: np.ndarray - Face embedding vector
    # gender: int - Gender prediction (0=female, 1=male)
    # age: int - Age prediction
    # landmark_3d_68: np.ndarray - 68 3D facial landmarks
    # pose: np.ndarray - Head pose [pitch, yaw, roll]

# Common type aliases
ImageArray = np.ndarray
BoundingBox = np.ndarray  # Shape: (4,) [x1, y1, x2, y2]
Landmarks = np.ndarray    # Shape: (n_points, 2) or (n_points, 3)
Embedding = np.ndarray    # Shape: (512,) for most models