ilia/punimtag
1
0
Fork 0
Code Issues 9 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
punimtag/README_DESKTOP.md
tanyar09 94385e3dcc migration to web
2025-10-31 12:10:44 -04:00

9.1 KiB
Raw Blame History

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

🏗️ 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

📧 Contact

[Add contact information]

⭐ Star History

If you find this project useful, please consider giving it a star!

Made with ❤️ for photo enthusiasts