punimtag/README.md

# PunimTag CLI - Minimal Photo Face Tagger

A simple command-line tool for automatic face recognition and photo tagging. No web interface, no complex dependencies - just the essentials.

## 📋 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 image viewing

### 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) - installs all dependencies including image viewer
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. Scan photos
python3 photo_tagger.py scan /path/to/your/photos

# 3. Process faces
python3 photo_tagger.py process

# 4. Identify faces with visual display
python3 photo_tagger.py identify --show-faces

# 5. Auto-match faces across photos (with improved algorithm)
python3 photo_tagger.py auto-match --show-faces

# 6. View and modify identified faces (NEW!)
python3 photo_tagger.py modifyidentified

# 7. View statistics
python3 photo_tagger.py stats
```

## 📦 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
```

## 🎯 Commands

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

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

### Process Photos for Faces (with Quality Scoring)
```bash
# Process 50 photos (default) - now includes face quality scoring
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
```

**🔬 Quality Scoring Features:**
- **Automatic Assessment** - Each face gets a quality score (0.0-1.0) based on multiple factors
- **Smart Filtering** - Only faces above quality threshold (≥0.2) are used for matching
- **Quality Metrics** - Evaluates sharpness, brightness, contrast, size, aspect ratio, and position
- **Verbose Output** - Use `--verbose` to see quality scores during processing

### Identify Faces (GUI-Enhanced!)
```bash
# Identify with GUI interface and face display (RECOMMENDED)
python3 photo_tagger.py identify --show-faces --batch 10

# GUI mode without face crops (coordinates only)
python3 photo_tagger.py identify --batch 10

# Auto-match faces across photos with GUI (NEW!)
python3 photo_tagger.py auto-match --show-faces

# Auto-identify high-confidence matches
python3 photo_tagger.py auto-match --auto --show-faces
```

**🎯 New GUI-Based Identification Features:**
- 🖼️ **Visual Face Display** - See individual face crops in the GUI
- 📝 **Dropdown Name Selection** - Choose from known people or type new names
- ☑️ **Compare with Similar Faces** - Compare current face with similar unidentified faces
- 🎨 **Modern Interface** - Clean, intuitive GUI with buttons and input fields
- 💾 **Window Size Memory** - Remembers your preferred window size
- 🚫 **No Terminal Input** - All interaction through the GUI interface
- ⬅️ **Back Navigation** - Go back to previous faces (shows images and identification status)
- 🔄 **Re-identification** - Change identifications by going back and re-identifying
- 💾 **Auto-Save** - All identifications are saved immediately (no need to save manually)
- ☑️ **Select All/Clear All** - Bulk selection buttons for similar faces (enabled only when Compare is active)
- ⚠️ **Smart Navigation Warnings** - Prevents accidental loss of selected similar faces
- 💾 **Quit Confirmation** - Saves pending identifications when closing the application
- ⚡ **Performance Optimized** - Pre-fetched data for faster similar faces display

**🎯 New Auto-Match GUI Features:**
- 📊 **Person-Centric View** - Shows matched person on left, all their unidentified faces on right
- ☑️ **Checkbox Selection** - Select which unidentified faces to identify with this person
- 📈 **Confidence Percentages** - Color-coded match confidence levels
- 🖼️ **Side-by-Side Layout** - Matched person on left, unidentified faces on right
- 📜 **Scrollable Matches** - Handle many potential matches easily
- 🎮 **Enhanced Controls** - Back, Next, or Quit buttons (navigation only)
- 💾 **Smart Save Button** - "Save changes for [Person Name]" button in left panel
- 🔄 **State Persistence** - Checkbox selections preserved when navigating between people
- 🚫 **Smart Navigation** - Next button disabled on last person, Back button disabled on first
- 💾 **Bidirectional Changes** - Can both identify and unidentify faces in the same session
- ⚡ **Optimized Performance** - Efficient database queries and streamlined interface

### View & Modify Identified Faces (NEW)
```bash
# Open the Modify Identified Faces interface
python3 photo_tagger.py modifyidentified
```

This GUI lets you quickly review all identified people, rename them, and temporarily unmatch faces before committing.

**Left Panel (People):**
- 👥 **People List** - Shows all identified people with face counts
- 🖱️ **Clickable Names** - Click to select a person (selected name is bold)
- ✏️ **Edit Name Icon** - Rename a person; tooltip shows "Update name"

**Right Panel (Faces):**
- 🧩 **Person Faces** - Thumbnails of all faces identified as the selected person
- ❌ **X on Each Face** - Temporarily unmatch a face (does not save yet)
- ↶ **Undo Changes** - Restores unmatched faces for the current person only
- 🔄 **Responsive Grid** - Faces wrap to the next line when the panel is narrow

**Bottom Controls:**
- 💾 **Save changes** - Commits all pending unmatched faces across all people to the database
- ❌ **Quit** - Closes the window (unsaved temporary changes are discarded)

Notes:
- Changes are temporary until you click "Save changes" at the bottom.
- Undo restores only the currently viewed person's faces.
- Saving updates the database and refreshes counts.

## 🧠 Advanced Algorithm Features

**🎯 Intelligent Face Matching Engine:**
- 🔍 **Face Quality Scoring** - Automatically evaluates face quality based on sharpness, brightness, contrast, size, and position
- 📊 **Adaptive Tolerance** - Adjusts matching strictness based on face quality (higher quality = stricter matching)
- 🚫 **Quality Filtering** - Only processes faces above minimum quality threshold (≥0.2) for better accuracy
- 🎯 **Smart Matching** - Uses multiple quality factors to determine the best matches
- ⚡ **Performance Optimized** - Efficient database queries with quality-based indexing

**🔬 Quality Assessment Metrics:**
- **Sharpness Detection** - Uses Laplacian variance to detect blurry faces
- **Brightness Analysis** - Prefers faces with optimal lighting conditions
- **Contrast Evaluation** - Higher contrast faces score better for recognition
- **Size Optimization** - Larger, clearer faces get higher quality scores
- **Aspect Ratio** - Prefers square face crops for better recognition
- **Position Scoring** - Centered faces in photos score higher

**📈 Confidence Levels:**
- 🟢 **Very High (80%+)** - Almost Certain match
- 🟡 **High (70%+)** - Likely Match
- 🟠 **Medium (60%+)** - Possible Match
- 🔴 **Low (50%+)** - Questionable
- ⚫ **Very Low (<50%)** - Unlikely

**GUI Interactive Elements:**
- **Person Name Dropdown** - Select from known people or type new names
- **Compare Checkbox** - Compare with similar unidentified faces (persistent setting)
- **Identify Button** - Confirm the identification (saves immediately)
- **Back Button** - Go back to previous face (shows image and identification status)
- **Next Button** - Move to next face
- **Quit Button** - Exit application (all changes already saved)

### Add Tags
```bash
# Tag photos matching pattern
python3 photo_tagger.py tag --pattern "vacation"

# Tag any photos
python3 photo_tagger.py tag
```

### Search
```bash
# Find photos with a person
python3 photo_tagger.py search "John"

# Find photos with partial name match
python3 photo_tagger.py search "Joh"
```

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

## 📊 Enhanced Example Workflow

```bash
# ALWAYS activate virtual environment first!
source venv/bin/activate

# 1. Scan your photo collection
python3 photo_tagger.py scan ~/Pictures --recursive

# 2. Process photos for faces (start with small batch)
python3 photo_tagger.py process --limit 20

# 3. Check what we found
python3 photo_tagger.py stats

# 4. Identify faces with GUI interface (ENHANCED!)
python3 photo_tagger.py identify --show-faces --batch 10

# 5. Auto-match faces across photos with GUI (NEW!)
python3 photo_tagger.py auto-match --show-faces

# 6. Search for photos of someone
python3 photo_tagger.py search "Alice"

# 7. Add some tags
python3 photo_tagger.py tag --pattern "birthday"
```

## 🗃️ Database

The tool uses SQLite database (`data/photos.db` by default) with these tables:
- **photos** - Photo file paths and processing status
- **people** - Known people names
- **faces** - Face encodings and locations
- **tags** - Custom tags for photos

## ⚙️ Configuration

### Face Detection Models
- **hog** - Faster, good for CPU-only systems
- **cnn** - More accurate, requires more processing power

### Database Location
```bash
# Use custom database file
python3 photo_tagger.py scan /photos --db /path/to/my.db
```

## 🔧 System Requirements

### Required System Packages (Ubuntu/Debian)
```bash
sudo apt update
sudo apt install -y cmake build-essential libopenblas-dev liblapack-dev libx11-dev libgtk-3-dev python3-dev python3-venv
```

### Python Dependencies
- `face-recognition` - Face detection and recognition
- `dlib` - Machine learning library  
- `pillow` - Image processing
- `numpy` - Numerical operations
- `click` - Command line interface
- `setuptools` - Package management

## 📁 File Structure

```
PunimTag/
├── photo_tagger.py     # Main CLI tool
├── setup.py           # Setup script
├── run.sh             # Convenience script (auto-activates venv)
├── requirements.txt   # Python dependencies
├── README.md          # This file
├── gui_config.json    # GUI window size preferences (created automatically)
├── venv/              # Virtual environment (created by setup)
├── data/
│   └── photos.db      # Database (created automatically)
├── data/              # Additional data files
└── logs/              # Log files
```

## 🚨 Troubleshooting

### "externally-managed-environment" Error
**Solution**: Always use a virtual environment!
```bash
python3 -m venv venv
source venv/bin/activate
python3 setup.py
```

### Virtual Environment Not Active
**Problem**: Commands fail or use wrong Python
**Solution**: Always activate the virtual environment:
```bash
source venv/bin/activate
# You should see (venv) in your prompt
```

### Image Viewer Not Opening During Identify
**Problem**: Face crops are saved but don't open automatically
**Solution**: The setup script installs `feh` (image viewer) automatically on Ubuntu/Debian. For other systems:
- **Ubuntu/Debian**: `sudo apt install feh`
- **macOS**: `brew install feh`
- **Windows**: Install a Linux subsystem or use WSL
- **Alternative**: Use `--show-faces` flag without auto-opening - face crops will be saved to `/tmp/` for manual viewing

### GUI Interface Issues
**Problem**: GUI doesn't appear or has issues
**Solution**: The tool now uses tkinter for all identification interfaces:
- **Ubuntu/Debian**: `sudo apt install python3-tk` (usually pre-installed)
- **macOS**: tkinter is included with Python
- **Windows**: tkinter is included with Python
- **Fallback**: If GUI fails, the tool will show error messages and continue

**Common GUI Issues:**
- **Window appears in corner**: The GUI centers itself automatically on first run
- **Window size not remembered**: Check that `gui_config.json` is writable
- **"destroy" command error**: Fixed in latest version - window cleanup is now safe
- **GUI freezes**: Use Ctrl+C to interrupt, then restart the command

### dlib Installation Issues
```bash
# Ubuntu/Debian - install system dependencies first
sudo apt-get install build-essential cmake libopenblas-dev

# Then retry setup
source venv/bin/activate
python3 setup.py
```

### "Please install face_recognition_models" Warning
This warning is harmless - the application still works correctly. It's a known issue with Python 3.13.

### Memory Issues
- Use `--model hog` for faster processing
- Process in smaller batches with `--limit 10`
- Close other applications to free memory

### No Faces Found
- Check image quality and lighting
- Ensure faces are clearly visible
- Try `--model cnn` for better detection

## 🎨 GUI Interface Guide

### Face Identification GUI
When you run `python3 photo_tagger.py identify --show-faces`, you'll see:

**Left Panel:**
- 📁 **Photo Info** - Shows filename and face location
- 🖼️ **Face Image** - Individual face crop for easy identification
- ✅ **Identification Status** - Shows if face is already identified and by whom

**Right Panel:**
- 📝 **Person Name Dropdown** - Select from known people or type new names (pre-filled for re-identification)
- ☑️ **Compare Checkbox** - Compare with similar unidentified faces (persistent across navigation)
- ☑️ **Select All/Clear All Buttons** - Bulk selection controls (enabled only when Compare is active)
- 📜 **Similar Faces List** - Scrollable list of similar unidentified faces with:
  - ☑️ **Individual Checkboxes** - Select specific faces to identify together
  - 📈 **Confidence Percentages** - Color-coded match quality
  - 🖼️ **Face Images** - Thumbnail previews of similar faces
- 🎮 **Control Buttons**:
  - **✅ Identify** - Confirm the identification (saves immediately)
  - **⬅️ Back** - Go back to previous face (shows image and status)
  - **➡️ Next** - Move to next face
  - **❌ Quit** - Exit application (all changes already saved)

### Auto-Match GUI (Enhanced with Smart Algorithm)
When you run `python3 photo_tagger.py auto-match --show-faces`, you'll see an improved interface with:

**🧠 Smart Algorithm Features:**
- **Quality-Based Matching** - Only high-quality faces are processed for better accuracy
- **Adaptive Tolerance** - Matching strictness adjusts based on face quality
- **Confidence Scoring** - Color-coded confidence levels (🟢 Very High, 🟡 High, 🟠 Medium, 🔴 Low, ⚫ Very Low)
- **Performance Optimized** - Faster processing with quality-based filtering

**Interface Layout:**

**Left Panel:**
- 👤 **Matched Person** - The already identified person
- 🖼️ **Person Face Image** - Individual face crop of the matched person
- 📁 **Photo Info** - Shows person name, photo filename, and face location
- 💾 **Save Button** - "Save changes for [Person Name]" - saves all checkbox selections

**Right Panel:**
- ☑️ **Unidentified Faces** - All unidentified faces that match this person (sorted by confidence):
  - ☑️ **Checkboxes** - Select which faces to identify with this person (pre-selected if previously identified)
  - 📈 **Confidence Percentages** - Color-coded match quality (highest confidence at top)
  - 🖼️ **Face Images** - Face crops of unidentified faces
- 📜 **Scrollable** - Handle many matches easily
- 🎯 **Smart Ordering** - Highest confidence matches appear first for easy selection

**Bottom Controls (Navigation Only):**
- **⏮️ Back** - Go back to previous person (disabled on first person)
- **⏭️ Next** - Move to next person (disabled on last person)
- **❌ Quit** - Exit auto-match process

### Compare with Similar Faces Workflow
The Compare feature in the Identify GUI works seamlessly with the main identification process:

1. **Enable Compare**: Check "Compare with similar faces" to see similar unidentified faces
2. **View Similar Faces**: Right panel shows all similar faces with confidence percentages and thumbnails
3. **Select Faces**: Use individual checkboxes or Select All/Clear All buttons to choose faces
4. **Enter Person Name**: Type or select the person's name in the dropdown
5. **Identify Together**: Click Identify to identify the current face and all selected similar faces at once
6. **Smart Navigation**: System warns if you try to navigate away with selected faces but no name
7. **Quit Protection**: When closing, system offers to save any pending identifications

**Key Benefits:**
- **Bulk Identification**: Identify multiple similar faces with one action
- **Visual Confirmation**: See exactly which faces you're identifying together
- **Smart Warnings**: Prevents accidental loss of work
- **Performance Optimized**: Instant loading of similar faces

### Auto-Match Workflow
The auto-match feature now 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
- **Fast Performance**: Optimized database queries and streamlined interface

### GUI Tips
- **Window Resizing**: Resize the window - it remembers your size preference
- **Keyboard Shortcuts**: Press Enter in the name field to identify
- **Back Navigation**: Use Back button to return to previous faces - images and identification status are preserved
- **Re-identification**: Go back to any face and change the identification - the name field is pre-filled
- **Auto-Save**: All identifications are saved immediately - no need to manually save
- **Compare Mode**: Enable Compare checkbox to see similar unidentified faces - setting persists across navigation
- **Bulk Selection**: Use Select All/Clear All buttons to quickly select or clear all similar faces
- **Smart Buttons**: Select All/Clear All buttons are only enabled when Compare mode is active
- **Navigation Warnings**: System warns if you try to navigate away with selected faces but no person name
- **Quit Confirmation**: When closing, system asks if you want to save pending identifications
- **Consistent Results**: Compare mode shows the same faces as auto-match with identical confidence scoring
- **Multiple Matches**: In auto-match, you can select multiple faces to identify with one person
- **Smart Navigation**: Back/Next buttons are disabled appropriately (Back disabled on first, Next disabled on last)
- **State Persistence**: Checkbox selections are preserved when navigating between people
- **Per-Person States**: Each person's selections are completely independent
- **Save Button Location**: Save button is in the left panel with the person's name for clarity
- **Performance**: Similar faces load instantly thanks to pre-fetched data optimization
- **Bidirectional Changes**: You can both identify and unidentify faces in the same session
- **Confidence Colors**: 
  - 🟢 80%+ = Very High (Almost Certain)
  - 🟡 70%+ = High (Likely Match)
  - 🟠 60%+ = Medium (Possible Match)
  - 🔴 50%+ = Low (Questionable)
  - ⚫ <50% = Very Low (Unlikely)

## 🆕 Recent Improvements

### Auto-Match UX Enhancements (Latest)
- **💾 Smart Save Button**: "Save changes for [Person Name]" button moved to left panel for better UX
- **🔄 State Persistence**: Checkbox selections now preserved when navigating between people
- **🚫 Smart Navigation**: Next button disabled on last person, Back button disabled on first
- **🎯 Per-Person States**: Each person's checkbox selections are completely independent
- **⚡ Real-time Saving**: Checkbox states saved immediately when changed

### Consistent Face-to-Face Comparison System
- **🔄 Unified Logic**: Both auto-match and identify now use the same face comparison algorithm
- **📊 Consistent Results**: Identical confidence scoring and face matching across both modes
- **🎯 Same Tolerance**: Both functionalities respect the same tolerance settings
- **⚡ Performance**: Eliminated code duplication for better maintainability
- **🔧 Refactored**: Single reusable function for face filtering and sorting

### Compare Checkbox Enhancements
- **🌐 Global Setting**: Compare checkbox state persists when navigating between faces
- **🔄 Auto-Update**: Similar faces automatically refresh when using Back/Next buttons
- **👥 Consistent Display**: Compare mode shows the same faces as auto-match
- **📈 Smart Filtering**: Only shows faces with 40%+ confidence (same as auto-match)
- **🎯 Proper Sorting**: Faces sorted by confidence (highest first)

### Back Navigation & Re-identification
- **⬅️ Back Button**: Navigate back to previous faces with full image display
- **🔄 Re-identification**: Change any identification by going back and re-identifying
- **📝 Pre-filled Names**: Name field shows current identification for easy changes
- **✅ Status Display**: Shows who each face is identified as when going back

### Improved Cleanup & Performance
- **🧹 Better Cleanup**: Proper cleanup of temporary files and resources
- **💾 Auto-Save**: All identifications save immediately (removed redundant Save & Quit)
- **🔄 Code Reuse**: Eliminated duplicate functions for better maintainability
- **⚡ Optimized**: Faster navigation and better memory management

### Enhanced User Experience
- **🖼️ Image Preservation**: Face images show correctly when navigating back
- **🎯 Smart Caching**: Face crops are properly cached and cleaned up
- **🔄 Bidirectional Changes**: Can both identify and unidentify faces in same session
- **💾 Window Memory**: Remembers window size and position preferences

## 🎯 What This Tool Does

✅ **Simple**: Single Python file, minimal dependencies
✅ **Fast**: Efficient face detection and recognition  
✅ **Private**: Everything runs locally, no cloud services
✅ **Flexible**: Batch processing, interactive identification
✅ **Lightweight**: No web interface overhead
✅ **GUI-Enhanced**: Modern interface for face identification
✅ **User-Friendly**: Back navigation, re-identification, and auto-save

## 📈 Performance Tips

- **Always use virtual environment** to avoid conflicts
- Start with small batches (`--limit 20`) to test
- Use `hog` model for speed, `cnn` for accuracy
- Process photos in smaller folders first
- Identify faces in batches to avoid fatigue

## 🤝 Contributing

This is now a minimal, focused tool. Key principles:
- Keep it simple and fast
- CLI-only interface
- Minimal dependencies
- Clear, readable code
- **Always use python3** commands

---

**Total project size**: ~300 lines of Python code
**Dependencies**: 6 essential packages
**Setup time**: ~5 minutes
**Perfect for**: Batch processing personal photo collections

## 🔄 Common Commands Cheat Sheet

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

# Daily usage - Option 1: Use run script (automatic venv activation)
./run.sh scan ~/Pictures --recursive
./run.sh process --limit 50
./run.sh identify --show-faces --batch 10
./run.sh auto-match --show-faces
./run.sh modifyidentified
./run.sh stats

# Daily usage - Option 2: Manual venv activation (GUI-ENHANCED)
source venv/bin/activate
python3 photo_tagger.py scan ~/Pictures --recursive
python3 photo_tagger.py process --limit 50
python3 photo_tagger.py identify --show-faces --batch 10  # Opens GUI
python3 photo_tagger.py auto-match --show-faces          # Opens GUI
python3 photo_tagger.py modifyidentified                  # Opens GUI to view/modify
python3 photo_tagger.py stats
```