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

# 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)

python run_dashboard.py

Or:

python src/gui/dashboard_gui.py

CLI Interface

python src/photo_tagger.py --help

First-Time Setup

If you have an existing database from before the DeepFace migration, you need to migrate:

# 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: System design and technical details
• Demo Guide: Step-by-step tutorial
• Dashboard Guide: GUI reference
• Contributing: 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 for details.

---

🎮 Usage

1. Import Photos

# 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

# 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 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 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 - Database updates with DeepFace columns
• Phase 2: Configuration - Configuration settings for DeepFace
• Phase 3: Core Processing - Face processing with DeepFace
• Phase 4: GUI Integration - GUI updates and metadata display
• Phase 5 & 6: Dependencies and Testing - Final validation
• Complete Migration Summary - Full overview
• Original Migration Plan - 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