faceswitch 0.2.1

Simple multi-model face detection library

FaceSwitch

FaceSwitch is a Python library that provides a common interface for multiple face detection backends.

Features

• Clean detector interface
• Optional backend dependencies via extras
• Pluggable architecture
• Automatic model download for supported backends
• Typed API (FaceBox)

Requirements

• Python 3.10+

Installation

pip install faceswitch

Install a specific backend via extras:

pip install "faceswitch[<backend>]"

Examples:

pip install "faceswitch[hog]"
pip install "faceswitch[yolo]"

Install demo dependencies (opencv-python):

pip install "faceswitch[examples]"

Install all optional dependencies:

pip install "faceswitch[all]"

Backend Model

• Each detector backend is optional and installed through extras.
• New backends can be added without changing the core detection interface.
• Current backend extras include hog and yolo.

Minimal Usage (Backend-Agnostic)

import cv2
from faceswitch.detectors.hog import HogDetector

image = cv2.imread("path/to/image.png")
if image is None:
    raise ValueError("Could not read image")

detector = HogDetector()
faces = detector.detect(image)

print(f"Detected: {len(faces)}")

To switch backend later, replace HogDetector with another detector class from faceswitch (for example, YoloDetector) and install its matching extra.

Detector Interface

faces = detector.detect(image)

All detectors return a list of FaceBox values:

FaceBox(
    x1=int,  # left
    y1=int,  # top
    x2=int,  # right
    y2=int,  # bottom
    confidence=float | None,
)

Some detectors may include backend-specific behavior (for example, model download/caching) documented in their module or config.

Run Demos

python examples/demo_hog.py path/to/image.png
python examples/demo_yolo.py path/to/image.png

Adding New Backends

FaceSwitch is designed to grow with more detector implementations. For contribution workflow and detector contract requirements, see CONTRIBUTING.md and ARCHITECTURE.md.