# 🎯 MyFaceDetect v0.2.2
[](https://pypi.org/project/myfacedetect/)
[](https://pypi.org/project/myfacedetect/)
[](LICENSE)
[](https://pypi.org/project/myfacedetect/)
[](https://github.com/Santoshkrishna-code/myfacedetect/stargazers)
A comprehensive Python library for **enhanced face detection** in images and real-time video streams using **OpenCV Haar cascades** and **MediaPipe** with **intelligent filtering algorithms**.
> 🚀 **NEW in v0.2.2**: Enhanced stability, critical bug fixes, and production-ready performance!
## 🌟 Features
### Core Detection
- **Multiple Detection Methods**: OpenCV Haar cascades, MediaPipe, or both combined
- **Static Image Detection**: Process individual images with detailed results
- **Real-time Video Detection**: Live webcam detection with interactive controls
- **Batch Processing**: Efficiently process multiple images
- **Face Extraction**: Save individual face crops from images
### Advanced Features
- **Quality Analysis**: Analyze image quality metrics affecting detection
- **Benchmarking**: Compare performance of different detection methods
- **Result Export**: Export results to JSON, CSV formats
- **Visualization**: Create annotated images showing detection results
- **Configuration Management**: Customizable detection parameters
- **Comprehensive Logging**: Detailed logging for debugging and monitoring
### Enhanced Real-time Detection
- **Interactive Controls**: Switch methods, capture screenshots, toggle settings
- **Performance Monitoring**: Real-time FPS display
- **Multiple Camera Support**: Support for different camera indices
- **Screenshot Capture**: Save detections with customizable output directory
## 🚀 Quick Start
### Installation
```bash
pip install myfacedetect
```
For development installation:
```bash
git clone https://github.com/yourusername/myfacedetect.git
cd myfacedetect
pip install -e .[dev]
```
### Basic Usage
```python
from myfacedetect import detect_faces, detect_faces_realtime
# Static image detection
faces = detect_faces("photo.jpg", method="mediapipe")
print(f"Found {len(faces)} faces")
for i, face in enumerate(faces):
print(f"Face {i+1}: {face}")
# Real-time detection
detect_faces_realtime(method="both", show_fps=True)
```
### Advanced Usage
```python
from myfacedetect import detect_faces, batch_detect_faces
from myfacedetect.utils import create_detection_report, visualize_detection_results
# Advanced detection with visualization
faces, annotated_image = detect_faces(
"photo.jpg",
method="both",
return_image=True,
scale_factor=1.05, # More sensitive detection
min_neighbors=3
)
# Create detailed report
report = create_detection_report(faces, "photo.jpg", "both", 0.123)
# Batch processing
image_paths = ["img1.jpg", "img2.jpg", "img3.jpg"]
all_results = batch_detect_faces(image_paths, method="mediapipe")
# Create visualization
visualization = visualize_detection_results(
"photo.jpg",
faces,
"mediapipe",
save_path="result.jpg"
)
```
## 📖 API Reference
### Core Functions
#### `detect_faces(image_path, method="mediapipe", **kwargs)`
Detect faces in an image with comprehensive options.
**Parameters:**
- `image_path` (str|Path|np.ndarray): Image file path or numpy array
- `method` (str): Detection method - "haar", "mediapipe", or "both"
- `return_image` (bool): Return annotated image with results
- `scale_factor` (float): Haar cascade scale factor (default: 1.1)
- `min_neighbors` (int): Haar cascade min neighbors (default: 4)
- `min_size` (tuple): Minimum face size (width, height) in pixels
**Returns:**
- List of `FaceDetectionResult` objects
- Optionally: tuple of (faces, annotated_image) if `return_image=True`
#### `detect_faces_realtime(camera_index=0, method="mediapipe", **kwargs)`
Real-time face detection with interactive controls.
**Parameters:**
- `camera_index` (int): Webcam index (default: 0)
- `method` (str): Detection method - "haar", "mediapipe", or "both"
- `window_name` (str): Display window name
- `show_fps` (bool): Display FPS counter
- `save_detections` (bool): Enable screenshot saving
- `output_dir` (str): Directory for saving screenshots
**Interactive Controls:**
- `ESC`: Exit detection
- `C` or `SPACE`: Capture screenshot
- `S`: Toggle screenshot saving
- `F`: Toggle FPS display
- `H`: Switch to Haar cascade method
- `M`: Switch to MediaPipe method
- `B`: Switch to both methods
### FaceDetectionResult Class
Represents a detected face with comprehensive information.
**Properties:**
- `bbox`: Bounding box as (x, y, width, height)
- `center`: Center point as (x, y)
- `confidence`: Detection confidence score (0.0-1.0)
- `x, y, width, height`: Individual bbox components
**Methods:**
- `__repr__()`: String representation with all details
### Utility Functions
#### `batch_detect_faces(image_paths, method="mediapipe", **kwargs)`
Process multiple images efficiently.
#### `save_face_crops(image_path, output_dir="face_crops", method="mediapipe")`
Extract and save individual face crops.
#### `benchmark_methods(image_paths, methods=["haar", "mediapipe"])`
Compare performance of different detection methods.
#### `create_detection_report(faces, image_path, method, execution_time)`
Generate detailed analysis report.
#### `visualize_detection_results(image_path, faces, method, save_path=None)`
Create annotated visualization of results.
## 🛠️ Configuration
MyFaceDetect supports configuration files for customizing detection parameters:
```python
from myfacedetect.config import config
# View current configuration
print(config.get("haar_cascade"))
# Modify parameters
config.set("mediapipe", "min_detection_confidence", 0.7)
# Save configuration
config.save_config()
```
Configuration file example (`myfacedetect_config.json`):
```json
{
"haar_cascade": {
"scale_factor": 1.05,
"min_neighbors": 3,
"min_size": [20, 20]
},
"mediapipe": {
"min_detection_confidence": 0.7,
"model_selection": 0
}
}
```
## 🎮 Demo Script
Run the comprehensive demo:
```bash
# Interactive demo
python -m myfacedetect.demo
# Command line options
python -m myfacedetect.demo --image photo.jpg --method both
python -m myfacedetect.demo --realtime
python -m myfacedetect.demo --batch ./photos
python -m myfacedetect.demo --advanced photo.jpg
```
## 🔧 Development
### Setup Development Environment
```bash
git clone https://github.com/yourusername/myfacedetect.git
cd myfacedetect
# Create virtual environment
python -m venv .venv
.venv\Scripts\activate # Windows
source .venv/bin/activate # Linux/Mac
# Install in development mode
pip install -e .[dev]
```
### Run Tests
```bash
pytest tests/ -v --cov=myfacedetect
```
### Code Formatting
```bash
black myfacedetect/
isort myfacedetect/
flake8 myfacedetect/
```
## 📊 Performance Comparison
| Method | Speed | Accuracy | Resource Usage |
|--------|-------|----------|----------------|
| Haar Cascade | Fast | Good | Low |
| MediaPipe | Medium | Excellent | Medium |
| Both Combined | Slower | Best | Higher |
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- OpenCV team for the excellent computer vision library
- MediaPipe team for the powerful ML framework
- Contributors and users of this library
## 📚 Resources
- [OpenCV Documentation](https://docs.opencv.org/)
- [MediaPipe Documentation](https://mediapipe.dev/)
- [Face Detection Guide](https://docs.opencv.org/master/db/d28/tutorial_cascade_classifier.html)
---
**Made with ❤️ by B Santosh Krishna**
Raw data
{
"_id": null,
"home_page": null,
"name": "myfacedetect",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "MyFaceDetect Team <contact@example.com>",
"keywords": "face-detection, opencv, mediapipe, computer-vision, image-processing",
"author": null,
"author_email": "MyFaceDetect Team <contact@example.com>",
"download_url": "https://files.pythonhosted.org/packages/12/32/be02d0362100be4a96178af24dc1f4e8a278d5ea8dfbfcd869187fba44fa/myfacedetect-0.2.2.tar.gz",
"platform": null,
"description": "# \ud83c\udfaf MyFaceDetect v0.2.2\n\n[](https://pypi.org/project/myfacedetect/)\n[](https://pypi.org/project/myfacedetect/)\n[](LICENSE)\n[](https://pypi.org/project/myfacedetect/)\n[](https://github.com/Santoshkrishna-code/myfacedetect/stargazers)\n\nA comprehensive Python library for **enhanced face detection** in images and real-time video streams using **OpenCV Haar cascades** and **MediaPipe** with **intelligent filtering algorithms**.\n\n> \ud83d\ude80 **NEW in v0.2.2**: Enhanced stability, critical bug fixes, and production-ready performance!\n\n## \ud83c\udf1f Features\n\n### Core Detection\n- **Multiple Detection Methods**: OpenCV Haar cascades, MediaPipe, or both combined\n- **Static Image Detection**: Process individual images with detailed results\n- **Real-time Video Detection**: Live webcam detection with interactive controls\n- **Batch Processing**: Efficiently process multiple images\n- **Face Extraction**: Save individual face crops from images\n\n### Advanced Features\n- **Quality Analysis**: Analyze image quality metrics affecting detection\n- **Benchmarking**: Compare performance of different detection methods\n- **Result Export**: Export results to JSON, CSV formats\n- **Visualization**: Create annotated images showing detection results\n- **Configuration Management**: Customizable detection parameters\n- **Comprehensive Logging**: Detailed logging for debugging and monitoring\n\n### Enhanced Real-time Detection\n- **Interactive Controls**: Switch methods, capture screenshots, toggle settings\n- **Performance Monitoring**: Real-time FPS display\n- **Multiple Camera Support**: Support for different camera indices\n- **Screenshot Capture**: Save detections with customizable output directory\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install myfacedetect\n```\n\nFor development installation:\n```bash\ngit clone https://github.com/yourusername/myfacedetect.git\ncd myfacedetect\npip install -e .[dev]\n```\n\n### Basic Usage\n\n```python\nfrom myfacedetect import detect_faces, detect_faces_realtime\n\n# Static image detection\nfaces = detect_faces(\"photo.jpg\", method=\"mediapipe\")\nprint(f\"Found {len(faces)} faces\")\n\nfor i, face in enumerate(faces):\n print(f\"Face {i+1}: {face}\")\n\n# Real-time detection\ndetect_faces_realtime(method=\"both\", show_fps=True)\n```\n\n### Advanced Usage\n\n```python\nfrom myfacedetect import detect_faces, batch_detect_faces\nfrom myfacedetect.utils import create_detection_report, visualize_detection_results\n\n# Advanced detection with visualization\nfaces, annotated_image = detect_faces(\n \"photo.jpg\", \n method=\"both\",\n return_image=True,\n scale_factor=1.05, # More sensitive detection\n min_neighbors=3\n)\n\n# Create detailed report\nreport = create_detection_report(faces, \"photo.jpg\", \"both\", 0.123)\n\n# Batch processing\nimage_paths = [\"img1.jpg\", \"img2.jpg\", \"img3.jpg\"]\nall_results = batch_detect_faces(image_paths, method=\"mediapipe\")\n\n# Create visualization\nvisualization = visualize_detection_results(\n \"photo.jpg\", \n faces, \n \"mediapipe\",\n save_path=\"result.jpg\"\n)\n```\n\n## \ud83d\udcd6 API Reference\n\n### Core Functions\n\n#### `detect_faces(image_path, method=\"mediapipe\", **kwargs)`\n\nDetect faces in an image with comprehensive options.\n\n**Parameters:**\n- `image_path` (str|Path|np.ndarray): Image file path or numpy array\n- `method` (str): Detection method - \"haar\", \"mediapipe\", or \"both\"\n- `return_image` (bool): Return annotated image with results\n- `scale_factor` (float): Haar cascade scale factor (default: 1.1)\n- `min_neighbors` (int): Haar cascade min neighbors (default: 4)\n- `min_size` (tuple): Minimum face size (width, height) in pixels\n\n**Returns:**\n- List of `FaceDetectionResult` objects\n- Optionally: tuple of (faces, annotated_image) if `return_image=True`\n\n#### `detect_faces_realtime(camera_index=0, method=\"mediapipe\", **kwargs)`\n\nReal-time face detection with interactive controls.\n\n**Parameters:**\n- `camera_index` (int): Webcam index (default: 0)\n- `method` (str): Detection method - \"haar\", \"mediapipe\", or \"both\"\n- `window_name` (str): Display window name\n- `show_fps` (bool): Display FPS counter\n- `save_detections` (bool): Enable screenshot saving\n- `output_dir` (str): Directory for saving screenshots\n\n**Interactive Controls:**\n- `ESC`: Exit detection\n- `C` or `SPACE`: Capture screenshot\n- `S`: Toggle screenshot saving\n- `F`: Toggle FPS display\n- `H`: Switch to Haar cascade method\n- `M`: Switch to MediaPipe method\n- `B`: Switch to both methods\n\n### FaceDetectionResult Class\n\nRepresents a detected face with comprehensive information.\n\n**Properties:**\n- `bbox`: Bounding box as (x, y, width, height)\n- `center`: Center point as (x, y)\n- `confidence`: Detection confidence score (0.0-1.0)\n- `x, y, width, height`: Individual bbox components\n\n**Methods:**\n- `__repr__()`: String representation with all details\n\n### Utility Functions\n\n#### `batch_detect_faces(image_paths, method=\"mediapipe\", **kwargs)`\nProcess multiple images efficiently.\n\n#### `save_face_crops(image_path, output_dir=\"face_crops\", method=\"mediapipe\")`\nExtract and save individual face crops.\n\n#### `benchmark_methods(image_paths, methods=[\"haar\", \"mediapipe\"])`\nCompare performance of different detection methods.\n\n#### `create_detection_report(faces, image_path, method, execution_time)`\nGenerate detailed analysis report.\n\n#### `visualize_detection_results(image_path, faces, method, save_path=None)`\nCreate annotated visualization of results.\n\n## \ud83d\udee0\ufe0f Configuration\n\nMyFaceDetect supports configuration files for customizing detection parameters:\n\n```python\nfrom myfacedetect.config import config\n\n# View current configuration\nprint(config.get(\"haar_cascade\"))\n\n# Modify parameters\nconfig.set(\"mediapipe\", \"min_detection_confidence\", 0.7)\n\n# Save configuration\nconfig.save_config()\n```\n\nConfiguration file example (`myfacedetect_config.json`):\n```json\n{\n \"haar_cascade\": {\n \"scale_factor\": 1.05,\n \"min_neighbors\": 3,\n \"min_size\": [20, 20]\n },\n \"mediapipe\": {\n \"min_detection_confidence\": 0.7,\n \"model_selection\": 0\n }\n}\n```\n\n## \ud83c\udfae Demo Script\n\nRun the comprehensive demo:\n\n```bash\n# Interactive demo\npython -m myfacedetect.demo\n\n# Command line options\npython -m myfacedetect.demo --image photo.jpg --method both\npython -m myfacedetect.demo --realtime\npython -m myfacedetect.demo --batch ./photos\npython -m myfacedetect.demo --advanced photo.jpg\n```\n\n## \ud83d\udd27 Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/yourusername/myfacedetect.git\ncd myfacedetect\n\n# Create virtual environment\npython -m venv .venv\n.venv\\Scripts\\activate # Windows\nsource .venv/bin/activate # Linux/Mac\n\n# Install in development mode\npip install -e .[dev]\n```\n\n### Run Tests\n\n```bash\npytest tests/ -v --cov=myfacedetect\n```\n\n### Code Formatting\n\n```bash\nblack myfacedetect/\nisort myfacedetect/\nflake8 myfacedetect/\n```\n\n## \ud83d\udcca Performance Comparison\n\n| Method | Speed | Accuracy | Resource Usage |\n|--------|-------|----------|----------------|\n| Haar Cascade | Fast | Good | Low |\n| MediaPipe | Medium | Excellent | Medium |\n| Both Combined | Slower | Best | Higher |\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- OpenCV team for the excellent computer vision library\n- MediaPipe team for the powerful ML framework\n- Contributors and users of this library\n\n## \ud83d\udcda Resources\n\n- [OpenCV Documentation](https://docs.opencv.org/)\n- [MediaPipe Documentation](https://mediapipe.dev/)\n- [Face Detection Guide](https://docs.opencv.org/master/db/d28/tutorial_cascade_classifier.html)\n\n---\n\n**Made with \u2764\ufe0f by B Santosh Krishna**\n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive face detection library with multiple detection methods and advanced features",
"version": "0.2.2",
"project_urls": {
"Bug Tracker": "https://github.com/Santoshkrishna-code/myfacedetect/issues",
"Documentation": "https://github.com/Santoshkrishna-code/myfacedetect#readme",
"Homepage": "https://github.com/Santoshkrishna-code/myfacedetect",
"Repository": "https://github.com/Santoshkrishna-code/myfacedetect"
},
"split_keywords": [
"face-detection",
" opencv",
" mediapipe",
" computer-vision",
" image-processing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "58a4aee723d4e7e89e9a0afceef33368df2465940c2662ff17df9cf8daf0cd1f",
"md5": "23e2e4dd71bd1a18fb3d261219ac51a6",
"sha256": "1862cfa77a87d3660b989b43a69ad3757bae9863c0b8015eea3215f8faab7c60"
},
"downloads": -1,
"filename": "myfacedetect-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "23e2e4dd71bd1a18fb3d261219ac51a6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 21138,
"upload_time": "2025-08-26T18:17:57",
"upload_time_iso_8601": "2025-08-26T18:17:57.849240Z",
"url": "https://files.pythonhosted.org/packages/58/a4/aee723d4e7e89e9a0afceef33368df2465940c2662ff17df9cf8daf0cd1f/myfacedetect-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1232be02d0362100be4a96178af24dc1f4e8a278d5ea8dfbfcd869187fba44fa",
"md5": "10d25516a7f9d55b0a689f105ff0be44",
"sha256": "411f1d05078f70c8f78b8f928335df6b375ff8051ed24db61eaebb386abbcb2d"
},
"downloads": -1,
"filename": "myfacedetect-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "10d25516a7f9d55b0a689f105ff0be44",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24900,
"upload_time": "2025-08-26T18:17:59",
"upload_time_iso_8601": "2025-08-26T18:17:59.260370Z",
"url": "https://files.pythonhosted.org/packages/12/32/be02d0362100be4a96178af24dc1f4e8a278d5ea8dfbfcd869187fba44fa/myfacedetect-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 18:17:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Santoshkrishna-code",
"github_project": "myfacedetect",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "opencv-python",
"specs": [
[
">=",
"4.5.0"
]
]
},
{
"name": "mediapipe",
"specs": [
[
">=",
"0.8.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.21.0"
]
]
}
],
"lcname": "myfacedetect"
}
JSON
