# RetinaFaceX (X-extended): Lightweight Face Detection Library
<div align="center">
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/retinafacex/)
[](https://github.com/yakhyo/retinafacex/actions)
[](https://pepy.tech/project/retinafacex)
[](https://www.python.org/dev/peps/pep-0008/)
</div>
RetinaFaceX is a lightweight face detection library designed for high-performance face localization and landmark detection. The library supports ONNX models and provides utilities for bounding box visualization and landmark plotting. To train RetinaFace model, see https://github.com/yakhyo/retinaface-pytorch.
---
## Features
- High-speed face detection using ONNX models.
- Accurate facial landmark localization (e.g., eyes, nose, and mouth).
- Easy-to-use API for inference and visualization.
- Customizable confidence thresholds for bounding box filtering.
---
## Installation
### Using pip
```bash
pip install retinafacex
```
### Local installation using pip
**Clone the repository**
```bash
git clone https://github.com/yakhyo/retinafacex.git
cd retinafacex
```
**Install using pip**
```bash
pip install .
```
---
## Quick Start
### Initialize the Model
```python
from retinafacex import RetinaFace
# Initialize the RetinaFace model
retinaface_inference = RetinaFace(
model="retinaface_mnet_v2", # Model name
conf_thresh=0.5, # Confidence threshold
pre_nms_topk=5000, # Pre-NMS Top-K detections
nms_thresh=0.4, # NMS IoU threshold
post_nms_topk=750 # Post-NMS Top-K detections
)
```
### Run Inference
```python
import cv2
from retinafacex.visualization import draw_detections
# Load an image
image_path = "assets/test.jpg"
original_image = cv2.imread(image_path)
# Perform inference
boxes, landmarks = retinaface_inference.detect(original_image)
# Visualize results
draw_detections(original_image, (boxes, landmarks), vis_threshold=0.6)
# Save the output image
output_path = "output.jpg"
cv2.imwrite(output_path, original_image)
print(f"Saved output image to {output_path}")
```
---
### Evaluation results of available models on WiderFace
| RetinaFace ONNX Backbones | Easy | Medium | Hard |
| ------------------------- | ---------- | ---------- | ---------- |
| retinaface_mnetv1_025 | 88.48% | 87.02% | 80.61% |
| retinaface_mnetv1_050 | 89.42% | 87.97% | 82.40% |
| retinaface_mnetv1 | 90.59% | 89.14% | 84.13% |
| retinaface_mnetv2 | 91.70% | 91.03% | 86.60% |
| retinaface_r18 | 92.50% | 91.02% | 86.63% |
| retinaface_r34 | **94.16%** | **93.12%** | **88.90%** |
## API Reference
### RetinaFace Class
#### Initialization
```python
RetinaFace(
model: str,
conf_thresh: float = 0.5,
pre_nms_topk: int = 5000,
nms_thresh: float = 0.4,
post_nms_topk: int = 750
)
```
- `model`: Model name (e.g., retinaface_mnet_v2).
- retinaface_mnet025
- retinaface_mnet050
- retinaface_mnet_v1
- retinaface_mnet_v2
- retinaface_r18
- retinaface_r34
- `conf_thresh`: Minimum confidence threshold for detections.
- `pre_nms_topk`: Maximum number of detections to keep before NMS.
- `nms_thresh`: IoU threshold for Non-Maximum Suppression.
- `post_nms_topk`: Maximum number of detections to keep after NMS.
#### `detect(image: np.ndarray, max_num: Optional[int] = 0, metric: Literal["default", "max"] = "default", center_weight: Optional[float] = 2.0) -> Tuple[np.ndarray, np.ndarray]`
- **Description**: Performs face detection on the input image and returns bounding boxes and landmarks for detected faces.
- **Inputs**:
- `image` (`np.ndarray`): The input image as a NumPy array in BGR format.
- `max_num` (`Optional[int]`, default=`0`): The maximum number of faces to return. If `0`, all detected faces are returned.
- `metric` (`Literal["default", "max"]`, default=`"default"`): The metric for prioritizing detections:
- `"default"`: Prioritize detections closer to the image center.
- `"max"`: Prioritize detections with larger bounding box areas.
- `center_weight` (`Optional[float]`, default=`2.0`): A weight factor for prioritizing faces closer to the center of the image.
- **Outputs**:
- `Tuple[np.ndarray, np.ndarray]`: A tuple containing:
- `bounding_boxes` (`np.ndarray`): An array of bounding boxes, each represented as `[x_min, y_min, x_max, y_max, confidence]`.
- `landmarks` (`np.ndarray`): An array of facial landmarks, each represented as `[(x1, y1), ..., (x5, y5)]`.
---
## Visualization Utilities
### `draw_detections(original_image, detections, vis_threshold)`
- Draws bounding boxes and landmarks on the image.
- Filters detections below the confidence threshold.
---
## Contributing
We welcome contributions to enhance the library! Feel free to:
- Submit bug reports or feature requests.
- Fork the repository and create a pull request.
---
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
---
## Acknowledgments
- Based on the RetinaFace model for face detection ([https://github.com/yakhyo/retinaface-pytorch](https://github.com/yakhyo/retinaface-pytorch)).
- Inspired by InsightFace and other face detection projects.
---
Raw data
{
"_id": null,
"home_page": "https://github.com/yakhyo/retinafacex",
"name": "retinafacex",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "retinaface, face detection, deep learning, onnx, opencv",
"author": "Yakhyokhuja Valikhujaev",
"author_email": "yakhyo9696@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/70/c7/69c78376dd0e38c389714e2d5e877d1bc530b1fafc8ef02ea1f90574f29d/retinafacex-0.1.2.tar.gz",
"platform": null,
"description": "# RetinaFaceX (X-extended): Lightweight Face Detection Library\n\n<div align=\"center\">\n\n[](https://opensource.org/licenses/MIT)\n\n[](https://pypi.org/project/retinafacex/)\n[](https://github.com/yakhyo/retinafacex/actions)\n[](https://pepy.tech/project/retinafacex)\n[](https://www.python.org/dev/peps/pep-0008/)\n\n</div>\n\nRetinaFaceX is a lightweight face detection library designed for high-performance face localization and landmark detection. The library supports ONNX models and provides utilities for bounding box visualization and landmark plotting. To train RetinaFace model, see https://github.com/yakhyo/retinaface-pytorch.\n\n---\n\n## Features\n\n- High-speed face detection using ONNX models.\n- Accurate facial landmark localization (e.g., eyes, nose, and mouth).\n- Easy-to-use API for inference and visualization.\n- Customizable confidence thresholds for bounding box filtering.\n\n---\n\n## Installation\n\n### Using pip\n\n```bash\npip install retinafacex\n```\n\n### Local installation using pip\n\n**Clone the repository**\n\n```bash\ngit clone https://github.com/yakhyo/retinafacex.git\ncd retinafacex\n```\n\n**Install using pip**\n\n```bash\npip install .\n```\n\n---\n\n## Quick Start\n\n### Initialize the Model\n\n```python\nfrom retinafacex import RetinaFace\n\n# Initialize the RetinaFace model\nretinaface_inference = RetinaFace(\n model=\"retinaface_mnet_v2\", # Model name\n conf_thresh=0.5, # Confidence threshold\n pre_nms_topk=5000, # Pre-NMS Top-K detections\n nms_thresh=0.4, # NMS IoU threshold\n post_nms_topk=750 # Post-NMS Top-K detections\n)\n```\n\n### Run Inference\n\n```python\nimport cv2\nfrom retinafacex.visualization import draw_detections\n\n# Load an image\nimage_path = \"assets/test.jpg\"\noriginal_image = cv2.imread(image_path)\n\n# Perform inference\nboxes, landmarks = retinaface_inference.detect(original_image)\n\n# Visualize results\ndraw_detections(original_image, (boxes, landmarks), vis_threshold=0.6)\n\n# Save the output image\noutput_path = \"output.jpg\"\ncv2.imwrite(output_path, original_image)\nprint(f\"Saved output image to {output_path}\")\n```\n\n---\n\n### Evaluation results of available models on WiderFace\n\n| RetinaFace ONNX Backbones | Easy | Medium | Hard |\n| ------------------------- | ---------- | ---------- | ---------- |\n| retinaface_mnetv1_025 | 88.48% | 87.02% | 80.61% |\n| retinaface_mnetv1_050 | 89.42% | 87.97% | 82.40% |\n| retinaface_mnetv1 | 90.59% | 89.14% | 84.13% |\n| retinaface_mnetv2 | 91.70% | 91.03% | 86.60% |\n| retinaface_r18 | 92.50% | 91.02% | 86.63% |\n| retinaface_r34 | **94.16%** | **93.12%** | **88.90%** |\n\n## API Reference\n\n### RetinaFace Class\n\n#### Initialization\n\n```python\nRetinaFace(\n model: str,\n conf_thresh: float = 0.5,\n pre_nms_topk: int = 5000,\n nms_thresh: float = 0.4,\n post_nms_topk: int = 750\n)\n```\n\n- `model`: Model name (e.g., retinaface_mnet_v2).\n - retinaface_mnet025\n - retinaface_mnet050\n - retinaface_mnet_v1\n - retinaface_mnet_v2\n - retinaface_r18\n - retinaface_r34\n- `conf_thresh`: Minimum confidence threshold for detections.\n- `pre_nms_topk`: Maximum number of detections to keep before NMS.\n- `nms_thresh`: IoU threshold for Non-Maximum Suppression.\n- `post_nms_topk`: Maximum number of detections to keep after NMS.\n\n#### `detect(image: np.ndarray, max_num: Optional[int] = 0, metric: Literal[\"default\", \"max\"] = \"default\", center_weight: Optional[float] = 2.0) -> Tuple[np.ndarray, np.ndarray]`\n\n- **Description**: Performs face detection on the input image and returns bounding boxes and landmarks for detected faces.\n\n- **Inputs**:\n\n - `image` (`np.ndarray`): The input image as a NumPy array in BGR format.\n - `max_num` (`Optional[int]`, default=`0`): The maximum number of faces to return. If `0`, all detected faces are returned.\n - `metric` (`Literal[\"default\", \"max\"]`, default=`\"default\"`): The metric for prioritizing detections:\n - `\"default\"`: Prioritize detections closer to the image center.\n - `\"max\"`: Prioritize detections with larger bounding box areas.\n - `center_weight` (`Optional[float]`, default=`2.0`): A weight factor for prioritizing faces closer to the center of the image.\n\n- **Outputs**:\n - `Tuple[np.ndarray, np.ndarray]`: A tuple containing:\n - `bounding_boxes` (`np.ndarray`): An array of bounding boxes, each represented as `[x_min, y_min, x_max, y_max, confidence]`.\n - `landmarks` (`np.ndarray`): An array of facial landmarks, each represented as `[(x1, y1), ..., (x5, y5)]`.\n\n---\n\n## Visualization Utilities\n\n### `draw_detections(original_image, detections, vis_threshold)`\n\n- Draws bounding boxes and landmarks on the image.\n- Filters detections below the confidence threshold.\n\n---\n\n## Contributing\n\nWe welcome contributions to enhance the library! Feel free to:\n\n- Submit bug reports or feature requests.\n- Fork the repository and create a pull request.\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n## Acknowledgments\n\n- Based on the RetinaFace model for face detection ([https://github.com/yakhyo/retinaface-pytorch](https://github.com/yakhyo/retinaface-pytorch)).\n- Inspired by InsightFace and other face detection projects.\n\n---\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "RetinaFaceX (X-extended): Lightweight Face Detection Library",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/yakhyo/retinafacex"
},
"split_keywords": [
"retinaface",
" face detection",
" deep learning",
" onnx",
" opencv"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a43870d084d49314e39f7d59fdf19a7065eb6b8fef27c5e2c372e26bbd525629",
"md5": "e2777b12760f550e85fa5937545c58d4",
"sha256": "876d3d0dcc76434b26ef16d70f5d70e75c975a017e17eae4026cf6c8e99fa728"
},
"downloads": -1,
"filename": "retinafacex-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2777b12760f550e85fa5937545c58d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14291,
"upload_time": "2024-11-19T07:49:47",
"upload_time_iso_8601": "2024-11-19T07:49:47.451119Z",
"url": "https://files.pythonhosted.org/packages/a4/38/70d084d49314e39f7d59fdf19a7065eb6b8fef27c5e2c372e26bbd525629/retinafacex-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "70c769c78376dd0e38c389714e2d5e877d1bc530b1fafc8ef02ea1f90574f29d",
"md5": "0a0683350aa8fe1891b6d5984981e2c0",
"sha256": "9486a6c69c3e31b66417975c954d6b471864f19044ec05ff1b63aee41026d072"
},
"downloads": -1,
"filename": "retinafacex-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "0a0683350aa8fe1891b6d5984981e2c0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14707,
"upload_time": "2024-11-19T07:49:48",
"upload_time_iso_8601": "2024-11-19T07:49:48.961201Z",
"url": "https://files.pythonhosted.org/packages/70/c7/69c78376dd0e38c389714e2d5e877d1bc530b1fafc8ef02ea1f90574f29d/retinafacex-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-19 07:49:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yakhyo",
"github_project": "retinafacex",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "retinafacex"
}
JSON
