Upload README.md with huggingface_hub

README.md

@@ -1,3 +1,132 @@
 ---
 license: apache-2.0
+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**: Apache License 2.0 (compatible with upstream `facexlib`).
+- **Underlying Model Checkpoints**: Subject to their respective original licenses (RetinaFace, BiSeNet, ArcFace, etc.).