File size: 4,680 Bytes
5f001f2 7be9ef9 3e0a14e 5f001f2 3e0a14e 7be9ef9 3e0a14e | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 | ---
license: mit
tags:
- face-detection
- face-alignment
- face-parsing
- face-restoration
- computer-vision
- python-3-14
- wheels
- comfyui
- stable-diffusion
- forge
library_name: facexlib
---
# FaceXLib (Universal Python 3.12 / 3.13 / 3.14 Compatible Build)
Universal, pure-Python wheel distribution for **`facexlib`** (v0.3.0), optimized for modern Python runtime environments (Python 3.10 through Python 3.14+).
Original upstream repository: [xinntao/facexlib](https://github.com/xinntao/facexlib)
---
## Overview
`facexlib` is a foundational computer vision library providing standardized face processing modules (detection, alignment, parsing, tracking, assessment, and restoration preprocessing) widely utilized across AI generation and restoration ecosystems, including **ComfyUI**, **Stable Diffusion WebUI Forge**, **GFPGAN**, **CodeFormer**, **RestoreFormer**, **IOPaint**, and **ReActor**.
Standard upstream releases pin legacy dependencies (specifically `numba` and restrictive `filterpy` builds) that frequently fail to compile or install on modern Python releases (Python 3.12, 3.13, and 3.14). This universal build solves those environment blockers while preserving 100% API and functional compatibility.
---
## Key Improvements in this Release
1. **Numba-Free / Safe JIT Fallback**:
- Upstream `data_association.py` hard-required `numba.jit`, causing installation and import failures in Python 3.12+ environments where prebuilt Numba wheels were unavailable.
- Replaced with a graceful fallback wrapper (`try ... except ImportError`) that defaults to native vectorized NumPy/SciPy operations when Numba is not installed.
2. **Cleaned & Minimal Dependency Tree**:
- Removed strict dependency pins. Core requirements are lightweight and modern:
- `numpy`
- `opencv-python`
- `Pillow`
- `scipy`
- `tqdm`
3. **Universal Pure-Python Wheel (`py3-none-any.whl`)**:
- Platform-independent (Windows, Linux, macOS) and architecture-independent (x86_64, ARM64/Apple Silicon).
- Zero C/C++ compilation requirements during `pip install`.
---
## Installation
### Direct Install via pip
```bash
pip install https://huggingface.co/ussoewwin/facexlib/resolve/main/facexlib-0.3.0-py3-none-any.whl
```
### In `requirements.txt`
```text
facexlib @ https://huggingface.co/ussoewwin/facexlib/resolve/main/facexlib-0.3.0-py3-none-any.whl
```
---
## Core Capabilities
| Module | Available Backends / Models | Typical Use Case |
| :--- | :--- | :--- |
| **`detection`** | RetinaFace (`resnet50`, `mobile0.25`), YOLOv5-face | High-precision face bounding box & 5-point landmark detection |
| **`alignment`** | 5-point similarity transformation, cropped affine warping | Face normalization for restoration models (GFPGAN / CodeFormer) |
| **`parsing`** | BiSeNet (19-class semantic segmentation) | Hair, skin, eye, mouth, and accessory segmentation |
| **`tracking`** | SORT with Kalman Filter | Real-time temporal face association in video pipelines |
| **`assessment`** | HyperIQA, MUSIQ | No-reference image and facial perceptual quality evaluation |
| **`recognition`** | ArcFace | Deep facial feature extraction and verification |
---
## Quick Start Example
### 1. Face Detection & Landmark Extraction
```python
import cv2
import torch
from facexlib.detection import init_detection_model, detect_faces
# Initialize RetinaFace detector (auto-downloads weights on first run)
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
det_net = init_detection_model("retinaface_resnet50", half=False, device=device)
# Load image (BGR)
img = cv2.imread("input.jpg")
# Detect faces
with torch.no_grad():
bboxes = detect_faces(det_net, img, device=device)
print(f"Detected {len(bboxes)} faces.")
# bboxes format: [[x1, y1, x2, y2, score, landmark_5x2...], ...]
```
### 2. Face Semantic Parsing (BiSeNet)
```python
import torch
from facexlib.parsing import init_parsing_model, parsenet
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
parse_net = init_parsing_model(model_name="bisenet", device=device)
# Input: Cropped & aligned 512x512 face tensor
with torch.no_grad():
# out tensor contains 19-class segmentation logits
pass
```
---
## Automatic Weight Management
Pretrained model weights continue to be automatically fetched and cached in standard local directories on demand:
- Windows: `%USERPROFILE%/.cache/facexlib/weights/`
- Linux / macOS: `~/.cache/facexlib/weights/`
---
## License
- **Library & Code**: MIT License.
- **Underlying Model Checkpoints**: Subject to their respective original licenses (RetinaFace, BiSeNet, ArcFace, etc.).
|