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

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

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

source venv/bin/activate  # Run this every time you open a new terminal

Manual Setup (Alternative)

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 photo_tagger.py stats  # Creates database

🎯 Commands

Scan for Photos

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

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

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

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

# 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

📋 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

# Tag photos matching pattern
python3 photo_tagger.py tag --pattern "vacation"

# Tag any photos
python3 photo_tagger.py tag

Search

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

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

Statistics

# View database statistics
python3 photo_tagger.py stats

Tag Manager GUI

# Open tag management interface
python3 photo_tagger.py tag-manager

📊 Enhanced Example Workflow

# 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

⚙️ Configuration

Face Detection Models

• hog - Faster, good for CPU-only systems
• cnn - More accurate, requires more processing power

Database Location

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

🔧 System Requirements

Required System Packages (Ubuntu/Debian)

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!

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:

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

# 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

🎨 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

# 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