faceswitch 0.2.0__tar.gz → 0.2.2__tar.gz

faceswitch-0.2.2/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: faceswitch
+Version: 0.2.2
+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: retinaface
+Requires-Dist: retina-face; extra == "retinaface"
+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"
+Requires-Dist: retina-face; extra == "all"
+Dynamic: license-file
+
+# FaceSwitch
+
+**Detect faces in any image with one line of Python — swap the detector without changing your code.**
+
+FaceSwitch is a lightweight Python library that wraps multiple face detection engines behind a single, consistent interface. Pick the detector that suits your needs, swap it later without rewriting anything, and only install what you actually use.
+
+---
+
+## What does it do?
+
+You give it an image. It tells you where the faces are.
+
+```python
+from faceswitch.detectors.yolo import YoloDetector
+import cv2
+
+image = cv2.imread("photo.jpg")
+detector = YoloDetector()
+faces = detector.detect(image)
+
+for face in faces:
+    print(f"Face at ({face.x1}, {face.y1}) → ({face.x2}, {face.y2})")
+```
+
+Every detector returns the same thing — a list of face boxes — so switching from YOLO to HOG (or any other detector) is just changing one import line.
+
+---
+
+## Installation
+
+You need Python 3.10 or newer.
+
+**Step 1 — install the base library:**
+
+```bash
+pip install faceswitch
+```
+
+**Step 2 — install the detector you want to use:**
+
+| Detector | What it is | Install command |
+|---|---|---|
+| HOG | Classic CPU-based detector (fast, lightweight, no GPU needed) | `pip install "faceswitch[hog]"` |
+| YOLO | Deep learning detector (more accurate, works best with GPU) | `pip install "faceswitch[yolo]"` |
+| RetinaFace | High-accuracy ResNet detector (best for difficult angles and small faces) | `pip install "faceswitch[retinaface]"` |
+
+| RetinaFace | Deep learning face detector using ResNet+FPN with multi-scale anchors for high-accuracy detection. | `pip install "faceswitch[retinaface]"` |
+
+**Or install everything at once:**
+
+```bash
+pip install "faceswitch[all]"
+```
+
+---
+
+## Quick start — 3 lines to detect faces
+
+```python
+import cv2
+from faceswitch.detectors.hog import HogDetector   # swap this line to switch detectors
+
+image = cv2.imread("photo.jpg")
+faces = HogDetector().detect(image)
+
+print(f"Found {len(faces)} face(s)")
+```
+
+To use a different detector, change only the import:
+
+```python
+from faceswitch.detectors.yolo import YoloDetector         # YOLO
+from faceswitch.detectors.retinaface import RetinaFaceDetector  # RetinaFace
+```
+
+Everything else stays exactly the same.
+
+---
+
+## Understanding the results
+
+`detector.detect(image)` always returns a list of `FaceBox` objects. Each one looks like this:
+
+```
+FaceBox(x1=120, y1=45, x2=210, y2=160, confidence=0.97)
+```
+
+| Field | Meaning |
+|---|---|
+| `x1`, `y1` | Top-left corner of the face box (pixels) |
+| `x2`, `y2` | Bottom-right corner of the face box (pixels) |
+| `confidence` | How sure the detector is (0.0 to 1.0). Some detectors don't provide this (`None`). |
+
+**Draw the boxes on your image:**
+
+```python
+import cv2
+from faceswitch.detectors.yolo import YoloDetector
+
+image = cv2.imread("photo.jpg")
+faces = YoloDetector().detect(image)
+
+for face in faces:
+    cv2.rectangle(image, (face.x1, face.y1), (face.x2, face.y2), (0, 255, 0), 2)
+
+cv2.imwrite("result.jpg", image)
+print(f"Saved result.jpg with {len(faces)} face(s) highlighted")
+```
+
+---
+
+## Choosing the right detector
+
+| | HOG | YOLO | RetinaFace |
+|---|---|---|---|
+| **Speed** | Fast | Medium | Slower |
+| **Accuracy** | Basic | High | Very high |
+| **GPU needed?** | No | Optional | No |
+| **Best for** | Quick scripts, low-power machines | General use, real-time video | Difficult angles, small faces, production use |
+| **Install size** | Small (~80MB) | Large (~500MB with torch) | Large (~200MB with TensorFlow) |
+
+**Not sure?** Start with HOG. If it misses faces, switch to YOLO or RetinaFace — your code won't change.
+
+---
+
+## Available detectors
+
+### HOG — `pip install "faceswitch[hog]"`
+
+Uses dlib's Histogram of Oriented Gradients detector. Works entirely on CPU, very fast, good for frontal faces.
+
+```python
+from faceswitch.detectors.hog import HogDetector
+faces = HogDetector().detect(image)
+```
+
+### YOLO — `pip install "faceswitch[yolo]"`
+
+Uses Ultralytics YOLOv8. Deep learning-based, excellent accuracy on varied poses and lighting. Downloads a model on first use (~6MB).
+
+```python
+from faceswitch.detectors.yolo import YoloDetector
+faces = YoloDetector().detect(image)
+```
+
+### RetinaFace — `pip install "faceswitch[retinaface]"`
+
+Uses the serengil/retinaface ResNet+FPN model. Best accuracy on small faces, side profiles, and crowded images. Downloads model weights on first use (~120MB).
+
+```python
+from faceswitch.detectors.retinaface import RetinaFaceDetector
+faces = RetinaFaceDetector().detect(image)
+```
+
+---
+
+## Common questions
+
+**Do I need a GPU?**
+No. All detectors run on CPU. YOLO and RetinaFace are faster with a GPU but don't require one.
+
+**I get "ImportError: ... install faceswitch[hog]"**
+You installed the base library but not the detector dependency. Run the install command from the table above.
+
+**The detector downloads a model on first use — is that normal?**
+Yes. YOLO (~6MB) and RetinaFace (~120MB) download their model weights automatically the first time you use them. After that, they're cached locally.
+
+**Can I use my own image loading library instead of OpenCV?**
+Yes, as long as the image is a NumPy array with shape `(height, width, 3)` and `uint8` dtype (standard BGR or RGB image). `cv2.imread()` gives you this automatically.
+
+---
+
+## More detectors coming
+
+FaceSwitch is actively maintained. New detectors are added regularly — run `pip install --upgrade faceswitch` to get the latest.
+
+Current version: **0.2.2** | [GitHub](https://github.com/game-sys/FaceSwitch) | [PyPI](https://pypi.org/project/faceswitch/)

faceswitch-0.2.2/README.md

@@ -0,0 +1,177 @@
+# FaceSwitch
+
+**Detect faces in any image with one line of Python — swap the detector without changing your code.**
+
+FaceSwitch is a lightweight Python library that wraps multiple face detection engines behind a single, consistent interface. Pick the detector that suits your needs, swap it later without rewriting anything, and only install what you actually use.
+
+---
+
+## What does it do?
+
+You give it an image. It tells you where the faces are.
+
+```python
+from faceswitch.detectors.yolo import YoloDetector
+import cv2
+
+image = cv2.imread("photo.jpg")
+detector = YoloDetector()
+faces = detector.detect(image)
+
+for face in faces:
+    print(f"Face at ({face.x1}, {face.y1}) → ({face.x2}, {face.y2})")
+```
+
+Every detector returns the same thing — a list of face boxes — so switching from YOLO to HOG (or any other detector) is just changing one import line.
+
+---
+
+## Installation
+
+You need Python 3.10 or newer.
+
+**Step 1 — install the base library:**
+
+```bash
+pip install faceswitch
+```
+
+**Step 2 — install the detector you want to use:**
+
+| Detector | What it is | Install command |
+|---|---|---|
+| HOG | Classic CPU-based detector (fast, lightweight, no GPU needed) | `pip install "faceswitch[hog]"` |
+| YOLO | Deep learning detector (more accurate, works best with GPU) | `pip install "faceswitch[yolo]"` |
+| RetinaFace | High-accuracy ResNet detector (best for difficult angles and small faces) | `pip install "faceswitch[retinaface]"` |
+
+| RetinaFace | Deep learning face detector using ResNet+FPN with multi-scale anchors for high-accuracy detection. | `pip install "faceswitch[retinaface]"` |
+
+**Or install everything at once:**
+
+```bash
+pip install "faceswitch[all]"
+```
+
+---
+
+## Quick start — 3 lines to detect faces
+
+```python
+import cv2
+from faceswitch.detectors.hog import HogDetector   # swap this line to switch detectors
+
+image = cv2.imread("photo.jpg")
+faces = HogDetector().detect(image)
+
+print(f"Found {len(faces)} face(s)")
+```
+
+To use a different detector, change only the import:
+
+```python
+from faceswitch.detectors.yolo import YoloDetector         # YOLO
+from faceswitch.detectors.retinaface import RetinaFaceDetector  # RetinaFace
+```
+
+Everything else stays exactly the same.
+
+---
+
+## Understanding the results
+
+`detector.detect(image)` always returns a list of `FaceBox` objects. Each one looks like this:
+
+```
+FaceBox(x1=120, y1=45, x2=210, y2=160, confidence=0.97)
+```
+
+| Field | Meaning |
+|---|---|
+| `x1`, `y1` | Top-left corner of the face box (pixels) |
+| `x2`, `y2` | Bottom-right corner of the face box (pixels) |
+| `confidence` | How sure the detector is (0.0 to 1.0). Some detectors don't provide this (`None`). |
+
+**Draw the boxes on your image:**
+
+```python
+import cv2
+from faceswitch.detectors.yolo import YoloDetector
+
+image = cv2.imread("photo.jpg")
+faces = YoloDetector().detect(image)
+
+for face in faces:
+    cv2.rectangle(image, (face.x1, face.y1), (face.x2, face.y2), (0, 255, 0), 2)
+
+cv2.imwrite("result.jpg", image)
+print(f"Saved result.jpg with {len(faces)} face(s) highlighted")
+```
+
+---
+
+## Choosing the right detector
+
+| | HOG | YOLO | RetinaFace |
+|---|---|---|---|
+| **Speed** | Fast | Medium | Slower |
+| **Accuracy** | Basic | High | Very high |
+| **GPU needed?** | No | Optional | No |
+| **Best for** | Quick scripts, low-power machines | General use, real-time video | Difficult angles, small faces, production use |
+| **Install size** | Small (~80MB) | Large (~500MB with torch) | Large (~200MB with TensorFlow) |
+
+**Not sure?** Start with HOG. If it misses faces, switch to YOLO or RetinaFace — your code won't change.
+
+---
+
+## Available detectors
+
+### HOG — `pip install "faceswitch[hog]"`
+
+Uses dlib's Histogram of Oriented Gradients detector. Works entirely on CPU, very fast, good for frontal faces.
+
+```python
+from faceswitch.detectors.hog import HogDetector
+faces = HogDetector().detect(image)
+```
+
+### YOLO — `pip install "faceswitch[yolo]"`
+
+Uses Ultralytics YOLOv8. Deep learning-based, excellent accuracy on varied poses and lighting. Downloads a model on first use (~6MB).
+
+```python
+from faceswitch.detectors.yolo import YoloDetector
+faces = YoloDetector().detect(image)
+```
+
+### RetinaFace — `pip install "faceswitch[retinaface]"`
+
+Uses the serengil/retinaface ResNet+FPN model. Best accuracy on small faces, side profiles, and crowded images. Downloads model weights on first use (~120MB).
+
+```python
+from faceswitch.detectors.retinaface import RetinaFaceDetector
+faces = RetinaFaceDetector().detect(image)
+```
+
+---
+
+## Common questions
+
+**Do I need a GPU?**
+No. All detectors run on CPU. YOLO and RetinaFace are faster with a GPU but don't require one.
+
+**I get "ImportError: ... install faceswitch[hog]"**
+You installed the base library but not the detector dependency. Run the install command from the table above.
+
+**The detector downloads a model on first use — is that normal?**
+Yes. YOLO (~6MB) and RetinaFace (~120MB) download their model weights automatically the first time you use them. After that, they're cached locally.
+
+**Can I use my own image loading library instead of OpenCV?**
+Yes, as long as the image is a NumPy array with shape `(height, width, 3)` and `uint8` dtype (standard BGR or RGB image). `cv2.imread()` gives you this automatically.
+
+---
+
+## More detectors coming
+
+FaceSwitch is actively maintained. New detectors are added regularly — run `pip install --upgrade faceswitch` to get the latest.
+
+Current version: **0.2.2** | [GitHub](https://github.com/game-sys/FaceSwitch) | [PyPI](https://pypi.org/project/faceswitch/)

{faceswitch-0.2.0 → faceswitch-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "faceswitch"
-version = "0.2.0"
+version = "0.2.2"
 description = "Simple multi-model face detection library"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -22,7 +22,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Image Recognition",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-dependencies = ["dlib>=19.24"]
+dependencies = []
 
 [project.urls]
 "Homepage" = "https://github.com/game-sys/FaceSwitch"
@@ -30,9 +30,18 @@ dependencies = ["dlib>=19.24"]
 "Documentation" = "https://github.com/game-sys/FaceSwitch/blob/main/README.md"
 
 [project.optional-dependencies]
-hog = ["dlib>=19.24", "ultralytics>=8.0.0"]
+hog = ["dlib>=19.24"]
+yolo = ["ultralytics>=8.0.0", "torch>=2.0.0"]
 examples = ["opencv-python>=4.8"]
 dev = ["pytest>=8.0"]
+retinaface = ["retina-face"]
+all = [
+    "dlib>=19.24",
+    "ultralytics>=8.0.0",
+    "torch>=2.0.0",
+    "opencv-python>=4.8",
+    "retina-face"
+]
 
 [tool.setuptools]
 package-dir = {"" = "src"}

{faceswitch-0.2.0 → faceswitch-0.2.2}/src/faceswitch/__init__.py

@@ -13,4 +13,11 @@ try:
 except ImportError:
     pass
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
+
+try:
+    from faceswitch.detectors.retinaface import RetinaFaceDetector, RetinaFaceDetectorConfig  # noqa: F401
+
+    __all__ += ["RetinaFaceDetector", "RetinaFaceDetectorConfig"]
+except ImportError:
+    pass

{faceswitch-0.2.0 → faceswitch-0.2.2}/src/faceswitch/detectors/__init__.py

@@ -9,4 +9,11 @@ try:
 
     __all__ += ["YoloDetector", "YoloDetectorConfig"]
 except ImportError:
-    pass
+    pass
+
+try:
+    from faceswitch.detectors.retinaface import RetinaFaceDetector, RetinaFaceDetectorConfig  # noqa: F401
+
+    __all__ += ["RetinaFaceDetector", "RetinaFaceDetectorConfig"]
+except ImportError:
+    pass

faceswitch-0.2.2/src/faceswitch/detectors/retinaface/__init__.py

@@ -0,0 +1,6 @@
+"""RetinaFace detector package."""
+
+from faceswitch.detectors.retinaface.config import RetinaFaceDetectorConfig
+from faceswitch.detectors.retinaface.detector import RetinaFaceDetector
+
+__all__ = ["RetinaFaceDetector", "RetinaFaceDetectorConfig"]

faceswitch-0.2.2/src/faceswitch/detectors/retinaface/config.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RetinaFaceDetectorConfig:
+    """Configuration for RetinaFace detector."""
+
+    pass

faceswitch-0.2.2/src/faceswitch/detectors/retinaface/detector.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+
+import numpy as np
+from numpy.typing import NDArray
+
+from faceswitch.core.interfaces import FaceDetector
+from faceswitch.core.types import FaceBox
+from faceswitch.detectors.retinaface.config import RetinaFaceDetectorConfig
+
+
+class RetinaFaceDetector(FaceDetector):
+    """RetinaFace face detector."""
+
+    def __init__(self, config: RetinaFaceDetectorConfig | None = None) -> None:
+        try:
+            from retinaface import RetinaFace as _rf  # type: ignore
+        except ImportError as exc:
+            raise ImportError(
+                "RetinaFaceDetector requires optional dependency 'retinaface'. "
+                "Install with: pip install 'faceswitch[retinaface]'"
+            ) from exc
+
+        self.config = config or RetinaFaceDetectorConfig()
+        self._model = _rf
+
+    def detect(self, image: NDArray[np.uint8]) -> list[FaceBox]:
+        """Detect faces and return list of FaceBox (xyxy)."""
+        if image is None:
+            return []
+
+        results = self._model.detect_faces(image)
+        if not isinstance(results, dict):
+            return []
+        boxes = []
+        for face in results.values():
+            x1, y1, x2, y2 = face["facial_area"]
+            score = float(face.get("score", 1.0))
+            boxes.append(FaceBox(x1=int(x1), y1=int(y1), x2=int(x2), y2=int(y2), confidence=score))
+        return boxes

{faceswitch-0.2.0 → faceswitch-0.2.2}/src/faceswitch/detectors/yolo/detector.py

@@ -18,8 +18,8 @@ class YoloDetector(FaceDetector):
     # Put the real URL(s) you want to support
     _MODEL_URLS: dict[str, str] = {
         "yolov8n-face.pt": "https://github.com/YapaLab/yolo-face/releases/download/1.0.0/yolov8n-face.pt",
-        # "yolov11n-face.pt": "...",
-        # "yolov12n-face.pt": "...",
+        "yolov8m-face.pt": "https://github.com/YapaLab/yolo-face/releases/download/1.0.0/yolov8m-face.pt",
+        "yolov8l-face.pt": "https://github.com/YapaLab/yolo-face/releases/download/1.0.0/yolov8l-face.pt",
     }
 
     def __init__(self, config: YoloDetectorConfig | None = None) -> None: