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

## 🚀 Quick Start

```bash
# 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)
```bash
# Clone and setup
git clone <your-repo>
cd PunimTag

# Create virtual environment (IMPORTANT!)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Run setup script
python3 setup.py
```

**⚠️ IMPORTANT**: Always activate the virtual environment before running any commands:
```bash
source venv/bin/activate  # Run this every time you open a new terminal
```

### Manual Setup (Alternative)
```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 photo_tagger.py stats  # Creates database
```

## 🎯 Commands

### Scan for Photos
```bash
# Scan a folder
python3 photo_tagger.py scan /path/to/photos

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

### Process Photos for Faces
```bash
# 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
```bash
# 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
```bash
# Tag photos matching pattern
python3 photo_tagger.py tag --pattern "vacation"

# Tag any photos
python3 photo_tagger.py tag
```

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

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

### Statistics
```bash
# View database statistics
python3 photo_tagger.py stats
```

## 📊 Example Workflow

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

# 1. Scan your photo collection
python3 photo_tagger.py scan ~/Pictures --recursive

# 2. Process photos for faces (start with small batch)
python3 photo_tagger.py process --limit 20

# 3. Check what we found
python3 photo_tagger.py stats

# 4. Identify 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
```bash
# Use custom database file
python3 photo_tagger.py scan /photos --db /path/to/my.db
```

## 🔧 System Requirements

### Required System Packages (Ubuntu/Debian)
```bash
sudo apt update
sudo apt install -y cmake build-essential libopenblas-dev liblapack-dev libx11-dev libgtk-3-dev python3-dev python3-venv
```

### Python Dependencies
- `face-recognition` - Face detection and recognition
- `dlib` - Machine learning library  
- `pillow` - Image processing
- `numpy` - Numerical operations
- `click` - Command line interface
- `setuptools` - Package management

## 📁 File Structure

```
PunimTag/
├── photo_tagger.py     # Main CLI tool
├── setup.py           # Setup script
├── run.sh             # Convenience script (auto-activates venv)
├── requirements.txt   # Python dependencies
├── README.md          # This file
├── 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!
```bash
python3 -m venv venv
source venv/bin/activate
python3 setup.py
```

### Virtual Environment Not Active
**Problem**: Commands fail or use wrong Python
**Solution**: Always activate the virtual environment:
```bash
source venv/bin/activate
# You should see (venv) in your prompt
```

### dlib Installation Issues
```bash
# Ubuntu/Debian - install system dependencies first
sudo apt-get install build-essential cmake libopenblas-dev

# Then retry setup
source venv/bin/activate
python3 setup.py
```

### "Please install face_recognition_models" Warning
This warning is harmless - the application still works correctly. It's a known issue with Python 3.13.

### Memory Issues
- Use `--model hog` for faster processing
- Process in smaller batches with `--limit 10`
- Close other applications to free memory

### No Faces Found
- Check image quality and lighting
- Ensure faces are clearly visible
- Try `--model cnn` for better detection

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

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

# Daily usage - Option 1: Use run script (automatic venv activation)
./run.sh scan ~/Pictures --recursive
./run.sh process --limit 50
./run.sh identify --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
```