Metadata-Version: 2.4
Name: faceswitch
Version: 0.2.1
Summary: Simple multi-model face detection library
Author: FaceSwitch Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/game-sys/FaceSwitch
Project-URL: Bug Tracker, https://github.com/game-sys/FaceSwitch/issues
Project-URL: Documentation, https://github.com/game-sys/FaceSwitch/blob/main/README.md
Keywords: face-detection,computer-vision,hog,dlib
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: hog
Requires-Dist: dlib>=19.24; extra == "hog"
Provides-Extra: yolo
Requires-Dist: ultralytics>=8.0.0; extra == "yolo"
Requires-Dist: torch>=2.0.0; extra == "yolo"
Provides-Extra: examples
Requires-Dist: opencv-python>=4.8; extra == "examples"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Provides-Extra: all
Requires-Dist: dlib>=19.24; extra == "all"
Requires-Dist: ultralytics>=8.0.0; extra == "all"
Requires-Dist: torch>=2.0.0; extra == "all"
Requires-Dist: opencv-python>=4.8; extra == "all"
Dynamic: license-file

# 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

```bash
pip install faceswitch
```

Install a specific backend via extras:

```bash
pip install "faceswitch[<backend>]"
```

Examples:

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

Install demo dependencies (`opencv-python`):

```bash
pip install "faceswitch[examples]"
```

Install all optional dependencies:

```bash
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)

```python
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

```python
faces = detector.detect(image)
```

All detectors return a list of `FaceBox` values:

```python
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

```bash
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`.
