# PunimTag - Unified Photo Face Tagger

A powerful photo face recognition and tagging system with a modern unified dashboard interface. Designed for easy web migration with clean separation between navigation and functionality.

## 🎯 What's New: Unified Dashboard

**PunimTag now features a unified dashboard interface** that brings all functionality into a single, professional window:

- **📱 Single Window Interface** - No more managing multiple windows
- **🖥️ Full Screen Mode** - Automatically opens maximized for optimal viewing
- **📐 Responsive Design** - All components adapt dynamically to window resizing
- **🎛️ Menu Bar Navigation** - All features accessible from the top menu
- **🔄 Panel Switching** - Seamless transitions between different functions
- **🌐 Web-Ready Architecture** - Designed for easy migration to web application
- **📊 Status Updates** - Real-time feedback on current operations
- **🎨 Enhanced Typography** - Larger, more readable fonts optimized for full screen
- **🏠 Smart Home Navigation** - Compact home icon for quick return to welcome screen
- **🚪 Unified Exit Behavior** - All exit buttons navigate to home instead of closing
- **✅ Complete Integration** - All panels fully functional and integrated

## 📋 System Requirements

### Minimum Requirements
- **Python**: 3.7 or higher
- **Operating System**: Linux, macOS, or Windows
- **RAM**: 2GB+ (4GB+ recommended for large photo collections)
- **Storage**: 100MB for application + space for photos and database
- **Display**: X11 display server (Linux) or equivalent for GUI interface

### Supported Platforms
- ✅ **Ubuntu/Debian** (fully supported with automatic dependency installation)
- ✅ **macOS** (manual dependency installation required)
- ✅ **Windows** (with WSL or manual setup)
- ⚠️ **Other Linux distributions** (manual dependency installation required)

### What Gets Installed Automatically (Ubuntu/Debian)
The setup script automatically installs these system packages:
- **Build tools**: `cmake`, `build-essential`
- **Math libraries**: `libopenblas-dev`, `liblapack-dev` (for face recognition)
- **GUI libraries**: `libx11-dev`, `libgtk-3-dev`, `libboost-python-dev`
- **Image viewer**: `feh` (for face identification interface)

## 🚀 Quick Start

```bash
# 1. Setup (one time only)
git clone <your-repo>
cd PunimTag
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
python3 setup.py  # Installs system deps + Python packages

# 2. Launch Unified Dashboard
python3 photo_tagger.py dashboard

# 3. Use the menu bar to access all features:
#    🏠 Home - Return to welcome screen (✅ Fully Functional)
#    📁 Scan - Add photos to your collection (✅ Fully Functional)
#    🔍 Process - Detect faces in photos (✅ Fully Functional)
#    👤 Identify - Identify people in photos (✅ Fully Functional)
#    🔗 Auto-Match - Find matching faces automatically (✅ Fully Functional)
#    🔎 Search - Find photos by person name (✅ Fully Functional)
#    ✏️ Modify - Edit face identifications (✅ Fully Functional)
#    🏷️ Tags - Manage photo tags (✅ Fully Functional)
```

## 📦 Installation

### Automatic Setup (Recommended)
```bash
# Clone and setup
git clone <your-repo>
cd PunimTag

# Create virtual environment (IMPORTANT!)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Run setup script
python3 setup.py
```

**⚠️ IMPORTANT**: Always activate the virtual environment before running any commands:
```bash
source venv/bin/activate  # Run this every time you open a new terminal
```

### Manual Setup (Alternative)
```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 photo_tagger.py stats  # Creates database
```

## 🎛️ Unified Dashboard Interface

### Launch the Dashboard
```bash
# Open the unified dashboard (RECOMMENDED)
python3 photo_tagger.py dashboard
```

### 🖥️ Full Screen & Responsive Features

The dashboard automatically opens in full screen mode and provides a fully responsive experience:

#### **Automatic Full Screen**
- **Cross-Platform Support**: Works on Windows, Linux, and macOS
- **Smart Maximization**: Uses the best available method for each platform
- **Fallback Handling**: Gracefully handles systems that don't support maximization
- **Minimum Size**: Prevents window from becoming too small (800x600 minimum)

#### **Dynamic Responsiveness**
- **Real-Time Resizing**: All components adapt as you resize the window
- **Grid-Based Layout**: Uses proper grid weights for optimal expansion
- **Status Updates**: Status bar shows current window dimensions
- **Panel Updates**: Active panels update their layout during resize
- **Canvas Scrolling**: Similar faces and other scrollable areas update automatically

#### **Enhanced Typography**
- **Full Screen Optimized**: Larger fonts (24pt titles, 14pt content) for better readability
- **Consistent Styling**: All panels use the same enhanced font sizes
- **Professional Appearance**: Clean, modern typography throughout

#### **Smart Navigation**
- **🏠 Home Icon**: Compact home button (🏠) in the leftmost position of the menu bar
- **Quick Return**: Click the home icon to instantly return to the welcome screen
- **Exit to Home**: All exit buttons in panels now navigate to home instead of closing
- **Consistent UX**: Unified navigation experience across all panels

### Dashboard Features

#### **🏠 Home Panel**
- Welcome screen with feature overview
- Quick access guide to all functionality
- Professional, modern interface with large fonts for full screen
- Responsive layout that adapts to window size

#### **📁 Scan Panel**
- **Folder Selection**: Browse and select photo directories
- **Recursive Scanning**: Include photos in subfolders
- **Path Validation**: Automatic validation and error handling
- **Real-time Status**: Live updates during scanning process
- **Responsive Forms**: Form elements expand and contract with window size

#### **🔍 Process Panel**
- **Batch Processing**: Process photos in configurable batches
- **Quality Scoring**: Automatic face quality assessment
- **Model Selection**: Choose between HOG (fast) and CNN (accurate) models
- **Progress Tracking**: Real-time processing status
- **Dynamic Layout**: All controls adapt to window resizing

#### **👤 Identify Panel** *(Fully Functional)*
- **Visual Face Display**: See individual face crops (400x400 pixels for full screen)
- **Smart Identification**: Separate fields for first name, last name, middle name, maiden name
- **Similar Face Matching**: Compare with other unidentified faces
- **Batch Processing**: Handle multiple faces efficiently
- **Responsive Layout**: Adapts to window resizing with dynamic updates
- **Enhanced Navigation**: Back/Next buttons with unsaved changes protection

#### **🔗 Auto-Match Panel** *(Fully Functional)*
- **Person-Centric Workflow**: Groups faces by already identified people
- **Visual Confirmation**: Left panel shows identified person, right panel shows potential matches
- **Confidence Scoring**: Color-coded match confidence levels with detailed descriptions
- **Bulk Selection**: Select multiple faces for identification with Select All/Clear All
- **Smart Navigation**: Back/Next buttons to move between different people
- **Search Functionality**: Filter people by last name for large databases
- **Pre-selection**: Previously identified faces are automatically checked
- **Unsaved Changes Protection**: Warns before losing unsaved work
- **Database Integration**: Proper transactions and face encoding updates

##### **Auto-Match Workflow**
The auto-match feature works in a **person-centric** way:

1. **Group by Person**: Faces are grouped by already identified people (not unidentified faces)
2. **Show Matched Person**: Left side shows the identified person and their face
3. **Show Unidentified Faces**: Right side shows all unidentified faces that match this person
4. **Select and Save**: Check the faces you want to identify with this person, then click "Save Changes"
5. **Navigate**: Use Back/Next to move between different people
6. **Correct Mistakes**: Go back and uncheck faces to unidentify them
7. **Pre-selected Checkboxes**: Previously identified faces are automatically checked when you go back

**Key Benefits:**
- **1-to-Many**: One person can have multiple unidentified faces matched to them
- **Visual Confirmation**: See exactly what you're identifying before saving
- **Easy Corrections**: Go back and fix mistakes by unchecking faces
- **Smart Tracking**: Previously identified faces are pre-selected for easy review

##### **Auto-Match Configuration**
- **Tolerance Setting**: Adjust matching sensitivity (lower = stricter matching)
- **Start Button**: Prominently positioned on the left for easy access
- **Search Functionality**: Filter people by last name for large databases
- **Exit Button**: "Exit Auto-Match" with unsaved changes protection

#### **🔎 Search Panel** *(Fully Functional)*
- **Multiple Search Types**: Search photos by name, date, tags, and special categories
- **Advanced Filtering**: Filter by folder location with browse functionality
- **Results Display**: Sortable table with person names, tags, processed status, and dates
- **Interactive Results**: Click to open photos, browse folders, and view people
- **Tag Management**: Add and remove tags from selected photos
- **Responsive Layout**: Adapts to window resizing with proper scrolling

#### **✏️ Modify Panel** *(Fully Functional)*
- **Review Identifications**: View all identified people with face counts
- **Edit Names**: Rename people with full name fields (first, last, middle, maiden, date of birth)
- **Unmatch Faces**: Temporarily remove face associations with visual confirmation
- **Bulk Operations**: Handle multiple changes efficiently with undo functionality
- **Search People**: Filter people by last name for large databases
- **Visual Calendar**: Date of birth selection with intuitive calendar interface
- **Responsive Layout**: Face grid adapts to window resizing
- **Unsaved Changes Protection**: Warns before losing unsaved work

#### **🏷️ Tag Manager Panel** *(Fully Functional)*
- **Photo Explorer**: Browse photos organized by folders with thumbnail previews
- **Multiple View Modes**: List view, icon view, compact view, and folder view
- **Tag Management**: Add, remove, and organize tags with bulk operations
- **People Integration**: View and manage people identified in photos
- **Bulk Tagging**: Link tags to entire folders or multiple photos at once
- **Search & Filter**: Find photos by tags, people, or folder location
- **Responsive Layout**: Adapts to window resizing with proper scrolling
- **Exit to Home**: Exit button navigates to home screen instead of closing

## 🎯 Command Line Interface (Legacy)

While the unified dashboard is the recommended interface, the command line interface is still available:

### Scan for Photos
```bash
# Scan a folder (absolute path recommended)
python3 photo_tagger.py scan /path/to/photos

# Scan with relative path (auto-converted to absolute)
python3 photo_tagger.py scan demo_photos

# Scan recursively (recommended)
python3 photo_tagger.py scan /path/to/photos --recursive
```

### Process Photos for Faces
```bash
# Process 50 photos (default)
python3 photo_tagger.py process

# Process 20 photos with CNN model (more accurate)
python3 photo_tagger.py process --limit 20 --model cnn

# Process with HOG model (faster)
python3 photo_tagger.py process --limit 100 --model hog
```

### Individual GUI Windows (Legacy)
```bash
# Open individual GUI windows (legacy mode)
python3 photo_tagger.py identify --show-faces --batch 10
python3 photo_tagger.py auto-match --show-faces
python3 photo_tagger.py search-gui
python3 photo_tagger.py modifyidentified
python3 photo_tagger.py tag-manager
```

## 🏗️ Architecture: Web Migration Ready

### Current Desktop Architecture
```
┌─────────────────────────────────────────────────────────────┐
│                    Unified Dashboard                        │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                Menu Bar                                 ││
│  │ [🏠] [Scan] [Process] [Identify] [Search] [Tags] [Modify]││
│  └─────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────┐│
│  │                Content Area                             ││
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐      ││
│  │  │Home Panel   │ │Identify     │ │Search Panel │      ││
│  │  │(Welcome)    │ │Panel        │ │             │      ││
│  │  └─────────────┘ └─────────────┘ └─────────────┘      ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  PhotoTagger    │
                    │  (Business      │
                    │   Logic)        │
                    └─────────────────┘
```

### Future Web Architecture
```
┌─────────────────────────────────────────────────────────────┐
│                    Web Browser                              │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                Navigation Bar                           ││
│  │ [🏠] [Scan] [Process] [Identify] [Search] [Tags] [Modify]││
│  └─────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────┐│
│  │                Main Content Area                        ││
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐      ││
│  │  │Home Page    │ │Identify     │ │Search Page  │      ││
│  │  │(Welcome)    │ │Page         │ │             │      ││
│  │  └─────────────┘ └─────────────┘ └─────────────┘      ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  Web API        │
                    │  (Flask/FastAPI)│
                    └─────────────────┘
                                 │
                    ┌─────────────────┐
                    │  PhotoTagger    │
                    │  (Business      │
                    │   Logic)        │
                    └─────────────────┘
```

### Migration Benefits
- **Clean Separation**: Navigation (menu bar) and content (panels) are clearly separated
- **Panel-Based Design**: Each panel can become a web page/route
- **Service Layer**: Business logic is already separated from GUI components
- **State Management**: Panel switching system mirrors web routing concepts
- **API-Ready**: Panel methods can easily become API endpoints

## 🧭 Navigation & User Experience

### Smart Navigation System
- **🏠 Home Icon**: Compact home button (🏠) positioned at the leftmost side of the menu bar
- **Quick Return**: Single click to return to the welcome screen from any panel
- **Exit to Home**: All exit buttons in panels now navigate to home instead of closing the application
- **Consistent UX**: Unified navigation experience across all panels and features
- **Tooltip Support**: Hover over the home icon to see "Go to the welcome screen"

### Panel Integration
- **Seamless Switching**: All panels are fully integrated and functional
- **State Preservation**: Panel states are maintained when switching between features
- **Background Processing**: Long operations continue running when switching panels
- **Memory Management**: Proper cleanup and resource management across panels

### Recent Updates (Latest Version)
- **✅ Complete Panel Integration**: All 7 panels (Home, Scan, Process, Identify, Auto-Match, Search, Modify, Tags) are fully functional
- **🏠 Home Navigation**: Added compact home icon for instant return to welcome screen
- **🚪 Exit Button Enhancement**: All exit buttons now navigate to home instead of closing
- **🎨 UI Improvements**: Enhanced typography and responsive design for full screen experience
- **🔧 Code Quality**: Improved architecture with proper callback system for navigation

## 🔧 Advanced Features

### Face Recognition Technology
- **Quality Scoring**: Automatic assessment of face quality (0.0-1.0)
- **Smart Filtering**: Only high-quality faces used for matching
- **Multiple Models**: HOG (fast) and CNN (accurate) detection models
- **Encoding Caching**: Optimized performance with face encoding caching

### Database Management
- **SQLite Database**: Lightweight, portable database
- **Optimized Queries**: Efficient database operations
- **Connection Pooling**: Thread-safe database access
- **Automatic Schema**: Self-initializing database structure

### Performance Optimizations
- **Pre-fetching**: Data loaded in advance for faster UI response
- **Background Processing**: Long operations run in separate threads
- **Memory Management**: Efficient cleanup of temporary files and caches
- **Batch Operations**: Process multiple items efficiently

## 📊 Statistics and Monitoring

```bash
# View database statistics
python3 photo_tagger.py stats
```

**Statistics Include:**
- Total photos in database
- Total faces detected
- Identified vs unidentified faces
- People count
- Tag statistics
- Processing status

## 🔄 Common Commands Cheat Sheet

```bash
# Setup (one time)
python3 -m venv venv && source venv/bin/activate && python3 setup.py

# Daily usage - Unified Dashboard (RECOMMENDED)
source venv/bin/activate
python3 photo_tagger.py dashboard

# Then use the menu bar in the dashboard:
# 🏠 Home - Return to welcome screen (✅ Fully Functional)
# 📁 Scan - Add photos (✅ Fully Functional)
# 🔍 Process - Detect faces (✅ Fully Functional)
# 👤 Identify - Identify people (✅ Fully Functional)
# 🔗 Auto-Match - Find matches (✅ Fully Functional)
# 🔎 Search - Find photos (✅ Fully Functional)
# ✏️ Modify - Edit identifications (✅ Fully Functional)
# 🏷️ Tags - Manage tags (✅ Fully Functional)

# Legacy command line usage
python3 photo_tagger.py scan ~/Pictures --recursive
python3 photo_tagger.py process --limit 50
python3 photo_tagger.py identify --show-faces --batch 10
python3 photo_tagger.py auto-match --show-faces
python3 photo_tagger.py search-gui
python3 photo_tagger.py modifyidentified
python3 photo_tagger.py tag-manager
python3 photo_tagger.py stats
```

## 🚀 Development Roadmap

### Phase 1: Core Panel Integration ✅
- [x] Unified dashboard structure
- [x] Menu bar navigation
- [x] Panel switching system
- [x] Scan panel (fully functional)
- [x] Process panel (fully functional)
- [x] Home panel with welcome screen
- [x] Full screen mode with automatic maximization
- [x] Responsive design with dynamic resizing
- [x] Enhanced typography for full screen viewing

### Phase 2: GUI Panel Integration ✅
- [x] Identify panel integration (fully functional)
- [x] Auto-Match panel integration (fully functional)
- [x] Search panel integration (fully functional)
- [x] Modify panel integration (fully functional)
- [x] Tag Manager panel integration (fully functional)
- [x] Home icon navigation (compact home button in menu)
- [x] Exit button navigation (all exit buttons navigate to home)

### Phase 3: Web Migration Preparation
- [ ] Service layer extraction
- [ ] API endpoint design
- [ ] State management refactoring
- [ ] File handling abstraction

### Phase 4: Web Application
- [ ] Web API implementation
- [ ] Frontend development
- [ ] Authentication system
- [ ] Deployment configuration

## 🎉 Key Benefits

### User Experience
- **Single Window**: No more managing multiple windows
- **Full Screen Experience**: Automatically opens maximized for optimal viewing
- **Responsive Design**: All components adapt when window is resized
- **Consistent Interface**: All features follow the same design patterns
- **Professional Look**: Modern, clean interface design with enhanced typography
- **Intuitive Navigation**: Menu bar makes all features easily accessible
- **Smart Home Navigation**: Compact home icon (🏠) for quick return to welcome screen
- **Unified Exit Behavior**: All exit buttons navigate to home instead of closing
- **Complete Feature Set**: All panels fully functional and integrated

### Developer Experience
- **Modular Design**: Each panel is independent and maintainable
- **Web-Ready**: Architecture designed for easy web migration
- **Clean Code**: Clear separation of concerns
- **Extensible**: Easy to add new panels and features

### Performance
- **Optimized Loading**: Panels load only when needed
- **Background Processing**: Long operations don't block the UI
- **Memory Efficient**: Proper cleanup and resource management
- **Responsive**: Fast panel switching and updates
- **Dynamic Resizing**: Real-time layout updates during window resize
- **Cross-Platform**: Works on Windows, Linux, and macOS with proper full screen support

---

**Total project size**: ~4,000+ lines of Python code  
**Dependencies**: 6 essential packages  
**Setup time**: ~5 minutes  
**Perfect for**: Professional photo management with modern unified interface  
**Status**: All panels fully functional and integrated with smart navigation

## 📞 Support

For issues, questions, or contributions:
- **GitHub Issues**: Report bugs and request features
- **Documentation**: Check this README for detailed usage instructions
- **Community**: Join discussions about photo management and face recognition

---

*PunimTag - Making photo face recognition simple, powerful, and web-ready.*