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
- 📝 **Separate Name Fields** - Dedicated text input fields for first name, last name, middle name, and maiden name
- 🎯 **Direct Field Storage** - Names are stored directly in separate fields for maximum reliability
- 🔤 **Last Name Autocomplete** - Smart autocomplete for last names with live filtering as you type
- ⭐ **Required Field Indicators** - Red asterisks (*) mark required fields (first name, last name, date of birth)
- ☑️ **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
- 🎯 **Clean Database Storage** - Names are stored as separate first_name and last_name fields without commas
- 🔧 **Improved Data Handling** - Fixed field restoration and quit confirmation logic for better reliability
 - 🧩 **Unique Faces Only Filter (NEW)**
   - Checkbox in the Date Filters section: "Unique faces only (hide duplicates with high/medium confidence)"
   - Applies only to the main face list (left/navigation); the Similar Faces panel (right) remains unfiltered
   - Groups faces with ≥60% confidence matches (Medium/High/Very High) and shows only one representative
   - Takes effect immediately when toggled (no need to click Apply Filter); Apply Filter is only for date filters
   - Uses existing database encodings for fast, non-blocking filtering

**🎯 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
 - 🔍 **Last Name Search** - Filter matched people by last name (case-insensitive) in the left panel
 - 🎯 **Filter-Aware Navigation** - Auto-selects the first match; Back/Next respect the filtered list

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

### Tag Manager GUI (NEW)
```bash
# Open the Tag Management interface
python3 photo_tagger.py tag-manager
```

This GUI provides a file explorer-like interface for managing photo tags with advanced column resizing and multiple view modes.

**🎯 Tag Manager Features:**
- 📊 **Multiple View Modes** - List view, icon view, compact view, and folder view for different needs
- 📁 **Folder Grouping** - Group photos by directory with expandable/collapsible folders
- 🔧 **Resizable Columns** - Drag column separators to resize both headers and data rows
- 👁️ **Column Visibility** - Right-click to show/hide columns in each view mode
- 🖼️ **Thumbnail Display** - Icon view shows photo thumbnails with metadata
- 📱 **Responsive Layout** - Adapts to window size with proper scrolling
- 🎨 **Modern Interface** - Clean, intuitive design with visual feedback
- ⚡ **Fast Performance** - Optimized for large photo collections
- 🏷️ **Smart Tag Management** - Duplicate tag prevention with silent handling
- 🔄 **Accurate Change Tracking** - Only counts photos with actual new tags as "changed"
- 🎯 **Reliable Tag Operations** - Uses tag IDs internally for consistent, bug-free behavior

**📋 Available View Modes:**

**List View:**
- 📄 **Detailed Information** - Shows ID, filename, path, processed status, date taken, face count, and tags
- 🔧 **Resizable Columns** - Drag red separators between columns to resize
- 📊 **Column Management** - Right-click headers to show/hide columns
- 🎯 **Full Data Access** - Complete photo information in tabular format

**Icon View:**
- 🖼️ **Photo Thumbnails** - Visual grid of photo thumbnails (150x150px)
- 📝 **Metadata Overlay** - Shows ID, filename, processed status, date taken, face count, and tags
- 📱 **Responsive Grid** - Thumbnails wrap to fit window width
- 🎨 **Visual Navigation** - Easy browsing through photo collection

**Compact View:**
- 📄 **Essential Info** - Shows filename, face count, and tags only
- ⚡ **Fast Loading** - Minimal data for quick browsing
- 🎯 **Focused Display** - Perfect for quick tag management

**Folder View:**
- 📁 **Directory Grouping** - Photos grouped by their directory path
- 🔽 **Expandable Folders** - Click folder headers to expand/collapse
- 📊 **Photo Counts** - Shows number of photos in each folder
- 🎯 **File Explorer Style** - Familiar tree-like interface
- 📄 **Photo Details** - Shows filename, processed status, date taken, face count, and tags
- 🖱️ **Easy Navigation** - Click anywhere on folder header to toggle

**🔧 Column Resizing:**
- 🖱️ **Drag to Resize** - Click and drag red separators between columns
- 📏 **Minimum Width** - Columns maintain minimum 50px width
- 🔄 **Real-time Updates** - Both headers and data rows resize together
- 💾 **Persistent Settings** - Column widths remembered between sessions
- 🎯 **Visual Feedback** - Cursor changes and separator highlighting during resize

**👁️ Column Management:**
- 🖱️ **Right-click Headers** - Access column visibility menu
- ✅ **Toggle Columns** - Show/hide individual columns in each view mode
- 🎯 **View-Specific** - Column settings saved per view mode
- 🔄 **Instant Updates** - Changes apply immediately

**📁 Folder View Usage:**
- 🖱️ **Click Folder Headers** - Click anywhere on a folder row to expand/collapse
- 🔽 **Expand/Collapse Icons** - ▶ indicates collapsed, ▼ indicates expanded
- 📊 **Photo Counts** - Each folder shows "(X photos)" in the header
- 🎯 **Root Directory** - Photos without a directory path are grouped under "Root"
- 📁 **Alphabetical Sorting** - Folders are sorted alphabetically by directory name
- 🖼️ **Photo Details** - Expanded folders show all photos with their metadata
- 🔄 **Persistent State** - Folder expansion state is maintained while browsing

**Left Panel (People):**
- 🔍 **Last Name Search** - Search box to filter people by last name (case-insensitive)
- 🔎 **Search Button** - Apply filter to show only matching people
- 🧹 **Clear Button** - Reset filter to show all people
- 👥 **People List** - Shows all identified people with face counts in full name format including middle names, maiden names, and birth dates
- 🖱️ **Clickable Names** - Click to select a person (selected name is bold)
- ✏️ **Edit Name Icon** - Comprehensive person editing with all fields; tooltip shows "Update name"
- 📝 **Complete Person Fields** - Edit with dedicated fields for:
  - **First Name** and **Last Name** (required)
  - **Middle Name** and **Maiden Name** (optional)
  - **Date of Birth** with visual calendar picker (required)
- 💡 **Smart Validation** - Save button only enabled when all required fields are filled
- 📅 **Calendar Integration** - Click 📅 button to open visual date picker
- 🎨 **Enhanced Layout** - Organized grid layout with labels directly under each field

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

**Performance Features:**
- ⚡ **Optimized Database Access** - Loads all people data once when opening, saves only when needed
- 🚫 **No Database Queries During Editing** - All editing operations use pre-loaded data
- 💾 **Immediate Person Saves** - Person information saved directly to database when clicking save
- 🔄 **Real-time Validation** - Save button state updates instantly as you type
- 📅 **Visual Calendar** - Professional date picker with month/year navigation

Notes:
- **Person Information**: Saved immediately to database when clicking the 💾 save button in edit mode
- **Face Unmatching**: Changes are temporary until you click "Save changes" at the bottom
- **Validation**: Save button only enabled when first name, last name, and date of birth are all provided
- **Calendar**: Date picker opens to existing date when editing, defaults to 25 years ago for new entries
- **Undo**: Restores only the currently viewed person's unmatched faces
- **Data Storage**: All person fields stored separately (first_name, last_name, middle_name, maiden_name, date_of_birth)

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

### Tag Manager GUI
```bash
# Open tag management interface
python3 photo_tagger.py tag-manager
```

## 📊 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"

# 8. Manage tags with GUI interface
python3 photo_tagger.py tag-manager
```

## 🗃️ Database

The tool uses SQLite database (`data/photos.db` by default) with these tables:

### Core Tables
- **photos** - Photo file paths and processing status
- **people** - Known people with separate first_name, last_name, and date_of_birth fields
- **faces** - Face encodings, locations, and quality scores
- **tags** - Tag definitions (unique tag names)
- **phototaglinkage** - Links between photos and tags (many-to-many relationship)
- **person_encodings** - Face encodings for each person (for matching)

### Database Schema Improvements
- **Clean Name Storage** - People table uses separate `first_name` and `last_name` fields
- **Date of Birth Integration** - People table includes `date_of_birth` column for complete identification
- **Unique Constraint** - Prevents duplicate people with same name and birth date combination
- **No Comma Issues** - Names are stored without commas, displayed as "Last, First" format
- **Quality Scoring** - Faces table includes quality scores for better matching
- **Normalized Tag Structure** - Separate `tags` table for tag definitions and `phototaglinkage` table for photo-tag relationships
- **No Duplicate Tags** - Unique constraint prevents duplicate tag-photo combinations
- **Optimized Queries** - Efficient indexing and query patterns for fast performance
- **Data Integrity** - Proper foreign key relationships and constraints
- **Tag ID-Based Operations** - All tag operations use efficient ID-based lookups instead of string comparisons
- **Robust Tag Handling** - Eliminates string parsing issues and edge cases in tag management

## ⚙️ 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 Fields** - Text input fields for:
  - **First name** (required)
  - **Last name** (required) 
  - **Middle name** (optional)
  - **Maiden name** (optional)
- 📅 **Date of Birth** - Required date field with calendar picker (📅 button)
- ☑️ **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) - requires first name, last name, and date of birth
  - **⬅️ Back** - Go back to previous face (shows image and status, repopulates fields)
  - **➡️ Next** - Move to next face (clears date of birth, middle name, and maiden name fields)
  - **❌ Quit** - Exit application (saves complete identifications only)

### 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 with complete information
- 🖼️ **Person Face Image** - Individual face crop of the matched person
- 📁 **Detailed Person Info** - Shows:
  - **Full Name** with middle and maiden names (if available)
  - **Date of Birth** (if available)
  - **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 the person's name in the text input fields
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

### Unique Faces Only Filter
- Location: in the "Date Filters" bar at the top of the Identify GUI.
- Behavior:
  - Filters the main navigation list on the left to avoid showing near-duplicate faces of the same person.
  - The Similar Faces panel on the right is NOT filtered and continues to show all similar faces for comparison.
  - Confidence rule: faces that match at ≥60% (Medium/High/Very High) are grouped; only one shows in the main list.
- Interaction:
  - Takes effect immediately when toggled. You do NOT need to press Apply Filter.
  - Apply Filter continues to control the date filters only (Taken/Processed ranges).
  - Filtering uses precomputed encodings from the database, so it is fast and non-blocking.

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

### 📅 Calendar Interface Guide
When you click the 📅 calendar button, you'll see:

**Calendar Features:**
- **Visual Grid Layout** - Traditional 7x7 calendar with clickable dates
- **Month/Year Navigation** - Use << >> < > buttons to navigate
- **Date Selection** - Click any date to select it
- **Visual Feedback** - Selected dates highlighted in bright blue, today's date in orange
- **Smart Pre-population** - Opens to existing date when editing previous identifications
- **Smooth Operation** - Opens centered without flickering

**Calendar Navigation:**
- **<< >>** - Jump by year (limited to 1900-current year)
- **< >** - Navigate by month
- **Click Date** - Select any visible date
- **Select Button** - Confirm your date choice
- **Cancel Button** - Close without selecting

### 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 - all fields are 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
- **Field Requirements**: First name, last name, and date of birth must be filled to identify (middle name and maiden name are optional)
- **Navigation Memory**: Date field clears on forward navigation, repopulates on back navigation
- **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
- GUI-enhanced interface for identification
- Minimal dependencies
- Clear, readable code
- **Always use python3** commands

## 🆕 Recent Improvements (Latest Version)

### 🔧 Data Storage & Reliability Improvements (NEW!)
- ✅ **Eliminated Redundant Storage** - Removed unnecessary combined name field for cleaner data structure
- ✅ **Direct Field Access** - Names stored and accessed directly without parsing/combining logic
- ✅ **Fixed Quit Confirmation** - Proper detection of pending identifications when quitting
- ✅ **Improved Error Handling** - Better type consistency prevents runtime errors
- ✅ **Enhanced Performance** - Eliminated string manipulation overhead for faster operations

### 🔄 Field Navigation & Preservation Fixes
- ✅ **Fixed Name Field Confusion** - First and last names now stay in correct fields during navigation
- ✅ **Enhanced Data Storage** - Individual field tracking prevents name swapping issues
- ✅ **Date of Birth Preservation** - Date of birth now preserved even when entered alone (without names)
- ✅ **Consistent Field Handling** - All navigation (Next/Back) uses unified field management logic
- ✅ **Smart Field Population** - Fields correctly repopulate based on original input context

### 📅 Date of Birth Integration
- ✅ **Required Date of Birth** - All face identifications now require date of birth
- ✅ **Visual Calendar Picker** - Interactive calendar widget for easy date selection
- ✅ **Smart Pre-population** - Calendar opens to existing date when editing
- ✅ **Database Schema Update** - People table now includes date_of_birth column
- ✅ **Unique Constraint** - Prevents duplicate people with same first name, last name, middle name, maiden name, and birth date
- ✅ **Field Validation** - First name, last name, and date of birth required; middle name and maiden name optional
- ✅ **Navigation Memory** - Date field clears on forward navigation, repopulates on back navigation

### 🎨 Enhanced Calendar Interface
- ✅ **Visual Calendar Grid** - Traditional 7x7 calendar layout with clickable dates
- ✅ **Month/Year Navigation** - Easy navigation with << >> < > buttons
- ✅ **Prominent Selection** - Selected dates highlighted in bright blue
- ✅ **Today Highlighting** - Current date shown in orange when visible
- ✅ **Smooth Positioning** - Calendar opens centered without flickering
- ✅ **Isolated Styling** - Calendar styles don't affect other dialog buttons

### 🔄 Smart Field Management
- ✅ **Forward Navigation** - Date of birth, middle name, and maiden name fields clear when moving to next face
- ✅ **Backward Navigation** - All fields repopulate with previously entered data

### 🆕 Enhanced Person Information (LATEST!)
- ✅ **Middle Name Field** - Optional middle name input field added to person identification
- ✅ **Maiden Name Field** - Optional maiden name input field added to person identification
- ✅ **Simplified Interface** - Removed dropdown functionality for cleaner, faster data entry
- ✅ **Optimized Field Layout** - Date of birth positioned before maiden name for better workflow
- ✅ **Enhanced Database Schema** - People table now includes middle_name and maiden_name columns
- ✅ **Unique Constraint Update** - Prevents duplicate people with same combination of all five fields
- ✅ **Streamlined Data Entry** - All name fields are now simple text inputs for faster typing

### 🏷️ Tag System Improvements (NEW!)
- ✅ **Tag ID-Based Architecture** - Complete refactoring to use tag IDs internally instead of tag names
- ✅ **Eliminated String Parsing Issues** - No more problems with empty strings, whitespace, or parsing errors
- ✅ **Improved Performance** - Tag ID comparisons are faster than string comparisons
- ✅ **Better Reliability** - No case sensitivity issues or string parsing bugs
- ✅ **Database Efficiency** - Direct ID operations instead of string lookups
- ✅ **Cleaner Architecture** - Clear separation between internal logic (IDs) and display (names)
- ✅ **Duplicate Prevention** - Silent prevention of duplicate tags without warning messages
- ✅ **Accurate Change Counting** - Only photos with actual new tags are counted as "changed"
- ✅ **Robust Tag Parsing** - Handles edge cases like empty tag strings and malformed data
- ✅ **Consistent Behavior** - All tag operations use the same reliable logic throughout the application

### 🎨 Enhanced Modify Identified Interface (NEW!)
- ✅ **Complete Person Information** - Shows full names with middle names, maiden names, and birth dates
- ✅ **Last Name Search** - Filter people by last name with case-insensitive search
- ✅ **Auto-Selection** - Automatically selects first person in filtered results
- ✅ **Comprehensive Editing** - Edit all person fields: first, last, middle, maiden names, and date of birth
- ✅ **Visual Calendar Integration** - Professional date picker with month/year navigation
- ✅ **Smart Validation** - Save button only enabled when all required fields (first name, last name, date of birth) are filled
- ✅ **Real-time Feedback** - Button state updates instantly as you type or clear fields
- ✅ **Enhanced Layout** - Organized grid layout with labels directly under each input field
- ✅ **Immediate Database Saves** - Person information saved directly to database when clicking save
- ✅ **Visual Button States** - Disabled save button clearly grayed out when validation fails

### Name Handling & Database
- ✅ **Fixed Comma Issues** - Names are now stored cleanly without commas in database
- ✅ **Separate Name Fields** - First name and last name are stored in separate database columns
- ✅ **Smart Parsing** - Supports "Last, First" input format that gets properly parsed
- ✅ **Optimized Database Access** - Single load/save operations for better performance

### GUI Enhancements
- ✅ **Improved Edit Interface** - Separate text boxes for first and last names with help text
- ✅ **Better Layout** - Help text positioned below input fields for clarity
- ✅ **Tooltips** - Edit buttons show helpful tooltips
- ✅ **Responsive Design** - Face grids adapt to window size

### Performance & Reliability
- ✅ **Efficient Database Operations** - Pre-loads data, saves only when needed
- ✅ **Fixed Virtual Environment** - Run script now works properly with dependencies
- ✅ **Clean Code Structure** - Improved error handling and state management

---

**Total project size**: ~3,800 lines of Python code
**Dependencies**: 6 essential packages
**Setup time**: ~5 minutes
**Perfect for**: Batch processing personal photo collections with modern GUI interface

## 🔄 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 tag-manager
./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 tag-manager                       # Opens GUI for tag management
python3 photo_tagger.py stats
```