punimtag/docs

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 (absolute or relative paths work)
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 (absolute path recommended)
python3 photo_tagger.py scan /path/to/photos

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

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

📁 Path Handling:

• Absolute paths: Use full paths like /home/user/photos or C:\Users\Photos
• Relative paths: Automatically converted to absolute paths (e.g., demo_photos → /current/directory/demo_photos)
• Cross-platform: Works on Windows, Linux, and macOS
• Web-app ready: Absolute paths work perfectly in web applications

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
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
• 🏷️ 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
• 🔗 Enhanced Tag Linking - Linkage icon (🔗) for intuitive tag management
• 📋 Comprehensive Tag Dialog - Manage tags dialog similar to Manage Tags interface
• ✅ Pending Tag System - Add and remove tags with pending changes until saved
• 🎯 Visual Status Indicators - Clear distinction between saved and pending tags
• 🗑️ Smart Tag Removal - Remove both pending and saved tags with proper tracking
• 🧩 Linkage Types (Single vs Bulk) - Tag links can be added per-photo (single) or for the entire folder (bulk). Bulk links appear on folder headers and follow special rules in dialogs

📋 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 grouping applies across all views:

• 📁 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
• 🏷️ Folder Bulk Tags - Folder header shows bulk tags that apply to all photos in that folder (includes pending bulk adds not marked for removal)

🔧 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

🏷️ Enhanced Tag Management System:

• 🔗 Linkage Icon - Click the 🔗 button next to tags to open the tag management dialog
• 📋 Comprehensive Dialog - Similar interface to Manage Tags with dropdown selection and tag listing
• ✅ Pending Changes - Add and remove tags with changes tracked until "Save Tagging" is clicked
• 🎯 Visual Status - Tags show "(pending)" in blue or "(saved)" in black for clear status indication
• 🗑️ Smart Removal - Remove both pending and saved tags with proper database tracking
• 📊 Batch Operations - Select multiple tags for removal with checkboxes
• 🔄 Real-time Updates - Tag display updates immediately when changes are made
• 💾 Save System - All tag changes (additions and removals) saved atomically when "Save Tagging" is clicked
• 🔁 Bulk Overrides Single - If a tag was previously added as single to some photos, adding the same tag in bulk for the folder upgrades those single links to bulk on save
• 🚫 Scoped Deletions - Single-photo tag dialog can delete saved/pending single links only; Bulk dialog deletes saved bulk links or cancels pending bulk adds only
• 🎯 ID-Based Architecture - Uses tag IDs internally for efficient, reliable operations
• ⚡ Performance Optimized - Fast tag operations with minimal database queries

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"

# Open the Search GUI
python3 photo_tagger.py search-gui

🔍 Enhanced Search GUI Features:

🔍 Multiple Search Types:

• Search photos by name: Find photos containing specific people
• Search photos by date: Find photos within date ranges (with calendar picker)
• Search photos by tags: Find photos with specific tags (with help icon)
• Photos without faces: Find photos with no detected faces
• Photos without tags: Find untagged photos

📋 Filters Area (Collapsible):

• Folder Location Filter: Filter results by specific folder path
• Browse Button: Visual folder selection dialog (selects absolute paths)
• Clear Button: Reset folder filter
• Apply Filters Button: Apply folder filter to current search
• Expand/Collapse: Click +/- to show/hide filters
• Tooltips: Hover over +/- for expand/collapse guidance

📊 Results Display:

• Person Column: Shows matched person's name (only in name search)
• 📁 Column: Click to open file's folder (tooltip: "Open file location")
• 🏷️ Column: Click to show photo tags in popup, hover for tag tooltip
• Photo Path Column: Click to open the photo (tooltip: "Open photo")
• ☑ Column: Click to select/deselect photos for bulk tagging
• Date Taken Column: Shows when photo was taken
• Sortable Columns: Click column headers to sort results

🎛️ Interactive Features:

• Tag Help Icon (❓): Hover to see all available tags in column format
• Calendar Picker: Click 📅 to select dates (date fields are read-only)
• Enter Key Support: Press Enter in search fields to trigger search
• Tag Selected Photos: Button to open linkage dialog for selected photos
• Clear All Selected: Button to deselect all checkboxes

🎯 Search GUI Workflow:

1. Search for Photos: Enter a person's name and press Enter or click Search
2. View Results: See all photos containing that person in a sortable table
3. Select Photos: Click checkboxes (☑) to select photos for bulk operations
4. View Tags: Click 🏷️ icon to see all tags for a photo, or hover for quick preview
5. Open Photos: Click the photo path to open the photo in your default viewer
6. Bulk Tagging: Select multiple photos and click "Tag selected photos" to add tags
7. Clear Selection: Use "Clear all selected" to deselect all photos at once

🏷️ Tag Management in Search GUI:

• Tag Popup: Click 🏷️ icon to see all tags for a photo in a scrollable popup
• Tag Tooltip: Hover over 🏷️ icon for quick tag preview (shows up to 5 tags)
• Bulk Tag Dialog: Select multiple photos and use "Tag selected photos" button
• Add New Tags: Type new tag names in the linkage dialog (auto-saves to database)
• Remove Tags: Use checkboxes in the linkage dialog to remove existing tags
• Enter Key Support: Press Enter in tag input field to quickly add tags

Statistics

# View database statistics
python3 photo_tagger.py stats

Tag Manager GUI

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

Dashboard GUI

# Open the main dashboard
python3 photo_tagger.py dashboard

🎯 Dashboard Features:

• 📁 Scan Section: Add photos to database with folder selection
• Browse Button: Visual folder selection dialog (selects absolute paths)
• Recursive Option: Include photos in subfolders
• Path Validation: Automatic path validation and error handling
• Cross-platform: Works on Windows, Linux, and macOS

📁 Enhanced Folder Selection:

• Visual Selection: Click "Browse" to select folders visually
• Absolute Paths: All selected paths are stored as absolute paths
• Path Normalization: Relative paths automatically converted to absolute
• Error Handling: Clear error messages for invalid paths

📊 Enhanced Example Workflow

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

# 1. Scan your photo collection (absolute or relative paths work)
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
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)
  • Columns: linkage_id (PK), photo_id, tag_id, linkage_type (INTEGER: 0=single, 1=bulk), created_date
• 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

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

🌐 Path Handling & Web Application Compatibility

Absolute Path System

PunimTag now uses a robust absolute path system that ensures consistency across all platforms and deployment scenarios.

📁 Key Features:

• Automatic Path Normalization: All paths are converted to absolute paths
• Cross-Platform Support: Works on Windows (C:\Photos), Linux (/home/user/photos), and macOS
• Web Application Ready: Absolute paths work perfectly in web applications
• Browse Buttons: Visual folder selection in all GUI components
• Path Validation: Automatic validation and error handling

🔧 Path Utilities:

• normalize_path(): Converts any path to absolute path
• validate_path_exists(): Checks if path exists and is accessible
• get_path_info(): Provides detailed path information
• Cross-platform: Handles Windows, Linux, and macOS path formats

🌐 Web Application Integration:

# Example: Flask web application integration
from path_utils import normalize_path

@app.route('/scan_photos', methods=['POST'])
def scan_photos():
    upload_dir = request.form['upload_dir']
    absolute_path = normalize_path(upload_dir)  # Always absolute
    # Run photo_tagger with absolute path
    subprocess.run(f"python3 photo_tagger.py scan {absolute_path}")

📋 Path Examples:

# CLI - relative path auto-converted
python3 photo_tagger.py scan demo_photos
# Stored as: /home/user/punimtag/demo_photos/photo.jpg

# CLI - absolute path used as-is
python3 photo_tagger.py scan /home/user/photos
# Stored as: /home/user/photos/photo.jpg

# GUI - Browse button selects absolute path
# User selects folder → absolute path stored in database

🔧 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
• 📷 Photo Icon - Click the camera icon in the top-right corner of the face to open the original photo in your default image viewer
• ✅ 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
  • 📷 Photo Icons - Click the camera icon on any similar face to view its original photo
• 🎮 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
• 📷 Photo Icon - Click the camera icon in the top-right corner to open the original photo
• 📁 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
  • 📷 Photo Icons - Click the camera icon on any face to view its original photo
• 📜 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 (doesn't close calendar immediately)
• Visual Feedback - Selected dates highlighted in bright blue, today's date in orange
• Future Date Restrictions - Future dates are disabled and grayed out (birth dates cannot be in the future)
• 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 (prevents navigation to future months)
• Click Date - Select any visible date (highlights in blue, doesn't close calendar)
• Select Button - Confirm your date choice and close calendar
• Cancel Button - Close without selecting

New Calendar Behavior:

• Two-Step Process - Click date to select, then click "Select" to confirm
• Future Date Protection - Cannot select dates after today (logical for birth dates)
• Smart Navigation - Month/year buttons prevent going to future periods
• Visual Clarity - Selected dates clearly highlighted, future dates clearly disabled

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
• Smart Quit Validation: Quit button only shows warning when all three required fields are filled (first name, last name, date of birth)
• Quit Confirmation: When closing, system asks if you want to save pending identifications
• Cancel Protection: Clicking "Cancel" in quit warning keeps the main window open
• 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 GUI Migration (Latest)

• ✅ Complete Migration: Auto-match GUI fully migrated from legacy version to current architecture
• 🔄 Exact Feature Parity: All functionality preserved including person-centric view, checkbox selection, and state persistence
• 🎯 Enhanced Integration: Seamlessly integrated with new modular architecture while maintaining all original features
• ⚡ Performance Optimized: Leverages new face processing and database management systems for better performance

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
• ✅ Future Date Restrictions - Future dates are disabled and grayed out (birth dates cannot be in the future)
• ✅ Select/Cancel Buttons - Proper confirmation workflow - click date to select, then click "Select" to confirm
• ✅ Smart Navigation Limits - Month/year navigation prevents going to future months/years

🔄 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 Quit Validation (NEW!)

• ✅ Smart Form Validation - Quit button only shows warning when ALL three required fields are filled (first name, last name, date of birth)
• ✅ Proper Cancel Behavior - Clicking "Cancel" in quit warning keeps the main window open instead of closing it
• ✅ Unsaved Changes Detection - Accurately detects when you have complete identification data ready but haven't pressed "Identify" yet
• ✅ Improved User Experience - No more false warnings when only partially filling form fields

🆕 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 Tag Management Interface (LATEST!)

• ✅ Linkage Icon - Replaced "+" button with intuitive 🔗 linkage icon for tag management
• ✅ Comprehensive Tag Dialog - Redesigned tag management dialog similar to Manage Tags interface
• ✅ Dropdown Tag Selection - Select from existing tags or create new ones via dropdown
• ✅ Pending Tag System - Add and remove tags with changes tracked until explicitly saved
• ✅ Visual Status Indicators - Clear distinction between saved tags (black) and pending tags (blue)
• ✅ Smart Tag Removal - Remove both pending and saved tags with proper database tracking
• ✅ Batch Tag Operations - Select multiple tags for removal with checkboxes
• ✅ Real-time UI Updates - Tag display updates immediately when changes are made
• ✅ Atomic Save Operations - All tag changes (additions and removals) saved in single transaction
• ✅ Efficient ID-Based Operations - Uses tag IDs internally for fast, reliable tag management
• ✅ Scrollable Tag Lists - Handle photos with many tags in scrollable interface
• ✅ Immediate Visual Feedback - Removed tags disappear from UI immediately
• ✅ Database Integrity - Proper cleanup of pending changes when tags are deleted

🎨 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

📷 Photo Icon Feature (NEW!)

• ✅ Source Photo Access - Click the 📷 camera icon on any face to open the original photo
• ✅ Smart Positioning - Icons appear exactly in the top-right corner of each face image
• ✅ Cross-Platform Support - Opens photos in properly sized windows on Windows, macOS, and Linux
• ✅ Helpful Tooltips - "Show original photo" tooltip appears on hover
• ✅ Available Everywhere - Works on main faces (left panel) and similar faces (right panel)
• ✅ Proper Window Sizing - Photos open in reasonable window sizes, not fullscreen
• ✅ Multiple Viewer Support - Tries multiple image viewers for optimal experience

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 search-gui                        # Opens Search GUI
python3 photo_tagger.py modifyidentified                  # Opens GUI to view/modify
python3 photo_tagger.py dashboard                         # Opens Dashboard with Browse buttons
python3 photo_tagger.py tag-manager                       # Opens GUI for tag management
python3 photo_tagger.py stats