Implementation:Kornia Kornia Face Detection

Knowledge Sources	Kornia
Domains	Vision, Face_Detection
Last Updated	2026-02-09 15:00 GMT

Overview

Detects faces in images using the YuNet model, returning bounding boxes, facial keypoints, and confidence scores.

Description

The face_detection module in the Kornia contrib package provides a high-level face detection API built on the YuNet model. It includes the FaceDetector nn.Module that wraps the YuNet backbone with NMS-based post-processing, the FaceDetectorResult class that provides convenient access to bounding box coordinates, five facial keypoints (left eye, right eye, nose, left mouth, right mouth), and detection scores, and the FaceKeypoint enum for referencing specific facial landmarks. The detector uses prior boxes, decoding, and non-maximum suppression to produce the final detections.

Usage

Import this module when you need to detect faces in images and access their bounding boxes and facial landmark positions, for example for face alignment, recognition preprocessing, or face tracking.

Code Reference

Source Location

• Repository: Kornia
• File: kornia/contrib/face_detection.py
• Lines: 1-243

Signature

class FaceKeypoint(Enum):
    EYE_LEFT = 0
    EYE_RIGHT = 1
    NOSE = 2
    MOUTH_LEFT = 3
    MOUTH_RIGHT = 4

class FaceDetectorResult:
    def __init__(self, data: torch.Tensor) -> None: ...
    @property
    def xmin(self) -> torch.Tensor: ...
    @property
    def ymin(self) -> torch.Tensor: ...
    @property
    def xmax(self) -> torch.Tensor: ...
    @property
    def ymax(self) -> torch.Tensor: ...
    @property
    def score(self) -> torch.Tensor: ...
    @property
    def width(self) -> torch.Tensor: ...
    @property
    def height(self) -> torch.Tensor: ...
    @property
    def top_left(self) -> torch.Tensor: ...
    @property
    def bottom_right(self) -> torch.Tensor: ...
    def get_keypoint(self, keypoint: FaceKeypoint) -> torch.Tensor: ...
    def to(self, device=None, dtype=None) -> "FaceDetectorResult": ...

class FaceDetector(nn.Module):
    def __init__(
        self, top_k: int = 5000, confidence_threshold: float = 0.3,
        nms_threshold: float = 0.3, keep_top_k: int = 750
    ) -> None: ...
    def forward(self, image: torch.Tensor) -> List[torch.Tensor]: ...

Import

from kornia.contrib import FaceDetector, FaceDetectorResult, FaceKeypoint

I/O Contract

Inputs (FaceDetector.__init__)

Name	Type	Required	Description
top_k	int	No	Maximum number of detections before NMS (default: 5000)
confidence_threshold	float	No	Score threshold to discard low-confidence detections (default: 0.3)
nms_threshold	float	No	IoU threshold for non-maximum suppression (default: 0.3)
keep_top_k	int	No	Maximum number of detections to keep after NMS (default: 750)

Inputs (FaceDetector.forward)

Name	Type	Required	Description
image	torch.Tensor	Yes	Batch of images with shape (B, 3, H, W)

Outputs

Name	Type	Description
detections	List[torch.Tensor]	List of B tensors, each with shape (N, 15) containing bounding box (4), keypoints (10), and score (1) per detection

FaceDetectorResult Fields

Each detection vector of length 15 encodes:

Index	Description
0-3	Bounding box: xmin, ymin, xmax, ymax
4-5	Left eye (x, y)
6-7	Right eye (x, y)
8-9	Nose (x, y)
10-11	Left mouth corner (x, y)
12-13	Right mouth corner (x, y)
14	Detection confidence score

Usage Examples

import torch
from kornia.contrib import FaceDetector, FaceDetectorResult, FaceKeypoint

# Initialize detector
detector = FaceDetector(confidence_threshold=0.5)

# Detect faces in an image batch
images = torch.rand(1, 3, 320, 320)
detections = detector(images)

# Process results for the first image
for det in detections[0]:
    result = FaceDetectorResult(det)
    print(f"Face score: {result.score:.2f}")
    print(f"BBox: ({result.xmin:.0f}, {result.ymin:.0f}) - ({result.xmax:.0f}, {result.ymax:.0f})")

    # Access facial keypoints
    left_eye = result.get_keypoint(FaceKeypoint.EYE_LEFT)
    nose = result.get_keypoint(FaceKeypoint.NOSE)
    print(f"Left eye: {left_eye}, Nose: {nose}")

Related Pages

• Principle:Kornia_Kornia_Face_Detection_Pipeline