# 1. Setup (one time only)
git clone <your-repo>
cd PunimTag
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
python3 setup.py

# 2. Scan photos
python3 photo_tagger.py scan /path/to/your/photos

# 3. Process faces
python3 photo_tagger.py process

# 4. Identify faces interactively
python3 photo_tagger.py identify

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

# Process 50 photos (default)
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

Identify Faces

# Identify 20 faces interactively
python3 photo_tagger.py identify

# Identify 10 faces at a time
python3 photo_tagger.py identify --batch 10

Interactive commands during identification:

Type person's name to identify
s = skip this face
q = quit
list = show known people

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

📊 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 some faces
python3 photo_tagger.py identify --batch 10

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

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

🗃️ Database

The tool uses SQLite database (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
├── venv/              # Virtual environment (created by setup)
├── 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

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

🎯 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

📈 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 --batch 10
./run.sh stats

# Daily usage - Option 2: Manual venv activation
source venv/bin/activate
python3 photo_tagger.py scan ~/Pictures --recursive
python3 photo_tagger.py process --limit 50
python3 photo_tagger.py identify --batch 10
python3 photo_tagger.py stats