tanyar09
d6b1e85998
This commit introduces a new confidence calibration system that converts DeepFace distance values into actual match probabilities, addressing previous misleading confidence percentages. Key changes include the addition of calibration methods in `FaceProcessor`, updates to the `IdentifyPanel` and `AutoMatchPanel` to utilize calibrated confidence, and new configuration settings in `config.py`. The README has been updated to document these enhancements, ensuring users see more realistic match probabilities throughout the application.
305 lines
9.1 KiB
Markdown
305 lines
9.1 KiB
Markdown
# PunimTag
|
|
|
|
**Photo Management and Facial Recognition System**
|
|
|
|
A powerful desktop application for organizing and tagging photos using **state-of-the-art DeepFace AI** with ArcFace recognition model.
|
|
|
|
---
|
|
|
|
## 🎯 Features
|
|
|
|
- **🔥 DeepFace AI**: State-of-the-art face detection with RetinaFace and ArcFace models
|
|
- **🎯 Superior Accuracy**: 512-dimensional embeddings (4x more detailed than face_recognition)
|
|
- **⚙️ Multiple Detectors**: Choose from RetinaFace, MTCNN, OpenCV, or SSD detectors
|
|
- **🎨 Flexible Models**: Select ArcFace, Facenet, Facenet512, or VGG-Face recognition models
|
|
- **📊 Rich Metadata**: Face confidence scores, quality metrics, detector/model info displayed in GUI
|
|
- **👤 Person Identification**: Identify and tag people across your photo collection
|
|
- **🤖 Smart Auto-Matching**: Intelligent face matching with quality scoring and cosine similarity
|
|
- **🔍 Advanced Search**: Search by people, dates, tags, and folders
|
|
- **🎚️ Quality Filtering**: Filter faces by quality score in Identify panel (0-100%)
|
|
- **🏷️ Tag Management**: Organize photos with hierarchical tags
|
|
- **⚡ Batch Processing**: Process thousands of photos efficiently
|
|
- **🔒 Privacy-First**: All data stored locally, no cloud dependencies
|
|
- **✅ Production Ready**: Complete migration with 20/20 tests passing
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
- Python 3.12 or higher
|
|
- pip package manager
|
|
- Virtual environment (recommended)
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone <repository-url>
|
|
cd punimtag
|
|
|
|
# Create and activate virtual environment
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Running the Application
|
|
|
|
#### GUI Dashboard (Recommended)
|
|
```bash
|
|
python run_dashboard.py
|
|
```
|
|
|
|
Or:
|
|
```bash
|
|
python src/gui/dashboard_gui.py
|
|
```
|
|
|
|
#### CLI Interface
|
|
```bash
|
|
python src/photo_tagger.py --help
|
|
```
|
|
|
|
### First-Time Setup
|
|
|
|
If you have an existing database from before the DeepFace migration, you need to migrate:
|
|
|
|
```bash
|
|
# IMPORTANT: This will delete all existing data!
|
|
python scripts/migrate_to_deepface.py
|
|
```
|
|
|
|
Then re-add your photos and process them with DeepFace.
|
|
|
|
---
|
|
|
|
## 📖 Documentation
|
|
|
|
- **[Architecture](docs/ARCHITECTURE.md)**: System design and technical details
|
|
- **[Demo Guide](docs/DEMO.md)**: Step-by-step tutorial
|
|
- **[Dashboard Guide](docs/README_UNIFIED_DASHBOARD.md)**: GUI reference
|
|
- **[Contributing](CONTRIBUTING.md)**: How to contribute
|
|
|
|
---
|
|
|
|
## 🏗️ Project Structure
|
|
|
|
```
|
|
punimtag/
|
|
├── src/ # Source code
|
|
│ ├── core/ # Business logic
|
|
│ ├── gui/ # GUI components
|
|
│ └── utils/ # Utilities
|
|
├── tests/ # Test suite
|
|
├── docs/ # Documentation
|
|
├── .notes/ # Project notes
|
|
└── data/ # Application data
|
|
```
|
|
|
|
See [Directory Structure](.notes/directory_structure.md) for details.
|
|
|
|
---
|
|
|
|
## 🎮 Usage
|
|
|
|
### 1. Import Photos
|
|
```bash
|
|
# Add photos from a folder
|
|
python src/photo_tagger.py scan /path/to/photos
|
|
```
|
|
|
|
### 2. Process Faces
|
|
Open the dashboard and click "Process Photos" to detect faces.
|
|
|
|
### 3. Identify People
|
|
Use the "Identify" panel to tag faces with names:
|
|
- **Quality Filter**: Adjust the quality slider (0-100%) to filter out low-quality faces
|
|
- **Unique Faces**: Enable to hide duplicate faces using cosine similarity
|
|
- **Date Filters**: Filter faces by date range
|
|
- **Navigation**: Browse through unidentified faces with prev/next buttons
|
|
- **Photo Viewer**: Click the photo icon to view the full source image
|
|
|
|
### 4. Search
|
|
Use the "Search" panel to find photos by people, dates, or tags.
|
|
|
|
---
|
|
|
|
## 🔧 Configuration
|
|
|
|
### GUI Configuration (Recommended)
|
|
Use the dashboard to configure DeepFace settings:
|
|
1. Open the dashboard: `python run_dashboard.py`
|
|
2. Click "🔍 Process"
|
|
3. Select your preferred:
|
|
- **Face Detector**: RetinaFace (best), MTCNN, OpenCV, or SSD
|
|
- **Recognition Model**: ArcFace (best), Facenet, Facenet512, or VGG-Face
|
|
|
|
### Manual Configuration
|
|
Edit `src/core/config.py` to customize:
|
|
- `DEEPFACE_DETECTOR_BACKEND` - Face detection model (default: `retinaface`)
|
|
- `DEEPFACE_MODEL_NAME` - Recognition model (default: `ArcFace`)
|
|
- `DEFAULT_FACE_TOLERANCE` - Similarity tolerance (default: `0.6` for DeepFace)
|
|
- `DEEPFACE_SIMILARITY_THRESHOLD` - Minimum similarity percentage (default: `60`)
|
|
- `MIN_FACE_QUALITY` - Minimum face quality score (default: `0.3`)
|
|
- Batch sizes and other processing thresholds
|
|
|
|
---
|
|
|
|
## 🧪 Testing
|
|
|
|
```bash
|
|
# Run all migration tests (20 tests total)
|
|
python tests/test_phase1_schema.py # Phase 1: Database schema (5 tests)
|
|
python tests/test_phase2_config.py # Phase 2: Configuration (5 tests)
|
|
python tests/test_phase3_deepface.py # Phase 3: Core processing (5 tests)
|
|
python tests/test_phase4_gui.py # Phase 4: GUI integration (5 tests)
|
|
python tests/test_deepface_integration.py # Phase 6: Integration tests (5 tests)
|
|
|
|
# Run DeepFace GUI test (working example)
|
|
python tests/test_deepface_gui.py
|
|
|
|
# All tests should pass ✅ (20/20 passing)
|
|
```
|
|
|
|
---
|
|
|
|
## 🗺️ Roadmap
|
|
|
|
### Current (v1.1 - DeepFace Edition) ✅
|
|
- ✅ Complete DeepFace migration (all 6 phases)
|
|
- ✅ Unified dashboard interface
|
|
- ✅ ArcFace recognition model (512-dim embeddings)
|
|
- ✅ RetinaFace detection (state-of-the-art)
|
|
- ✅ Multiple detector/model options (GUI selectable)
|
|
- ✅ Cosine similarity matching
|
|
- ✅ Face confidence scores and quality metrics
|
|
- ✅ Quality filtering in Identify panel (adjustable 0-100%)
|
|
- ✅ Unique faces detection (cosine similarity-based deduplication)
|
|
- ✅ Enhanced thumbnail display (100x100px)
|
|
- ✅ External system photo viewer integration
|
|
- ✅ Improved auto-match save responsiveness
|
|
- ✅ Metadata display (detector/model info in GUI)
|
|
- ✅ Enhanced accuracy and reliability
|
|
- ✅ Comprehensive test coverage (20/20 tests passing)
|
|
|
|
### Next (v1.2)
|
|
- 📋 GPU acceleration for faster processing
|
|
- 📋 Performance optimization
|
|
- 📋 Enhanced GUI features
|
|
- 📋 Batch processing improvements
|
|
|
|
### Future (v2.0+)
|
|
- Web interface
|
|
- Cloud storage integration
|
|
- Mobile app
|
|
- Video face detection
|
|
- Face clustering (unsupervised)
|
|
- Age estimation
|
|
- Emotion detection
|
|
|
|
---
|
|
|
|
## 🤝 Contributing
|
|
|
|
We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
|
|
|
### Quick Contribution Guide
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Add tests
|
|
5. Submit a pull request
|
|
|
|
---
|
|
|
|
## 📊 Current Status
|
|
|
|
- **Version**: 1.1 (DeepFace Edition)
|
|
- **Face Detection**: DeepFace with RetinaFace (state-of-the-art)
|
|
- **Recognition Model**: ArcFace (512-dimensional embeddings)
|
|
- **Database**: SQLite with DeepFace schema and metadata columns
|
|
- **GUI**: Tkinter with model selection and metadata display
|
|
- **Platform**: Cross-platform (Linux, Windows, macOS)
|
|
- **Migration Status**: ✅ Complete (all 6 phases done, 20/20 tests passing)
|
|
- **Test Coverage**: 100% (20 tests across 6 phases)
|
|
- **Production Ready**: Yes ✅
|
|
|
|
---
|
|
|
|
## 🐛 Known Limitations
|
|
|
|
- Processing ~2-3x slower than old face_recognition (but much more accurate!)
|
|
- Large databases (>50K photos) may experience slowdown
|
|
- No GPU acceleration yet (CPU-only processing)
|
|
- First run downloads models (~100MB+)
|
|
- Existing databases require migration (data will be lost)
|
|
|
|
See [Task List](.notes/task_list.md) for all tracked issues.
|
|
|
|
## 📦 Model Downloads
|
|
|
|
On first run, DeepFace will download required models:
|
|
- ArcFace model (~100MB)
|
|
- RetinaFace detector (~1.5MB)
|
|
- Models stored in `~/.deepface/weights/`
|
|
- Requires internet connection for first run only
|
|
|
|
---
|
|
|
|
## 📝 License
|
|
|
|
[Add your license here]
|
|
|
|
---
|
|
|
|
## 👥 Authors
|
|
|
|
PunimTag Development Team
|
|
|
|
---
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
- **DeepFace** library by Sefik Ilkin Serengil - Modern face recognition framework
|
|
- **ArcFace** - Additive Angular Margin Loss for Deep Face Recognition
|
|
- **RetinaFace** - State-of-the-art face detection
|
|
- TensorFlow, OpenCV, NumPy, and Pillow teams
|
|
- All contributors and users
|
|
|
|
## 📚 Technical Details
|
|
|
|
### Face Recognition Technology
|
|
- **Detection**: RetinaFace (default), MTCNN, OpenCV, or SSD
|
|
- **Model**: ArcFace (512-dim), Facenet (128-dim), Facenet512 (512-dim), or VGG-Face (2622-dim)
|
|
- **Similarity**: Cosine similarity (industry standard for deep learning embeddings)
|
|
- **Accuracy**: Significantly improved over previous face_recognition library
|
|
|
|
### Migration Documentation
|
|
- [Phase 1: Database Schema](PHASE1_COMPLETE.md) - Database updates with DeepFace columns
|
|
- [Phase 2: Configuration](PHASE2_COMPLETE.md) - Configuration settings for DeepFace
|
|
- [Phase 3: Core Processing](PHASE3_COMPLETE.md) - Face processing with DeepFace
|
|
- [Phase 4: GUI Integration](PHASE4_COMPLETE.md) - GUI updates and metadata display
|
|
- [Phase 5 & 6: Dependencies and Testing](PHASE5_AND_6_COMPLETE.md) - Final validation
|
|
- [Complete Migration Summary](DEEPFACE_MIGRATION_COMPLETE_SUMMARY.md) - Full overview
|
|
- [Original Migration Plan](.notes/deepface_migration_plan.md) - Detailed plan
|
|
|
|
---
|
|
|
|
## 📧 Contact
|
|
|
|
[Add contact information]
|
|
|
|
---
|
|
|
|
## ⭐ Star History
|
|
|
|
If you find this project useful, please consider giving it a star!
|
|
|
|
---
|
|
|
|
**Made with ❤️ for photo enthusiasts**
|
|
|