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

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

🎯 New Auto-Match GUI Features:

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

View & Modify Identified Faces (NEW)

# Open the Modify Identified Faces interface
python3 photo_tagger.py modifyidentified

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

Left Panel (People):

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

Right Panel (Faces):

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

Bottom Controls:

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

Notes:

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

🧠 Advanced Algorithm Features

🎯 Intelligent Face Matching Engine:

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

🔬 Quality Assessment Metrics:

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

📈 Confidence Levels:

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

GUI Interactive Elements:

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

Add Tags

# 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

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

🗃️ Database

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

• photos - Photo file paths and processing status
• people - Known people names
• faces - Face encodings and locations
• tags - Custom tags for photos

⚙️ Configuration

Face Detection Models

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

Database Location

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

Auto-Match GUI (Enhanced with Smart Algorithm)

When you run python3 photo_tagger.py auto-match --show-faces, you'll see an improved interface with:

🧠 Smart Algorithm Features:

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

Interface Layout:

Left Panel:

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

Right Panel:

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

Bottom Controls (Navigation Only):

• ⏮️ Back - Go back to previous person (disabled on first person)
• ⏭️ Next - Move to next person (disabled on last person)
• ❌ Quit - Exit auto-match process

Compare with Similar Faces Workflow

The Compare feature in the Identify GUI works seamlessly with the main identification process:

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

Key Benefits:

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

Auto-Match Workflow

The auto-match feature now works in a person-centric way:

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

Key Benefits:

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

GUI Tips

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

🆕 Recent Improvements

Auto-Match UX Enhancements (Latest)

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

Consistent Face-to-Face Comparison System

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

Compare Checkbox Enhancements

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

Back Navigation & Re-identification

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

Improved Cleanup & Performance

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

Enhanced User Experience

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

🎯 What This Tool Does

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

📈 Performance Tips

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

🤝 Contributing

This is now a minimal, focused tool. Key principles:

• Keep it simple and fast
• CLI-only interface
• Minimal dependencies
• Clear, readable code
• Always use python3 commands

---

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

🔄 Common Commands Cheat Sheet

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

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

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